ghc/docs/users_guide/phases.sgml

   1   <sect1 id="options-phases">
   2     <title>Options related to a particular phase</title>
   3
   4     <sect2 id="replacing-phases">
   5       <title>Replacing the program for one or more phases.</title>
   6       <indexterm><primary>phases, changing</primary></indexterm>
   7
   8       <para>You may specify that a different program be used for one
   9       of the phases of the compilation system, in place of whatever
  10       the <Command>ghc</Command> has wired into it.  For example, you
  11       might want to try a different assembler.  The following options
  12       allow you to change the external program used for a given
  13       compilation phases:</para>
  14
  15     </sect2>
  16
  17     <sect2 id="forcing-options-through">
  18       <title>Forcing options to a particular phase.</title>
  19       <indexterm><primary>forcing GHC-phase options</primary></indexterm>
  20
  21       <para>Options can be forced through to a particlar compilation
  22       phase, using the following flags:</para>
  23
  24
  25       <para>So, for example, to force an <option>-Ewurble</option>
  26       option to the assembler, you would tell the driver
  27       <option>-opta-Ewurble</option> (the dash before the E is
  28       required).</para>
  29
  30       <para>GHC is itself a Haskell program, so if you need to pass
  31       options directly to GHC's runtime system you can enclose them in
  32       <literal>+RTS ... -RTS</literal> (see <xref
  33       linkend="runtime-control">).</para>
  34
  35     </sect2>
  36
  37     <sect2 id="c-pre-processor">
  38       <title>Options affecting the C pre-processor</title>
  39
  40       <indexterm><primary>pre-processing: cpp</primary></indexterm>
  41       <indexterm><primary>C pre-processor options</primary></indexterm>
  42       <indexterm><primary>cpp, pre-processing with</primary></indexterm>
  43
  44       <variablelist>
  45
  46         <varlistentry>
  47           <term><option>-cpp</option></term>
  48           <indexterm><primary><option>-cpp</option></primary></indexterm>
  49           <listitem>
  50             <para>The C pre-processor <command>cpp</command> is run
  51             over your Haskell code only if the <option>-cpp</option>
  52             option <indexterm><primary>-cpp
  53             option</primary></indexterm> is given.  Unless you are
  54             building a large system with significant doses of
  55             conditional compilation, you really shouldn't need
  56             it.</para>
  57           </listitem>
  58         </varlistentry>
  59
  60         <varlistentry>
  61           <term><option>-D</option><replaceable>symbol</replaceable><optional>=<replaceable>value</replaceable></optional></term>
  62           <indexterm><primary><option>-D</option></primary></indexterm>
  63           <listitem>
  64             <para>Define macro <replaceable>symbol</replaceable> in the
  65             usual way.  NB: does <emphasis>not</emphasis> affect
  66             <option>-D</option> macros passed to the C&nbsp;compiler
  67             when compiling via C!  For those, use the
  68             <option>-optc-Dfoo</option> hack&hellip; (see <xref
  69             linkend="forcing-options-through">).</para>
  70           </listitem>
  71         </varlistentry>
  72
  73         <varlistentry>
  74           <term><option>-U</option><replaceable>symbol</replaceable></term>
  75           <indexterm><primary><option>-U</option></primary></indexterm>
  76           <listitem>
  77             <para> Undefine macro <replaceable>symbol</replaceable> in the
  78             usual way.</para>
  79           </listitem>
  80         </varlistentry>
  81
  82         <varlistentry>
  83           <term><option>-I</option><replaceable>dir</replaceable></term>
  84           <indexterm><primary><option>-I</option></primary></indexterm>
  85           <listitem>
  86             <para> Specify a directory in which to look for
  87             <literal>&num;include</literal> files, in the usual C
  88             way.</para>
  89           </listitem>
  90         </varlistentry>
  91       </variablelist>
  92
  93       <para>The GHC driver pre-defines several macros when processing
  94       Haskell source code (<filename>.hs</filename> or
  95       <filename>.lhs</filename> files):</para>
  96
  97       <variablelist>
  98
  99         <varlistentry>
 100           <term><constant>&lowbar;&lowbar;HASKELL98&lowbar;&lowbar;</constant></term>
 101           <indexterm><primary><literal>&lowbar;&lowbar;HASKELL98&lowbar;&lowbar;</literal></primary></indexterm>
 102           <listitem>
 103             <para>If defined, this means that GHC supports the
 104             language defined by the Haskell 98 report.</para>
 105           </listitem>
 106         </varlistentry>
 107
 108         <varlistentry>
 109           <term><constant>&lowbar;&lowbar;HASKELL&lowbar;&lowbar;=98</constant></term>
 110           <indexterm><primary><constant>&lowbar;&lowbar;HASKELL&lowbar;&lowbar;=98</constant></primary></indexterm>
 111           <listitem>
 112             <para>In GHC 4.04 and later, the
 113             <constant>&lowbar;&lowbar;HASKELL&lowbar;&lowbar;</constant>
 114             macro is defined as having the value
 115             <constant>98</constant>.</para>
 116           </listitem>
 117         </varlistentry>
 118
 119         <varlistentry>
 120           <term><constant>&lowbar;&lowbar;HASKELL1&lowbar;&lowbar;</constant></term>
 121           <indexterm><primary><constant>&lowbar;&lowbar;HASKELL1&lowbar;&lowbar;
 122           </constant></primary></indexterm>
 123           <listitem>
 124             <para>If defined to <replaceable>n</replaceable>, that
 125             means GHC supports the Haskell language defined in the
 126             Haskell report version <emphasis>1.n</emphasis>.
 127             Currently 5.  This macro is deprecated, and will probably
 128             disappear in future versions.</para>
 129           </listitem>
 130         </varlistentry>
 131
 132         <varlistentry>
 133           <term><constant>&lowbar;&lowbar;GLASGOW&lowbar;HASKELL&lowbar;&lowbar;</constant></term>
 134           <indexterm><primary><constant>&lowbar;&lowbar;GLASGOW&lowbar;HASKELL&lowbar;&lowbar;</constant></primary></indexterm>
 135           <listitem>
 136             <para>For version <replaceable>n</replaceable> of the GHC
 137             system, this will be <literal>&num;define</literal>d to
 138             <replaceable>100n</replaceable>.  For example, for version
 139             5.00, it is 500.</para>
 140
 141             <para>With any luck,
 142             <constant>&lowbar;&lowbar;GLASGOW&lowbar;HASKELL&lowbar;&lowbar;</constant>
 143             will be undefined in all other implementations that
 144             support C-style pre-processing.</para>
 145
 146             <para>(For reference: the comparable symbols for other
 147             systems are:
 148             <constant>&lowbar;&lowbar;HUGS&lowbar;&lowbar;</constant>
 149             for Hugs,
 150             <constant>&lowbar;&lowbar;NHC&lowbar;&lowbar;</constant>
 151             for nhc98, and
 152             <constant>&lowbar;&lowbar;HBC&lowbar;&lowbar;</constant>
 153             for Chalmers.)</para>
 154
 155             <para>NB. This macro is set when pre-processing both
 156             Haskell source and C source, including the C source
 157             generated from a Haskell module
 158             (i.e. <filename>.hs</filename>, <filename>.lhs</filename>,
 159             <filename>.c</filename> and <filename>.hc</filename>
 160             files).</para>
 161           </listitem>
 162         </varlistentry>
 163
 164         <varlistentry>
 165           <term><constant>&lowbar;&lowbar;CONCURRENT&lowbar;HASKELL&lowbar;&lowbar;</constant></term>
 166           <indexterm><primary><constant>&lowbar;&lowbar;CONCURRENT&lowbar;HASKELL&lowbar;&lowbar;</constant></primary></indexterm>
 167           <listitem>
 168             <para>This symbol is defined when pre-processing Haskell
 169             (input) and pre-processing C (GHC output).  Since GHC from
 170             verion 4.00 now supports concurrent haskell by default,
 171             this symbol is always defined.</para>
 172           </listitem>
 173         </varlistentry>
 174
 175         <varlistentry>
 176           <term><constant>&lowbar;&lowbar;PARALLEL&lowbar;HASKELL&lowbar;&lowbar;</constant></term>
 177           <indexterm><primary><constant>&lowbar;&lowbar;PARALLEL&lowbar;HASKELL&lowbar;&lowbar;</constant></primary></indexterm>
 178           <listitem>
 179             <para>Only defined when <option>-parallel</option> is in
 180             use!  This symbol is defined when pre-processing Haskell
 181             (input) and pre-processing C (GHC output).</para>
 182           </listitem>
 183         </varlistentry>
 184       </variablelist>
 185
 186       <para>A small word of warning: <option>-cpp</option> is not
 187       friendly to &ldquo;string gaps&rdquo;.<indexterm><primary>-cpp
 188       vs string gaps</primary></indexterm><indexterm><primary>string
 189       gaps vs -cpp</primary></indexterm>.  In other words, strings
 190       such as the following:</para>
 191
 192 <ProgramListing>
 193 strmod = "\
 194 \ p \
 195 \ "
 196 </ProgramListing>
 197
 198       <para>don't work with <option>-cpp</option>;
 199       <filename>/usr/bin/cpp</filename> elides the backslash-newline
 200       pairs.</para>
 201
 202       <para>However, it appears that if you add a space at the end of
 203       the line, then <command>cpp</command> (at least GNU
 204       <command>cpp</command> and possibly other
 205       <command>cpp</command>s) leaves the backslash-space pairs alone
 206       and the string gap works as expected.</para>
 207     </sect2>
 208
 209     <sect2 id="options-C-compiler">
 210       <title>Options affecting the C compiler (if applicable)</title>
 211
 212       <indexterm><primary>include-file options</primary></indexterm>
 213       <indexterm><primary>C compiler options</primary></indexterm>
 214       <indexterm><primary>GCC options</primary></indexterm>
 215
 216       <para>If you are compiling with lots of foreign calls, you may
 217       need to tell the C&nbsp;compiler about some
 218       <literal>&num;include</literal> files.  There is no real pretty
 219       way to do this, but you can use this hack from the
 220       command-line:</para>
 221
 222 <Screen>
 223 % ghc -c '-#include &lt;X/Xlib.h&gt;' Xstuff.lhs
 224 </Screen>
 225
 226     </sect2>
 227
 228     <sect2 id="options-codegen">
 229       <title>Options affecting code generation</title>
 230
 231       <variablelist>
 232         <varlistentry>
 233           <term><option>-fasm</option></term>
 234           <indexterm><primary><option>-fasm</option></primary></indexterm>
 235           <listitem>
 236             <para>Use GHC's native code generator rather than
 237             compiling via C.  This will compile faster (up to twice as
 238             fast), but may produce code that is slightly slower than
 239             compiling via C.  <option>-fasm</option> is the default
 240             when optimisation is off (see <xref
 241             linkend="options-optimise">).</para>
 242           </listitem>
 243         </varlistentry>
 244
 245         <varlistentry>
 246           <term><option>-fvia-C</option></term>
 247           <indexterm><primary><option>-fvia-C</option></primary>
 248           </indexterm>
 249           <listitem>
 250             <para>Compile via C instead of using the native code
 251             generator.  This is default for optimised compilations,
 252             and on architectures for which GHC doesn't have a native
 253             code generator.</para>
 254           </listitem>
 255         </varlistentry>
 256
 257         <varlistentry>
 258           <term><option>-fno-code</option></term>
 259           <indexterm><primary><option>-fno-code</option></primary>
 260           </indexterm>
 261           <listitem>
 262             <para>Omit code generation (and all later phases)
 263             altogether.  Might be of some use if you just want to see
 264             dumps of the intermediate compilation phases.</para>
 265           </listitem>
 266         </varlistentry>
 267       </variablelist>
 268     </sect2>
 269
 270     <sect2 id="options-linker">
 271       <title>Options affecting linking</title>
 272
 273       <indexterm><primary>linker options</primary></indexterm>
 274       <indexterm><primary>ld options</primary></indexterm>
 275
 276
 277       <para>GHC has to link your code with various libraries, possibly
 278       including: user-supplied, GHC-supplied, and system-supplied
 279       (<option>-lm</option> math library, for example).</para>
 280
 281       <variablelist>
 282
 283         <varlistentry>
 284           <term><option>-l</option><replaceable>lib</replaceable></term>
 285           <indexterm><primary><option>-l</option></primary></indexterm>
 286           <listitem>
 287             <para>Link in the <replaceable>lib</replaceable> library.
 288             On Unix systems, this will be in a file called
 289             <filename>lib<replaceable>lib</replaceable>.a</filename>
 290             or
 291             <filename>lib<replaceable>lib</replaceable>.so</filename>
 292             which resides somewhere on the library directories path.</para>
 293
 294             <para>Because of the sad state of most UNIX linkers, the
 295             order of such options does matter.  If library
 296             <replaceable>foo</replaceable> requires library
 297             <replaceable>bar</replaceable>, then in general
 298             <option>-l</option><replaceable>foo</replaceable> should
 299             come <emphasis>before</emphasis>
 300             <option>-l</option><replaceable>bar</replaceable> on the
 301             command line.</para>
 302
 303             <para>There's one other gotcha to bear in mind when using
 304             external libraries: if the library contains a
 305             <literal>main()</literal> function, then this will be
 306             linked in preference to GHC's own
 307             <literal>main()</literal> function
 308             (eg. <literal>libf2c</literal> and <literal>libl</literal>
 309             have their own <literal>main()</literal>s).  This is
 310             because GHC's <literal>main()</literal> comes from the
 311             <literal>HSrts</literal> library, which is normally
 312             included <emphasis>after</emphasis> all the other
 313             libraries on the linker's command line.  To force GHC's
 314             <literal>main()</literal> to be used in preference to any
 315             other <literal>main()</literal>s from external libraries,
 316             just add the option <option>-lHSrts</option> before any
 317             other libraries on the command line.</para>
 318           </listitem>
 319         </varlistentry>
 320
 321         <varlistentry>
 322           <term><option>-package</option> <replaceable>name</replaceable></term>
 323           <indexterm><primary><option>-package</option></primary></indexterm>
 324           <listitem>
 325             <para>If you are using a Haskell &ldquo;package&rdquo;
 326             (see <xref linkend="packages">), don't forget to add the
 327             relevant <option>-package</option> option when linking the
 328             program too: it will cause the appropriate libraries to be
 329             linked in with the program.  Forgetting the
 330             <option>-package</option> option will likely result in
 331             several pages of link errors.</para>
 332           </listitem>
 333         </varlistentry>
 334
 335         <varlistentry>
 336           <term><option>-L</option><replaceable>dir</replaceable></term>
 337           <indexterm><primary><option>-L</option></primary></indexterm>
 338           <listitem>
 339             <para>Where to find user-supplied libraries&hellip;
 340             Prepend the directory <replaceable>dir</replaceable> to
 341             the library directories path.</para>
 342           </listitem>
 343         </varlistentry>
 344
 345         <varlistentry>
 346           <term><option>-split-objs</option></term>
 347           <indexterm><primary><option>-split-objs</option></primary></indexterm>
 348           <listitem>
 349             <para>Tell the linker to split the single object file that
 350             would normally be generated into multiple object files,
 351             one per top-level Haskell function or type in the module.
 352             We use this feature for building GHC's libraries libraries
 353             (warning: don't use it unless you know what you're
 354             doing!).</para>
 355           </listitem>
 356         </varlistentry>
 357
 358         <varlistentry>
 359           <term><option>-static</option></term>
 360           <indexterm><primary><option>-static</option></primary></indexterm>
 361           <listitem>
 362             <para>Tell the linker to avoid shared Haskell libraries,
 363             if possible.  This is the default.</para>
 364           </listitem>
 365         </varlistentry>
 366
 367         <varlistentry>
 368           <term><option>-dynamic</option></term>
 369           <indexterm><primary><option>-dynamic</option></primary></indexterm>
 370           <listitem>
 371             <para>Tell the linker to use shared Haskell libraries, if
 372             available (this option is only supported on Windows at the
 373             moment, and also note that your distribution of GHC may
 374             not have been supplied with shared libraries).</para>
 375           </listitem>
 376         </varlistentry>
 377
 378         <varlistentry>
 379           <term><option>-no-hs-main</option></term>
 380           <indexterm><primary><option>-no-hs-main</option></primary></indexterm>
 381           <indexterm><primary>linking Haskell libraries with foreign code</primary></indexterm>
 382           <listitem>
 383             <para>In the event you want to include ghc-compiled code
 384             as part of another (non-Haskell) program, the RTS will not
 385             be supplying its definition of <function>main()</function>
 386             at link-time, you will have to. To signal that to the
 387             driver script when linking, use
 388             <option>-no-hs-main</option>.</para>
 389
 390             <para>Notice that since the command-line passed to the
 391             linker is rather involved, you probably want to use
 392             <command>ghc</command> to do the final link of your
 393             `mixed-language' application. This is not a requirement
 394             though, just try linking once with <option>-v</option> on
 395             to see what options the driver passes through to the
 396             linker.</para>
 397           </listitem>
 398         </varlistentry>
 399       </variablelist>
 400     </sect2>
 401
 402   </sect1>
 403
 404 <!-- Emacs stuff:
 405      ;;; Local Variables: ***
 406      ;;; mode: sgml ***
 407      ;;; sgml-parent-document: ("users_guide.sgml" "book" "chapter") ***
 408      ;;; End: ***
 409  -->