path: root/docs/users_guide/phases.xml

<?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>-pgmlo</option> <replaceable>cmd</replaceable>
          <indexterm><primary><option>-pgmlo</option></primary></indexterm>
        </term>
        <listitem>
          <para>Use <replaceable>cmd</replaceable> as the LLVM
          optimiser.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>
          <option>-pgmlc</option> <replaceable>cmd</replaceable>
          <indexterm><primary><option>-pgmlc</option></primary></indexterm>
        </term>
        <listitem>
          <para>Use <replaceable>cmd</replaceable> as the LLVM
          compiler.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>
          <option>-pgms</option> <replaceable>cmd</replaceable>
          <indexterm><primary><option>-pgms</option></primary></indexterm>
        </term>
        <listitem>
          <para>Use <replaceable>cmd</replaceable> as the
          splitter.</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>-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>

      <varlistentry>
        <term>
          <option>-pgmwindres</option> <replaceable>cmd</replaceable>
          <indexterm><primary><option>-pgmwindres</option></primary></indexterm>
        </term>
        <listitem>
          <para>Use <replaceable>cmd</replaceable> as the
          program to use for embedding manifests on Windows.  Normally this
            is the program <literal>windres</literal>, which is supplied with a
            GHC installation. See <option>-fno-embed-manifest</option> in <xref
              linkend="options-linker" />.</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 particular 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>-optlo</option> <replaceable>option</replaceable>
          <indexterm><primary><option>-optlo</option></primary></indexterm>
        </term>
        <listitem>
          <para>Pass <replaceable>option</replaceable> to the LLVM optimiser.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>
          <option>-optlc</option> <replaceable>option</replaceable>
          <indexterm><primary><option>-optlc</option></primary></indexterm>
        </term>
        <listitem>
          <para>Pass <replaceable>option</replaceable> to the LLVM compiler.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>
          <option>-optm</option>  <replaceable>option</replaceable>
          <indexterm><primary><option>-optm</option></primary></indexterm>
        </term>
        <listitem>
          <para>Pass <replaceable>option</replaceable> to the mangler.</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>-optwindres</option>  <replaceable>option</replaceable>
          <indexterm><primary><option>-optwindres</option></primary></indexterm>
        </term>
        <listitem>
          <para>Pass <replaceable>option</replaceable> to
            <literal>windres</literal> when embedding manifests on Windows.
            See <option>-fno-embed-manifest</option> in <xref
              linkend="options-linker" />.</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&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>
          <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>&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>

    <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 -E -optP-dM -cpp foo.hs
$ cat foo.hspp</screen>

    <para>(you need a file <filename>foo.hs</filename>, but it isn't
    actually used).</para>

    <variablelist>
      <varlistentry>
        <term>
          <constant>&lowbar;&lowbar;GLASGOW&lowbar;HASKELL&lowbar;&lowbar;</constant>
          <indexterm><primary><constant>&lowbar;&lowbar;GLASGOW&lowbar;HASKELL&lowbar;&lowbar;</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>&lowbar;&lowbar;GLASGOW&lowbar;HASKELL&lowbar;&lowbar;</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>&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 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>&lowbar;&lowbar;PARALLEL&lowbar;HASKELL&lowbar;&lowbar;</constant>
          <indexterm><primary><constant>&lowbar;&lowbar;PARALLEL&lowbar;HASKELL&lowbar;&lowbar;</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>_HOST_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>_HOST_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 &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>
          <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&nbsp;<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>

          <para>
          An example of a pre-processor is to convert your source files to the
          input encoding that GHC expects, i.e. create a script
          <literal>convert.sh</literal> containing the lines:
          </para>

<screen>#!/bin/sh
( echo "{-# LINE 1 \"$2\" #-}" ; iconv -f l1 -t utf-8 $2 ) > $3</screen>

          <para>and pass <literal>-F -pgmF convert.sh</literal> to GHC.
          The <literal>-f l1</literal> option tells iconv to convert your
          Latin-1 file, supplied in argument <literal>$2</literal>, while
          the "-t utf-8" options tell iconv to return a UTF-8 encoded file.
          The result is redirected into argument <literal>$3</literal>.
          The <literal>echo "{-# LINE 1 \"$2\" #-}"</literal>
          just makes sure that your error positions are reported as
          in the original source file.</para>
        </listitem>
      </varlistentry>
    </variablelist>
  </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 LLVM.
          <option>-fasm</option> is the default.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>
          <option>-fllvm</option>
          <indexterm><primary><option>-fllvm</option></primary></indexterm>
        </term>
        <listitem>
          <para>Compile via LLVM instead of using the native code
          generator. This will generally take slightly longer than the
          native code generator to compile.
          Produced code is generally the same speed or faster
          than the other two code generators. Compiling via LLVM
          requires LLVM version 2.7 or later to be on the path.</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>

      <varlistentry>
        <term>
          <option>-fobject-code</option>
          <indexterm><primary><option>-fobject-code</option></primary></indexterm>
        </term>
        <listitem>
          <para>Generate object code.  This is the default outside of
          GHCi, and can be used with GHCi to cause object code to be
          generated in preference to bytecode.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>
          <option>-fbyte-code</option>
          <indexterm><primary><option>-fbyte-code</option></primary></indexterm>
        </term>
        <listitem>
          <para>Generate byte-code instead of object-code.  This is
          the default in GHCi.  Byte-code can currently only be used
          in the interactive interpreter, not saved to disk.  This
          option is only useful for reversing the effect of
          <option>-fobject-code</option>.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>
          <option>-fPIC</option>
          <indexterm><primary><option>-fPIC</option></primary></indexterm>
        </term>
        <listitem>
          <para>Generate position-independent code (code that can be put into
          shared libraries). This currently works on Linux x86 and x86-64 when
          using the native code generator (-fasm).
          On Windows, position-independent code is never used
          so the flag is a no-op on that platform.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>
          <option>-dynamic</option>
        </term>
        <listitem>
          <para>When generating code, assume that entities imported from a
          different package will reside in a different shared library or
          binary.</para>
          <para>Note that using this option when linking causes GHC to link
          against shared libraries.</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>-c</option>
          <indexterm><primary><option>-c</option></primary></indexterm>
        </term>
        <listitem>
          <para>Omits the link step.  This option can be used with
            <option>&ndash;&ndash;make</option> to avoid the automatic linking
            that takes place 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 &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>
          <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 &ldquo;Carbon&rdquo; 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&hellip;
          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.
          This only makes sense for libraries, where it means that
          executables linked against the library are smaller as they only
          link against the object files that they need. However, assembling
          all the sections separately is expensive, so this is slower than
          compiling normally.
          We use this feature for building GHC's 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>This flag tells GHC to link against shared Haskell libraries.
          This flag only affects the selection of dependent libraries, not
          the form of the current target (see -shared).
          See <xref linkend="using-shared-libs" /> on how to
          create them.</para>

          <para>Note that this option also has an effect on
          code generation (see above).</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>
          <option>-shared</option>
          <indexterm><primary><option>-shared</option></primary></indexterm>
        </term>
        <listitem>
          <para>Instead of creating an executable, GHC produces a
          shared object with this linker flag. Depending on the
          operating system target, this might be an ELF DSO, a Windows
          DLL, or a Mac OS dylib. GHC hides the operating system
          details beneath this uniform flag.</para>

          <para>The flags <option>-dynamic</option>/<option>-static</option> control whether the
          resulting shared object links statically or dynamically to
          Haskell package libraries given as <option>-package</option> option. Non-Haskell
          libraries are linked as gcc would regularly link it on your
          system, e.g. on most ELF system the linker uses the dynamic
          libraries when found.</para>

          <para>Object files linked into shared objects must be
          compiled with <option>-fPIC</option>, see <xref linkend="options-codegen" /></para>

          <para>When creating shared objects for Haskell packages, the
          shared object must be named properly, so that GHC recognizes
          the shared object when linked against this package. See
          shared object name mangling.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>
          <option>-dynload</option>
          <indexterm><primary><option>-dynload</option></primary></indexterm>
        </term>
        <listitem>
          <para>
            This flag selects one of a number of modes for finding shared
            libraries at runtime. See <xref linkend="finding-shared-libs"/> for
            a description of each mode.
          </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>A module name <literal>A</literal>.  GHC assumes that the main function is <literal>A.main</literal>.</para></listitem>
        <listitem><para>A 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>.
            However, if all the modules are otherwise up to date, you may need to force
            recompilation both of the module where the new "main" is, and of the
            module where the "main" function used to be;
            <literal>ghc</literal> is not clever
            enough to figure out that they both need recompiling.  You can
            force recompilation by removing the object file, or by using the
            <option>-fforce-recomp</option> flag.
            </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&nbsp;-?</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" version of the
          runtime system.  The threaded runtime system is so-called
          because it manages multiple OS threads, as opposed to the
          default runtime system which is purely
          single-threaded.</para>

          <para>Note that you do <emphasis>not</emphasis> need
          <option>-threaded</option> in order to use concurrency; the
          single-threaded runtime supports concurrency between Haskell
          threads just fine.</para>

          <para>The threaded runtime system provides the following
          benefits:</para>

          <itemizedlist>
            <listitem>
              <para>Parallelism<indexterm><primary>parallelism</primary></indexterm> on a multiprocessor<indexterm><primary>multiprocessor</primary></indexterm><indexterm><primary>SMP</primary></indexterm> or multicore<indexterm><primary>multicore</primary></indexterm>
              machine.  See <xref linkend="using-smp" />.</para>

              <para>The ability to make a foreign call that does not
              block all other Haskell threads, and to invoke
              foreign-exported Haskell functions from multiple OS
              threads. See <xref linkend="ffi-threads" />.</para>
            </listitem>
          </itemizedlist>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>
          <option>-eventlog</option>
          <indexterm><primary><option>-eventlog</option></primary></indexterm>
        </term>
        <listitem>
          <para>
            Link the program with the "eventlog" version of the
            runtime system.  A program linked in this way can generate
            a runtime trace of events (such as thread start/stop) to a
            binary file
            <literal><replaceable>program</replaceable>.eventlog</literal>,
            which can then be interpreted later by various tools.  See
            <xref linkend="rts-eventlog" /> for more information.
          </para>
          <para>
            <option>-eventlog</option> can be used
            with <option>-threaded</option>.  It is implied
            by <option>-debug</option>.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>
          <option>-rtsopts</option>
          <indexterm><primary><option>-rtsopts</option></primary></indexterm>
        </term>
        <listitem>
          <para>
            This option affects the processing of RTS control options given either
            on the command line or via the <envar>GHCRTS</envar> environment variable.
            There are three possibilities:
          </para>
          <variablelist>
            <varlistentry>
              <term><option>-rtsopts=none</option></term>
              <listitem>
                <para>
                  Disable all processing of RTS options.
                  If <option>+RTS</option> appears anywhere on the command
                  line, then the program will abort with an error message.
                  If the <envar>GHCRTS</envar> environment variable is
                  set, then the program will emit a warning message,
                  <envar>GHCRTS</envar> will be ignored, and the program
                  will run as normal.
                </para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term><option>-rtsopts=some</option></term>
              <listitem>
                <para>&lsqb;this is the default setting&rsqb; Enable
                  only the "safe" RTS options: (Currently
                  only <option>-?</option>
                  and <option>--info</option>.)  Any other RTS options
                  on the command line or in the <envar>GHCRTS</envar>
                  environment variable causes the program with to abort
                  with an error message.
                </para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term><option>-rtsopts=all</option>, or
 just <option>-rtsopts</option></term>
              <listitem>
                <para>
                  Enable <emphasis>all</emphasis> RTS option
                  processing, both on the command line and through
                  the <envar>GHCRTS</envar> environment variable.
                </para>
              </listitem>
            </varlistentry>
          </variablelist>
          <para>
            In GHC 6.12.3 and earlier, the default was to process all
            RTS options. However, since RTS options can be used to
            write logging data to arbitrary files under the security
            context of the running program, there is a potential
            security problem.  For this reason, GHC 7.0.1 and later
            default to <option>-rtsops=some</option>.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>
          <option>-with-rtsopts</option>
          <indexterm><primary><option>-with-rtsopts</option></primary></indexterm>
        </term>
        <listitem>
          <para>
            This option allows you to set the default RTS options at link-time. For example,
            <option>-with-rtsopts="-H128m"</option> sets the default heap size to 128MB.
            This will always be the default heap size for this program, unless the user overrides it.
            (Depending on the setting of the <option>-rtsopts</option> option, the user might
            not have the ability to change RTS options at run-time, in which case
            <option>-with-rtsopts</option> would be the <emphasis>only</emphasis> way to set
            them.)
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>
          <option>-fno-gen-manifest</option>
          <indexterm><primary><option>-fno-gen-manifest</option></primary>
          </indexterm>
        </term>
        <listitem>
          <para>On Windows, GHC normally generates a
            <firstterm>manifest</firstterm><indexterm><primary>manifest</primary>
            </indexterm> file when linking a binary.  The
            manifest is placed in the file
            <literal><replaceable>prog</replaceable>.exe.manifest</literal>
            where <replaceable>prog.exe</replaceable> is the name of the
            executable.  The manifest file currently serves just one purpose:
            it disables the "installer detection"<indexterm><primary>installer detection</primary>
            </indexterm>in Windows Vista that
            attempts to elevate privileges for executables with certain names
            (e.g. names containing "install", "setup" or "patch").  Without the
            manifest file to turn off installer detection, attempting to run an
            executable that Windows deems to be an installer will return a
            permission error code to the invoker.  Depending on the invoker,
            the result might be a dialog box asking the user for elevated
            permissions, or it might simply be a permission denied
            error.</para>

          <para>Installer detection can be also turned off globally for the
            system using the security control panel, but GHC by default
            generates binaries that don't depend on the user having disabled
            installer detection.</para>

          <para>The <option>-fno-gen-manifest</option> disables generation of
            the manifest file.  One reason to do this would be if you had
            a manifest file of your own, for example.</para>

          <para>In the future, GHC might use the manifest file for more things,
            such as supplying the location of dependent DLLs.</para>

          <para><option>-fno-gen-manifest</option> also implies
            <option>-fno-embed-manifest</option>, see below.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>
          <option>-fno-embed-manifest</option>
          <indexterm><primary><option>-fno-embed-manifest</option></primary>
          </indexterm>
        </term>
        <listitem>
          <para>The manifest file that GHC generates when linking a binary on
            Windows is also embedded in the executable itself, by default.
            This means that the binary can be distributed without having to
            supply the manifest file too.  The embedding is done by running
            <literal>windres</literal><indexterm><primary><literal>windres</literal></primary>
            </indexterm>; to see exactly what GHC does to embed the manifest,
            use the <option>-v</option> flag.  A GHC installation comes with
            its own copy of <literal>windres</literal> for this reason.</para>

          <para>See also <option>-pgmwindres</option> (<xref
              linkend="replacing-phases" />) and
            <option>-optwindres</option> (<xref
                                            linkend="forcing-options-through"
              />).</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>
          <option>-fno-shared-implib</option>
          <indexterm><primary><option>-fno-shared-implib</option></primary>
          </indexterm>
        </term>
        <listitem>
          <para>DLLs on Windows are typically linked to by linking to a corresponding
            <literal>.lib</literal> or <literal>.dll.a</literal> - the so-called import library.
            GHC will typically generate such a file for every DLL you create by compiling in
            <literal>-shared</literal> mode. However, sometimes you don't want to pay the
            disk-space cost of creating this import library, which can be substantial - it
            might require as much space as the code itself, as Haskell DLLs tend to export
            lots of symbols.</para>

          <para>As long as you are happy to only be able to link to the DLL using
            <literal>GetProcAddress</literal> and friends, you can supply the
            <option>-fno-shared-implib</option> flag to disable the creation of the import
            library entirely.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>
          <option>-dylib-install-name <replaceable>path</replaceable></option>
          <indexterm><primary><option>-dylib-install-name</option></primary>
          </indexterm>
        </term>
        <listitem>
          <para>On Darwin/MacOS X, dynamic libraries are stamped at build time with an
              "install name", which is the ultimate install path of the library file.
              Any libraries or executables that subsequently link against it will pick
              up that path as their runtime search location for it. By default, ghc sets
              the install name to the location where the library is built. This option
              allows you to override it with the specified file path. (It passes
              <literal>-install_name</literal> to Apple's linker.) Ignored on other
              platforms.</para>
        </listitem>
      </varlistentry>
    </variablelist>
  </sect2>

</sect1>

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