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

Document {-# INCLUDE #-}

diff --git a/ghc/docs/users_guide/glasgow_exts.xml b/ghc/docs/users_guide/glasgow_exts.xml
index 0e19d42..765ff85 100644 (file)
--- a/ghc/docs/users_guide/glasgow_exts.xml
+++ b/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>