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       </variablelist>
 257     </sect2>
 258
 259     <sect2 id="options-linker">
 260       <title>Options affecting linking</title>
 261
 262       <indexterm><primary>linker options</primary></indexterm>
 263       <indexterm><primary>ld options</primary></indexterm>
 264
 265
 266       <para>GHC has to link your code with various libraries, possibly
 267       including: user-supplied, GHC-supplied, and system-supplied
 268       (<option>-lm</option> math library, for example).</para>
 269
 270       <variablelist>
 271
 272         <varlistentry>
 273           <term><option>-l</option><replaceable>lib</replaceable></term>
 274           <indexterm><primary><option>-l</option></primary></indexterm>
 275           <listitem>
 276             <para>Link in the <replaceable>lib</replaceable> library.
 277             On Unix systems, this will be in a file called
 278             <filename>lib<replaceable>lib</replaceable>.a</filename>
 279             or
 280             <filename>lib<replaceable>lib</replaceable>.so</filename>
 281             which resides somewhere on the library directories path.</para>
 282
 283             <para>Because of the sad state of most UNIX linkers, the
 284             order of such options does matter.  If library
 285             <replaceable>foo</replaceable> requires library
 286             <replaceable>bar</replaceable>, then in general
 287             <option>-l</option><replaceable>foo</replaceable> should
 288             come <emphasis>before</emphasis>
 289             <option>-l</option><replaceable>bar</replaceable> on the
 290             command line.</para>
 291           </listitem>
 292         </varlistentry>
 293
 294         <varlistentry>
 295           <term><option>-package</option> <replaceable>name</replaceable></term>
 296           <indexterm><primary><option>-package</option></primary></indexterm>
 297           <listitem>
 298             <para>If you are using a Haskell &ldquo;package&rdquo;
 299             (see <xref linkend="packages">), don't forget to add the
 300             relevant <option>-package</option> option when linking the
 301             program too: it will cause the appropriate libraries to be
 302             linked in with the program.  Forgetting the
 303             <option>-package</option> option will likely result in
 304             several pages of link errors.</para>
 305           </listitem>
 306         </varlistentry>
 307
 308         <varlistentry>
 309           <term><option>-L</option><replaceable>dir</replaceable></term>
 310           <indexterm><primary><option>-L</option></primary></indexterm>
 311           <listitem>
 312             <para>Where to find user-supplied libraries&hellip;
 313             Prepend the directory <replaceable>dir</replaceable> to
 314             the library directories path.</para>
 315           </listitem>
 316         </varlistentry>
 317
 318         <varlistentry>
 319           <term><option>-split-objs</option></term>
 320           <indexterm><primary><option>-split-objs</option></primary></indexterm>
 321           <listitem>
 322             <para>Tell the linker to split the single object file that
 323             would normally be generated into multiple object files,
 324             one per top-level Haskell function or type in the module.
 325             We use this feature for building GHC's libraries libraries
 326             (warning: don't use it unless you know what you're
 327             doing!).</para>
 328           </listitem>
 329         </varlistentry>
 330
 331         <varlistentry>
 332           <term><option>-static</option></term>
 333           <indexterm><primary><option>-static</option></primary></indexterm>
 334           <listitem>
 335             <para>Tell the linker to avoid shared Haskell libraries,
 336             if possible.  This is the default.</para>
 337           </listitem>
 338         </varlistentry>
 339
 340         <varlistentry>
 341           <term><option>-dynamic</option></term>
 342           <indexterm><primary><option>-dynamic</option></primary></indexterm>
 343           <listitem>
 344             <para>Tell the linker to use shared Haskell libraries, if
 345             available (this option is only supported on Windows at the
 346             moment, and also note that your distribution of GHC may
 347             not have been supplied with shared libraries).</para>
 348           </listitem>
 349         </varlistentry>
 350
 351         <varlistentry>
 352           <term><option>-no-hs-main</option></term>
 353           <indexterm><primary><option>-no-hs-main</option></primary></indexterm>
 354           <indexterm><primary>linking Haskell libraries with foreign code</primary></indexterm>
 355           <listitem>
 356             <para>In the event you want to include ghc-compiled code
 357             as part of another (non-Haskell) program, the RTS will not
 358             be supplying its definition of <function>main()</function>
 359             at link-time, you will have to. To signal that to the
 360             driver script when linking, use
 361             <option>-no-hs-main</option>. In fact, this only has an
 362             effect when the RTS is compiled into a DLL; the
 363             rest of the time, static linking allows the RTS's
 364             <function>main()</function> to be overridden in the same
 365             way as any other library routine.</para>
 366
 367             <para>Notice that since the command-line passed to the
 368             linker is rather involved, you probably want to use
 369             <command>ghc</command> to do the final link of your
 370             `mixed-language' application. This is not a requirement
 371             though, just try linking once with <option>-v</option> on
 372             to see what options the driver passes through to the
 373             linker.</para>
 374           </listitem>
 375         </varlistentry>
 376       </variablelist>
 377     </sect2>
 378
 379   </sect1>
 380
 381 <!-- Emacs stuff:
 382      ;;; Local Variables: ***
 383      ;;; mode: sgml ***
 384      ;;; sgml-parent-document: ("users_guide.sgml" "book" "chapter") ***
 385      ;;; End: ***
 386  -->