<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>-#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: ***
+ -->
</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>-#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>
projects / ghc-hetmet.git / commitdiff