[[project @ 2005-01-28 14:41:09 by simonmar]
simonmar**20050128144109
 Document {-# INCLUDE #-}
] {
hunk ./ghc/docs/users_guide/glasgow_exts.xml 4202
+
+    <sect2 id="include-pragma">
+      <title>INCLUDE pragma</title>
+
+      <para>The <literal>INCLUDE</literal> pragma is for specifying the names
+	of C header files that should be <literal>#include</literal>'d into
+	the C source code generated by the compiler for the current module (if
+	compiling via C).  For example:</para>
+
+<programlisting>
+{-# INCLUDE "foo.h" #-}
+{-# INCLUDE &lt;stdio.h&gt; #-}</programlisting>
+
+      <para>The <literal>INCLUDE</literal> pragma(s) must appear at the top of
+	your source file with any <literal>OPTIONS_GHC</literal>
+	pragma(s).</para>
+
+      <para>An <literal>INCLUDE</literal> pragma is  the preferred alternative
+	to the <option>-#include</option> option (<xref
+	  linkend="options-C-compiler" />), because the
+	<literal>INCLUDE</literal> pragma is understood by other
+	compilers.  Yet another alternative is to add the include file to each
+	<literal>foreign import</literal> declaration in your code, but we
+	don't recommend using this approach with GHC.</para>
+    </sect2>
}