<title>Options related to a particular phase</title>
<sect2 id="replacing-phases">
- <title>Replacing the program for one or more phases.</title>
+ <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
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 phases:</para>
+ compilation phase:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term><option>-pgmL</option> <replaceable>cmd</replaceable></term>
+ <indexterm><primary><option>-pgmL</option></primary>
+ </indexterm>
+ <listitem>
+ <para>Use <replaceable>cmd</replaceable> as the literate
+ pre-processor.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-pgmP</option> <replaceable>cmd</replaceable></term>
+ <indexterm><primary><option>-pgmP</option></primary>
+ </indexterm>
+ <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></term>
+ <indexterm><primary><option>-pgmc</option></primary>
+ </indexterm>
+ <listitem>
+ <para>Use <replaceable>cmd</replaceable> as the C
+ compiler.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-pgma</option> <replaceable>cmd</replaceable></term>
+ <indexterm><primary><option>-pgma</option></primary>
+ </indexterm>
+ <listitem>
+ <para>Use <replaceable>cmd</replaceable> as the
+ assembler.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-pgml</option> <replaceable>cmd</replaceable></term>
+ <indexterm><primary><option>-pgml</option></primary>
+ </indexterm>
+ <listitem>
+ <para>Use <replaceable>cmd</replaceable> as the
+ linker.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-pgmdll</option> <replaceable>cmd</replaceable></term>
+ <indexterm><primary><option>-pgmdll</option></primary>
+ </indexterm>
+ <listitem>
+ <para>Use <replaceable>cmd</replaceable> as the DLL
+ generator.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-pgmdep</option> <replaceable>cmd</replaceable></term>
+ <indexterm><primary><option>-pgmdep</option></primary>
+ </indexterm>
+ <listitem>
+ <para>Use <replaceable>cmd</replaceable> as the dependency
+ generator.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-pgmF</option> <replaceable>cmd</replaceable></term>
+ <indexterm><primary><option>-pgmF</option></primary>
+ </indexterm>
+ <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>
+ <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
<indexterm><primary>C pre-processor options</primary></indexterm>
<indexterm><primary>cpp, pre-processing with</primary></indexterm>
- <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>
-
<variablelist>
<varlistentry>
+ <term><option>-cpp</option></term>
+ <indexterm><primary><option>-cpp</option></primary></indexterm>
+ <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></term>
<indexterm><primary><option>-D</option></primary></indexterm>
<listitem>
<para>(For reference: the comparable symbols for other
systems are:
<constant>__HUGS__</constant>
- for Hugs and
+ for Hugs,
+ <constant>__NHC__</constant>
+ for nhc98, and
<constant>__HBC__</constant>
for Chalmers.)</para>
</varlistentry>
</variablelist>
- <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>
+ <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>
- <para>don't work with <option>-cpp</option>;
- <filename>/usr/bin/cpp</filename> elides the backslash-newline
- pairs.</para>
+ <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>
- <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>
+ <variablelist>
+ <varlistentry>
+ <term><option>-F</option></term>
+ <indexterm><primary><option>-F</option></primary></indexterm>
+ <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>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-pgmF</option> <replaceable>cmd</replaceable></term>
+ <indexterm><primary><option>-pgmF</option> <replaceable>cmd</replaceable></primary></indexterm>
+ <listitem>
+ <para>Use <replaceable>cmd</replaceable> as the Haskell
+ pre-processor. 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
+ <replaceable>cmd</replaceable> 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">
<indexterm><primary>C compiler options</primary></indexterm>
<indexterm><primary>GCC options</primary></indexterm>
- <informaltable>
- <tgroup cols=3 align=left colsep=1 rowsep=1>
- <thead>
- <row>
- <entry>Flag</entry>
- <entry>Description</entry>
- <entry>Static/Dynamic</entry>
- <entry>Reverse</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry><option>-#include</option> <replaceable>file</replaceable></entry>
- <entry>Include <replaceable>file</replaceable> when
- compiling the <filename>.hc</filename> file</entry>
- <entry>dynamic</entry>
- <entry>-</entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
-
<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
</sect2>
+ <sect2 id="options-codegen">
+ <title>Options affecting code generation</title>
+
+ <variablelist>
+ <varlistentry>
+ <term><option>-fasm</option></term>
+ <indexterm><primary><option>-fasm</option></primary></indexterm>
+ <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></term>
+ <indexterm><primary><option>-fvia-C</option></primary>
+ </indexterm>
+ <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></term>
+ <indexterm><primary><option>-fno-code</option></primary>
+ </indexterm>
+ <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>
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>
<varlistentry>
+ <term><option>-framework</option> <replaceable>name</replaceable></term>
+ <indexterm><primary><option>-framework</option></primary></indexterm>
+ <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></term>
<indexterm><primary><option>-L</option></primary></indexterm>
<listitem>
</varlistentry>
<varlistentry>
+ <term><option>-framework-path</option><replaceable>dir</replaceable></term>
+ <indexterm><primary><option>-framework-path</option></primary></indexterm>
+ <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></term>
<indexterm><primary><option>-split-objs</option></primary></indexterm>
<listitem>