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