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       <para>The C pre-processor <command>cpp</command> is run over
  45       your Haskell code only if the <option>-cpp</option> option
  46       <indexterm><primary>-cpp option</primary></indexterm> is given.
  47       Unless you are building a large system with significant doses of
  48       conditional compilation, you really shouldn't need it.</para>
  49
  50       <variablelist>
  51
  52         <varlistentry>
  53           <term><option>-D</option><replaceable>symbol</replaceable><optional>=<replaceable>value</replaceable></optional></term>
  54           <indexterm><primary><option>-D</option></primary></indexterm>
  55           <listitem>
  56             <para>Define macro <replaceable>symbol</replaceable> in the
  57             usual way.  NB: does <emphasis>not</emphasis> affect
  58             <option>-D</option> macros passed to the C&nbsp;compiler
  59             when compiling via C!  For those, use the
  60             <option>-optc-Dfoo</option> hack&hellip; (see <xref
  61             linkend="forcing-options-through">).</para>
  62           </listitem>
  63         </varlistentry>
  64
  65         <varlistentry>
  66           <term><option>-U</option><replaceable>symbol</replaceable></term>
  67           <indexterm><primary><option>-U</option></primary></indexterm>
  68           <listitem>
  69             <para> Undefine macro <replaceable>symbol</replaceable> in the
  70             usual way.</para>
  71           </listitem>
  72         </varlistentry>
  73
  74         <varlistentry>
  75           <term><option>-I</option><replaceable>dir</replaceable></term>
  76           <indexterm><primary><option>-I</option></primary></indexterm>
  77           <listitem>
  78             <para> Specify a directory in which to look for
  79             <literal>&num;include</literal> files, in the usual C
  80             way.</para>
  81           </listitem>
  82         </varlistentry>
  83       </variablelist>
  84
  85       <para>The GHC driver pre-defines several macros when processing
  86       Haskell source code (<filename>.hs</filename> or
  87       <filename>.lhs</filename> files):</para>
  88
  89       <variablelist>
  90
  91         <varlistentry>
  92           <term><constant>&lowbar;&lowbar;HASKELL98&lowbar;&lowbar;</constant></term>
  93           <indexterm><primary><literal>&lowbar;&lowbar;HASKELL98&lowbar;&lowbar;</literal></primary></indexterm>
  94           <listitem>
  95             <para>If defined, this means that GHC supports the
  96             language defined by the Haskell 98 report.</para>
  97           </listitem>
  98         </varlistentry>
  99
 100         <varlistentry>
 101           <term><constant>&lowbar;&lowbar;HASKELL&lowbar;&lowbar;=98</constant></term>
 102           <indexterm><primary><constant>&lowbar;&lowbar;HASKELL&lowbar;&lowbar;=98</constant></primary></indexterm>
 103           <listitem>
 104             <para>In GHC 4.04 and later, the
 105             <constant>&lowbar;&lowbar;HASKELL&lowbar;&lowbar;</constant>
 106             macro is defined as having the value
 107             <constant>98</constant>.</para>
 108           </listitem>
 109         </varlistentry>
 110
 111         <varlistentry>
 112           <term><constant>&lowbar;&lowbar;HASKELL1&lowbar;&lowbar;</constant></term>
 113           <indexterm><primary><constant>&lowbar;&lowbar;HASKELL1&lowbar;&lowbar;
 114           </constant></primary></indexterm>
 115           <listitem>
 116             <para>If defined to <replaceable>n</replaceable>, that
 117             means GHC supports the Haskell language defined in the
 118             Haskell report version <emphasis>1.n</emphasis>.
 119             Currently 5.  This macro is deprecated, and will probably
 120             disappear in future versions.</para>
 121           </listitem>
 122         </varlistentry>
 123
 124         <varlistentry>
 125           <term><constant>&lowbar;&lowbar;GLASGOW&lowbar;HASKELL&lowbar;&lowbar;</constant></term>
 126           <indexterm><primary><constant>&lowbar;&lowbar;GLASGOW&lowbar;HASKELL&lowbar;&lowbar;</constant></primary></indexterm>
 127           <listitem>
 128             <para>For version <replaceable>n</replaceable> of the GHC
 129             system, this will be <literal>&num;define</literal>d to
 130             <replaceable>100n</replaceable>.  For example, for version
 131             5.00, it is 500.</para>
 132
 133             <para>With any luck,
 134             <constant>&lowbar;&lowbar;GLASGOW&lowbar;HASKELL&lowbar;&lowbar;</constant>
 135             will be undefined in all other implementations that
 136             support C-style pre-processing.</para>
 137
 138             <para>(For reference: the comparable symbols for other
 139             systems are:
 140             <constant>&lowbar;&lowbar;HUGS&lowbar;&lowbar;</constant>
 141             for Hugs and
 142             <constant>&lowbar;&lowbar;HBC&lowbar;&lowbar;</constant>
 143             for Chalmers.)</para>
 144
 145             <para>NB. This macro is set when pre-processing both
 146             Haskell source and C source, including the C source
 147             generated from a Haskell module
 148             (i.e. <filename>.hs</filename>, <filename>.lhs</filename>,
 149             <filename>.c</filename> and <filename>.hc</filename>
 150             files).</para>
 151           </listitem>
 152         </varlistentry>
 153
 154         <varlistentry>
 155           <term><constant>&lowbar;&lowbar;CONCURRENT&lowbar;HASKELL&lowbar;&lowbar;</constant></term>
 156           <indexterm><primary><constant>&lowbar;&lowbar;CONCURRENT&lowbar;HASKELL&lowbar;&lowbar;</constant></primary></indexterm>
 157           <listitem>
 158             <para>This symbol is defined when pre-processing Haskell
 159             (input) and pre-processing C (GHC output).  Since GHC from
 160             verion 4.00 now supports concurrent haskell by default,
 161             this symbol is always defined.</para>
 162           </listitem>
 163         </varlistentry>
 164
 165         <varlistentry>
 166           <term><constant>&lowbar;&lowbar;PARALLEL&lowbar;HASKELL&lowbar;&lowbar;</constant></term>
 167           <indexterm><primary><constant>&lowbar;&lowbar;PARALLEL&lowbar;HASKELL&lowbar;&lowbar;</constant></primary></indexterm>
 168           <listitem>
 169             <para>Only defined when <option>-parallel</option> is in
 170             use!  This symbol is defined when pre-processing Haskell
 171             (input) and pre-processing C (GHC output).</para>
 172           </listitem>
 173         </varlistentry>
 174       </variablelist>
 175
 176       <para>A small word of warning: <option>-cpp</option> is not
 177       friendly to &ldquo;string gaps&rdquo;.<indexterm><primary>-cpp
 178       vs string gaps</primary></indexterm><indexterm><primary>string
 179       gaps vs -cpp</primary></indexterm>.  In other words, strings
 180       such as the following:</para>
 181
 182 <ProgramListing>
 183 strmod = "\
 184 \ p \
 185 \ "
 186 </ProgramListing>
 187
 188       <para>don't work with <option>-cpp</option>;
 189       <filename>/usr/bin/cpp</filename> elides the backslash-newline
 190       pairs.</para>
 191
 192       <para>However, it appears that if you add a space at the end of
 193       the line, then <command>cpp</command> (at least GNU
 194       <command>cpp</command> and possibly other
 195       <command>cpp</command>s) leaves the backslash-space pairs alone
 196       and the string gap works as expected.</para>
 197     </sect2>
 198
 199     <sect2 id="options-C-compiler">
 200       <title>Options affecting the C compiler (if applicable)</title>
 201
 202       <indexterm><primary>include-file options</primary></indexterm>
 203       <indexterm><primary>C compiler options</primary></indexterm>
 204       <indexterm><primary>GCC options</primary></indexterm>
 205
 206       <informaltable>
 207         <tgroup cols=3 align=left colsep=1 rowsep=1>
 208           <thead>
 209             <row>
 210               <entry>Flag</entry>
 211               <entry>Description</entry>
 212               <entry>Static/Dynamic</entry>
 213               <entry>Reverse</entry>
 214             </row>
 215           </thead>
 216           <tbody>
 217             <row>
 218               <entry><option>-#include</option> <replaceable>file</replaceable></entry>
 219               <entry>Include <replaceable>file</replaceable> when
 220               compiling the <filename>.hc</filename> file</entry>
 221               <entry>dynamic</entry>
 222               <entry>-</entry>
 223             </row>
 224           </tbody>
 225         </tgroup>
 226       </informaltable>
 227
 228       <para>If you are compiling with lots of foreign calls, you may
 229       need to tell the C&nbsp;compiler about some
 230       <literal>&num;include</literal> files.  There is no real pretty
 231       way to do this, but you can use this hack from the
 232       command-line:</para>
 233
 234 <Screen>
 235 % ghc -c '-#include &lt;X/Xlib.h&gt;' Xstuff.lhs
 236 </Screen>
 237
 238     </sect2>
 239
 240     <sect2 id="options-linker">
 241       <title>Options affecting linking</title>
 242
 243       <indexterm><primary>linker options</primary></indexterm>
 244       <indexterm><primary>ld options</primary></indexterm>
 245
 246
 247       <para>GHC has to link your code with various libraries, possibly
 248       including: user-supplied, GHC-supplied, and system-supplied
 249       (<option>-lm</option> math library, for example).</para>
 250
 251       <variablelist>
 252
 253         <varlistentry>
 254           <term><option>-l</option><replaceable>lib</replaceable></term>
 255           <indexterm><primary><option>-l</option></primary></indexterm>
 256           <listitem>
 257             <para>Link in the <replaceable>lib</replaceable> library.
 258             On Unix systems, this will be in a file called
 259             <filename>lib<replaceable>lib</replaceable>.a</filename>
 260             or
 261             <filename>lib<replaceable>lib</replaceable>.so</filename>
 262             which resides somewhere on the library directories path.</para>
 263
 264             <para>Because of the sad state of most UNIX linkers, the
 265             order of such options does matter.  If library
 266             <replaceable>foo</replaceable> requires library
 267             <replaceable>bar</replaceable>, then in general
 268             <option>-l</option><replaceable>foo</replaceable> should
 269             come <emphasis>before</emphasis>
 270             <option>-l</option><replaceable>bar</replaceable> on the
 271             command line.</para>
 272           </listitem>
 273         </varlistentry>
 274
 275         <varlistentry>
 276           <term><option>-package</option> <replaceable>name</replaceable></term>
 277           <indexterm><primary><option>-package</option></primary></indexterm>
 278           <listitem>
 279             <para>If you are using a Haskell &ldquo;package&rdquo;
 280             (see <xref linkend="packages">), don't forget to add the
 281             relevant <option>-package</option> option when linking the
 282             program too: it will cause the appropriate libraries to be
 283             linked in with the program.  Forgetting the
 284             <option>-package</option> option will likely result in
 285             several pages of link errors.</para>
 286           </listitem>
 287         </varlistentry>
 288
 289         <varlistentry>
 290           <term><option>-L</option><replaceable>dir</replaceable></term>
 291           <indexterm><primary><option>-L</option></primary></indexterm>
 292           <listitem>
 293             <para>Where to find user-supplied libraries&hellip;
 294             Prepend the directory <replaceable>dir</replaceable> to
 295             the library directories path.</para>
 296           </listitem>
 297         </varlistentry>
 298
 299         <varlistentry>
 300           <term><option>-split-objs</option></term>
 301           <indexterm><primary><option>-split-objs</option></primary></indexterm>
 302           <listitem>
 303             <para>Tell the linker to split the single object file that
 304             would normally be generated into multiple object files,
 305             one per top-level Haskell function or type in the module.
 306             We use this feature for building GHC's libraries libraries
 307             (warning: don't use it unless you know what you're
 308             doing!).</para>
 309           </listitem>
 310         </varlistentry>
 311
 312         <varlistentry>
 313           <term><option>-static</option></term>
 314           <indexterm><primary><option>-static</option></primary></indexterm>
 315           <listitem>
 316             <para>Tell the linker to avoid shared Haskell libraries,
 317             if possible.  This is the default.</para>
 318           </listitem>
 319         </varlistentry>
 320
 321         <varlistentry>
 322           <term><option>-dynamic</option></term>
 323           <indexterm><primary><option>-dynamic</option></primary></indexterm>
 324           <listitem>
 325             <para>Tell the linker to use shared Haskell libraries, if
 326             available (this option is only supported on Windows at the
 327             moment, and also note that your distribution of GHC may
 328             not have been supplied with shared libraries).</para>
 329           </listitem>
 330         </varlistentry>
 331
 332         <varlistentry>
 333           <term><option>-no-hs-main</option></term>
 334           <indexterm><primary><option>-no-hs-main</option></primary></indexterm>
 335           <indexterm><primary>linking Haskell libraries with foreign code</primary></indexterm>
 336           <listitem>
 337             <para>In the event you want to include ghc-compiled code
 338             as part of another (non-Haskell) program, the RTS will not
 339             be supplying its definition of <function>main()</function>
 340             at link-time, you will have to. To signal that to the
 341             driver script when linking, use
 342             <option>-no-hs-main</option>.</para>
 343
 344             <para>Notice that since the command-line passed to the
 345             linker is rather involved, you probably want to use
 346             <command>ghc</command> to do the final link of your
 347             `mixed-language' application. This is not a requirement
 348             though, just try linking once with <option>-v</option> on
 349             to see what options the driver passes through to the
 350             linker.</para>
 351           </listitem>
 352         </varlistentry>
 353       </variablelist>
 354     </sect2>
 355
 356   </sect1>
 357
 358 <!-- Emacs stuff:
 359      ;;; Local Variables: ***
 360      ;;; mode: sgml ***
 361      ;;; sgml-parent-document: ("users_guide.sgml" "book" "chapter") ***
 362      ;;; End: ***
 363  -->