docs/users_guide/phases.xml

   1 <?xml version="1.0" encoding="iso-8859-1"?>
   2 <sect1 id="options-phases">
   3   <title>Options related to a particular phase</title>
   4
   5   <sect2 id="replacing-phases">
   6     <title>Replacing the program for one or more phases</title>
   7     <indexterm><primary>phases, changing</primary></indexterm>
   8
   9     <para>You may specify that a different program be used for one
  10     of the phases of the compilation system, in place of whatever
  11     the <command>ghc</command> has wired into it.  For example, you
  12     might want to try a different assembler.  The following options
  13     allow you to change the external program used for a given
  14     compilation phase:</para>
  15
  16     <variablelist>
  17       <varlistentry>
  18         <term>
  19           <option>-pgmL</option> <replaceable>cmd</replaceable>
  20         <indexterm><primary><option>-pgmL</option></primary></indexterm>
  21         </term>
  22         <listitem>
  23           <para>Use <replaceable>cmd</replaceable> as the literate
  24           pre-processor.</para>
  25         </listitem>
  26       </varlistentry>
  27
  28       <varlistentry>
  29         <term>
  30           <option>-pgmP</option> <replaceable>cmd</replaceable>
  31           <indexterm><primary><option>-pgmP</option></primary></indexterm>
  32         </term>
  33         <listitem>
  34           <para>Use <replaceable>cmd</replaceable> as the C
  35           pre-processor (with <option>-cpp</option> only).</para>
  36         </listitem>
  37       </varlistentry>
  38
  39       <varlistentry>
  40         <term>
  41           <option>-pgmc</option> <replaceable>cmd</replaceable>
  42           <indexterm><primary><option>-pgmc</option></primary></indexterm>
  43         </term>
  44         <listitem>
  45           <para>Use <replaceable>cmd</replaceable> as the C
  46           compiler.</para>
  47         </listitem>
  48       </varlistentry>
  49
  50       <varlistentry>
  51         <term>
  52           <option>-pgmm</option> <replaceable>cmd</replaceable>
  53           <indexterm><primary><option>-pgmm</option></primary></indexterm>
  54         </term>
  55         <listitem>
  56           <para>Use <replaceable>cmd</replaceable> as the
  57           mangler.</para>
  58         </listitem>
  59       </varlistentry>
  60
  61       <varlistentry>
  62         <term>
  63           <option>-pgms</option> <replaceable>cmd</replaceable>
  64           <indexterm><primary><option>-pgms</option></primary></indexterm>
  65         </term>
  66         <listitem>
  67           <para>Use <replaceable>cmd</replaceable> as the
  68           splitter.</para>
  69         </listitem>
  70       </varlistentry>
  71
  72       <varlistentry>
  73         <term>
  74           <option>-pgma</option> <replaceable>cmd</replaceable>
  75           <indexterm><primary><option>-pgma</option></primary></indexterm>
  76         </term>
  77         <listitem>
  78           <para>Use <replaceable>cmd</replaceable> as the
  79           assembler.</para>
  80         </listitem>
  81       </varlistentry>
  82
  83       <varlistentry>
  84         <term>
  85           <option>-pgml</option> <replaceable>cmd</replaceable>
  86           <indexterm><primary><option>-pgml</option></primary></indexterm>
  87         </term>
  88         <listitem>
  89           <para>Use <replaceable>cmd</replaceable> as the
  90           linker.</para>
  91         </listitem>
  92       </varlistentry>
  93
  94       <varlistentry>
  95         <term>
  96           <option>-pgmdll</option> <replaceable>cmd</replaceable>
  97           <indexterm><primary><option>-pgmdll</option></primary></indexterm>
  98         </term>
  99         <listitem>
 100           <para>Use <replaceable>cmd</replaceable> as the DLL
 101           generator.</para>
 102         </listitem>
 103       </varlistentry>
 104
 105       <varlistentry>
 106         <term>
 107           <option>-pgmF</option> <replaceable>cmd</replaceable>
 108           <indexterm><primary><option>-pgmF</option></primary></indexterm>
 109         </term>
 110         <listitem>
 111           <para>Use <replaceable>cmd</replaceable> as the
 112           pre-processor (with <option>-F</option> only).</para>
 113         </listitem>
 114       </varlistentry>
 115
 116       <varlistentry>
 117         <term>
 118           <option>-pgmwindres</option> <replaceable>cmd</replaceable>
 119           <indexterm><primary><option>-pgmwindres</option></primary></indexterm>
 120         </term>
 121         <listitem>
 122           <para>Use <replaceable>cmd</replaceable> as the
 123           program to use for embedding manifests on Windows.  Normally this
 124             is the program <literal>windres</literal>, which is supplied with a
 125             GHC installation. See <option>-fno-embed-manifest</option> in <xref
 126               linkend="options-linker" />.</para>
 127         </listitem>
 128       </varlistentry>
 129     </variablelist>
 130   </sect2>
 131
 132   <sect2 id="forcing-options-through">
 133     <title>Forcing options to a particular phase</title>
 134     <indexterm><primary>forcing GHC-phase options</primary></indexterm>
 135
 136     <para>Options can be forced through to a particlar compilation
 137     phase, using the following flags:</para>
 138
 139     <variablelist>
 140       <varlistentry>
 141         <term>
 142           <option>-optL</option> <replaceable>option</replaceable>
 143           <indexterm><primary><option>-optL</option></primary></indexterm>
 144         </term>
 145         <listitem>
 146           <para>Pass <replaceable>option</replaceable> to the
 147           literate pre-processor</para>
 148         </listitem>
 149       </varlistentry>
 150       <varlistentry>
 151         <term>
 152           <option>-optP</option>  <replaceable>option</replaceable>
 153           <indexterm><primary><option>-optP</option></primary></indexterm>
 154         </term>
 155         <listitem>
 156           <para>Pass <replaceable>option</replaceable> to CPP (makes
 157           sense only if <option>-cpp</option> is also on).</para>
 158         </listitem>
 159       </varlistentry>
 160       <varlistentry>
 161         <term>
 162           <option>-optF</option> <replaceable>option</replaceable>
 163           <indexterm><primary><option>-optF</option></primary></indexterm>
 164         </term>
 165         <listitem>
 166           <para>Pass <replaceable>option</replaceable> to the
 167           custom pre-processor (see <xref linkend="pre-processor"/>).</para>
 168         </listitem>
 169       </varlistentry>
 170       <varlistentry>
 171         <term>
 172           <option>-optc</option> <replaceable>option</replaceable>
 173           <indexterm><primary><option>-optc</option></primary></indexterm>
 174         </term>
 175         <listitem>
 176           <para>Pass <replaceable>option</replaceable> to the C compiler.</para>
 177         </listitem>
 178       </varlistentry>
 179       <varlistentry>
 180         <term>
 181           <option>-optm</option>  <replaceable>option</replaceable>
 182           <indexterm><primary><option>-optm</option></primary></indexterm>
 183         </term>
 184         <listitem>
 185           <para>Pass <replaceable>option</replaceable> to the mangler.</para>
 186         </listitem>
 187       </varlistentry>
 188       <varlistentry>
 189         <term>
 190           <option>-opta</option>  <replaceable>option</replaceable>
 191           <indexterm><primary><option>-opta</option></primary></indexterm>
 192         </term>
 193         <listitem>
 194           <para>Pass <replaceable>option</replaceable> to the assembler.</para>
 195         </listitem>
 196       </varlistentry>
 197       <varlistentry>
 198         <term>
 199           <option>-optl</option> <replaceable>option</replaceable>
 200           <indexterm><primary><option>-optl</option></primary></indexterm>
 201         </term>
 202         <listitem>
 203           <para>Pass <replaceable>option</replaceable> to the linker.</para>
 204         </listitem>
 205       </varlistentry>
 206       <varlistentry>
 207         <term>
 208           <option>-optdll</option>  <replaceable>option</replaceable>
 209           <indexterm><primary><option>-optdll</option></primary></indexterm>
 210         </term>
 211         <listitem>
 212           <para>Pass <replaceable>option</replaceable> to the DLL generator.</para>
 213         </listitem>
 214       </varlistentry>
 215       <varlistentry>
 216         <term>
 217           <option>-optdep</option>  <replaceable>option</replaceable>
 218           <indexterm><primary><option>-optdep</option></primary></indexterm>
 219         </term>
 220         <listitem>
 221           <para>Pass <replaceable>option</replaceable> to the
 222           dependency generator.</para>
 223         </listitem>
 224       </varlistentry>
 225       <varlistentry>
 226         <term>
 227           <option>-optwindres</option>  <replaceable>option</replaceable>
 228           <indexterm><primary><option>-optwindres</option></primary></indexterm>
 229         </term>
 230         <listitem>
 231           <para>Pass <replaceable>option</replaceable> to
 232             <literal>windres</literal> when embedding manifests on Windows.
 233             See <option>-fno-embed-manifest</option> in <xref
 234               linkend="options-linker" />.</para>
 235         </listitem>
 236       </varlistentry>
 237     </variablelist>
 238
 239     <para>So, for example, to force an <option>-Ewurble</option>
 240     option to the assembler, you would tell the driver
 241     <option>-opta-Ewurble</option> (the dash before the E is
 242     required).</para>
 243
 244     <para>GHC is itself a Haskell program, so if you need to pass
 245     options directly to GHC's runtime system you can enclose them in
 246     <literal>+RTS ... -RTS</literal> (see <xref
 247     linkend="runtime-control"/>).</para>
 248
 249   </sect2>
 250
 251   <sect2 id="c-pre-processor">
 252     <title>Options affecting the C pre-processor</title>
 253
 254     <indexterm><primary>pre-processing: cpp</primary></indexterm>
 255     <indexterm><primary>C pre-processor options</primary></indexterm>
 256     <indexterm><primary>cpp, pre-processing with</primary></indexterm>
 257
 258     <variablelist>
 259
 260       <varlistentry>
 261         <term>
 262           <option>-cpp</option>
 263           <indexterm><primary><option>-cpp</option></primary></indexterm>
 264         </term>
 265         <listitem>
 266           <para>The C pre-processor <command>cpp</command> is run
 267           over your Haskell code only if the <option>-cpp</option>
 268           option <indexterm><primary>-cpp
 269           option</primary></indexterm> is given.  Unless you are
 270           building a large system with significant doses of
 271           conditional compilation, you really shouldn't need
 272           it.</para>
 273         </listitem>
 274       </varlistentry>
 275
 276       <varlistentry>
 277         <term>
 278           <option>-D</option><replaceable>symbol</replaceable><optional>=<replaceable>value</replaceable></optional>
 279           <indexterm><primary><option>-D</option></primary></indexterm>
 280         </term>
 281         <listitem>
 282           <para>Define macro <replaceable>symbol</replaceable> in the
 283           usual way.  NB: does <emphasis>not</emphasis> affect
 284           <option>-D</option> macros passed to the C&nbsp;compiler
 285           when compiling via C!  For those, use the
 286           <option>-optc-Dfoo</option> hack&hellip; (see <xref
 287           linkend="forcing-options-through"/>).</para>
 288         </listitem>
 289       </varlistentry>
 290
 291       <varlistentry>
 292         <term>
 293           <option>-U</option><replaceable>symbol</replaceable>
 294           <indexterm><primary><option>-U</option></primary></indexterm>
 295         </term>
 296         <listitem>
 297           <para> Undefine macro <replaceable>symbol</replaceable> in the
 298           usual way.</para>
 299         </listitem>
 300       </varlistentry>
 301
 302       <varlistentry>
 303         <term>
 304           <option>-I</option><replaceable>dir</replaceable>
 305           <indexterm><primary><option>-I</option></primary></indexterm>
 306         </term>
 307         <listitem>
 308           <para> Specify a directory in which to look for
 309           <literal>&num;include</literal> files, in the usual C
 310           way.</para>
 311         </listitem>
 312       </varlistentry>
 313     </variablelist>
 314
 315     <para>The GHC driver pre-defines several macros when processing
 316     Haskell source code (<filename>.hs</filename> or
 317     <filename>.lhs</filename> files).</para>
 318
 319     <para>The symbols defined by GHC are listed below.  To check which
 320     symbols are defined by your local GHC installation, the following
 321     trick is useful:</para>
 322
 323 <screen>$ ghc -E -optP-dM -cpp foo.hs
 324 $ cat foo.hspp</screen>
 325
 326     <para>(you need a file <filename>foo.hs</filename>, but it isn't
 327     actually used).</para>
 328
 329     <variablelist>
 330       <varlistentry>
 331         <term>
 332           <constant>&lowbar;&lowbar;HASKELL98&lowbar;&lowbar;</constant>
 333           <indexterm><primary><literal>&lowbar;&lowbar;HASKELL98&lowbar;&lowbar;</literal></primary></indexterm>
 334         </term>
 335         <listitem>
 336           <para>If defined, this means that GHC supports the
 337           language defined by the Haskell 98 report.</para>
 338         </listitem>
 339       </varlistentry>
 340
 341       <varlistentry>
 342         <term>
 343           <constant>&lowbar;&lowbar;HASKELL&lowbar;&lowbar;=98</constant>
 344           <indexterm><primary><constant>&lowbar;&lowbar;HASKELL&lowbar;&lowbar;=98</constant></primary></indexterm>
 345         </term>
 346         <listitem>
 347           <para>In GHC 4.04 and later, the
 348           <constant>&lowbar;&lowbar;HASKELL&lowbar;&lowbar;</constant>
 349           macro is defined as having the value
 350           <constant>98</constant>.</para>
 351         </listitem>
 352       </varlistentry>
 353
 354       <varlistentry>
 355         <term>
 356           <constant>&lowbar;&lowbar;HASKELL1&lowbar;&lowbar;</constant>
 357           <indexterm><primary><constant>&lowbar;&lowbar;HASKELL1&lowbar;&lowbar;</constant></primary></indexterm>
 358         </term>
 359         <listitem>
 360           <para>If defined to <replaceable>n</replaceable>, that
 361           means GHC supports the Haskell language defined in the
 362           Haskell report version <emphasis>1.n</emphasis>.
 363           Currently 5.  This macro is deprecated, and will probably
 364           disappear in future versions.</para>
 365         </listitem>
 366       </varlistentry>
 367
 368       <varlistentry>
 369         <term>
 370           <constant>&lowbar;&lowbar;GLASGOW&lowbar;HASKELL&lowbar;&lowbar;</constant>
 371           <indexterm><primary><constant>&lowbar;&lowbar;GLASGOW&lowbar;HASKELL&lowbar;&lowbar;</constant></primary></indexterm>
 372         </term>
 373         <listitem>
 374           <para>For version
 375           <literal><replaceable>x</replaceable>.<replaceable>y</replaceable>.<replaceable>z</replaceable></literal>
 376           of GHC, the value of
 377           <constant>&lowbar;&lowbar;GLASGOW&lowbar;HASKELL&lowbar;&lowbar;</constant>
 378           is the integer <replaceable>xyy</replaceable> (if
 379         <replaceable>y</replaceable> is a single digit, then a leading zero
 380         is added, so for example in version 6.2 of GHC,
 381         <literal>__GLASGOW_HASKELL__==602</literal>).  More
 382           information in <xref linkend="version-numbering"/>.</para>
 383
 384           <para>With any luck,
 385           <constant>&lowbar;&lowbar;GLASGOW&lowbar;HASKELL&lowbar;&lowbar;</constant>
 386           will be undefined in all other implementations that
 387           support C-style pre-processing.</para>
 388
 389           <para>(For reference: the comparable symbols for other
 390           systems are:
 391           <constant>&lowbar;&lowbar;HUGS&lowbar;&lowbar;</constant>
 392           for Hugs,
 393           <constant>&lowbar;&lowbar;NHC&lowbar;&lowbar;</constant>
 394           for nhc98, and
 395           <constant>&lowbar;&lowbar;HBC&lowbar;&lowbar;</constant>
 396           for hbc.)</para>
 397
 398           <para>NB. This macro is set when pre-processing both
 399           Haskell source and C source, including the C source
 400           generated from a Haskell module
 401           (i.e. <filename>.hs</filename>, <filename>.lhs</filename>,
 402           <filename>.c</filename> and <filename>.hc</filename>
 403           files).</para>
 404         </listitem>
 405       </varlistentry>
 406
 407       <varlistentry>
 408       <term>
 409           <constant>&lowbar;&lowbar;CONCURRENT&lowbar;HASKELL&lowbar;&lowbar;</constant>
 410           <indexterm><primary><constant>&lowbar;&lowbar;CONCURRENT&lowbar;HASKELL&lowbar;&lowbar;</constant></primary></indexterm>
 411         </term>
 412       <listitem>
 413         <para>This symbol is defined when pre-processing Haskell
 414           (input) and pre-processing C (GHC output).  Since GHC from
 415           verion 4.00 now supports concurrent haskell by default,
 416           this symbol is always defined.</para>
 417         </listitem>
 418       </varlistentry>
 419
 420       <varlistentry>
 421         <term>
 422           <constant>&lowbar;&lowbar;PARALLEL&lowbar;HASKELL&lowbar;&lowbar;</constant>
 423           <indexterm><primary><constant>&lowbar;&lowbar;PARALLEL&lowbar;HASKELL&lowbar;&lowbar;</constant></primary></indexterm>
 424         </term>
 425         <listitem>
 426           <para>Only defined when <option>-parallel</option> is in
 427           use!  This symbol is defined when pre-processing Haskell
 428           (input) and pre-processing C (GHC output).</para>
 429         </listitem>
 430       </varlistentry>
 431
 432       <varlistentry>
 433         <term>
 434           <constant><replaceable>os</replaceable>_HOST_OS=1</constant>
 435         </term>
 436         <listitem>
 437           <para>This define allows conditional compilation based on
 438           the Operating System, where<replaceable>os</replaceable> is
 439           the name of the current Operating System
 440           (eg. <literal>linux</literal>, <literal>mingw32</literal>
 441           for Windows, <literal>solaris</literal>, etc.).</para>
 442         </listitem>
 443       </varlistentry>
 444
 445       <varlistentry>
 446         <term>
 447           <constant><replaceable>arch</replaceable>_HOST_ARCH=1</constant>
 448         </term>
 449         <listitem>
 450           <para>This define allows conditional compilation based on
 451           the host architecture, where<replaceable>arch</replaceable>
 452           is the name of the current architecture
 453           (eg. <literal>i386</literal>, <literal>x86_64</literal>,
 454           <literal>powerpc</literal>, <literal>sparc</literal>,
 455           etc.).</para>
 456         </listitem>
 457       </varlistentry>
 458     </variablelist>
 459
 460     <sect3 id="cpp-string-gaps">
 461       <title>CPP and string gaps</title>
 462
 463       <para>A small word of warning: <option>-cpp</option> is not
 464       friendly to &ldquo;string gaps&rdquo;.<indexterm><primary>-cpp
 465       vs string gaps</primary></indexterm><indexterm><primary>string
 466       gaps vs -cpp</primary></indexterm>.  In other words, strings
 467       such as the following:</para>
 468
 469 <programlisting>strmod = "\
 470 \ p \
 471 \ "</programlisting>
 472
 473       <para>don't work with <option>-cpp</option>;
 474       <filename>/usr/bin/cpp</filename> elides the backslash-newline
 475       pairs.</para>
 476
 477       <para>However, it appears that if you add a space at the end
 478       of the line, then <command>cpp</command> (at least GNU
 479       <command>cpp</command> and possibly other
 480       <command>cpp</command>s) leaves the backslash-space pairs
 481       alone and the string gap works as expected.</para>
 482     </sect3>
 483   </sect2>
 484
 485   <sect2 id="pre-processor">
 486     <title>Options affecting a Haskell pre-processor</title>
 487
 488     <indexterm><primary>pre-processing: custom</primary></indexterm>
 489     <indexterm><primary>Pre-processor options</primary></indexterm>
 490
 491     <variablelist>
 492       <varlistentry>
 493         <term>
 494           <option>-F</option>
 495           <indexterm><primary><option>-F</option></primary></indexterm>
 496         </term>
 497         <listitem>
 498           <para>A custom pre-processor is run over your Haskell
 499           source file only if the <option>-F</option> option
 500           <indexterm><primary>-F</primary></indexterm> is
 501           given.</para>
 502
 503           <para>Running a custom pre-processor at compile-time is in
 504           some settings appropriate and useful. The
 505           <option>-F</option> option lets you run a pre-processor as
 506           part of the overall GHC compilation pipeline, which has
 507           the advantage over running a Haskell pre-processor
 508           separately in that it works in interpreted mode and you
 509           can continue to take reap the benefits of GHC's
 510           recompilation checker.</para>
 511
 512           <para>The pre-processor is run just before the Haskell
 513           compiler proper processes the Haskell input, but after the
 514           literate markup has been stripped away and (possibly) the
 515           C pre-processor has washed the Haskell input.</para>
 516
 517           <para>Use
 518           <option>-pgmF&nbsp;<replaceable>cmd</replaceable></option>
 519           to select the program to use as the preprocessor.  When
 520           invoked, the <replaceable>cmd</replaceable> pre-processor
 521           is given at least three arguments on its command-line: the
 522           first argument is the name of the original source file,
 523           the second is the name of the file holding the input, and
 524           the third is the name of the file where
 525           <replaceable>cmd</replaceable> should write its output
 526           to.</para>
 527
 528           <para>Additional arguments to the pre-processor can be
 529           passed in using the <option>-optF</option> option. These
 530           are fed to <replaceable>cmd</replaceable> on the command
 531           line after the three standard input and output
 532           arguments.</para>
 533
 534           <para>
 535           An example of a pre-processor is to convert your source files to the
 536           input encoding that GHC expects, i.e. create a script
 537           <literal>convert.sh</literal> containing the lines:
 538           </para>
 539
 540 <screen>#!/bin/sh
 541 ( echo "{-# LINE 1 \"$2\" #-}" ; iconv -f l1 -t utf-8 $2 ) > $3</screen>
 542
 543           <para>and pass <literal>-F -pgmF convert.sh</literal> to GHC.
 544           The <literal>-f l1</literal> option tells iconv to convert your
 545           Latin-1 file, supplied in argument <literal>$2</literal>, while
 546           the "-t utf-8" options tell iconv to return a UTF-8 encoded file.
 547           The result is redirected into argument <literal>$3</literal>.
 548           The <literal>echo "{-# LINE 1 \"$2\" #-}"</literal>
 549           just makes sure that your error positions are reported as
 550           in the original source file.</para>
 551         </listitem>
 552       </varlistentry>
 553     </variablelist>
 554   </sect2>
 555
 556   <sect2 id="options-C-compiler">
 557     <title>Options affecting the C compiler (if applicable)</title>
 558
 559     <indexterm><primary>include-file options</primary></indexterm>
 560     <indexterm><primary>C compiler options</primary></indexterm>
 561     <indexterm><primary>GCC options</primary></indexterm>
 562
 563     <para>If you are compiling with lots of foreign calls, you may
 564     need to tell the C&nbsp;compiler about some
 565     <literal>&num;include</literal> files.  The Right Way to do this is to
 566       add an <literal>INCLUDE</literal> pragma to the top of your source file
 567       (<xref linkend="include-pragma" />):</para>
 568
 569 <programlisting>{-# INCLUDE &lt;X/Xlib.h&gt; #-}</programlisting>
 570
 571     <para>Sometimes this isn't convenient.  In those cases there's an
 572       equivalent command-line option:</para>
 573
 574 <screen>% ghc -c '-#include &lt;X/Xlib.h&gt;' Xstuff.lhs</screen>
 575
 576     <indexterm><primary><option>-#include</option></primary>
 577     </indexterm>
 578
 579   </sect2>
 580
 581   <sect2 id="options-codegen">
 582     <title>Options affecting code generation</title>
 583
 584     <variablelist>
 585       <varlistentry>
 586         <term>
 587           <option>-fasm</option>
 588           <indexterm><primary><option>-fasm</option></primary></indexterm>
 589         </term>
 590         <listitem>
 591           <para>Use GHC's native code generator rather than
 592           compiling via C.  This will compile faster (up to twice as
 593           fast), but may produce code that is slightly slower than
 594           compiling via C.  <option>-fasm</option> is the default.</para>
 595         </listitem>
 596       </varlistentry>
 597
 598       <varlistentry>
 599         <term>
 600           <option>-fvia-C</option>
 601           <indexterm><primary><option>-fvia-C</option></primary></indexterm>
 602         </term>
 603         <listitem>
 604           <para>Compile via C instead of using the native code
 605           generator.  This is the default on architectures for which GHC
 606           doesn't have a native code generator.</para>
 607         </listitem>
 608       </varlistentry>
 609
 610       <varlistentry>
 611         <term>
 612           <option>-fno-code</option>
 613           <indexterm><primary><option>-fno-code</option></primary></indexterm>
 614         </term>
 615         <listitem>
 616           <para>Omit code generation (and all later phases)
 617           altogether.  Might be of some use if you just want to see
 618           dumps of the intermediate compilation phases.</para>
 619         </listitem>
 620       </varlistentry>
 621
 622       <varlistentry>
 623         <term>
 624           <option>-fobject-code</option>
 625           <indexterm><primary><option>-fobject-code</option></primary></indexterm>
 626         </term>
 627         <listitem>
 628           <para>Generate object code.  This is the default outside of
 629           GHCi, and can be used with GHCi to cause object code to be
 630           generated in preference to bytecode.</para>
 631         </listitem>
 632       </varlistentry>
 633
 634       <varlistentry>
 635         <term>
 636           <option>-fbyte-code</option>
 637           <indexterm><primary><option>-fbyte-code</option></primary></indexterm>
 638         </term>
 639         <listitem>
 640           <para>Generate byte-code instead of object-code.  This is
 641           the default in GHCi.  Byte-code can currently only be used
 642           in the interactive interpreter, not saved to disk.  This
 643           option is only useful for reversing the effect of
 644           <option>-fobject-code</option>.</para>
 645         </listitem>
 646       </varlistentry>
 647
 648       <varlistentry>
 649         <term>
 650           <option>-fPIC</option>
 651           <indexterm><primary><option>-fPIC</option></primary></indexterm>
 652         </term>
 653         <listitem>
 654           <para>Generate position-independent code (code that can be put into
 655           shared libraries). This currently works on Mac OS X; it works on
 656           PowerPC Linux when using the native code generator (-fasm).
 657           It is not quite ready to be used yet for x86 Linux.
 658           On Windows, position-independent code is never used,
 659           and on PowerPC64 Linux, position-independent code is always used,
 660           so the flag is a no-op on those platforms.</para>
 661         </listitem>
 662       </varlistentry>
 663
 664       <varlistentry>
 665         <term>
 666           <option>-dynamic</option>
 667         </term>
 668         <listitem>
 669           <para>When generating code, assume that entities imported from a
 670           different package will reside in a different shared library or
 671           binary.</para>
 672           <para>Note that this option also causes GHC to use shared libraries
 673           when linking.</para>
 674         </listitem>
 675       </varlistentry>
 676     </variablelist>
 677   </sect2>
 678
 679   <sect2 id="options-linker">
 680     <title>Options affecting linking</title>
 681
 682     <indexterm><primary>linker options</primary></indexterm>
 683     <indexterm><primary>ld options</primary></indexterm>
 684
 685
 686     <para>GHC has to link your code with various libraries, possibly
 687     including: user-supplied, GHC-supplied, and system-supplied
 688     (<option>-lm</option> math library, for example).</para>
 689
 690     <variablelist>
 691
 692       <varlistentry>
 693         <term>
 694           <option>-l</option><replaceable>lib</replaceable>
 695           <indexterm><primary><option>-l</option></primary></indexterm>
 696         </term>
 697         <listitem>
 698           <para>Link in the <replaceable>lib</replaceable> library.
 699           On Unix systems, this will be in a file called
 700           <filename>lib<replaceable>lib</replaceable>.a</filename>
 701           or
 702           <filename>lib<replaceable>lib</replaceable>.so</filename>
 703           which resides somewhere on the library directories path.</para>
 704
 705           <para>Because of the sad state of most UNIX linkers, the
 706           order of such options does matter.  If library
 707           <replaceable>foo</replaceable> requires library
 708           <replaceable>bar</replaceable>, then in general
 709           <option>-l</option><replaceable>foo</replaceable> should
 710           come <emphasis>before</emphasis>
 711           <option>-l</option><replaceable>bar</replaceable> on the
 712           command line.</para>
 713
 714           <para>There's one other gotcha to bear in mind when using
 715           external libraries: if the library contains a
 716           <literal>main()</literal> function, then this will be
 717           linked in preference to GHC's own
 718           <literal>main()</literal> function
 719           (eg. <literal>libf2c</literal> and <literal>libl</literal>
 720           have their own <literal>main()</literal>s).  This is
 721           because GHC's <literal>main()</literal> comes from the
 722           <literal>HSrts</literal> library, which is normally
 723           included <emphasis>after</emphasis> all the other
 724           libraries on the linker's command line.  To force GHC's
 725           <literal>main()</literal> to be used in preference to any
 726           other <literal>main()</literal>s from external libraries,
 727           just add the option <option>-lHSrts</option> before any
 728           other libraries on the command line.</para>
 729         </listitem>
 730       </varlistentry>
 731
 732       <varlistentry>
 733         <term>
 734           <option>-c</option>
 735           <indexterm><primary><option>-c</option></primary></indexterm>
 736         </term>
 737         <listitem>
 738           <para>Omits the link step.  This option can be used with
 739             <option>&ndash;&ndash;make</option> to avoid the automatic linking
 740             that takes place if the program contains a <literal>Main</literal>
 741             module.</para>
 742         </listitem>
 743       </varlistentry>
 744
 745       <varlistentry>
 746         <term>
 747           <option>-package</option> <replaceable>name</replaceable>
 748           <indexterm><primary><option>-package</option></primary></indexterm>
 749         </term>
 750         <listitem>
 751           <para>If you are using a Haskell &ldquo;package&rdquo;
 752           (see <xref linkend="packages"/>), don't forget to add the
 753           relevant <option>-package</option> option when linking the
 754           program too: it will cause the appropriate libraries to be
 755           linked in with the program.  Forgetting the
 756           <option>-package</option> option will likely result in
 757           several pages of link errors.</para>
 758         </listitem>
 759       </varlistentry>
 760
 761       <varlistentry>
 762         <term>
 763           <option>-framework</option> <replaceable>name</replaceable>
 764           <indexterm><primary><option>-framework</option></primary></indexterm>
 765         </term>
 766         <listitem>
 767           <para>On Darwin/MacOS X only, link in the framework <replaceable>name</replaceable>.
 768           This option corresponds to the <option>-framework</option> option for Apple's Linker.
 769           Please note that frameworks and packages are two different things - frameworks don't
 770           contain any haskell code. Rather, they are Apple's way of packaging shared libraries.
 771           To link to Apple's &ldquo;Carbon&rdquo; API, for example, you'd use
 772           <option>-framework Carbon</option>.
 773           </para>
 774         </listitem>
 775       </varlistentry>
 776
 777       <varlistentry>
 778         <term>
 779           <option>-L</option><replaceable>dir</replaceable>
 780           <indexterm><primary><option>-L</option></primary></indexterm>
 781         </term>
 782         <listitem>
 783           <para>Where to find user-supplied libraries&hellip;
 784           Prepend the directory <replaceable>dir</replaceable> to
 785           the library directories path.</para>
 786         </listitem>
 787       </varlistentry>
 788
 789       <varlistentry>
 790         <term>
 791           <option>-framework-path</option><replaceable>dir</replaceable>
 792           <indexterm><primary><option>-framework-path</option></primary></indexterm>
 793         </term>
 794         <listitem>
 795           <para>On Darwin/MacOS X only, prepend the directory <replaceable>dir</replaceable> to
 796           the framework directories path. This option corresponds to the <option>-F</option>
 797           option for Apple's Linker (<option>-F</option> already means something else for GHC).</para>
 798         </listitem>
 799       </varlistentry>
 800
 801       <varlistentry>
 802         <term>
 803           <option>-split-objs</option>
 804           <indexterm><primary><option>-split-objs</option></primary></indexterm>
 805         </term>
 806         <listitem>
 807           <para>Tell the linker to split the single object file that
 808           would normally be generated into multiple object files,
 809           one per top-level Haskell function or type in the module.
 810           This only makes sense for libraries, where it means that
 811           executables linked against the library are smaller as they only
 812           link against the object files that they need. However, assembling
 813           all the sections separately is expensive, so this is slower than
 814           compiling normally.
 815           We use this feature for building GHC's libraries
 816           (warning: don't use it unless you know what you're
 817           doing!).</para>
 818         </listitem>
 819       </varlistentry>
 820
 821       <varlistentry>
 822         <term>
 823           <option>-static</option>
 824           <indexterm><primary><option>-static</option></primary></indexterm>
 825         </term>
 826         <listitem>
 827           <para>Tell the linker to avoid shared Haskell libraries,
 828           if possible.  This is the default.</para>
 829         </listitem>
 830       </varlistentry>
 831
 832       <varlistentry>
 833         <term>
 834           <option>-dynamic</option>
 835           <indexterm><primary><option>-dynamic</option></primary></indexterm>
 836         </term>
 837         <listitem>
 838           <para>This flag switches to shared Haskell libraries for
 839           linking. See <xref linkend="building-packages" /> on how to
 840           create them.</para>
 841
 842           <para>Note that this option also has an effect on
 843           code generation (see above).</para>
 844         </listitem>
 845       </varlistentry>
 846
 847       <varlistentry>
 848         <term>
 849           <option>-shared</option>
 850           <indexterm><primary><option>-shared</option></primary></indexterm>
 851         </term>
 852         <listitem>
 853           <para>Instead of creating an executable, GHC produces a
 854           shared object with this linker flag. Depending on the
 855           operating system target, this might be an ELF DSO, a Windows
 856           DLL, or a Mac OS dylib. GHC hides the operating system
 857           details beneath this uniform flag.</para>
 858
 859           <para>The flags <option>-dynamic</option>/<option>-static</option> control whether the
 860           resulting shared object links statically or dynamically to
 861           Haskell package libraries given as <option>-package</option> option. Non-Haskell
 862           libraries are linked as gcc would regularly link it on your
 863           system, e.g. on most ELF system the linker uses the dynamic
 864           libraries when found.</para>
 865
 866           <para>Object files linked into shared objects must be
 867           compiled with <option>-fPIC</option>, see <xref linkend="options-codegen" /></para>
 868
 869           <para>When creating shared objects for Haskell packages, the
 870           shared object must be named properly, so that GHC recognizes
 871           the shared object when linked against this package. See
 872           shared object name mangling.</para>
 873         </listitem>
 874       </varlistentry>
 875
 876
 877       <varlistentry>
 878         <term>
 879           <option>-main-is <replaceable>thing</replaceable></option>
 880           <indexterm><primary><option>-main-is</option></primary></indexterm>
 881           <indexterm><primary>specifying your own main function</primary></indexterm>
 882         </term>
 883         <listitem>
 884           <para> The normal rule in Haskell is that your program must supply a <literal>main</literal>
 885             function in module <literal>Main</literal>.  When testing, it is often convenient
 886             to change which function is the "main" one, and the <option>-main-is</option> flag
 887             allows you to do so.  The  <replaceable>thing</replaceable> can be one of:
 888             <itemizedlist>
 889         <listitem><para>A lower-case identifier <literal>foo</literal>.  GHC assumes that the main function is <literal>Main.foo</literal>.</para></listitem>
 890         <listitem><para>An module name <literal>A</literal>.  GHC assumes that the main function is <literal>A.main</literal>.</para></listitem>
 891         <listitem><para>An qualified name <literal>A.foo</literal>.  GHC assumes that the main function is <literal>A.foo</literal>.</para></listitem>
 892         </itemizedlist>
 893             Strictly speaking, <option>-main-is</option> is not a link-phase flag at all; it has no effect on the link step.
 894             The flag must be specified when compiling the module containing the specified main function (e.g. module <literal>A</literal>
 895             in the latter two items above).  It has no effect for other modules,
 896             and hence can safely be given to <literal>ghc --make</literal>.
 897             However, if all the modules are otherwise up to date, you may need to force
 898             recompilation both of the module where the new "main" is, and of the
 899             module where the "main" function used to be;
 900             <literal>ghc</literal> is not clever
 901             enough to figure out that they both need recompiling.  You can
 902             force recompilation by removing the object file, or by using the
 903             <option>-fforce-recomp</option> flag.
 904             </para>
 905         </listitem>
 906       </varlistentry>
 907
 908       <varlistentry>
 909         <term>
 910           <option>-no-hs-main</option>
 911           <indexterm><primary><option>-no-hs-main</option></primary></indexterm>
 912           <indexterm><primary>linking Haskell libraries with foreign code</primary></indexterm>
 913         </term>
 914         <listitem>
 915           <para>In the event you want to include ghc-compiled code
 916           as part of another (non-Haskell) program, the RTS will not
 917           be supplying its definition of <function>main()</function>
 918           at link-time, you will have to. To signal that to the
 919           compiler when linking, use
 920           <option>-no-hs-main</option>. See also <xref linkend="using-own-main"/>.</para>
 921
 922           <para>Notice that since the command-line passed to the
 923           linker is rather involved, you probably want to use
 924           <command>ghc</command> to do the final link of your
 925           `mixed-language' application. This is not a requirement
 926           though, just try linking once with <option>-v</option> on
 927           to see what options the driver passes through to the
 928           linker.</para>
 929
 930           <para>The <option>-no-hs-main</option> flag can also be
 931           used to persuade the compiler to do the link step in
 932           <option>--make</option> mode when there is no Haskell
 933           <literal>Main</literal> module present (normally the
 934           compiler will not attempt linking when there is no
 935           <literal>Main</literal>).</para>
 936         </listitem>
 937       </varlistentry>
 938
 939       <varlistentry>
 940         <term>
 941           <option>-debug</option>
 942           <indexterm><primary><option>-debug</option></primary></indexterm>
 943         </term>
 944         <listitem>
 945           <para>Link the program with a debugging version of the
 946           runtime system.  The debugging runtime turns on numerous
 947           assertions and sanity checks, and provides extra options
 948           for producing debugging output at runtime (run the program
 949           with <literal>+RTS&nbsp;-?</literal> to see a list).</para>
 950         </listitem>
 951       </varlistentry>
 952
 953       <varlistentry>
 954         <term>
 955           <option>-threaded</option>
 956           <indexterm><primary><option>-threaded</option></primary></indexterm>
 957         </term>
 958         <listitem>
 959           <para>Link the program with the "threaded" version of the
 960           runtime system.  The threaded runtime system is so-called
 961           because it manages multiple OS threads, as opposed to the
 962           default runtime system which is purely
 963           single-threaded.</para>
 964
 965           <para>Note that you do <emphasis>not</emphasis> need
 966           <option>-threaded</option> in order to use concurrency; the
 967           single-threaded runtime supports concurrency between Haskell
 968           threads just fine.</para>
 969
 970           <para>The threaded runtime system provides the following
 971           benefits:</para>
 972
 973           <itemizedlist>
 974             <listitem>
 975               <para>Parallelism<indexterm><primary>parallelism</primary></indexterm> on a multiprocessor<indexterm><primary>multiprocessor</primary></indexterm><indexterm><primary>SMP</primary></indexterm> or multicore<indexterm><primary>multicore</primary></indexterm>
 976               machine.  See <xref linkend="using-smp" />.</para>
 977
 978               <para>The ability to make a foreign call that does not
 979               block all other Haskell threads.</para>
 980
 981               <para>The ability to invoke foreign exported Haskell
 982               functions from multiple OS threads.</para>
 983             </listitem>
 984           </itemizedlist>
 985
 986           <para>With <option>-threaded</option>, calls to foreign
 987           functions are made using the same OS thread that created the
 988           Haskell thread (if it was created by a call to a foreign
 989           exported Haskell function), or an arbitrary OS thread
 990           otherwise (if the Haskell thread was created by
 991           <literal>forkIO</literal>).</para>
 992
 993           <para>More details on the use of "bound threads" in the
 994           threaded runtime can be found in the <ulink
 995           url="../libraries/base/Control.Concurrent.html"><literal>Control.Concurrent</literal></ulink> module.</para>
 996         </listitem>
 997       </varlistentry>
 998
 999       <varlistentry>
1000         <term>
1001           <option>-fno-gen-manifest</option>
1002           <indexterm><primary><option>-fno-gen-manifest</option></primary>
1003           </indexterm>
1004         </term>
1005         <listitem>
1006           <para>On Windows, GHC normally generates a
1007             <firstterm>manifest</firstterm><indexterm><primary>manifest</primary>
1008             </indexterm>file when linking a binary.  The
1009             manifest is placed in the file
1010             <literal><replaceable>prog</replaceable>.exe.manifest</literal>
1011             where <replaceable>prog.exe</replaceable> is the name of the
1012             executable.  The manifest file currently serves just one purpose:
1013             it disables the "installer detection"<indexterm><primary>installer detection</primary>
1014             </indexterm>in Windows Vista that
1015             attempts to elevate privileges for executables with certain names
1016             (e.g. names containing "install", "setup" or "patch").  Without the
1017             manifest file to turn off installer detection, attempting to run an
1018             executable that Windows deems to be an installer will return a
1019             permission error code to the invoker.  Depending on the invoker,
1020             the result might be a dialog box asking the user for elevated
1021             permissions, or it might simply be a permission denied
1022             error.</para>
1023
1024           <para>Installer detection can be also turned off globally for the
1025             system using the security control panel, but GHC by default
1026             generates binaries that don't depend on the user having disabled
1027             installer detection.</para>
1028
1029           <para>The <option>-fno-gen-manifest</option> disables generation of
1030             the manifest file.  One reason to do this would be if you had
1031             a manifest file of your own, for example.</para>
1032
1033           <para>In the future, GHC might use the manifest file for more things,
1034             such as supplying the location of dependent DLLs.</para>
1035
1036           <para><option>-fno-gen-manifest</option> also implies
1037             <option>-fno-embed-manifest</option>, see below.</para>
1038         </listitem>
1039       </varlistentry>
1040
1041       <varlistentry>
1042         <term>
1043           <option>-fno-embed-manifest</option>
1044           <indexterm><primary><option>-fno-embed-manifest</option></primary>
1045           </indexterm>
1046         </term>
1047         <listitem>
1048           <para>The manifest file that GHC generates when linking a binary on
1049             Windows is also embedded in the executable itself, by default.
1050             This means that the binary can be distributed without having to
1051             supply the manifest file too.  The embedding is done by running
1052             <literal>windres</literal><indexterm><primary><literal>windres</literal></primary>
1053             </indexterm>; to see exactly what GHC does to embed the manifest,
1054             use the <option>-v</option> flag.  A GHC installation comes with
1055             its own copy of <literal>windres</literal> for this reason.</para>
1056
1057           <para>See also <option>-pgmwindres</option> (<xref
1058               linkend="replacing-phases" />) and
1059             <option>-optwindres</option> (<xref
1060                                             linkend="forcing-options-through"
1061               />).</para>
1062         </listitem>
1063       </varlistentry>
1064     </variablelist>
1065   </sect2>
1066
1067 </sect1>
1068
1069 <!-- Emacs stuff:
1070      ;;; Local Variables: ***
1071      ;;; mode: xml ***
1072      ;;; sgml-parent-document: ("users_guide.xml" "book" "chapter" "sect1") ***
1073      ;;; End: ***
1074  -->