<?xml version="1.0" encoding="iso-8859-1"?>
- <sect1 id="options-phases">
- <title>Options related to a particular phase</title>
-
- <sect2 id="replacing-phases">
- <title>Replacing the program for one or more phases</title>
- <indexterm><primary>phases, changing</primary></indexterm>
-
- <para>You may specify that a different program be used for one
- of the phases of the compilation system, in place of whatever
- the <command>ghc</command> has wired into it. For example, you
- might want to try a different assembler. The following options
- allow you to change the external program used for a given
- compilation phase:</para>
-
- <variablelist>
- <varlistentry>
- <term>
- <option>-pgmL</option> <replaceable>cmd</replaceable>
- <indexterm><primary><option>-pgmL</option></primary></indexterm>
- </term>
- <listitem>
- <para>Use <replaceable>cmd</replaceable> as the literate
- pre-processor.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <option>-pgmP</option> <replaceable>cmd</replaceable>
- <indexterm><primary><option>-pgmP</option></primary></indexterm>
- </term>
- <listitem>
- <para>Use <replaceable>cmd</replaceable> as the C
- pre-processor (with <option>-cpp</option> only).</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <option>-pgmc</option> <replaceable>cmd</replaceable>
- <indexterm><primary><option>-pgmc</option></primary></indexterm>
- </term>
- <listitem>
- <para>Use <replaceable>cmd</replaceable> as the C
- compiler.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <option>-pgma</option> <replaceable>cmd</replaceable>
- <indexterm><primary><option>-pgma</option></primary></indexterm>
- </term>
- <listitem>
- <para>Use <replaceable>cmd</replaceable> as the
- assembler.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <option>-pgml</option> <replaceable>cmd</replaceable>
- <indexterm><primary><option>-pgml</option></primary></indexterm>
- </term>
- <listitem>
- <para>Use <replaceable>cmd</replaceable> as the
- linker.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <option>-pgmdll</option> <replaceable>cmd</replaceable>
- <indexterm><primary><option>-pgmdll</option></primary></indexterm>
- </term>
- <listitem>
- <para>Use <replaceable>cmd</replaceable> as the DLL
- generator.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <option>-pgmdep</option> <replaceable>cmd</replaceable>
- <indexterm><primary><option>-pgmdep</option></primary></indexterm>
- </term>
- <listitem>
- <para>Use <replaceable>cmd</replaceable> as the dependency
- generator.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <option>-pgmF</option> <replaceable>cmd</replaceable>
- <indexterm><primary><option>-pgmF</option></primary></indexterm>
- </term>
- <listitem>
- <para>Use <replaceable>cmd</replaceable> as the
- pre-processor (with <option>-F</option> only).</para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- </sect2>
-
- <sect2 id="forcing-options-through">
- <title>Forcing options to a particular phase</title>
- <indexterm><primary>forcing GHC-phase options</primary></indexterm>
-
- <para>Options can be forced through to a particlar compilation
- phase, using the following flags:</para>
-
- <variablelist>
- <varlistentry>
- <term>
- <option>-optL</option> <replaceable>option</replaceable>
- <indexterm><primary><option>-optL</option></primary></indexterm>
- </term>
- <listitem>
- <para>Pass <replaceable>option</replaceable> to the
- literate pre-processor</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <option>-optP</option> <replaceable>option</replaceable>
- <indexterm><primary><option>-optP</option></primary></indexterm>
- </term>
- <listitem>
- <para>Pass <replaceable>option</replaceable> to CPP (makes
- sense only if <option>-cpp</option> is also on).</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <option>-optF</option> <replaceable>option</replaceable>
- <indexterm><primary><option>-optF</option></primary></indexterm>
- </term>
- <listitem>
- <para>Pass <replaceable>option</replaceable> to the
- custom pre-processor (see <xref linkend="pre-processor"/>).</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <option>-optc</option> <replaceable>option</replaceable>
- <indexterm><primary><option>-optc</option></primary></indexterm>
- </term>
- <listitem>
- <para>Pass <replaceable>option</replaceable> to the C compiler.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <option>-opta</option> <replaceable>option</replaceable>
- <indexterm><primary><option>-opta</option></primary></indexterm>
- </term>
- <listitem>
- <para>Pass <replaceable>option</replaceable> to the assembler.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <option>-optl</option> <replaceable>option</replaceable>
- <indexterm><primary><option>-optl</option></primary></indexterm>
- </term>
- <listitem>
- <para>Pass <replaceable>option</replaceable> to the linker.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <option>-optdll</option> <replaceable>option</replaceable>
- <indexterm><primary><option>-optdll</option></primary></indexterm>
- </term>
- <listitem>
- <para>Pass <replaceable>option</replaceable> to the DLL generator.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <option>-optdep</option> <replaceable>option</replaceable>
- <indexterm><primary><option>-optdep</option></primary></indexterm>
- </term>
- <listitem>
- <para>Pass <replaceable>option</replaceable> to the
- dependency generator.</para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- <para>So, for example, to force an <option>-Ewurble</option>
- option to the assembler, you would tell the driver
- <option>-opta-Ewurble</option> (the dash before the E is
- required).</para>
-
- <para>GHC is itself a Haskell program, so if you need to pass
- options directly to GHC's runtime system you can enclose them in
- <literal>+RTS ... -RTS</literal> (see <xref
- linkend="runtime-control"/>).</para>
-
- </sect2>
-
- <sect2 id="c-pre-processor">
- <title>Options affecting the C pre-processor</title>
-
- <indexterm><primary>pre-processing: cpp</primary></indexterm>
- <indexterm><primary>C pre-processor options</primary></indexterm>
- <indexterm><primary>cpp, pre-processing with</primary></indexterm>
-
- <variablelist>
-
- <varlistentry>
- <term>
- <option>-cpp</option>
- <indexterm><primary><option>-cpp</option></primary></indexterm>
- </term>
- <listitem>
- <para>The C pre-processor <command>cpp</command> is run
- over your Haskell code only if the <option>-cpp</option>
- option <indexterm><primary>-cpp
- option</primary></indexterm> is given. Unless you are
- building a large system with significant doses of
- conditional compilation, you really shouldn't need
- it.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <option>-D</option><replaceable>symbol</replaceable><optional>=<replaceable>value</replaceable></optional>
- <indexterm><primary><option>-D</option></primary></indexterm>
- </term>
- <listitem>
- <para>Define macro <replaceable>symbol</replaceable> in the
- usual way. NB: does <emphasis>not</emphasis> affect
- <option>-D</option> macros passed to the C compiler
- when compiling via C! For those, use the
- <option>-optc-Dfoo</option> hack… (see <xref
- linkend="forcing-options-through"/>).</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <option>-U</option><replaceable>symbol</replaceable>
- <indexterm><primary><option>-U</option></primary></indexterm>
- </term>
- <listitem>
- <para> Undefine macro <replaceable>symbol</replaceable> in the
- usual way.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <option>-I</option><replaceable>dir</replaceable>
- <indexterm><primary><option>-I</option></primary></indexterm>
- </term>
- <listitem>
- <para> Specify a directory in which to look for
- <literal>#include</literal> files, in the usual C
- way.</para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- <para>The GHC driver pre-defines several macros when processing
- Haskell source code (<filename>.hs</filename> or
- <filename>.lhs</filename> files):</para>
-
- <variablelist>
-
- <varlistentry>
- <term>
- <constant>__HASKELL98__</constant>
- <indexterm><primary><literal>__HASKELL98__</literal></primary></indexterm>
- </term>
- <listitem>
- <para>If defined, this means that GHC supports the
- language defined by the Haskell 98 report.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <constant>__HASKELL__=98</constant>
- <indexterm><primary><constant>__HASKELL__=98</constant></primary></indexterm>
- </term>
- <listitem>
- <para>In GHC 4.04 and later, the
- <constant>__HASKELL__</constant>
- macro is defined as having the value
- <constant>98</constant>.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <constant>__HASKELL1__</constant>
- <indexterm><primary><constant>__HASKELL1__</constant></primary></indexterm>
- </term>
- <listitem>
- <para>If defined to <replaceable>n</replaceable>, that
- means GHC supports the Haskell language defined in the
- Haskell report version <emphasis>1.n</emphasis>.
- Currently 5. This macro is deprecated, and will probably
- disappear in future versions.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <constant>__GLASGOW_HASKELL__</constant>
- <indexterm><primary><constant>__GLASGOW_HASKELL__</constant></primary></indexterm>
- </term>
- <listitem>
- <para>For version <replaceable>n</replaceable> of the GHC
- system, this will be <literal>#define</literal>d to
- <replaceable>100n</replaceable>. For example, for version
- 5.00, it is 500.</para>
-
- <para>With any luck,
- <constant>__GLASGOW_HASKELL__</constant>
- will be undefined in all other implementations that
- support C-style pre-processing.</para>
-
- <para>(For reference: the comparable symbols for other
- systems are:
- <constant>__HUGS__</constant>
- for Hugs,
- <constant>__NHC__</constant>
- for nhc98, and
- <constant>__HBC__</constant>
- for Chalmers.)</para>
-
- <para>NB. This macro is set when pre-processing both
- Haskell source and C source, including the C source
- generated from a Haskell module
- (i.e. <filename>.hs</filename>, <filename>.lhs</filename>,
- <filename>.c</filename> and <filename>.hc</filename>
- files).</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <constant>__CONCURRENT_HASKELL__</constant>
- <indexterm><primary><constant>__CONCURRENT_HASKELL__</constant></primary></indexterm>
- </term>
- <listitem>
- <para>This symbol is defined when pre-processing Haskell
- (input) and pre-processing C (GHC output). Since GHC from
- verion 4.00 now supports concurrent haskell by default,
- this symbol is always defined.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <constant>__PARALLEL_HASKELL__</constant>
- <indexterm><primary><constant>__PARALLEL_HASKELL__</constant></primary></indexterm>
- </term>
- <listitem>
- <para>Only defined when <option>-parallel</option> is in
- use! This symbol is defined when pre-processing Haskell
- (input) and pre-processing C (GHC output).</para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- <sect3 id="cpp-string-gaps">
- <title>CPP and string gaps</title>
-
- <para>A small word of warning: <option>-cpp</option> is not
- friendly to “string gaps”.<indexterm><primary>-cpp
- vs string gaps</primary></indexterm><indexterm><primary>string
- gaps vs -cpp</primary></indexterm>. In other words, strings
- such as the following:</para>
-
-<programlisting>
-strmod = "\
-\ p \
-\ "
-</programlisting>
-
- <para>don't work with <option>-cpp</option>;
- <filename>/usr/bin/cpp</filename> elides the backslash-newline
- pairs.</para>
-
- <para>However, it appears that if you add a space at the end
- of the line, then <command>cpp</command> (at least GNU
- <command>cpp</command> and possibly other
- <command>cpp</command>s) leaves the backslash-space pairs
- alone and the string gap works as expected.</para>
- </sect3>
- </sect2>
-
- <sect2 id="pre-processor">
- <title>Options affecting a Haskell pre-processor</title>
-
- <indexterm><primary>pre-processing: custom</primary></indexterm>
- <indexterm><primary>Pre-processor options</primary></indexterm>
-
- <variablelist>
- <varlistentry>
- <term>
- <option>-F</option>
- <indexterm><primary><option>-F</option></primary></indexterm>
- </term>
- <listitem>
- <para>A custom pre-processor is run over your Haskell
- source file only if the <option>-F</option> option
- <indexterm><primary>-F</primary></indexterm> is
- given.</para>
-
- <para>Running a custom pre-processor at compile-time is in
- some settings appropriate and useful. The
- <option>-F</option> option lets you run a pre-processor as
- part of the overall GHC compilation pipeline, which has
- the advantage over running a Haskell pre-processor
- separately in that it works in interpreted mode and you
- can continue to take reap the benefits of GHC's
- recompilation checker.</para>
-
- <para>The pre-processor is run just before the Haskell
- compiler proper processes the Haskell input, but after the
- literate markup has been stripped away and (possibly) the
- C pre-processor has washed the Haskell input.</para>
-
- <para>Use
- <option>-pgmF <replaceable>cmd</replaceable></option>
- to select the program to use as the preprocessor. When
- invoked, the <replaceable>cmd</replaceable> pre-processor
- is given at least three arguments on its command-line: the
- first argument is the name of the original source file,
- the second is the name of the file holding the input, and
- the third is the name of the file where
- <replaceable>cmd</replaceable> should write its output
- to.</para>
-
- <para>Additional arguments to the pre-processor can be
- passed in using the <option>-optF</option> option. These
- are fed to <replaceable>cmd</replaceable> on the command
- line after the three standard input and output
- arguments.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </sect2>
-
- <sect2 id="options-C-compiler">
- <title>Options affecting the C compiler (if applicable)</title>
-
- <indexterm><primary>include-file options</primary></indexterm>
- <indexterm><primary>C compiler options</primary></indexterm>
- <indexterm><primary>GCC options</primary></indexterm>
-
- <para>If you are compiling with lots of foreign calls, you may
- need to tell the C compiler about some
- <literal>#include</literal> files. There is no real pretty
- way to do this, but you can use this hack from the
- command-line:</para>
+<sect1 id="options-phases">
+ <title>Options related to a particular phase</title>
+
+ <sect2 id="replacing-phases">
+ <title>Replacing the program for one or more phases</title>
+ <indexterm><primary>phases, changing</primary></indexterm>
+
+ <para>You may specify that a different program be used for one
+ of the phases of the compilation system, in place of whatever
+ the <command>ghc</command> has wired into it. For example, you
+ might want to try a different assembler. The following options
+ allow you to change the external program used for a given
+ compilation phase:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term>
+ <option>-pgmL</option> <replaceable>cmd</replaceable>
+ <indexterm><primary><option>-pgmL</option></primary></indexterm>
+ </term>
+ <listitem>
+ <para>Use <replaceable>cmd</replaceable> as the literate
+ pre-processor.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <option>-pgmP</option> <replaceable>cmd</replaceable>
+ <indexterm><primary><option>-pgmP</option></primary></indexterm>
+ </term>
+ <listitem>
+ <para>Use <replaceable>cmd</replaceable> as the C
+ pre-processor (with <option>-cpp</option> only).</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <option>-pgmc</option> <replaceable>cmd</replaceable>
+ <indexterm><primary><option>-pgmc</option></primary></indexterm>
+ </term>
+ <listitem>
+ <para>Use <replaceable>cmd</replaceable> as the C
+ compiler.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <option>-pgma</option> <replaceable>cmd</replaceable>
+ <indexterm><primary><option>-pgma</option></primary></indexterm>
+ </term>
+ <listitem>
+ <para>Use <replaceable>cmd</replaceable> as the
+ assembler.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <option>-pgml</option> <replaceable>cmd</replaceable>
+ <indexterm><primary><option>-pgml</option></primary></indexterm>
+ </term>
+ <listitem>
+ <para>Use <replaceable>cmd</replaceable> as the
+ linker.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <option>-pgmdll</option> <replaceable>cmd</replaceable>
+ <indexterm><primary><option>-pgmdll</option></primary></indexterm>
+ </term>
+ <listitem>
+ <para>Use <replaceable>cmd</replaceable> as the DLL
+ generator.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <option>-pgmdep</option> <replaceable>cmd</replaceable>
+ <indexterm><primary><option>-pgmdep</option></primary></indexterm>
+ </term>
+ <listitem>
+ <para>Use <replaceable>cmd</replaceable> as the dependency
+ generator.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <option>-pgmF</option> <replaceable>cmd</replaceable>
+ <indexterm><primary><option>-pgmF</option></primary></indexterm>
+ </term>
+ <listitem>
+ <para>Use <replaceable>cmd</replaceable> as the
+ pre-processor (with <option>-F</option> only).</para>
+ </listitem>
+ </varlistentry>
+
+
+ </variablelist>
+ </sect2>
+
+ <sect2 id="forcing-options-through">
+ <title>Forcing options to a particular phase</title>
+ <indexterm><primary>forcing GHC-phase options</primary></indexterm>
+
+ <para>Options can be forced through to a particlar compilation
+ phase, using the following flags:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term>
+ <option>-optL</option> <replaceable>option</replaceable>
+ <indexterm><primary><option>-optL</option></primary></indexterm>
+ </term>
+ <listitem>
+ <para>Pass <replaceable>option</replaceable> to the
+ literate pre-processor</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <option>-optP</option> <replaceable>option</replaceable>
+ <indexterm><primary><option>-optP</option></primary></indexterm>
+ </term>
+ <listitem>
+ <para>Pass <replaceable>option</replaceable> to CPP (makes
+ sense only if <option>-cpp</option> is also on).</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <option>-optF</option> <replaceable>option</replaceable>
+ <indexterm><primary><option>-optF</option></primary></indexterm>
+ </term>
+ <listitem>
+ <para>Pass <replaceable>option</replaceable> to the
+ custom pre-processor (see <xref linkend="pre-processor"/>).</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <option>-optc</option> <replaceable>option</replaceable>
+ <indexterm><primary><option>-optc</option></primary></indexterm>
+ </term>
+ <listitem>
+ <para>Pass <replaceable>option</replaceable> to the C compiler.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <option>-opta</option> <replaceable>option</replaceable>
+ <indexterm><primary><option>-opta</option></primary></indexterm>
+ </term>
+ <listitem>
+ <para>Pass <replaceable>option</replaceable> to the assembler.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <option>-optl</option> <replaceable>option</replaceable>
+ <indexterm><primary><option>-optl</option></primary></indexterm>
+ </term>
+ <listitem>
+ <para>Pass <replaceable>option</replaceable> to the linker.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <option>-optdll</option> <replaceable>option</replaceable>
+ <indexterm><primary><option>-optdll</option></primary></indexterm>
+ </term>
+ <listitem>
+ <para>Pass <replaceable>option</replaceable> to the DLL generator.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <option>-optdep</option> <replaceable>option</replaceable>
+ <indexterm><primary><option>-optdep</option></primary></indexterm>
+ </term>
+ <listitem>
+ <para>Pass <replaceable>option</replaceable> to the
+ dependency generator.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>So, for example, to force an <option>-Ewurble</option>
+ option to the assembler, you would tell the driver
+ <option>-opta-Ewurble</option> (the dash before the E is
+ required).</para>
+
+ <para>GHC is itself a Haskell program, so if you need to pass
+ options directly to GHC's runtime system you can enclose them in
+ <literal>+RTS ... -RTS</literal> (see <xref
+ linkend="runtime-control"/>).</para>
+
+ </sect2>
+
+ <sect2 id="c-pre-processor">
+ <title>Options affecting the C pre-processor</title>
+
+ <indexterm><primary>pre-processing: cpp</primary></indexterm>
+ <indexterm><primary>C pre-processor options</primary></indexterm>
+ <indexterm><primary>cpp, pre-processing with</primary></indexterm>
+
+ <variablelist>
+
+ <varlistentry>
+ <term>
+ <option>-cpp</option>
+ <indexterm><primary><option>-cpp</option></primary></indexterm>
+ </term>
+ <listitem>
+ <para>The C pre-processor <command>cpp</command> is run
+ over your Haskell code only if the <option>-cpp</option>
+ option <indexterm><primary>-cpp
+ option</primary></indexterm> is given. Unless you are
+ building a large system with significant doses of
+ conditional compilation, you really shouldn't need
+ it.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <option>-D</option><replaceable>symbol</replaceable><optional>=<replaceable>value</replaceable></optional>
+ <indexterm><primary><option>-D</option></primary></indexterm>
+ </term>
+ <listitem>
+ <para>Define macro <replaceable>symbol</replaceable> in the
+ usual way. NB: does <emphasis>not</emphasis> affect
+ <option>-D</option> macros passed to the C compiler
+ when compiling via C! For those, use the
+ <option>-optc-Dfoo</option> hack… (see <xref
+ linkend="forcing-options-through"/>).</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <option>-U</option><replaceable>symbol</replaceable>
+ <indexterm><primary><option>-U</option></primary></indexterm>
+ </term>
+ <listitem>
+ <para> Undefine macro <replaceable>symbol</replaceable> in the
+ usual way.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <option>-I</option><replaceable>dir</replaceable>
+ <indexterm><primary><option>-I</option></primary></indexterm>
+ </term>
+ <listitem>
+ <para> Specify a directory in which to look for
+ <literal>#include</literal> files, in the usual C
+ way.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>The GHC driver pre-defines several macros when processing
+ Haskell source code (<filename>.hs</filename> or
+ <filename>.lhs</filename> files).</para>
+
+ <para>The symbols defined by GHC are listed below. To check which
+ symbols are defined by your local GHC installation, the following
+ trick is useful:</para>
<screen>
-% ghc -c '-#include <X/Xlib.h>' Xstuff.lhs
+ $ ghc -E -optP-dM -cpp foo.hs
+ $ cat foo.hspp
</screen>
- </sect2>
-
- <sect2 id="options-codegen">
- <title>Options affecting code generation</title>
-
- <variablelist>
- <varlistentry>
- <term>
- <option>-fasm</option>
- <indexterm><primary><option>-fasm</option></primary></indexterm>
- </term>
- <listitem>
- <para>Use GHC's native code generator rather than
- compiling via C. This will compile faster (up to twice as
- fast), but may produce code that is slightly slower than
- compiling via C. <option>-fasm</option> is the default
- when optimisation is off (see <xref
- linkend="options-optimise"/>).</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <option>-fvia-C</option>
- <indexterm><primary><option>-fvia-C</option></primary></indexterm>
- </term>
- <listitem>
- <para>Compile via C instead of using the native code
- generator. This is default for optimised compilations,
- and on architectures for which GHC doesn't have a native
- code generator.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <option>-fno-code</option>
- <indexterm><primary><option>-fno-code</option></primary></indexterm>
- </term>
- <listitem>
- <para>Omit code generation (and all later phases)
- altogether. Might be of some use if you just want to see
- dumps of the intermediate compilation phases.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </sect2>
-
- <sect2 id="options-linker">
- <title>Options affecting linking</title>
-
- <indexterm><primary>linker options</primary></indexterm>
- <indexterm><primary>ld options</primary></indexterm>
-
-
- <para>GHC has to link your code with various libraries, possibly
- including: user-supplied, GHC-supplied, and system-supplied
- (<option>-lm</option> math library, for example).</para>
-
- <variablelist>
-
- <varlistentry>
- <term>
- <option>-l</option><replaceable>lib</replaceable>
- <indexterm><primary><option>-l</option></primary></indexterm>
- </term>
- <listitem>
- <para>Link in the <replaceable>lib</replaceable> library.
- On Unix systems, this will be in a file called
- <filename>lib<replaceable>lib</replaceable>.a</filename>
- or
- <filename>lib<replaceable>lib</replaceable>.so</filename>
- which resides somewhere on the library directories path.</para>
-
- <para>Because of the sad state of most UNIX linkers, the
- order of such options does matter. If library
- <replaceable>foo</replaceable> requires library
- <replaceable>bar</replaceable>, then in general
- <option>-l</option><replaceable>foo</replaceable> should
- come <emphasis>before</emphasis>
- <option>-l</option><replaceable>bar</replaceable> on the
- command line.</para>
-
- <para>There's one other gotcha to bear in mind when using
- external libraries: if the library contains a
- <literal>main()</literal> function, then this will be
- linked in preference to GHC's own
- <literal>main()</literal> function
- (eg. <literal>libf2c</literal> and <literal>libl</literal>
- have their own <literal>main()</literal>s). This is
- because GHC's <literal>main()</literal> comes from the
- <literal>HSrts</literal> library, which is normally
- included <emphasis>after</emphasis> all the other
- libraries on the linker's command line. To force GHC's
- <literal>main()</literal> to be used in preference to any
- other <literal>main()</literal>s from external libraries,
- just add the option <option>-lHSrts</option> before any
- other libraries on the command line.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <option>-no-link</option>
- <indexterm><primary><option>-no-link</option></primary></indexterm>
- </term>
- <listitem>
- <para>Omit the link step. This flag can be useful if you
- want to avoid linking in <option>--make</option> mode,
- where linking is normally done automatically if the program
- contains a <literal>Main</literal> module.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <option>-package</option> <replaceable>name</replaceable>
- <indexterm><primary><option>-package</option></primary></indexterm>
- </term>
- <listitem>
- <para>If you are using a Haskell “package”
- (see <xref linkend="packages"/>), don't forget to add the
- relevant <option>-package</option> option when linking the
- program too: it will cause the appropriate libraries to be
- linked in with the program. Forgetting the
- <option>-package</option> option will likely result in
- several pages of link errors.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <option>-framework</option> <replaceable>name</replaceable>
- <indexterm><primary><option>-framework</option></primary></indexterm>
- </term>
- <listitem>
- <para>On Darwin/MacOS X only, link in the framework <replaceable>name</replaceable>.
- This option corresponds to the <option>-framework</option> option for Apple's Linker.
- Please note that frameworks and packages are two different things - frameworks don't
- contain any haskell code. Rather, they are Apple's way of packaging shared libraries.
- To link to Apple's “Carbon” API, for example, you'd use
- <option>-framework Carbon</option>.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <option>-L</option><replaceable>dir</replaceable>
- <indexterm><primary><option>-L</option></primary></indexterm>
- </term>
- <listitem>
- <para>Where to find user-supplied libraries…
- Prepend the directory <replaceable>dir</replaceable> to
- the library directories path.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <option>-framework-path</option><replaceable>dir</replaceable>
- <indexterm><primary><option>-framework-path</option></primary></indexterm>
- </term>
- <listitem>
- <para>On Darwin/MacOS X only, prepend the directory <replaceable>dir</replaceable> to
- the framework directories path. This option corresponds to the <option>-F</option>
- option for Apple's Linker (<option>-F</option> already means something else for GHC).</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <option>-split-objs</option>
- <indexterm><primary><option>-split-objs</option></primary></indexterm>
- </term>
- <listitem>
- <para>Tell the linker to split the single object file that
- would normally be generated into multiple object files,
- one per top-level Haskell function or type in the module.
- We use this feature for building GHC's libraries libraries
- (warning: don't use it unless you know what you're
- doing!).</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <option>-static</option>
- <indexterm><primary><option>-static</option></primary></indexterm>
- </term>
- <listitem>
- <para>Tell the linker to avoid shared Haskell libraries,
- if possible. This is the default.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <option>-dynamic</option>
- <indexterm><primary><option>-dynamic</option></primary></indexterm>
- </term>
- <listitem>
- <para>Tell the linker to use shared Haskell libraries, if
- available (this option is only supported on Windows at the
- moment, and also note that your distribution of GHC may
- not have been supplied with shared libraries).</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <option>-main-is <replaceable>thing</replaceable></option>
- <indexterm><primary><option>-main-is</option></primary></indexterm>
- <indexterm><primary>specifying your own main function</primary></indexterm>
- </term>
- <listitem>
- <para> The normal rule in Haskell is that your program must supply a <literal>main</literal>
- function in module <literal>Main</literal>. When testing, it is often convenient
- to change which function is the "main" one, and the <option>-main-is</option> flag
- allows you to do so. The <replaceable>thing</replaceable> can be one of:
- <itemizedlist>
- <listitem><para>A lower-case identifier <literal>foo</literal>. GHC assumes that the main function is <literal>Main.foo</literal>.</para></listitem>
- <listitem><para>An module name <literal>A</literal>. GHC assumes that the main function is <literal>A.main</literal>.</para></listitem>
- <listitem><para>An qualified name <literal>A.foo</literal>. GHC assumes that the main function is <literal>A.foo</literal>.</para></listitem>
- </itemizedlist>
- Strictly speaking, <option>-main-is</option> is not a link-phase flag at all; it has no effect on the link step.
- The flag must be specified when compiling the module containing the specified main function (e.g. module <literal>A</literal>
- in the latter two items above. It has no effect for other modules (and hence can safely be given to <literal>ghc --make</literal>).
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <option>-no-hs-main</option>
- <indexterm><primary><option>-no-hs-main</option></primary></indexterm>
- <indexterm><primary>linking Haskell libraries with foreign code</primary></indexterm>
- </term>
- <listitem>
- <para>In the event you want to include ghc-compiled code
- as part of another (non-Haskell) program, the RTS will not
- be supplying its definition of <function>main()</function>
- at link-time, you will have to. To signal that to the
- compiler when linking, use
- <option>-no-hs-main</option>. See also <xref linkend="using-own-main"/>.</para>
-
- <para>Notice that since the command-line passed to the
- linker is rather involved, you probably want to use
- <command>ghc</command> to do the final link of your
- `mixed-language' application. This is not a requirement
- though, just try linking once with <option>-v</option> on
- to see what options the driver passes through to the
- linker.</para>
-
- <para>The <option>-no-hs-main</option> flag can also be
- used to persuade the compiler to do the link step in
- <option>--make</option> mode when there is no Haskell
- <literal>Main</literal> module present (normally the
- compiler will not attempt linking when there is no
- <literal>Main</literal>).</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <option>-debug</option>
- <indexterm><primary><option>-debug</option></primary></indexterm>
- </term>
- <listitem>
- <para>Link the program with a debugging version of the
- runtime system. The debugging runtime turns on numerous
- assertions and sanity checks, and provides extra options
- for producing debugging output at runtime (run the program
- with <literal>+RTS -?</literal> to see a list).</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <option>-threaded</option>
- <indexterm><primary><option>-threaded</option></primary></indexterm>
- </term>
- <listitem>
- <para>Link the program with the "threaded" runtime system.
- This version of the runtime is designed to be used in
- programs that use multiple operating-system threads. It
- supports calls to foreign-exported functions from multiple
- OS threads. Calls to foreign functions are made using the
- same OS thread that created the Haskell thread (if it was
- created by a call-in), or an arbitrary OS thread otherwise
- (if the Haskell thread was created by
- <literal>forkIO</literal>).</para>
-
- <para>More details on the use of "bound threads" in the
- threaded runtime can be found in the <ulink
- url="../libraries/base/Control.Concurrent.html"><literal>Control.Concurrent</literal></ulink> module.</para>
-
- <para>The threaded RTS does <emphasis>not</emphasis>
- support using multiple CPUs to speed up execution of a
- multi-threaded Haskell program. The GHC runtime platform
- is still single-threaded, but using the
- <option>-threaded</option> option it can be used safely in
- a multi-threaded environment.</para>
- </listitem>
- </varlistentry>
-
- </variablelist>
- </sect2>
-
- </sect1>
+ <para>(you need a file <filename>foo.hs</filename>, but it isn't
+ actually used).</para>
+
+ <variablelist>
+ <varlistentry>
+ <term>
+ <constant>__HASKELL98__</constant>
+ <indexterm><primary><literal>__HASKELL98__</literal></primary></indexterm>
+ </term>
+ <listitem>
+ <para>If defined, this means that GHC supports the
+ language defined by the Haskell 98 report.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <constant>__HASKELL__=98</constant>
+ <indexterm><primary><constant>__HASKELL__=98</constant></primary></indexterm>
+ </term>
+ <listitem>
+ <para>In GHC 4.04 and later, the
+ <constant>__HASKELL__</constant>
+ macro is defined as having the value
+ <constant>98</constant>.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <constant>__HASKELL1__</constant>
+ <indexterm><primary><constant>__HASKELL1__</constant></primary></indexterm>
+ </term>
+ <listitem>
+ <para>If defined to <replaceable>n</replaceable>, that
+ means GHC supports the Haskell language defined in the
+ Haskell report version <emphasis>1.n</emphasis>.
+ Currently 5. This macro is deprecated, and will probably
+ disappear in future versions.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <constant>__GLASGOW_HASKELL__</constant>
+ <indexterm><primary><constant>__GLASGOW_HASKELL__</constant></primary></indexterm>
+ </term>
+ <listitem>
+ <para>For version
+ <literal><replaceable>x</replaceable>.<replaceable>y</replaceable>.<replaceable>z</replaceable></literal>
+ of GHC, the value of
+ <constant>__GLASGOW_HASKELL__</constant>
+ is the integer <replaceable>xyy</replaceable> (if
+ <replaceable>y</replaceable> is a single digit, then a leading zero
+ is added, so for example in version 6.2 of GHC,
+ <literal>__GLASGOW_HASKELL__==602</literal>). More
+ information in <xref linkend="version-numbering"/>.</para>
+
+ <para>With any luck,
+ <constant>__GLASGOW_HASKELL__</constant>
+ will be undefined in all other implementations that
+ support C-style pre-processing.</para>
+
+ <para>(For reference: the comparable symbols for other
+ systems are:
+ <constant>__HUGS__</constant>
+ for Hugs,
+ <constant>__NHC__</constant>
+ for nhc98, and
+ <constant>__HBC__</constant>
+ for hbc.)</para>
+
+ <para>NB. This macro is set when pre-processing both
+ Haskell source and C source, including the C source
+ generated from a Haskell module
+ (i.e. <filename>.hs</filename>, <filename>.lhs</filename>,
+ <filename>.c</filename> and <filename>.hc</filename>
+ files).</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <constant>__CONCURRENT_HASKELL__</constant>
+ <indexterm><primary><constant>__CONCURRENT_HASKELL__</constant></primary></indexterm>
+ </term>
+ <listitem>
+ <para>This symbol is defined when pre-processing Haskell
+ (input) and pre-processing C (GHC output). Since GHC from
+ verion 4.00 now supports concurrent haskell by default,
+ this symbol is always defined.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <constant>__PARALLEL_HASKELL__</constant>
+ <indexterm><primary><constant>__PARALLEL_HASKELL__</constant></primary></indexterm>
+ </term>
+ <listitem>
+ <para>Only defined when <option>-parallel</option> is in
+ use! This symbol is defined when pre-processing Haskell
+ (input) and pre-processing C (GHC output).</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <constant><replaceable>os</replaceable>_TARGET_OS=1</constant>
+ </term>
+ <listitem>
+ <para>This define allows conditional compilation based on
+ the Operating System, where<replaceable>os</replaceable> is
+ the name of the current Operating System
+ (eg. <literal>linux</literal>, <literal>mingw32</literal>
+ for Windows, <literal>solaris</literal>, etc.).</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <constant><replaceable>arch</replaceable>_TARGET_ARCH=1</constant>
+ </term>
+ <listitem>
+ <para>This define allows conditional compilation based on
+ the host architecture, where<replaceable>arch</replaceable>
+ is the name of the current architecture
+ (eg. <literal>i386</literal>, <literal>x86_64</literal>,
+ <literal>powerpc</literal>, <literal>sparc</literal>,
+ etc.).</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <sect3 id="cpp-string-gaps">
+ <title>CPP and string gaps</title>
+
+ <para>A small word of warning: <option>-cpp</option> is not
+ friendly to “string gaps”.<indexterm><primary>-cpp
+ vs string gaps</primary></indexterm><indexterm><primary>string
+ gaps vs -cpp</primary></indexterm>. In other words, strings
+ such as the following:</para>
+
+rogramlisting>
+rmod = "\
+p \
+"
+programlisting>
+
+ <para>don't work with <option>-cpp</option>;
+ <filename>/usr/bin/cpp</filename> elides the backslash-newline
+ pairs.</para>
+
+ <para>However, it appears that if you add a space at the end
+ of the line, then <command>cpp</command> (at least GNU
+ <command>cpp</command> and possibly other
+ <command>cpp</command>s) leaves the backslash-space pairs
+ alone and the string gap works as expected.</para>
+ </sect3>
+ </sect2>
+
+ <sect2 id="pre-processor">
+ <title>Options affecting a Haskell pre-processor</title>
+
+ <indexterm><primary>pre-processing: custom</primary></indexterm>
+ <indexterm><primary>Pre-processor options</primary></indexterm>
+
+ <variablelist>
+ <varlistentry>
+ <term>
+ <option>-F</option>
+ <indexterm><primary><option>-F</option></primary></indexterm>
+ </term>
+ <listitem>
+ <para>A custom pre-processor is run over your Haskell
+ source file only if the <option>-F</option> option
+ <indexterm><primary>-F</primary></indexterm> is
+ given.</para>
+
+ <para>Running a custom pre-processor at compile-time is in
+ some settings appropriate and useful. The
+ <option>-F</option> option lets you run a pre-processor as
+ part of the overall GHC compilation pipeline, which has
+ the advantage over running a Haskell pre-processor
+ separately in that it works in interpreted mode and you
+ can continue to take reap the benefits of GHC's
+ recompilation checker.</para>
+
+ <para>The pre-processor is run just before the Haskell
+ compiler proper processes the Haskell input, but after the
+ literate markup has been stripped away and (possibly) the
+ C pre-processor has washed the Haskell input.</para>
+
+ <para>Use
+ <option>-pgmF <replaceable>cmd</replaceable></option>
+ to select the program to use as the preprocessor. When
+ invoked, the <replaceable>cmd</replaceable> pre-processor
+ is given at least three arguments on its command-line: the
+ first argument is the name of the original source file,
+ the second is the name of the file holding the input, and
+ the third is the name of the file where
+ <replaceable>cmd</replaceable> should write its output
+ to.</para>
+
+ <para>Additional arguments to the pre-processor can be
+ passed in using the <option>-optF</option> option. These
+ are fed to <replaceable>cmd</replaceable> on the command
+ line after the three standard input and output
+ arguments.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </sect2>
+
+ <sect2 id="options-C-compiler">
+ <title>Options affecting the C compiler (if applicable)</title>
+
+ <indexterm><primary>include-file options</primary></indexterm>
+ <indexterm><primary>C compiler options</primary></indexterm>
+ <indexterm><primary>GCC options</primary></indexterm>
+
+ <para>If you are compiling with lots of foreign calls, you may
+ need to tell the C compiler about some
+ <literal>#include</literal> files. There is no real pretty
+ way to do this, but you can use this hack from the
+ command-line:</para>
+
+creen>
+ghc -c '-#include <X/Xlib.h>' Xstuff.lhs
+screen>
+
+ </sect2>
+
+ <sect2 id="options-codegen">
+ <title>Options affecting code generation</title>
+
+ <variablelist>
+ <varlistentry>
+ <term>
+ <option>-fasm</option>
+ <indexterm><primary><option>-fasm</option></primary></indexterm>
+ </term>
+ <listitem>
+ <para>Use GHC's native code generator rather than
+ compiling via C. This will compile faster (up to twice as
+ fast), but may produce code that is slightly slower than
+ compiling via C. <option>-fasm</option> is the default
+ when optimisation is off (see <xref
+ linkend="options-optimise"/>).</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <option>-fvia-C</option>
+ <indexterm><primary><option>-fvia-C</option></primary></indexterm>
+ </term>
+ <listitem>
+ <para>Compile via C instead of using the native code
+ generator. This is default for optimised compilations,
+ and on architectures for which GHC doesn't have a native
+ code generator.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <option>-fno-code</option>
+ <indexterm><primary><option>-fno-code</option></primary></indexterm>
+ </term>
+ <listitem>
+ <para>Omit code generation (and all later phases)
+ altogether. Might be of some use if you just want to see
+ dumps of the intermediate compilation phases.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </sect2>
+
+ <sect2 id="options-linker">
+ <title>Options affecting linking</title>
+
+ <indexterm><primary>linker options</primary></indexterm>
+ <indexterm><primary>ld options</primary></indexterm>
+
+
+ <para>GHC has to link your code with various libraries, possibly
+ including: user-supplied, GHC-supplied, and system-supplied
+ (<option>-lm</option> math library, for example).</para>
+
+ <variablelist>
+
+ <varlistentry>
+ <term>
+ <option>-l</option><replaceable>lib</replaceable>
+ <indexterm><primary><option>-l</option></primary></indexterm>
+ </term>
+ <listitem>
+ <para>Link in the <replaceable>lib</replaceable> library.
+ On Unix systems, this will be in a file called
+ <filename>lib<replaceable>lib</replaceable>.a</filename>
+ or
+ <filename>lib<replaceable>lib</replaceable>.so</filename>
+ which resides somewhere on the library directories path.</para>
+
+ <para>Because of the sad state of most UNIX linkers, the
+ order of such options does matter. If library
+ <replaceable>foo</replaceable> requires library
+ <replaceable>bar</replaceable>, then in general
+ <option>-l</option><replaceable>foo</replaceable> should
+ come <emphasis>before</emphasis>
+ <option>-l</option><replaceable>bar</replaceable> on the
+ command line.</para>
+
+ <para>There's one other gotcha to bear in mind when using
+ external libraries: if the library contains a
+ <literal>main()</literal> function, then this will be
+ linked in preference to GHC's own
+ <literal>main()</literal> function
+ (eg. <literal>libf2c</literal> and <literal>libl</literal>
+ have their own <literal>main()</literal>s). This is
+ because GHC's <literal>main()</literal> comes from the
+ <literal>HSrts</literal> library, which is normally
+ included <emphasis>after</emphasis> all the other
+ libraries on the linker's command line. To force GHC's
+ <literal>main()</literal> to be used in preference to any
+ other <literal>main()</literal>s from external libraries,
+ just add the option <option>-lHSrts</option> before any
+ other libraries on the command line.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <option>-no-link</option>
+ <indexterm><primary><option>-no-link</option></primary></indexterm>
+ </term>
+ <listitem>
+ <para>Omit the link step. This flag can be useful if you
+ want to avoid linking in <option>--make</option> mode,
+ where linking is normally done automatically if the program
+ contains a <literal>Main</literal> module.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <option>-package</option> <replaceable>name</replaceable>
+ <indexterm><primary><option>-package</option></primary></indexterm>
+ </term>
+ <listitem>
+ <para>If you are using a Haskell “package”
+ (see <xref linkend="packages"/>), don't forget to add the
+ relevant <option>-package</option> option when linking the
+ program too: it will cause the appropriate libraries to be
+ linked in with the program. Forgetting the
+ <option>-package</option> option will likely result in
+ several pages of link errors.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <option>-framework</option> <replaceable>name</replaceable>
+ <indexterm><primary><option>-framework</option></primary></indexterm>
+ </term>
+ <listitem>
+ <para>On Darwin/MacOS X only, link in the framework <replaceable>name</replaceable>.
+ This option corresponds to the <option>-framework</option> option for Apple's Linker.
+ Please note that frameworks and packages are two different things - frameworks don't
+ contain any haskell code. Rather, they are Apple's way of packaging shared libraries.
+ To link to Apple's “Carbon” API, for example, you'd use
+ <option>-framework Carbon</option>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <option>-L</option><replaceable>dir</replaceable>
+ <indexterm><primary><option>-L</option></primary></indexterm>
+ </term>
+ <listitem>
+ <para>Where to find user-supplied libraries…
+ Prepend the directory <replaceable>dir</replaceable> to
+ the library directories path.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <option>-framework-path</option><replaceable>dir</replaceable>
+ <indexterm><primary><option>-framework-path</option></primary></indexterm>
+ </term>
+ <listitem>
+ <para>On Darwin/MacOS X only, prepend the directory <replaceable>dir</replaceable> to
+ the framework directories path. This option corresponds to the <option>-F</option>
+ option for Apple's Linker (<option>-F</option> already means something else for GHC).</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <option>-split-objs</option>
+ <indexterm><primary><option>-split-objs</option></primary></indexterm>
+ </term>
+ <listitem>
+ <para>Tell the linker to split the single object file that
+ would normally be generated into multiple object files,
+ one per top-level Haskell function or type in the module.
+ We use this feature for building GHC's libraries libraries
+ (warning: don't use it unless you know what you're
+ doing!).</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <option>-static</option>
+ <indexterm><primary><option>-static</option></primary></indexterm>
+ </term>
+ <listitem>
+ <para>Tell the linker to avoid shared Haskell libraries,
+ if possible. This is the default.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <option>-dynamic</option>
+ <indexterm><primary><option>-dynamic</option></primary></indexterm>
+ </term>
+ <listitem>
+ <para>Tell the linker to use shared Haskell libraries, if
+ available (this option is only supported on Windows at the
+ moment, and also note that your distribution of GHC may
+ not have been supplied with shared libraries).</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <option>-main-is <replaceable>thing</replaceable></option>
+ <indexterm><primary><option>-main-is</option></primary></indexterm>
+ <indexterm><primary>specifying your own main function</primary></indexterm>
+ </term>
+ <listitem>
+ <para> The normal rule in Haskell is that your program must supply a <literal>main</literal>
+ function in module <literal>Main</literal>. When testing, it is often convenient
+ to change which function is the "main" one, and the <option>-main-is</option> flag
+ allows you to do so. The <replaceable>thing</replaceable> can be one of:
+ <itemizedlist>
+ <listitem><para>A lower-case identifier <literal>foo</literal>. GHC assumes that the main function is <literal>Main.foo</literal>.</para></listitem>
+ <listitem><para>An module name <literal>A</literal>. GHC assumes that the main function is <literal>A.main</literal>.</para></listitem>
+ <listitem><para>An qualified name <literal>A.foo</literal>. GHC assumes that the main function is <literal>A.foo</literal>.</para></listitem>
+ </itemizedlist>
+ Strictly speaking, <option>-main-is</option> is not a link-phase flag at all; it has no effect on the link step.
+ The flag must be specified when compiling the module containing the specified main function (e.g. module <literal>A</literal>
+ in the latter two items above. It has no effect for other modules (and hence can safely be given to <literal>ghc --make</literal>).
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <option>-no-hs-main</option>
+ <indexterm><primary><option>-no-hs-main</option></primary></indexterm>
+ <indexterm><primary>linking Haskell libraries with foreign code</primary></indexterm>
+ </term>
+ <listitem>
+ <para>In the event you want to include ghc-compiled code
+ as part of another (non-Haskell) program, the RTS will not
+ be supplying its definition of <function>main()</function>
+ at link-time, you will have to. To signal that to the
+ compiler when linking, use
+ <option>-no-hs-main</option>. See also <xref linkend="using-own-main"/>.</para>
+
+ <para>Notice that since the command-line passed to the
+ linker is rather involved, you probably want to use
+ <command>ghc</command> to do the final link of your
+ `mixed-language' application. This is not a requirement
+ though, just try linking once with <option>-v</option> on
+ to see what options the driver passes through to the
+ linker.</para>
+
+ <para>The <option>-no-hs-main</option> flag can also be
+ used to persuade the compiler to do the link step in
+ <option>--make</option> mode when there is no Haskell
+ <literal>Main</literal> module present (normally the
+ compiler will not attempt linking when there is no
+ <literal>Main</literal>).</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <option>-debug</option>
+ <indexterm><primary><option>-debug</option></primary></indexterm>
+ </term>
+ <listitem>
+ <para>Link the program with a debugging version of the
+ runtime system. The debugging runtime turns on numerous
+ assertions and sanity checks, and provides extra options
+ for producing debugging output at runtime (run the program
+ with <literal>+RTS -?</literal> to see a list).</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <option>-threaded</option>
+ <indexterm><primary><option>-threaded</option></primary></indexterm>
+ </term>
+ <listitem>
+ <para>Link the program with the "threaded" runtime system.
+ This version of the runtime is designed to be used in
+ programs that use multiple operating-system threads. It
+ supports calls to foreign-exported functions from multiple
+ OS threads. Calls to foreign functions are made using the
+ same OS thread that created the Haskell thread (if it was
+ created by a call-in), or an arbitrary OS thread otherwise
+ (if the Haskell thread was created by
+ <literal>forkIO</literal>).</para>
+
+ <para>More details on the use of "bound threads" in the
+ threaded runtime can be found in the <ulink
+ url="../libraries/base/Control.Concurrent.html"><literal>Control.Concurrent</literal></ulink> module.</para>
+
+ <para>The threaded RTS does <emphasis>not</emphasis>
+ support using multiple CPUs to speed up execution of a
+ multi-threaded Haskell program. The GHC runtime platform
+ is still single-threaded, but using the
+ <option>-threaded</option> option it can be used safely in
+ a multi-threaded environment.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </sect2>
+
+</sect1>
<!-- Emacs stuff:
;;; Local Variables: ***
;;; mode: xml ***
- ;;; sgml-parent-document: ("users_guide.xml" "book" "chapter") ***
+ ;;; sgml-parent-document: ("users_guide.xml" "book" "chapter" "sect1") ***
;;; End: ***
-->
projects / ghc-hetmet.git / commitdiff