Commit 14d65c3f authored by simonmar's avatar simonmar
Browse files

[project @ 2001-08-08 13:19:07 by simonmar]

- Rearrange the FFI documentation: put it all in chapter 8.

- Add a section "Using the FFI with GHC", and add some information about
  the stub files generated by GHC for foreign export dynamic.
parent da582343
......@@ -2,5 +2,138 @@
<Chapter id="ffi">
<Title>Foreign function interface</Title>
<para>The foreign interface consists of the following components:</para>
<itemizedlist>
<listitem>
<para>The Foreign Function Interface language specification
(which constitutes most of this Chapter, beginning with <xref
linkend="sec-ffi-intro">). You must use the
<option>-fglasgow-exts</option> command-line option to make GHC
understand the <literal>foreign</literal> declarations defined
by the FFI.</para>
</listitem>
<listitem>
<para>The <literal>Foreign</literal> module (see <xref
linkend="sec-Foreign">) collects together several interfaces
which are useful in specifying foreign language interfaces,
including the following:</para>
<itemizedlist>
<listitem>
<para>The <literal>ForeignObj</literal> module (see <xref
linkend="sec-ForeignObj">), for managing pointers from
Haskell into the outside world.</para>
</listitem>
<listitem>
<para>The <literal>StablePtr</literal> module (see <xref
linkend="sec-stable-pointers">), for managing pointers into
Haskell from the outside world.</para>
</listitem>
<listitem>
<para>The <literal>CTypes</literal> module (see <xref
linkend="sec-CTypes">) gives Haskell equivalents for the
standard C datatypes, for use in making Haskell bindings to
existing C libraries.</para>
</listitem>
<listitem>
<para>The <literal>CTypesISO</literal> module (see <xref
linkend="sec-CTypesISO">) gives Haskell equivalents for C
types defined by the ISO C standard.</para>
</listitem>
<listitem>
<para>The <literal>Storable</literal> library, for primitive
marshalling of data types between Haskell and the foreign
language.</para>
</listitem>
</itemizedlist>
</listitem>
</itemizedlist>
&ffi-body;
<sect1 id="ffi-ghc">
<title>Using the FFI with GHC</title>
<para>The following sections also give some hints and tips on the
use of the foreign function interface in GHC.</para>
<sect2 id="foreign-export-dynamic-ghc">
<title>Using <literal>foreign export dynamic</literal> with
GHC</title>
<indexterm><primary><literal>foreign export
dynamic</literal></primary><secondary>with GHC</secondary>
</indexterm>
<para>When GHC compiles a module (say <filename>M.hs</filename>)
which uses <literal>foreign export dynamic</literal>, it
generates two additional files, <filename>M_stub.c</filename>
and <filename>M_stub.h</filename>. GHC will automatically
compile <filename>M_stub.c</filename> to generate
<filename>M_stub.o</filename> at the same time.</para>
<para>The C file <filename>M_stub.c</filename> contains small
helper functions used by the code generated for the
<literal>foreign export dynamic</literal>, so it must be linked
in to the final program. When linking the program, remember to
include <filename>M_stub.o</filename> in the final link command
line, or you'll get link errors for the missing function(s)
(this isn't necessary when building your program with
<literal>ghc --make</literal>, as GHC will automatically link in
the correct bits).</para>
</sect2>
<sect2 id="glasgow-foreign-headers">
<title>Using function headers</title>
<indexterm><primary>C calls, function headers</primary></indexterm>
<para>When generating C (using the <option>-fvia-C</option>
directive), one can assist the C compiler in detecting type
errors by using the <option>-&num;include</option> directive
(<xref linkend="options-C-compiler">) to provide
<filename>.h</filename> files containing function
headers.</para>
<para>For example,</para>
<programlisting>
#include "HsFFI.h"
void initialiseEFS (HsInt size);
HsInt terminateEFS (void);
HsForeignObj emptyEFS(void);
HsForeignObj updateEFS (HsForeignObj a, HsInt i, HsInt x);
HsInt lookupEFS (HsForeignObj a, HsInt i);
</programlisting>
<para>The types <literal>HsInt</literal>,
<literal>HsForeignObj</literal> etc. are described in <xref
linkend="sec-ffi-mapping-table">.</para>
<para>Note that this approach is only
<emphasis>essential</emphasis> for returning
<literal>float</literal>s (or if <literal>sizeof(int) !=
sizeof(int *)</literal> on your architecture) but is a Good
Thing for anyone who cares about writing solid code. You're
crazy not to do it.</para>
</sect2>
</sect1>
</Chapter>
<!-- Emacs stuff:
;;; Local Variables: ***
;;; mode: sgml ***
;;; sgml-parent-document: ("users_guide.sgml" "book" "chapter") ***
;;; End: ***
-->
......@@ -617,111 +617,6 @@ qualifier list has just one element, a boolean expression.
</sect1>
<sect1 id="sec-ffi">
<title>The foreign interface</title>
<para>The foreign interface consists of the following components:</para>
<itemizedlist>
<listitem>
<para>The Foreign Function Interface language specification
(included in this manual, in <xref linkend="ffi">).
You must use the <option>-fglasgow-exts</option> command-line option
to make GHC understand the <literal>foreign</literal> declarations
defined by the FFI.</para>
</listitem>
<listitem>
<para>The <literal>Foreign</literal> module (see <xref
linkend="sec-Foreign">) collects together several interfaces
which are useful in specifying foreign language
interfaces, including the following:</para>
<itemizedlist>
<listitem>
<para>The <literal>ForeignObj</literal> module (see <xref
linkend="sec-ForeignObj">), for managing pointers from
Haskell into the outside world.</para>
</listitem>
<listitem>
<para>The <literal>StablePtr</literal> module (see <xref
linkend="sec-stable-pointers">), for managing pointers
into Haskell from the outside world.</para>
</listitem>
<listitem>
<para>The <literal>CTypes</literal> module (see <xref
linkend="sec-CTypes">) gives Haskell equivalents for the
standard C datatypes, for use in making Haskell bindings
to existing C libraries.</para>
</listitem>
<listitem>
<para>The <literal>CTypesISO</literal> module (see <xref
linkend="sec-CTypesISO">) gives Haskell equivalents for C
types defined by the ISO C standard.</para>
</listitem>
<listitem>
<para>The <literal>Storable</literal> library, for
primitive marshalling of data types between Haskell and
the foreign language.</para>
</listitem>
</itemizedlist>
</listitem>
</itemizedlist>
<para>The following sections also give some hints and tips on the use
of the foreign function interface in GHC.</para>
<sect2 id="glasgow-foreign-headers">
<title>Using function headers
</title>
<para>
<indexterm><primary>C calls, function headers</primary></indexterm>
</para>
<para>
When generating C (using the <option>-fvia-C</option> directive), one can assist the
C compiler in detecting type errors by using the <option>-&num;include</option> directive
(<xref linkend="options-C-compiler">) to provide <filename>.h</filename> files containing function headers.
</para>
<para>
For example,
</para>
<para>
<programlisting>
#include "HsFFI.h"
void initialiseEFS (HsInt size);
HsInt terminateEFS (void);
HsForeignObj emptyEFS(void);
HsForeignObj updateEFS (HsForeignObj a, HsInt i, HsInt x);
HsInt lookupEFS (HsForeignObj a, HsInt i);
</programlisting>
</para>
<para>The types <literal>HsInt</literal>,
<literal>HsForeignObj</literal> etc. are described in <xref
linkend="sec-mapping-table">.</para>
<para>Note that this approach is only
<emphasis>essential</emphasis> for returning
<literal>float</literal>s (or if <literal>sizeof(int) !=
sizeof(int *)</literal> on your architecture) but is a Good
Thing for anyone who cares about writing solid code. You're
crazy not to do it.</para>
</sect2>
</sect1>
<sect1 id="multi-param-type-classes">
<title>Multi-parameter type classes
</title>
......
......@@ -460,7 +460,7 @@ to compete with it, but link with it.
</Para>
<Para>
<XRef LinkEnd="sec-ffi"> describes the foreign calling interface.
<XRef LinkEnd="ffi"> describes the foreign function interface.
</Para>
</ListItem>
</VarListEntry>
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment