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

[ghc-hetmet.git] / ghc / docs / users_guide / ffi-chap.sgml

diff --git a/ghc/docs/users_guide/ffi-chap.sgml b/ghc/docs/users_guide/ffi-chap.sgml
index 869c901..1bcc717 100644 (file)
--- a/ghc/docs/users_guide/ffi-chap.sgml
+++ b/ghc/docs/users_guide/ffi-chap.sgml
@@ -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: ***
+ -->