[project @ 2005-01-28 14:41:09 by simonmar]

Document {-# INCLUDE #-}

ghc/docs/users_guide/glasgow_exts.xml

@@ -4200,6 +4200,31 @@ Assertion failures can be caught, see the documentation for the
       <option>-fno-warn-deprecations</option>.</para>
     </sect2>
 
+    <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>
+
     <sect2 id="inline-noinline-pragma">
       <title>INLINE and NOINLINE pragmas</title>