[project @ 2006-01-03 11:06:45 by simonmar]

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

diff --git a/ghc/docs/users_guide/ffi-chap.xml b/ghc/docs/users_guide/ffi-chap.xml
index 789a6a1..e1374c4 100644 (file)
--- a/ghc/docs/users_guide/ffi-chap.xml
+++ b/ghc/docs/users_guide/ffi-chap.xml
@@ -2,13 +2,20 @@
 <!-- FFI docs as a chapter -->
 
 <chapter id="ffi">
-<title>Foreign function interface (FFI)</title>
+ <title>
+Foreign function interface (FFI)
+ </title>
 
   <para>GHC (mostly) conforms to the Haskell 98 Foreign Function Interface
-  Addendum 1.0, whose definition is available from <ulink
-  url="http://haskell.org/"><literal>http://haskell.org/</literal></ulink >.
-  The FFI support in GHC diverges from the Addendum in the following ways:
-  </para>
+  Addendum 1.0, whose definition is available from <ulink url="http://haskell.org/"><literal>http://haskell.org/</literal></ulink>.</para>
+
+  <para>To enable FFI support in GHC, give the <option>-fffi</option><indexterm><primary><option>-fffi</option></primary>
+    </indexterm>flag, or
+the <option>-fglasgow-exts</option><indexterm><primary><option>-fglasgow-exts</option></primary>
+    </indexterm> flag which implies <option>-fffi</option>
+.</para>
+
+  <para>The FFI support in GHC diverges from the Addendum in the following ways:</para>
 
   <itemizedlist>
     <listitem>
@@ -18,8 +25,7 @@
 
     <listitem>
       <para>GHC implements a number of GHC-specific extensions to the FFI
-      Addendum.  These extensions are described in <xref
-      linkend="sec-ffi-ghcexts"/>, but please note that programs using
+      Addendum.  These extensions are described in <xref linkend="sec-ffi-ghcexts" />, but please note that programs using
       these features are not portable.  Hence, these features should be
       avoided where possible.</para>
     </listitem>
@@ -101,6 +107,11 @@ extern HsInt foo(HsInt a0);</programlisting>
       invoke <literal>foo()</literal> from C, just <literal>#include
       "Foo_stub.h"</literal> and call <literal>foo()</literal>.</para>
 
+      <para>The <filename>foo_stub.c</filename> and
+       <filename>foo_stub.h</filename> files can be redirected using the
+       <option>-stubdir</option> option; see <xref linkend="options-output"
+         />.</para>
+
       <sect3 id="using-own-main"> 
        <title>Using your own <literal>main()</literal></title>
 
@@ -108,7 +119,7 @@ extern HsInt foo(HsInt a0);</programlisting>
        <literal>main()</literal>, which arranges to invoke
        <literal>Main.main</literal> in the Haskell program.  However,
        you might want to link some Haskell code into a program which
-       has a main function written in another languagem, say C.  In
+       has a main function written in another language, say C.  In
        order to do this, you have to initialize the Haskell runtime
        system explicitly.</para>
 
@@ -280,7 +291,7 @@ declaration itself:
 </programlisting>
 When compiling this module, GHC will generate a C file that includes
 the specified <option>-&num;include</option>.  However, GHC
-<emphasis>disables</emphasis> cross-module inlinding for such foreign
+<emphasis>disables</emphasis> cross-module inlining for such foreign
 calls, because it doesn't transport the <option>-&num;include</option>
 information across module boundaries.  (There is no fundamental reason for this;
 it was just tiresome to implement.  The wrapper, which unboxes the arguments
@@ -327,7 +338,7 @@ to be inlined across modules, use the command-line and package-configuration
          <listitem>
            <para>Useful for short-term allocation when the allocation
            is intended to scope over a given <literal>IO</literal>
-           compuatation.  This kind of allocation is commonly used
+           computation.  This kind of allocation is commonly used
            when marshalling data to and from FFI functions.</para>
 
            <para>In GHC, <literal>alloca</literal> is implemented
@@ -366,7 +377,7 @@ to be inlined across modules, use the command-line and package-configuration
            <para>If all else fails, then you need to resort to
            <literal>Foreign.malloc</literal> and
            <literal>Foreign.free</literal>.  These are just wrappers
-           around the C funcitons of the same name, and their
+           around the C functions of the same name, and their
            efficiency will depend ultimately on the implementations
            of these functions in your platform's C library.  We
            usually find <literal>malloc</literal> and
@@ -376,14 +387,14 @@ to be inlined across modules, use the command-line and package-configuration
        </varlistentry>
 
        <varlistentry>
-         <term><literal>Foreign.Marhsal.Pool</literal></term>
+         <term><literal>Foreign.Marshal.Pool</literal></term>
          <listitem>
            <para>Pools are currently implemented using
            <literal>malloc/free</literal>, so while they might be a
            more convenient way to structure your memory allocation
            than using one of the other forms of allocation, they
            won't be any more efficient.  We do plan to provide an
-           improved-performance implementaiton of Pools in the
+           improved-performance implementation of Pools in the
            future, however.</para>
          </listitem>
        </varlistentry>