Skip to content

Commit

Permalink
Be more specific about file-header pragmas
Browse files Browse the repository at this point in the history 
Document the rules for pragmas that must occur at the top of a file.

Please merge this patch
  • Loading branch information
simonpj@microsoft.com committed Sep 24, 2007
1 parent 34ff0e5 commit 390b7c4
Show file tree
Hide file tree
Showing 2 changed files with 86 additions and 66 deletions.
2 changes: 1 addition & 1 deletion docs/users_guide/flags.xml
View file
Expand Up @@ -789,7 +789,7 @@
</row>
<row>
<entry><option>-XKindSignatures</option></entry>
<entry>Enable kind signatures.</entry>
<entry>Enable <link linkend="kinding">kind signatures</link>.</entry>
<entry>dynamic</entry>
<entry><option>-XNoKindSignatures</option></entry>
</row>
Expand Down
150 changes: 85 additions & 65 deletions docs/users_guide/glasgow_exts.xml
View file
Expand Up @@ -3604,7 +3604,10 @@ kind for the type variable <literal>cxt</literal>.
</para>
<para>
GHC now instead allows you to specify the kind of a type variable directly, wherever
a type variable is explicitly bound. Namely:
a type variable is explicitly bound, with the flag <option>-XKindSignatures</option>.
</para>
<para>
This flag enables kind signatures in the following places:
<itemizedlist>
<listitem><para><literal>data</literal> declarations:
<screen>
Expand Down Expand Up @@ -5306,6 +5309,87 @@ Assertion failures can be caught, see the documentation for the
unrecognised <replaceable>word</replaceable> is (silently)
ignored.</para>

<para>Certain pragmas are <emphasis>file-header pragmas</emphasis>. A file-header
pragma must precede the <literal>module</literal> keyword in the file.
There can be as many file-header pragmas as you please, and they can be
preceded or followed by comments.</para>

<sect2 id="language-pragma">
<title>LANGUAGE pragma</title>

<indexterm><primary>LANGUAGE</primary><secondary>pragma</secondary></indexterm>
<indexterm><primary>pragma</primary><secondary>LANGUAGE</secondary></indexterm>

<para>The <literal>LANGUAGE</literal> pragma allows language extensions to be enabled
in a portable way.
It is the intention that all Haskell compilers support the
<literal>LANGUAGE</literal> pragma with the same syntax, although not
all extensions are supported by all compilers, of
course. The <literal>LANGUAGE</literal> pragma should be used instead
of <literal>OPTIONS_GHC</literal>, if possible.</para>

<para>For example, to enable the FFI and preprocessing with CPP:</para>

<programlisting>{-# LANGUAGE ForeignFunctionInterface, CPP #-}</programlisting>

<para><literal>LANGUAGE</literal> is a file-header pragma (see <xref linkend="pragmas"/>).</para>

<para>Every language extension can also be turned into a command-line flag
by prefixing it with "<literal>-X</literal>"; for example <option>-XForeignFunctionInterface</option>.
(Similarly, all "<literal>-X</literal>" flags can be written as <literal>LANGUAGE</literal> pragmas.
</para>

<para>A list of all supported language extensions can be obtained by invoking
<literal>ghc --supported-languages</literal> (see <xref linkend="modes"/>).</para>

<para>Any extension from the <literal>Extension</literal> type defined in
<ulink
url="../libraries/Cabal/Language-Haskell-Extension.html"><literal>Language.Haskell.Extension</literal></ulink>
may be used. GHC will report an error if any of the requested extensions are not supported.</para>
</sect2>


<sect2 id="options-pragma">
<title>OPTIONS_GHC pragma</title>
<indexterm><primary>OPTIONS_GHC</primary>
</indexterm>
<indexterm><primary>pragma</primary><secondary>OPTIONS_GHC</secondary>
</indexterm>

<para>The <literal>OPTIONS_GHC</literal> pragma is used to specify
additional options that are given to the compiler when compiling
this source file. See <xref linkend="source-file-options"/> for
details.</para>

<para>Previous versions of GHC accepted <literal>OPTIONS</literal> rather
than <literal>OPTIONS_GHC</literal>, but that is now deprecated.</para>
</sect2>

<para><literal>OPTIONS_GHC</literal> is a file-header pragma (see <xref linkend="pragmas"/>).</para>

<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><literal>INCLUDE</literal> is a file-header pragma (see <xref linkend="pragmas"/>).</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="deprecated-pragma">
<title>DEPRECATED pragma</title>
<indexterm><primary>DEPRECATED</primary>
Expand Down Expand Up @@ -5358,31 +5442,6 @@ 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>

Expand Down Expand Up @@ -5529,29 +5588,6 @@ happen.
</sect3>
</sect2>

<sect2 id="language-pragma">
<title>LANGUAGE pragma</title>

<indexterm><primary>LANGUAGE</primary><secondary>pragma</secondary></indexterm>
<indexterm><primary>pragma</primary><secondary>LANGUAGE</secondary></indexterm>

<para>This allows language extensions to be enabled in a portable way.
It is the intention that all Haskell compilers support the
<literal>LANGUAGE</literal> pragma with the same syntax, although not
all extensions are supported by all compilers, of
course. The <literal>LANGUAGE</literal> pragma should be used instead
of <literal>OPTIONS_GHC</literal>, if possible.</para>

<para>For example, to enable the FFI and preprocessing with CPP:</para>

<programlisting>{-# LANGUAGE ForeignFunctionInterface, CPP #-}</programlisting>

<para>Any extension from the <literal>Extension</literal> type defined in
<ulink
url="../libraries/Cabal/Language-Haskell-Extension.html"><literal>Language.Haskell.Extension</literal></ulink> may be used. GHC will report an error if any of the requested extensions are not supported.</para>
</sect2>


<sect2 id="line-pragma">
<title>LINE pragma</title>

Expand All @@ -5571,22 +5607,6 @@ happen.
pragma.</para>
</sect2>

<sect2 id="options-pragma">
<title>OPTIONS_GHC pragma</title>
<indexterm><primary>OPTIONS_GHC</primary>
</indexterm>
<indexterm><primary>pragma</primary><secondary>OPTIONS_GHC</secondary>
</indexterm>

<para>The <literal>OPTIONS_GHC</literal> pragma is used to specify
additional options that are given to the compiler when compiling
this source file. See <xref linkend="source-file-options"/> for
details.</para>

<para>Previous versions of GHC accepted <literal>OPTIONS</literal> rather
than <literal>OPTIONS_GHC</literal>, but that is now deprecated.</para>
</sect2>

<sect2 id="rules">
<title>RULES pragma</title>

Expand Down

0 comments on commit 390b7c4

Please sign in to comment.