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 and
 150             <constant>&lowbar;&lowbar;HBC&lowbar;&lowbar;</constant>
 151             for Chalmers.)</para>
 152
 153             <para>NB. This macro is set when pre-processing both
 154             Haskell source and C source, including the C source
 155             generated from a Haskell module
 156             (i.e. <filename>.hs</filename>, <filename>.lhs</filename>,
 157             <filename>.c</filename> and <filename>.hc</filename>
 158             files).</para>
 159           </listitem>
 160         </varlistentry>
 161
 162         <varlistentry>
 163           <term><constant>&lowbar;&lowbar;CONCURRENT&lowbar;HASKELL&lowbar;&lowbar;</constant></term>
 164           <indexterm><primary><constant>&lowbar;&lowbar;CONCURRENT&lowbar;HASKELL&lowbar;&lowbar;</constant></primary></indexterm>
 165           <listitem>
 166             <para>This symbol is defined when pre-processing Haskell
 167             (input) and pre-processing C (GHC output).  Since GHC from
 168             verion 4.00 now supports concurrent haskell by default,
 169             this symbol is always defined.</para>
 170           </listitem>
 171         </varlistentry>
 172
 173         <varlistentry>
 174           <term><constant>&lowbar;&lowbar;PARALLEL&lowbar;HASKELL&lowbar;&lowbar;</constant></term>
 175           <indexterm><primary><constant>&lowbar;&lowbar;PARALLEL&lowbar;HASKELL&lowbar;&lowbar;</constant></primary></indexterm>
 176           <listitem>
 177             <para>Only defined when <option>-parallel</option> is in
 178             use!  This symbol is defined when pre-processing Haskell
 179             (input) and pre-processing C (GHC output).</para>
 180           </listitem>
 181         </varlistentry>
 182       </variablelist>
 183
 184       <para>A small word of warning: <option>-cpp</option> is not
 185       friendly to &ldquo;string gaps&rdquo;.<indexterm><primary>-cpp
 186       vs string gaps</primary></indexterm><indexterm><primary>string
 187       gaps vs -cpp</primary></indexterm>.  In other words, strings
 188       such as the following:</para>
 189
 190 <ProgramListing>
 191 strmod = "\
 192 \ p \
 193 \ "
 194 </ProgramListing>
 195
 196       <para>don't work with <option>-cpp</option>;
 197       <filename>/usr/bin/cpp</filename> elides the backslash-newline
 198       pairs.</para>
 199
 200       <para>However, it appears that if you add a space at the end of
 201       the line, then <command>cpp</command> (at least GNU
 202       <command>cpp</command> and possibly other
 203       <command>cpp</command>s) leaves the backslash-space pairs alone
 204       and the string gap works as expected.</para>
 205     </sect2>
 206
 207     <sect2 id="options-C-compiler">
 208       <title>Options affecting the C compiler (if applicable)</title>
 209
 210       <indexterm><primary>include-file options</primary></indexterm>
 211       <indexterm><primary>C compiler options</primary></indexterm>
 212       <indexterm><primary>GCC options</primary></indexterm>
 213
 214       <para>If you are compiling with lots of foreign calls, you may
 215       need to tell the C&nbsp;compiler about some
 216       <literal>&num;include</literal> files.  There is no real pretty
 217       way to do this, but you can use this hack from the
 218       command-line:</para>
 219
 220 <Screen>
 221 % ghc -c '-#include &lt;X/Xlib.h&gt;' Xstuff.lhs
 222 </Screen>
 223
 224     </sect2>
 225
 226     <sect2 id="options-codegen">
 227       <title>Options affecting code generation</title>
 228
 229       <variablelist>
 230         <varlistentry>
 231           <term><option>-fasm</option></term>
 232           <indexterm><primary><option>-fasm</option></primary></indexterm>
 233           <listitem>
 234             <para>Use GHC's native code generator rather than
 235             compiling via C.  This will compile faster (up to twice as
 236             fast), but may produce code that is slightly slower than
 237             compiling via C.  <option>-fasm</option> is the default
 238             when optimisation is off (see <xref
 239             linkend="options-optimise">).</para>
 240           </listitem>
 241         </varlistentry>
 242
 243         <varlistentry>
 244           <term><option>-fvia-C</option></term>
 245           <indexterm><primary><option>-fvia-C</option></primary>
 246           </indexterm>
 247           <listitem>
 248             <para>Compile via C instead of using the native code
 249             generator.  This is default for optimised compilations,
 250             and on architectures for which GHC doesn't have a native
 251             code generator.</para>
 252           </listitem>
 253         </varlistentry>
 254       </variablelist>
 255     </sect2>
 256
 257     <sect2 id="options-linker">
 258       <title>Options affecting linking</title>
 259
 260       <indexterm><primary>linker options</primary></indexterm>
 261       <indexterm><primary>ld options</primary></indexterm>
 262
 263
 264       <para>GHC has to link your code with various libraries, possibly
 265       including: user-supplied, GHC-supplied, and system-supplied
 266       (<option>-lm</option> math library, for example).</para>
 267
 268       <variablelist>
 269
 270         <varlistentry>
 271           <term><option>-l</option><replaceable>lib</replaceable></term>
 272           <indexterm><primary><option>-l</option></primary></indexterm>
 273           <listitem>
 274             <para>Link in the <replaceable>lib</replaceable> library.
 275             On Unix systems, this will be in a file called
 276             <filename>lib<replaceable>lib</replaceable>.a</filename>
 277             or
 278             <filename>lib<replaceable>lib</replaceable>.so</filename>
 279             which resides somewhere on the library directories path.</para>
 280
 281             <para>Because of the sad state of most UNIX linkers, the
 282             order of such options does matter.  If library
 283             <replaceable>foo</replaceable> requires library
 284             <replaceable>bar</replaceable>, then in general
 285             <option>-l</option><replaceable>foo</replaceable> should
 286             come <emphasis>before</emphasis>
 287             <option>-l</option><replaceable>bar</replaceable> on the
 288             command line.</para>
 289           </listitem>
 290         </varlistentry>
 291
 292         <varlistentry>
 293           <term><option>-package</option> <replaceable>name</replaceable></term>
 294           <indexterm><primary><option>-package</option></primary></indexterm>
 295           <listitem>
 296             <para>If you are using a Haskell &ldquo;package&rdquo;
 297             (see <xref linkend="packages">), don't forget to add the
 298             relevant <option>-package</option> option when linking the
 299             program too: it will cause the appropriate libraries to be
 300             linked in with the program.  Forgetting the
 301             <option>-package</option> option will likely result in
 302             several pages of link errors.</para>
 303           </listitem>
 304         </varlistentry>
 305
 306         <varlistentry>
 307           <term><option>-L</option><replaceable>dir</replaceable></term>
 308           <indexterm><primary><option>-L</option></primary></indexterm>
 309           <listitem>
 310             <para>Where to find user-supplied libraries&hellip;
 311             Prepend the directory <replaceable>dir</replaceable> to
 312             the library directories path.</para>
 313           </listitem>
 314         </varlistentry>
 315
 316         <varlistentry>
 317           <term><option>-split-objs</option></term>
 318           <indexterm><primary><option>-split-objs</option></primary></indexterm>
 319           <listitem>
 320             <para>Tell the linker to split the single object file that
 321             would normally be generated into multiple object files,
 322             one per top-level Haskell function or type in the module.
 323             We use this feature for building GHC's libraries libraries
 324             (warning: don't use it unless you know what you're
 325             doing!).</para>
 326           </listitem>
 327         </varlistentry>
 328
 329         <varlistentry>
 330           <term><option>-static</option></term>
 331           <indexterm><primary><option>-static</option></primary></indexterm>
 332           <listitem>
 333             <para>Tell the linker to avoid shared Haskell libraries,
 334             if possible.  This is the default.</para>
 335           </listitem>
 336         </varlistentry>
 337
 338         <varlistentry>
 339           <term><option>-dynamic</option></term>
 340           <indexterm><primary><option>-dynamic</option></primary></indexterm>
 341           <listitem>
 342             <para>Tell the linker to use shared Haskell libraries, if
 343             available (this option is only supported on Windows at the
 344             moment, and also note that your distribution of GHC may
 345             not have been supplied with shared libraries).</para>
 346           </listitem>
 347         </varlistentry>
 348
 349         <varlistentry>
 350           <term><option>-no-hs-main</option></term>
 351           <indexterm><primary><option>-no-hs-main</option></primary></indexterm>
 352           <indexterm><primary>linking Haskell libraries with foreign code</primary></indexterm>
 353           <listitem>
 354             <para>In the event you want to include ghc-compiled code
 355             as part of another (non-Haskell) program, the RTS will not
 356             be supplying its definition of <function>main()</function>
 357             at link-time, you will have to. To signal that to the
 358             driver script when linking, use
 359             <option>-no-hs-main</option>.</para>
 360
 361             <para>Notice that since the command-line passed to the
 362             linker is rather involved, you probably want to use
 363             <command>ghc</command> to do the final link of your
 364             `mixed-language' application. This is not a requirement
 365             though, just try linking once with <option>-v</option> on
 366             to see what options the driver passes through to the
 367             linker.</para>
 368           </listitem>
 369         </varlistentry>
 370       </variablelist>
 371     </sect2>
 372
 373   </sect1>
 374
 375 <!-- Emacs stuff:
 376      ;;; Local Variables: ***
 377      ;;; mode: sgml ***
 378      ;;; sgml-parent-document: ("users_guide.sgml" "book" "chapter") ***
 379      ;;; End: ***
 380  -->