ffi-chap.sgml 4.77 KB
Newer Older
rrt's avatar
rrt committed
1 2 3
<!-- FFI docs as a chapter -->

<Chapter id="ffi">
rrt's avatar
rrt committed
4
<Title>Foreign function interface</Title>
5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59

  <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>

rrt's avatar
rrt committed
60
&ffi-body;
61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131

  <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>
rrt's avatar
rrt committed
132
</Chapter>
133 134 135 136 137 138 139

<!-- Emacs stuff:
     ;;; Local Variables: ***
     ;;; mode: sgml ***
     ;;; sgml-parent-document: ("users_guide.sgml" "book" "chapter") ***
     ;;; End: ***
 -->