ghc/docs/users_guide/ffi-chap.sgml

   1 <!-- FFI docs as a chapter -->
   2
   3 <Chapter id="ffi">
   4 <Title>Foreign function interface</Title>
   5
   6   <para>The foreign interface consists of the following components:</para>
   7
   8   <itemizedlist>
   9     <listitem>
  10       <para>The Foreign Function Interface language specification
  11       (which constitutes most of this Chapter, beginning with <xref
  12       linkend="sec-ffi-intro">).  You must use the
  13       <option>-fglasgow-exts</option> command-line option to make GHC
  14       understand the <literal>foreign</literal> declarations defined
  15       by the FFI.</para>
  16     </listitem>
  17
  18     <listitem>
  19       <para>The <literal>Foreign</literal> module (see <xref
  20       linkend="sec-Foreign">) collects together several interfaces
  21       which are useful in specifying foreign language interfaces,
  22       including the following:</para>
  23
  24       <itemizedlist>
  25         <listitem>
  26           <para>The <literal>ForeignObj</literal> module (see <xref
  27           linkend="sec-ForeignObj">), for managing pointers from
  28           Haskell into the outside world.</para>
  29         </listitem>
  30
  31         <listitem>
  32           <para>The <literal>StablePtr</literal> module (see <xref
  33           linkend="sec-stable-pointers">), for managing pointers into
  34           Haskell from the outside world.</para>
  35         </listitem>
  36
  37         <listitem>
  38           <para>The <literal>CTypes</literal> module (see <xref
  39           linkend="sec-CTypes">) gives Haskell equivalents for the
  40           standard C datatypes, for use in making Haskell bindings to
  41           existing C libraries.</para>
  42         </listitem>
  43
  44         <listitem>
  45           <para>The <literal>CTypesISO</literal> module (see <xref
  46           linkend="sec-CTypesISO">) gives Haskell equivalents for C
  47           types defined by the ISO C standard.</para>
  48         </listitem>
  49
  50         <listitem>
  51           <para>The <literal>Storable</literal> library, for primitive
  52           marshalling of data types between Haskell and the foreign
  53           language.</para>
  54         </listitem>
  55       </itemizedlist>
  56
  57     </listitem>
  58   </itemizedlist>
  59
  60 &ffi-body;
  61
  62   <sect1 id="ffi-ghc">
  63     <title>Using the FFI with GHC</title>
  64
  65     <para>The following sections also give some hints and tips on the
  66     use of the foreign function interface in GHC.</para>
  67
  68     <sect2 id="foreign-export-dynamic-ghc">
  69       <title>Using <literal>foreign export dynamic</literal> with
  70       GHC</title>
  71
  72       <indexterm><primary><literal>foreign export
  73       dynamic</literal></primary><secondary>with GHC</secondary>
  74       </indexterm>
  75
  76       <para>When GHC compiles a module (say <filename>M.hs</filename>)
  77       which uses <literal>foreign export dynamic</literal>, it
  78       generates two additional files, <filename>M_stub.c</filename>
  79       and <filename>M_stub.h</filename>.  GHC will automatically
  80       compile <filename>M_stub.c</filename> to generate
  81       <filename>M_stub.o</filename> at the same time.</para>
  82
  83       <para>The C file <filename>M_stub.c</filename> contains small
  84       helper functions used by the code generated for the
  85       <literal>foreign export dynamic</literal>, so it must be linked
  86       in to the final program.  When linking the program, remember to
  87       include <filename>M_stub.o</filename> in the final link command
  88       line, or you'll get link errors for the missing function(s)
  89       (this isn't necessary when building your program with
  90       <literal>ghc --make</literal>, as GHC will automatically link in
  91       the correct bits).</para>
  92     </sect2>
  93
  94     <sect2 id="glasgow-foreign-headers">
  95       <title>Using function headers</title>
  96
  97       <indexterm><primary>C calls, function headers</primary></indexterm>
  98
  99       <para>When generating C (using the <option>-fvia-C</option>
 100
 101       directive), one can assist the C compiler in detecting type
 102       errors by using the <option>-&num;include</option> directive
 103       (<xref linkend="options-C-compiler">) to provide
 104       <filename>.h</filename> files containing function
 105       headers.</para>
 106
 107       <para>For example,</para>
 108
 109 <programlisting>
 110 #include "HsFFI.h"
 111
 112 void         initialiseEFS (HsInt size);
 113 HsInt        terminateEFS (void);
 114 HsForeignObj emptyEFS(void);
 115 HsForeignObj updateEFS (HsForeignObj a, HsInt i, HsInt x);
 116 HsInt        lookupEFS (HsForeignObj a, HsInt i);
 117 </programlisting>
 118
 119       <para>The types <literal>HsInt</literal>,
 120       <literal>HsForeignObj</literal> etc. are described in <xref
 121       linkend="sec-ffi-mapping-table">.</para>
 122
 123       <para>Note that this approach is only
 124       <emphasis>essential</emphasis> for returning
 125       <literal>float</literal>s (or if <literal>sizeof(int) !=
 126       sizeof(int *)</literal> on your architecture) but is a Good
 127       Thing for anyone who cares about writing solid code.  You're
 128       crazy not to do it.</para>
 129
 130     </sect2>
 131   </sect1>
 132 </Chapter>
 133
 134 <!-- Emacs stuff:
 135      ;;; Local Variables: ***
 136      ;;; mode: sgml ***
 137      ;;; sgml-parent-document: ("users_guide.sgml" "book" "chapter") ***
 138      ;;; End: ***
 139  -->