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. This currently works on Mac OS X; it works on PowerPC Linux when
 672           using the native code generator. As with <option>-fPIC</option>,
 673           x86 Linux support is not quite ready yet. Windows is not supported,
 674           and it is a no-op on PowerPC64 Linux.</para>
 675           <para>Note that this option also causes GHC to use shared libraries
 676           when linking.</para>
 677         </listitem>
 678       </varlistentry>
 679     </variablelist>
 680   </sect2>
 681
 682   <sect2 id="options-linker">
 683     <title>Options affecting linking</title>
 684
 685     <indexterm><primary>linker options</primary></indexterm>
 686     <indexterm><primary>ld options</primary></indexterm>
 687
 688
 689     <para>GHC has to link your code with various libraries, possibly
 690     including: user-supplied, GHC-supplied, and system-supplied
 691     (<option>-lm</option> math library, for example).</para>
 692
 693     <variablelist>
 694
 695       <varlistentry>
 696         <term>
 697           <option>-l</option><replaceable>lib</replaceable>
 698           <indexterm><primary><option>-l</option></primary></indexterm>
 699         </term>
 700         <listitem>
 701           <para>Link in the <replaceable>lib</replaceable> library.
 702           On Unix systems, this will be in a file called
 703           <filename>lib<replaceable>lib</replaceable>.a</filename>
 704           or
 705           <filename>lib<replaceable>lib</replaceable>.so</filename>
 706           which resides somewhere on the library directories path.</para>
 707
 708           <para>Because of the sad state of most UNIX linkers, the
 709           order of such options does matter.  If library
 710           <replaceable>foo</replaceable> requires library
 711           <replaceable>bar</replaceable>, then in general
 712           <option>-l</option><replaceable>foo</replaceable> should
 713           come <emphasis>before</emphasis>
 714           <option>-l</option><replaceable>bar</replaceable> on the
 715           command line.</para>
 716
 717           <para>There's one other gotcha to bear in mind when using
 718           external libraries: if the library contains a
 719           <literal>main()</literal> function, then this will be
 720           linked in preference to GHC's own
 721           <literal>main()</literal> function
 722           (eg. <literal>libf2c</literal> and <literal>libl</literal>
 723           have their own <literal>main()</literal>s).  This is
 724           because GHC's <literal>main()</literal> comes from the
 725           <literal>HSrts</literal> library, which is normally
 726           included <emphasis>after</emphasis> all the other
 727           libraries on the linker's command line.  To force GHC's
 728           <literal>main()</literal> to be used in preference to any
 729           other <literal>main()</literal>s from external libraries,
 730           just add the option <option>-lHSrts</option> before any
 731           other libraries on the command line.</para>
 732         </listitem>
 733       </varlistentry>
 734
 735       <varlistentry>
 736         <term>
 737           <option>-c</option>
 738           <indexterm><primary><option>-c</option></primary></indexterm>
 739         </term>
 740         <listitem>
 741           <para>Omits the link step.  This option can be used with
 742             <option>&ndash;&ndash;make</option> to avoid the automatic linking
 743             that takes place if the program contains a <literal>Main</literal>
 744             module.</para>
 745         </listitem>
 746       </varlistentry>
 747
 748       <varlistentry>
 749         <term>
 750           <option>-package</option> <replaceable>name</replaceable>
 751           <indexterm><primary><option>-package</option></primary></indexterm>
 752         </term>
 753         <listitem>
 754           <para>If you are using a Haskell &ldquo;package&rdquo;
 755           (see <xref linkend="packages"/>), don't forget to add the
 756           relevant <option>-package</option> option when linking the
 757           program too: it will cause the appropriate libraries to be
 758           linked in with the program.  Forgetting the
 759           <option>-package</option> option will likely result in
 760           several pages of link errors.</para>
 761         </listitem>
 762       </varlistentry>
 763
 764       <varlistentry>
 765         <term>
 766           <option>-framework</option> <replaceable>name</replaceable>
 767           <indexterm><primary><option>-framework</option></primary></indexterm>
 768         </term>
 769         <listitem>
 770           <para>On Darwin/MacOS X only, link in the framework <replaceable>name</replaceable>.
 771           This option corresponds to the <option>-framework</option> option for Apple's Linker.
 772           Please note that frameworks and packages are two different things - frameworks don't
 773           contain any haskell code. Rather, they are Apple's way of packaging shared libraries.
 774           To link to Apple's &ldquo;Carbon&rdquo; API, for example, you'd use
 775           <option>-framework Carbon</option>.
 776           </para>
 777         </listitem>
 778       </varlistentry>
 779
 780       <varlistentry>
 781         <term>
 782           <option>-L</option><replaceable>dir</replaceable>
 783           <indexterm><primary><option>-L</option></primary></indexterm>
 784         </term>
 785         <listitem>
 786           <para>Where to find user-supplied libraries&hellip;
 787           Prepend the directory <replaceable>dir</replaceable> to
 788           the library directories path.</para>
 789         </listitem>
 790       </varlistentry>
 791
 792       <varlistentry>
 793         <term>
 794           <option>-framework-path</option><replaceable>dir</replaceable>
 795           <indexterm><primary><option>-framework-path</option></primary></indexterm>
 796         </term>
 797         <listitem>
 798           <para>On Darwin/MacOS X only, prepend the directory <replaceable>dir</replaceable> to
 799           the framework directories path. This option corresponds to the <option>-F</option>
 800           option for Apple's Linker (<option>-F</option> already means something else for GHC).</para>
 801         </listitem>
 802       </varlistentry>
 803
 804       <varlistentry>
 805         <term>
 806           <option>-split-objs</option>
 807           <indexterm><primary><option>-split-objs</option></primary></indexterm>
 808         </term>
 809         <listitem>
 810           <para>Tell the linker to split the single object file that
 811           would normally be generated into multiple object files,
 812           one per top-level Haskell function or type in the module.
 813           This only makes sense for libraries, where it means that
 814           executables linked against the library are smaller as they only
 815           link against the object files that they need. However, assembling
 816           all the sections separately is expensive, so this is slower than
 817           compiling normally.
 818           We use this feature for building GHC's libraries
 819           (warning: don't use it unless you know what you're
 820           doing!).</para>
 821         </listitem>
 822       </varlistentry>
 823
 824       <varlistentry>
 825         <term>
 826           <option>-static</option>
 827           <indexterm><primary><option>-static</option></primary></indexterm>
 828         </term>
 829         <listitem>
 830           <para>Tell the linker to avoid shared Haskell libraries,
 831           if possible.  This is the default.</para>
 832         </listitem>
 833       </varlistentry>
 834
 835       <varlistentry>
 836         <term>
 837           <option>-dynamic</option>
 838           <indexterm><primary><option>-dynamic</option></primary></indexterm>
 839         </term>
 840         <listitem>
 841           <para>Tell the linker to use shared Haskell libraries, if
 842           available (this option is only supported on Mac OS X at the
 843           moment, and also note that your distribution of GHC may
 844           not have been supplied with shared libraries).</para>
 845           <para>Note that this option also has an effect on
 846           code generation (see above).</para>
 847         </listitem>
 848       </varlistentry>
 849
 850       <varlistentry>
 851         <term>
 852           <option>-main-is <replaceable>thing</replaceable></option>
 853           <indexterm><primary><option>-main-is</option></primary></indexterm>
 854           <indexterm><primary>specifying your own main function</primary></indexterm>
 855         </term>
 856         <listitem>
 857           <para> The normal rule in Haskell is that your program must supply a <literal>main</literal>
 858             function in module <literal>Main</literal>.  When testing, it is often convenient
 859             to change which function is the "main" one, and the <option>-main-is</option> flag
 860             allows you to do so.  The  <replaceable>thing</replaceable> can be one of:
 861             <itemizedlist>
 862         <listitem><para>A lower-case identifier <literal>foo</literal>.  GHC assumes that the main function is <literal>Main.foo</literal>.</para></listitem>
 863         <listitem><para>An module name <literal>A</literal>.  GHC assumes that the main function is <literal>A.main</literal>.</para></listitem>
 864         <listitem><para>An qualified name <literal>A.foo</literal>.  GHC assumes that the main function is <literal>A.foo</literal>.</para></listitem>
 865         </itemizedlist>
 866             Strictly speaking, <option>-main-is</option> is not a link-phase flag at all; it has no effect on the link step.
 867             The flag must be specified when compiling the module containing the specified main function (e.g. module <literal>A</literal>
 868             in the latter two items above).  It has no effect for other modules,
 869             and hence can safely be given to <literal>ghc --make</literal>.
 870             However, if all the modules are otherwise up to date, you may need to force
 871             recompilation both of the module where the new "main" is, and of the
 872             module where the "main" function used to be;
 873             <literal>ghc</literal> is not clever
 874             enough to figure out that they both need recompiling.  You can
 875             force recompilation by removing the object file, or by using the
 876             <option>-fforce-recomp</option> flag.
 877             </para>
 878         </listitem>
 879       </varlistentry>
 880
 881       <varlistentry>
 882         <term>
 883           <option>-no-hs-main</option>
 884           <indexterm><primary><option>-no-hs-main</option></primary></indexterm>
 885           <indexterm><primary>linking Haskell libraries with foreign code</primary></indexterm>
 886         </term>
 887         <listitem>
 888           <para>In the event you want to include ghc-compiled code
 889           as part of another (non-Haskell) program, the RTS will not
 890           be supplying its definition of <function>main()</function>
 891           at link-time, you will have to. To signal that to the
 892           compiler when linking, use
 893           <option>-no-hs-main</option>. See also <xref linkend="using-own-main"/>.</para>
 894
 895           <para>Notice that since the command-line passed to the
 896           linker is rather involved, you probably want to use
 897           <command>ghc</command> to do the final link of your
 898           `mixed-language' application. This is not a requirement
 899           though, just try linking once with <option>-v</option> on
 900           to see what options the driver passes through to the
 901           linker.</para>
 902
 903           <para>The <option>-no-hs-main</option> flag can also be
 904           used to persuade the compiler to do the link step in
 905           <option>--make</option> mode when there is no Haskell
 906           <literal>Main</literal> module present (normally the
 907           compiler will not attempt linking when there is no
 908           <literal>Main</literal>).</para>
 909         </listitem>
 910       </varlistentry>
 911
 912       <varlistentry>
 913         <term>
 914           <option>-debug</option>
 915           <indexterm><primary><option>-debug</option></primary></indexterm>
 916         </term>
 917         <listitem>
 918           <para>Link the program with a debugging version of the
 919           runtime system.  The debugging runtime turns on numerous
 920           assertions and sanity checks, and provides extra options
 921           for producing debugging output at runtime (run the program
 922           with <literal>+RTS&nbsp;-?</literal> to see a list).</para>
 923         </listitem>
 924       </varlistentry>
 925
 926       <varlistentry>
 927         <term>
 928           <option>-threaded</option>
 929           <indexterm><primary><option>-threaded</option></primary></indexterm>
 930         </term>
 931         <listitem>
 932           <para>Link the program with the "threaded" version of the
 933           runtime system.  The threaded runtime system is so-called
 934           because it manages multiple OS threads, as opposed to the
 935           default runtime system which is purely
 936           single-threaded.</para>
 937
 938           <para>Note that you do <emphasis>not</emphasis> need
 939           <option>-threaded</option> in order to use concurrency; the
 940           single-threaded runtime supports concurrency between Haskell
 941           threads just fine.</para>
 942
 943           <para>The threaded runtime system provides the following
 944           benefits:</para>
 945
 946           <itemizedlist>
 947             <listitem>
 948               <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>
 949               machine.  See <xref linkend="using-smp" />.</para>
 950
 951               <para>The ability to make a foreign call that does not
 952               block all other Haskell threads.</para>
 953
 954               <para>The ability to invoke foreign exported Haskell
 955               functions from multiple OS threads.</para>
 956             </listitem>
 957           </itemizedlist>
 958
 959           <para>With <option>-threaded</option>, calls to foreign
 960           functions are made using the same OS thread that created the
 961           Haskell thread (if it was created by a call to a foreign
 962           exported Haskell function), or an arbitrary OS thread
 963           otherwise (if the Haskell thread was created by
 964           <literal>forkIO</literal>).</para>
 965
 966           <para>More details on the use of "bound threads" in the
 967           threaded runtime can be found in the <ulink
 968           url="../libraries/base/Control.Concurrent.html"><literal>Control.Concurrent</literal></ulink> module.</para>
 969         </listitem>
 970       </varlistentry>
 971
 972       <varlistentry>
 973         <term>
 974           <option>-fno-gen-manifest</option>
 975           <indexterm><primary><option>-fno-gen-manifest</option></primary>
 976           </indexterm>
 977         </term>
 978         <listitem>
 979           <para>On Windows, GHC normally generates a
 980             <firstterm>manifest</firstterm><indexterm><primary>manifest</primary>
 981             </indexterm>file when linking a binary.  The
 982             manifest is placed in the file
 983             <literal><replaceable>prog</replaceable>.exe.manifest</literal>
 984             where <replaceable>prog.exe</replaceable> is the name of the
 985             executable.  The manifest file currently serves just one purpose:
 986             it disables the "installer detection"<indexterm><primary>installer detection</primary>
 987             </indexterm>in Windows Vista that
 988             attempts to elevate privileges for executables with certain names
 989             (e.g. names containing "install", "setup" or "patch").  Without the
 990             manifest file to turn off installer detection, attempting to run an
 991             executable that Windows deems to be an installer will return a
 992             permission error code to the invoker.  Depending on the invoker,
 993             the result might be a dialog box asking the user for elevated
 994             permissions, or it might simply be a permission denied
 995             error.</para>
 996
 997           <para>Installer detection can be also turned off globally for the
 998             system using the security control panel, but GHC by default
 999             generates binaries that don't depend on the user having disabled
1000             installer detection.</para>
1001
1002           <para>The <option>-fno-gen-manifest</option> disables generation of
1003             the manifest file.  One reason to do this would be if you had
1004             a manifest file of your own, for example.</para>
1005
1006           <para>In the future, GHC might use the manifest file for more things,
1007             such as supplying the location of dependent DLLs.</para>
1008
1009           <para><option>-fno-gen-manifest</option> also implies
1010             <option>-fno-embed-manifest</option>, see below.</para>
1011         </listitem>
1012       </varlistentry>
1013
1014       <varlistentry>
1015         <term>
1016           <option>-fno-embed-manifest</option>
1017           <indexterm><primary><option>-fno-embed-manifest</option></primary>
1018           </indexterm>
1019         </term>
1020         <listitem>
1021           <para>The manifest file that GHC generates when linking a binary on
1022             Windows is also embedded in the executable itself, by default.
1023             This means that the binary can be distributed without having to
1024             supply the manifest file too.  The embedding is done by running
1025             <literal>windres</literal><indexterm><primary><literal>windres</literal></primary>
1026             </indexterm>; to see exactly what GHC does to embed the manifest,
1027             use the <option>-v</option> flag.  A GHC installation comes with
1028             its own copy of <literal>windres</literal> for this reason.</para>
1029
1030           <para>See also <option>-pgmwindres</option> (<xref
1031               linkend="replacing-phases" />) and
1032             <option>-optwindres</option> (<xref
1033                                             linkend="forcing-options-through"
1034               />).</para>
1035         </listitem>
1036       </varlistentry>
1037     </variablelist>
1038   </sect2>
1039
1040 </sect1>
1041
1042 <!-- Emacs stuff:
1043      ;;; Local Variables: ***
1044      ;;; mode: xml ***
1045      ;;; sgml-parent-document: ("users_guide.xml" "book" "chapter" "sect1") ***
1046      ;;; End: ***
1047  -->