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="pre-processor">
 210       <title>Options affecting a Haskell pre-processor</title>
 211
 212       <indexterm><primary>pre-processing: custom</primary></indexterm>
 213       <indexterm><primary>Pre-processor options</primary></indexterm>
 214
 215       <variablelist>
 216         <varlistentry>
 217           <term><option>-F</option></term>
 218           <indexterm><primary><option>-F</option></primary></indexterm>
 219           <listitem>
 220             <para>A custom pre-processor is run over your Haskell
 221             source file only if the <option>-F</option> option
 222             <indexterm><primary>-F</primary></indexterm> is given.
 223             </para>
 224             <para>
 225             Running a custom pre-processor at compile-time is in some
 226             settings appropriate and useful. The <option>-F</option>
 227             option lets you run a pre-processor as part of the overall
 228             GHC compilation pipeline, which has the advantage over
 229             running a Haskell pre-processor separately in that it
 230             works in interpreted mode and you can continue to take
 231             reap the benefits of GHC's recompilation checker.
 232             </para>
 233             <para>
 234             The pre-processor is run just before the Haskell
 235             compiler proper processes the Haskell input, but after
 236             the literate markup has been stripped away and (possibly)
 237             the C pre-processor has washed the Haskell input.
 238             </para>
 239           </listitem>
 240         </varlistentry>
 241         <varlistentry>
 242           <term><option>-pgmF</option> <replaceable>cmd</replaceable></term>
 243           <indexterm><primary><option>-pgmF</option> <replaceable>cmd</replaceable></primary></indexterm>
 244           <listitem>
 245             <para>Use <replaceable>cmd</replaceable> as the Haskell
 246           pre-processor. When invoked, the
 247           <replaceable>cmd</replaceable> pre-processor is given at
 248           least three arguments on its command-line: the first
 249           argument is the name of the original source file, the second
 250           is the name of the file holding the input, and the third is
 251           the name of the file where
 252           <replaceable>cmd</replaceable> should write its output to.
 253           </para>
 254           <para>Additional arguments to the
 255           <replaceable>cmd</replaceable> pre-processor can be passed
 256           in using the <option>-optF</option> option. These are fed to
 257           <replaceable>cmd</replaceable> on the command line after the
 258           three standard input and output arguments.
 259         </para>
 260           </listitem>
 261         </varlistentry>
 262       </variablelist>
 263     </sect2>
 264
 265     <sect2 id="options-C-compiler">
 266       <title>Options affecting the C compiler (if applicable)</title>
 267
 268       <indexterm><primary>include-file options</primary></indexterm>
 269       <indexterm><primary>C compiler options</primary></indexterm>
 270       <indexterm><primary>GCC options</primary></indexterm>
 271
 272       <para>If you are compiling with lots of foreign calls, you may
 273       need to tell the C&nbsp;compiler about some
 274       <literal>&num;include</literal> files.  There is no real pretty
 275       way to do this, but you can use this hack from the
 276       command-line:</para>
 277
 278 <Screen>
 279 % ghc -c '-#include &lt;X/Xlib.h&gt;' Xstuff.lhs
 280 </Screen>
 281
 282     </sect2>
 283
 284     <sect2 id="options-codegen">
 285       <title>Options affecting code generation</title>
 286
 287       <variablelist>
 288         <varlistentry>
 289           <term><option>-fasm</option></term>
 290           <indexterm><primary><option>-fasm</option></primary></indexterm>
 291           <listitem>
 292             <para>Use GHC's native code generator rather than
 293             compiling via C.  This will compile faster (up to twice as
 294             fast), but may produce code that is slightly slower than
 295             compiling via C.  <option>-fasm</option> is the default
 296             when optimisation is off (see <xref
 297             linkend="options-optimise">).</para>
 298           </listitem>
 299         </varlistentry>
 300
 301         <varlistentry>
 302           <term><option>-fvia-C</option></term>
 303           <indexterm><primary><option>-fvia-C</option></primary>
 304           </indexterm>
 305           <listitem>
 306             <para>Compile via C instead of using the native code
 307             generator.  This is default for optimised compilations,
 308             and on architectures for which GHC doesn't have a native
 309             code generator.</para>
 310           </listitem>
 311         </varlistentry>
 312
 313         <varlistentry>
 314           <term><option>-fno-code</option></term>
 315           <indexterm><primary><option>-fno-code</option></primary>
 316           </indexterm>
 317           <listitem>
 318             <para>Omit code generation (and all later phases)
 319             altogether.  Might be of some use if you just want to see
 320             dumps of the intermediate compilation phases.</para>
 321           </listitem>
 322         </varlistentry>
 323       </variablelist>
 324     </sect2>
 325
 326     <sect2 id="options-linker">
 327       <title>Options affecting linking</title>
 328
 329       <indexterm><primary>linker options</primary></indexterm>
 330       <indexterm><primary>ld options</primary></indexterm>
 331
 332
 333       <para>GHC has to link your code with various libraries, possibly
 334       including: user-supplied, GHC-supplied, and system-supplied
 335       (<option>-lm</option> math library, for example).</para>
 336
 337       <variablelist>
 338
 339         <varlistentry>
 340           <term><option>-l</option><replaceable>lib</replaceable></term>
 341           <indexterm><primary><option>-l</option></primary></indexterm>
 342           <listitem>
 343             <para>Link in the <replaceable>lib</replaceable> library.
 344             On Unix systems, this will be in a file called
 345             <filename>lib<replaceable>lib</replaceable>.a</filename>
 346             or
 347             <filename>lib<replaceable>lib</replaceable>.so</filename>
 348             which resides somewhere on the library directories path.</para>
 349
 350             <para>Because of the sad state of most UNIX linkers, the
 351             order of such options does matter.  If library
 352             <replaceable>foo</replaceable> requires library
 353             <replaceable>bar</replaceable>, then in general
 354             <option>-l</option><replaceable>foo</replaceable> should
 355             come <emphasis>before</emphasis>
 356             <option>-l</option><replaceable>bar</replaceable> on the
 357             command line.</para>
 358
 359             <para>There's one other gotcha to bear in mind when using
 360             external libraries: if the library contains a
 361             <literal>main()</literal> function, then this will be
 362             linked in preference to GHC's own
 363             <literal>main()</literal> function
 364             (eg. <literal>libf2c</literal> and <literal>libl</literal>
 365             have their own <literal>main()</literal>s).  This is
 366             because GHC's <literal>main()</literal> comes from the
 367             <literal>HSrts</literal> library, which is normally
 368             included <emphasis>after</emphasis> all the other
 369             libraries on the linker's command line.  To force GHC's
 370             <literal>main()</literal> to be used in preference to any
 371             other <literal>main()</literal>s from external libraries,
 372             just add the option <option>-lHSrts</option> before any
 373             other libraries on the command line.</para>
 374           </listitem>
 375         </varlistentry>
 376
 377         <varlistentry>
 378           <term><option>-package</option> <replaceable>name</replaceable></term>
 379           <indexterm><primary><option>-package</option></primary></indexterm>
 380           <listitem>
 381             <para>If you are using a Haskell &ldquo;package&rdquo;
 382             (see <xref linkend="packages">), don't forget to add the
 383             relevant <option>-package</option> option when linking the
 384             program too: it will cause the appropriate libraries to be
 385             linked in with the program.  Forgetting the
 386             <option>-package</option> option will likely result in
 387             several pages of link errors.</para>
 388           </listitem>
 389         </varlistentry>
 390
 391         <varlistentry>
 392           <term><option>-L</option><replaceable>dir</replaceable></term>
 393           <indexterm><primary><option>-L</option></primary></indexterm>
 394           <listitem>
 395             <para>Where to find user-supplied libraries&hellip;
 396             Prepend the directory <replaceable>dir</replaceable> to
 397             the library directories path.</para>
 398           </listitem>
 399         </varlistentry>
 400
 401         <varlistentry>
 402           <term><option>-split-objs</option></term>
 403           <indexterm><primary><option>-split-objs</option></primary></indexterm>
 404           <listitem>
 405             <para>Tell the linker to split the single object file that
 406             would normally be generated into multiple object files,
 407             one per top-level Haskell function or type in the module.
 408             We use this feature for building GHC's libraries libraries
 409             (warning: don't use it unless you know what you're
 410             doing!).</para>
 411           </listitem>
 412         </varlistentry>
 413
 414         <varlistentry>
 415           <term><option>-static</option></term>
 416           <indexterm><primary><option>-static</option></primary></indexterm>
 417           <listitem>
 418             <para>Tell the linker to avoid shared Haskell libraries,
 419             if possible.  This is the default.</para>
 420           </listitem>
 421         </varlistentry>
 422
 423         <varlistentry>
 424           <term><option>-dynamic</option></term>
 425           <indexterm><primary><option>-dynamic</option></primary></indexterm>
 426           <listitem>
 427             <para>Tell the linker to use shared Haskell libraries, if
 428             available (this option is only supported on Windows at the
 429             moment, and also note that your distribution of GHC may
 430             not have been supplied with shared libraries).</para>
 431           </listitem>
 432         </varlistentry>
 433
 434         <varlistentry>
 435           <term><option>-no-hs-main</option></term>
 436           <indexterm><primary><option>-no-hs-main</option></primary></indexterm>
 437           <indexterm><primary>linking Haskell libraries with foreign code</primary></indexterm>
 438           <listitem>
 439             <para>In the event you want to include ghc-compiled code
 440             as part of another (non-Haskell) program, the RTS will not
 441             be supplying its definition of <function>main()</function>
 442             at link-time, you will have to. To signal that to the
 443             driver script when linking, use
 444             <option>-no-hs-main</option>.</para>
 445
 446             <para>Notice that since the command-line passed to the
 447             linker is rather involved, you probably want to use
 448             <command>ghc</command> to do the final link of your
 449             `mixed-language' application. This is not a requirement
 450             though, just try linking once with <option>-v</option> on
 451             to see what options the driver passes through to the
 452             linker.</para>
 453           </listitem>
 454         </varlistentry>
 455       </variablelist>
 456     </sect2>
 457
 458   </sect1>
 459
 460 <!-- Emacs stuff:
 461      ;;; Local Variables: ***
 462      ;;; mode: sgml ***
 463      ;;; sgml-parent-document: ("users_guide.sgml" "book" "chapter") ***
 464      ;;; End: ***
 465  -->