  <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></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>
      <indexterm><primary>forcing GHC-phase options</primary></indexterm>

      <para>Options can be forced through to a particlar compilation
      phase, using the following flags:</para>


      <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></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>Define macro <replaceable>symbol</replaceable> in the
            usual way.  NB: does <emphasis>not</emphasis> affect
            <option>-D</option> macros passed to the C&nbsp;compiler
            when compiling via C!  For those, use the
            <option>-optc-Dfoo</option> hack&hellip; (see <xref
            linkend="forcing-options-through">).</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><option>-U</option><replaceable>symbol</replaceable></term>
	  <indexterm><primary><option>-U</option></primary></indexterm>
	  <listitem>
	    <para> Undefine macro <replaceable>symbol</replaceable> in the
	    usual way.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><option>-I</option><replaceable>dir</replaceable></term>
	  <indexterm><primary><option>-I</option></primary></indexterm>
	  <listitem>
	    <para> Specify a directory in which to look for
            <literal>&num;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>&lowbar;&lowbar;HASKELL98&lowbar;&lowbar;</constant></term>
	  <indexterm><primary><literal>&lowbar;&lowbar;HASKELL98&lowbar;&lowbar;</literal></primary></indexterm>
	  <listitem>
	    <para>If defined, this means that GHC supports the
            language defined by the Haskell 98 report.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><constant>&lowbar;&lowbar;HASKELL&lowbar;&lowbar;=98</constant></term>
	  <indexterm><primary><constant>&lowbar;&lowbar;HASKELL&lowbar;&lowbar;=98</constant></primary></indexterm>
	  <listitem>
	    <para>In GHC 4.04 and later, the
            <constant>&lowbar;&lowbar;HASKELL&lowbar;&lowbar;</constant>
            macro is defined as having the value
            <constant>98</constant>.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><constant>&lowbar;&lowbar;HASKELL1&lowbar;&lowbar;</constant></term>
	  <indexterm><primary><constant>&lowbar;&lowbar;HASKELL1&lowbar;&lowbar;
	  </constant></primary></indexterm>
	  <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>&lowbar;&lowbar;GLASGOW&lowbar;HASKELL&lowbar;&lowbar;</constant></term>
	  <indexterm><primary><constant>&lowbar;&lowbar;GLASGOW&lowbar;HASKELL&lowbar;&lowbar;</constant></primary></indexterm>
	  <listitem>
	    <para>For version <replaceable>n</replaceable> of the GHC
            system, this will be <literal>&num;define</literal>d to
            <replaceable>100n</replaceable>.  For example, for version
            5.00, it is 500.</para>

	    <para>With any luck,
            <constant>&lowbar;&lowbar;GLASGOW&lowbar;HASKELL&lowbar;&lowbar;</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>&lowbar;&lowbar;HUGS&lowbar;&lowbar;</constant>
            for Hugs,
            <constant>&lowbar;&lowbar;NHC&lowbar;&lowbar;</constant>
            for nhc98, and
            <constant>&lowbar;&lowbar;HBC&lowbar;&lowbar;</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>&lowbar;&lowbar;CONCURRENT&lowbar;HASKELL&lowbar;&lowbar;</constant></term>
	  <indexterm><primary><constant>&lowbar;&lowbar;CONCURRENT&lowbar;HASKELL&lowbar;&lowbar;</constant></primary></indexterm>
	  <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>&lowbar;&lowbar;PARALLEL&lowbar;HASKELL&lowbar;&lowbar;</constant></term>
	  <indexterm><primary><constant>&lowbar;&lowbar;PARALLEL&lowbar;HASKELL&lowbar;&lowbar;</constant></primary></indexterm>
	  <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 &ldquo;string gaps&rdquo;.<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></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">
      <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&nbsp;compiler about some
      <literal>&num;include</literal> files.  There is no real pretty
      way to do this, but you can use this hack from the
      command-line:</para>

<Screen>
% ghc -c '-#include &lt;X/Xlib.h&gt;' Xstuff.lhs
</Screen>

    </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>

      <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></term>
	  <indexterm><primary><option>-l</option></primary></indexterm>
	  <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>-package</option> <replaceable>name</replaceable></term>
	  <indexterm><primary><option>-package</option></primary></indexterm>
	  <listitem>
	    <para>If you are using a Haskell &ldquo;package&rdquo;
            (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></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 &ldquo;Carbon&rdquo; 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>
	    <para>Where to find user-supplied libraries&hellip;
            Prepend the directory <replaceable>dir</replaceable> to
            the library directories path.</para>
	  </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>
	    <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></term>
	  <indexterm><primary><option>-static</option></primary></indexterm>
	  <listitem>
	    <para>Tell the linker to avoid shared Haskell libraries,
	    if possible.  This is the default.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><option>-dynamic</option></term>
	  <indexterm><primary><option>-dynamic</option></primary></indexterm>
	  <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>-no-hs-main</option></term>
	  <indexterm><primary><option>-no-hs-main</option></primary></indexterm>
	  <indexterm><primary>linking Haskell libraries with foreign code</primary></indexterm>
	  <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
            driver script when linking, use
            <option>-no-hs-main</option>.</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>
	  </listitem>
	</varlistentry>
      </variablelist>
    </sect2>

  </sect1>

<!-- Emacs stuff:
     ;;; Local Variables: ***
     ;;; mode: sgml ***
     ;;; sgml-parent-document: ("users_guide.sgml" "book" "chapter") ***
     ;;; End: ***
 -->
