<!-- 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>
<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>
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>
<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>
</programlisting>
When compiling this module, GHC will generate a C file that includes
the specified <option>-#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>-#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
<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
<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
</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>