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 C.  This will compile faster (up to twice as
 547           fast), but may produce code that is slightly slower than
 548           compiling via C.  <option>-fasm</option> is the default.</para>
 549         </listitem>
 550       </varlistentry>
 551
 552       <varlistentry>
 553         <term>
 554           <option>-fvia-C</option>
 555           <indexterm><primary><option>-fvia-C</option></primary></indexterm>
 556         </term>
 557         <listitem>
 558           <para>Compile via C instead of using the native code
 559           generator.  This is the default on architectures for which GHC
 560           doesn't have a native code generator.</para>
 561         </listitem>
 562       </varlistentry>
 563
 564       <varlistentry>
 565         <term>
 566           <option>-fllvm</option>
 567           <indexterm><primary><option>-fllvm</option></primary></indexterm>
 568         </term>
 569         <listitem>
 570           <para>Compile via LLVM instead of using the native code
 571           generator. This will generally take slightly longer than the
 572           native code generator to compile but quicker than compiling
 573           via C. Produced code is generally the same speed or faster
 574           than the other two code generators. Compiling via LLVM
 575           requires LLVM version 2.7 or later to be on the path.</para>
 576         </listitem>
 577       </varlistentry>
 578
 579       <varlistentry>
 580         <term>
 581           <option>-fno-code</option>
 582           <indexterm><primary><option>-fno-code</option></primary></indexterm>
 583         </term>
 584         <listitem>
 585           <para>Omit code generation (and all later phases)
 586           altogether.  Might be of some use if you just want to see
 587           dumps of the intermediate compilation phases.</para>
 588         </listitem>
 589       </varlistentry>
 590
 591       <varlistentry>
 592         <term>
 593           <option>-fobject-code</option>
 594           <indexterm><primary><option>-fobject-code</option></primary></indexterm>
 595         </term>
 596         <listitem>
 597           <para>Generate object code.  This is the default outside of
 598           GHCi, and can be used with GHCi to cause object code to be
 599           generated in preference to bytecode.</para>
 600         </listitem>
 601       </varlistentry>
 602
 603       <varlistentry>
 604         <term>
 605           <option>-fbyte-code</option>
 606           <indexterm><primary><option>-fbyte-code</option></primary></indexterm>
 607         </term>
 608         <listitem>
 609           <para>Generate byte-code instead of object-code.  This is
 610           the default in GHCi.  Byte-code can currently only be used
 611           in the interactive interpreter, not saved to disk.  This
 612           option is only useful for reversing the effect of
 613           <option>-fobject-code</option>.</para>
 614         </listitem>
 615       </varlistentry>
 616
 617       <varlistentry>
 618         <term>
 619           <option>-fPIC</option>
 620           <indexterm><primary><option>-fPIC</option></primary></indexterm>
 621         </term>
 622         <listitem>
 623           <para>Generate position-independent code (code that can be put into
 624           shared libraries). This currently works on Linux x86 and x86-64 when
 625           using the native code generator (-fasm).
 626           On Windows, position-independent code is never used
 627           so the flag is a no-op on that platform.</para>
 628         </listitem>
 629       </varlistentry>
 630
 631       <varlistentry>
 632         <term>
 633           <option>-dynamic</option>
 634         </term>
 635         <listitem>
 636           <para>When generating code, assume that entities imported from a
 637           different package will reside in a different shared library or
 638           binary.</para>
 639           <para>Note that using this option when linking causes GHC to link
 640           against shared libraries.</para>
 641         </listitem>
 642       </varlistentry>
 643     </variablelist>
 644   </sect2>
 645
 646   <sect2 id="options-linker">
 647     <title>Options affecting linking</title>
 648
 649     <indexterm><primary>linker options</primary></indexterm>
 650     <indexterm><primary>ld options</primary></indexterm>
 651
 652
 653     <para>GHC has to link your code with various libraries, possibly
 654     including: user-supplied, GHC-supplied, and system-supplied
 655     (<option>-lm</option> math library, for example).</para>
 656
 657     <variablelist>
 658
 659       <varlistentry>
 660         <term>
 661           <option>-l</option><replaceable>lib</replaceable>
 662           <indexterm><primary><option>-l</option></primary></indexterm>
 663         </term>
 664         <listitem>
 665           <para>Link in the <replaceable>lib</replaceable> library.
 666           On Unix systems, this will be in a file called
 667           <filename>lib<replaceable>lib</replaceable>.a</filename>
 668           or
 669           <filename>lib<replaceable>lib</replaceable>.so</filename>
 670           which resides somewhere on the library directories path.</para>
 671
 672           <para>Because of the sad state of most UNIX linkers, the
 673           order of such options does matter.  If library
 674           <replaceable>foo</replaceable> requires library
 675           <replaceable>bar</replaceable>, then in general
 676           <option>-l</option><replaceable>foo</replaceable> should
 677           come <emphasis>before</emphasis>
 678           <option>-l</option><replaceable>bar</replaceable> on the
 679           command line.</para>
 680
 681           <para>There's one other gotcha to bear in mind when using
 682           external libraries: if the library contains a
 683           <literal>main()</literal> function, then this will be
 684           linked in preference to GHC's own
 685           <literal>main()</literal> function
 686           (eg. <literal>libf2c</literal> and <literal>libl</literal>
 687           have their own <literal>main()</literal>s).  This is
 688           because GHC's <literal>main()</literal> comes from the
 689           <literal>HSrts</literal> library, which is normally
 690           included <emphasis>after</emphasis> all the other
 691           libraries on the linker's command line.  To force GHC's
 692           <literal>main()</literal> to be used in preference to any
 693           other <literal>main()</literal>s from external libraries,
 694           just add the option <option>-lHSrts</option> before any
 695           other libraries on the command line.</para>
 696         </listitem>
 697       </varlistentry>
 698
 699       <varlistentry>
 700         <term>
 701           <option>-c</option>
 702           <indexterm><primary><option>-c</option></primary></indexterm>
 703         </term>
 704         <listitem>
 705           <para>Omits the link step.  This option can be used with
 706             <option>&ndash;&ndash;make</option> to avoid the automatic linking
 707             that takes place if the program contains a <literal>Main</literal>
 708             module.</para>
 709         </listitem>
 710       </varlistentry>
 711
 712       <varlistentry>
 713         <term>
 714           <option>-package</option> <replaceable>name</replaceable>
 715           <indexterm><primary><option>-package</option></primary></indexterm>
 716         </term>
 717         <listitem>
 718           <para>If you are using a Haskell &ldquo;package&rdquo;
 719           (see <xref linkend="packages"/>), don't forget to add the
 720           relevant <option>-package</option> option when linking the
 721           program too: it will cause the appropriate libraries to be
 722           linked in with the program.  Forgetting the
 723           <option>-package</option> option will likely result in
 724           several pages of link errors.</para>
 725         </listitem>
 726       </varlistentry>
 727
 728       <varlistentry>
 729         <term>
 730           <option>-framework</option> <replaceable>name</replaceable>
 731           <indexterm><primary><option>-framework</option></primary></indexterm>
 732         </term>
 733         <listitem>
 734           <para>On Darwin/MacOS X only, link in the framework <replaceable>name</replaceable>.
 735           This option corresponds to the <option>-framework</option> option for Apple's Linker.
 736           Please note that frameworks and packages are two different things - frameworks don't
 737           contain any haskell code. Rather, they are Apple's way of packaging shared libraries.
 738           To link to Apple's &ldquo;Carbon&rdquo; API, for example, you'd use
 739           <option>-framework Carbon</option>.
 740           </para>
 741         </listitem>
 742       </varlistentry>
 743
 744       <varlistentry>
 745         <term>
 746           <option>-L</option><replaceable>dir</replaceable>
 747           <indexterm><primary><option>-L</option></primary></indexterm>
 748         </term>
 749         <listitem>
 750           <para>Where to find user-supplied libraries&hellip;
 751           Prepend the directory <replaceable>dir</replaceable> to
 752           the library directories path.</para>
 753         </listitem>
 754       </varlistentry>
 755
 756       <varlistentry>
 757         <term>
 758           <option>-framework-path</option><replaceable>dir</replaceable>
 759           <indexterm><primary><option>-framework-path</option></primary></indexterm>
 760         </term>
 761         <listitem>
 762           <para>On Darwin/MacOS X only, prepend the directory <replaceable>dir</replaceable> to
 763           the framework directories path. This option corresponds to the <option>-F</option>
 764           option for Apple's Linker (<option>-F</option> already means something else for GHC).</para>
 765         </listitem>
 766       </varlistentry>
 767
 768       <varlistentry>
 769         <term>
 770           <option>-split-objs</option>
 771           <indexterm><primary><option>-split-objs</option></primary></indexterm>
 772         </term>
 773         <listitem>
 774           <para>Tell the linker to split the single object file that
 775           would normally be generated into multiple object files,
 776           one per top-level Haskell function or type in the module.
 777           This only makes sense for libraries, where it means that
 778           executables linked against the library are smaller as they only
 779           link against the object files that they need. However, assembling
 780           all the sections separately is expensive, so this is slower than
 781           compiling normally.
 782           We use this feature for building GHC's libraries
 783           (warning: don't use it unless you know what you're
 784           doing!).</para>
 785         </listitem>
 786       </varlistentry>
 787
 788       <varlistentry>
 789         <term>
 790           <option>-static</option>
 791           <indexterm><primary><option>-static</option></primary></indexterm>
 792         </term>
 793         <listitem>
 794           <para>Tell the linker to avoid shared Haskell libraries,
 795           if possible.  This is the default.</para>
 796         </listitem>
 797       </varlistentry>
 798
 799       <varlistentry>
 800         <term>
 801           <option>-dynamic</option>
 802           <indexterm><primary><option>-dynamic</option></primary></indexterm>
 803         </term>
 804         <listitem>
 805           <para>This flag tells GHC to link against shared Haskell libraries.
 806           This flag only affects the selection of dependent libraries, not
 807           the form of the current target (see -shared).
 808           See <xref linkend="using-shared-libs" /> on how to
 809           create them.</para>
 810
 811           <para>Note that this option also has an effect on
 812           code generation (see above).</para>
 813         </listitem>
 814       </varlistentry>
 815
 816       <varlistentry>
 817         <term>
 818           <option>-shared</option>
 819           <indexterm><primary><option>-shared</option></primary></indexterm>
 820         </term>
 821         <listitem>
 822           <para>Instead of creating an executable, GHC produces a
 823           shared object with this linker flag. Depending on the
 824           operating system target, this might be an ELF DSO, a Windows
 825           DLL, or a Mac OS dylib. GHC hides the operating system
 826           details beneath this uniform flag.</para>
 827
 828           <para>The flags <option>-dynamic</option>/<option>-static</option> control whether the
 829           resulting shared object links statically or dynamically to
 830           Haskell package libraries given as <option>-package</option> option. Non-Haskell
 831           libraries are linked as gcc would regularly link it on your
 832           system, e.g. on most ELF system the linker uses the dynamic
 833           libraries when found.</para>
 834
 835           <para>Object files linked into shared objects must be
 836           compiled with <option>-fPIC</option>, see <xref linkend="options-codegen" /></para>
 837
 838           <para>When creating shared objects for Haskell packages, the
 839           shared object must be named properly, so that GHC recognizes
 840           the shared object when linked against this package. See
 841           shared object name mangling.</para>
 842         </listitem>
 843       </varlistentry>
 844
 845       <varlistentry>
 846         <term>
 847           <option>-dynload</option>
 848           <indexterm><primary><option>-dynload</option></primary></indexterm>
 849         </term>
 850         <listitem>
 851           <para>
 852             This flag selects one of a number of modes for finding shared
 853             libraries at runtime. See <xref linkend="finding-shared-libs"/> for
 854             a description of each mode.
 855           </para>
 856         </listitem>
 857       </varlistentry>
 858
 859       <varlistentry>
 860         <term>
 861           <option>-main-is <replaceable>thing</replaceable></option>
 862           <indexterm><primary><option>-main-is</option></primary></indexterm>
 863           <indexterm><primary>specifying your own main function</primary></indexterm>
 864         </term>
 865         <listitem>
 866           <para> The normal rule in Haskell is that your program must supply a <literal>main</literal>
 867             function in module <literal>Main</literal>.  When testing, it is often convenient
 868             to change which function is the "main" one, and the <option>-main-is</option> flag
 869             allows you to do so.  The  <replaceable>thing</replaceable> can be one of:
 870             <itemizedlist>
 871         <listitem><para>A lower-case identifier <literal>foo</literal>.  GHC assumes that the main function is <literal>Main.foo</literal>.</para></listitem>
 872         <listitem><para>An module name <literal>A</literal>.  GHC assumes that the main function is <literal>A.main</literal>.</para></listitem>
 873         <listitem><para>An qualified name <literal>A.foo</literal>.  GHC assumes that the main function is <literal>A.foo</literal>.</para></listitem>
 874         </itemizedlist>
 875             Strictly speaking, <option>-main-is</option> is not a link-phase flag at all; it has no effect on the link step.
 876             The flag must be specified when compiling the module containing the specified main function (e.g. module <literal>A</literal>
 877             in the latter two items above).  It has no effect for other modules,
 878             and hence can safely be given to <literal>ghc --make</literal>.
 879             However, if all the modules are otherwise up to date, you may need to force
 880             recompilation both of the module where the new "main" is, and of the
 881             module where the "main" function used to be;
 882             <literal>ghc</literal> is not clever
 883             enough to figure out that they both need recompiling.  You can
 884             force recompilation by removing the object file, or by using the
 885             <option>-fforce-recomp</option> flag.
 886             </para>
 887         </listitem>
 888       </varlistentry>
 889
 890       <varlistentry>
 891         <term>
 892           <option>-no-hs-main</option>
 893           <indexterm><primary><option>-no-hs-main</option></primary></indexterm>
 894           <indexterm><primary>linking Haskell libraries with foreign code</primary></indexterm>
 895         </term>
 896         <listitem>
 897           <para>In the event you want to include ghc-compiled code
 898           as part of another (non-Haskell) program, the RTS will not
 899           be supplying its definition of <function>main()</function>
 900           at link-time, you will have to. To signal that to the
 901           compiler when linking, use
 902           <option>-no-hs-main</option>. See also <xref linkend="using-own-main"/>.</para>
 903
 904           <para>Notice that since the command-line passed to the
 905           linker is rather involved, you probably want to use
 906           <command>ghc</command> to do the final link of your
 907           `mixed-language' application. This is not a requirement
 908           though, just try linking once with <option>-v</option> on
 909           to see what options the driver passes through to the
 910           linker.</para>
 911
 912           <para>The <option>-no-hs-main</option> flag can also be
 913           used to persuade the compiler to do the link step in
 914           <option>--make</option> mode when there is no Haskell
 915           <literal>Main</literal> module present (normally the
 916           compiler will not attempt linking when there is no
 917           <literal>Main</literal>).</para>
 918         </listitem>
 919       </varlistentry>
 920
 921       <varlistentry>
 922         <term>
 923           <option>-debug</option>
 924           <indexterm><primary><option>-debug</option></primary></indexterm>
 925         </term>
 926         <listitem>
 927           <para>Link the program with a debugging version of the
 928           runtime system.  The debugging runtime turns on numerous
 929           assertions and sanity checks, and provides extra options
 930           for producing debugging output at runtime (run the program
 931           with <literal>+RTS&nbsp;-?</literal> to see a list).</para>
 932         </listitem>
 933       </varlistentry>
 934
 935       <varlistentry>
 936         <term>
 937           <option>-threaded</option>
 938           <indexterm><primary><option>-threaded</option></primary></indexterm>
 939         </term>
 940         <listitem>
 941           <para>Link the program with the "threaded" version of the
 942           runtime system.  The threaded runtime system is so-called
 943           because it manages multiple OS threads, as opposed to the
 944           default runtime system which is purely
 945           single-threaded.</para>
 946
 947           <para>Note that you do <emphasis>not</emphasis> need
 948           <option>-threaded</option> in order to use concurrency; the
 949           single-threaded runtime supports concurrency between Haskell
 950           threads just fine.</para>
 951
 952           <para>The threaded runtime system provides the following
 953           benefits:</para>
 954
 955           <itemizedlist>
 956             <listitem>
 957               <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>
 958               machine.  See <xref linkend="using-smp" />.</para>
 959
 960               <para>The ability to make a foreign call that does not
 961               block all other Haskell threads, and to invoke
 962               foreign-exported Haskell functions from multiple OS
 963               threads. See <xref linkend="ffi-threads" />.</para>
 964             </listitem>
 965           </itemizedlist>
 966         </listitem>
 967       </varlistentry>
 968
 969       <varlistentry>
 970         <term>
 971           <option>-eventlog</option>
 972           <indexterm><primary><option>-eventlog</option></primary></indexterm>
 973         </term>
 974         <listitem>
 975           <para>
 976             Link the program with the "eventlog" version of the
 977             runtime system.  A program linked in this way can generate
 978             a runtime trace of events (such as thread start/stop) to a
 979             binary file
 980             <literal><replaceable>program</replaceable>.eventlog</literal>,
 981             which can then be interpreted later by various tools.  See
 982             <xref linkend="rts-eventlog" /> for more information.
 983           </para>
 984           <para>
 985             <option>-eventlog</option> can be used
 986             with <option>-threaded</option>.  It is implied
 987             by <option>-debug</option>.
 988           </para>
 989         </listitem>
 990       </varlistentry>
 991
 992       <varlistentry>
 993         <term>
 994           <option>-rtsopts</option>
 995           <indexterm><primary><option>-rtsopts</option></primary></indexterm>
 996         </term>
 997         <listitem>
 998           <para>
 999             This option affects the processing of RTS control options given either
1000             on the command line or via the <envar>GHCRTS</envar> environment variable.
1001             There are three possibilities:
1002           </para>
1003           <variablelist>
1004             <varlistentry>
1005               <term><option>-rtsopts=none</option></term>
1006               <listitem>
1007                 <para>
1008                   Disable all processing of RTS options.
1009                   If <option>+RTS</option> appears anywhere on the command
1010                   line, then the program will abort with an error message.
1011                   If the <envar>GHCRTS</envar> environment variable is
1012                   set, then the program will emit a warning message,
1013                   <envar>GHCRTS</envar> will be ignored, and the program
1014                   will run as normal.
1015                 </para>
1016               </listitem>
1017             </varlistentry>
1018             <varlistentry>
1019               <term><option>-rtsopts=some</option></term>
1020               <listitem>
1021                 <para>&lsqb;this is the default setting&rsqb; Enable
1022                   only the "safe" RTS options: (Currently
1023                   only <option>-?</option>
1024                   and <option>--info</option>.)  Any other RTS options
1025                   on the command line or in the <envar>GHCRTS</envar>
1026                   environment variable causes the program with to abort
1027                   with an error message.
1028                 </para>
1029               </listitem>
1030             </varlistentry>
1031             <varlistentry>
1032               <term><option>-rtsopts=all</option>, or
1033  just <option>-rtsopts</option></term>
1034               <listitem>
1035                 <para>
1036                   Enable <emphasis>all</emphasis> RTS option
1037                   processing, both on the command line and through
1038                   the <envar>GHCRTS</envar> environment variable.
1039                 </para>
1040               </listitem>
1041             </varlistentry>
1042           </variablelist>
1043           <para>
1044             In GHC 6.12.3 and earlier, the default was to process all
1045             RTS options. However, since RTS options can be used to
1046             write logging data to arbitrary files under the security
1047             context of the running program, there is a potential
1048             security problem.  For this reason, GHC 7.0.1 and later
1049             default to <option>-rtsops=some</option>.
1050           </para>
1051         </listitem>
1052       </varlistentry>
1053
1054       <varlistentry>
1055         <term>
1056           <option>-with-rtsopts</option>
1057           <indexterm><primary><option>-with-rtsopts</option></primary></indexterm>
1058         </term>
1059         <listitem>
1060           <para>
1061             This option allows you to set the default RTS options at link-time. For example,
1062             <option>-with-rtsopts="-H128m"</option> sets the default heap size to 128MB.
1063             This will always be the default heap size for this program, unless the user overrides it.
1064             (Depending on the setting of the <option>-rtsopts</option> option, the user might
1065             not have the ability to change RTS options at run-time, in which case
1066             <option>-with-rtsopts</option> would be the <emphasis>only</emphasis> way to set
1067             them.)
1068           </para>
1069         </listitem>
1070       </varlistentry>
1071
1072       <varlistentry>
1073         <term>
1074           <option>-fno-gen-manifest</option>
1075           <indexterm><primary><option>-fno-gen-manifest</option></primary>
1076           </indexterm>
1077         </term>
1078         <listitem>
1079           <para>On Windows, GHC normally generates a
1080             <firstterm>manifest</firstterm><indexterm><primary>manifest</primary>
1081             </indexterm>file when linking a binary.  The
1082             manifest is placed in the file
1083             <literal><replaceable>prog</replaceable>.exe.manifest</literal>
1084             where <replaceable>prog.exe</replaceable> is the name of the
1085             executable.  The manifest file currently serves just one purpose:
1086             it disables the "installer detection"<indexterm><primary>installer detection</primary>
1087             </indexterm>in Windows Vista that
1088             attempts to elevate privileges for executables with certain names
1089             (e.g. names containing "install", "setup" or "patch").  Without the
1090             manifest file to turn off installer detection, attempting to run an
1091             executable that Windows deems to be an installer will return a
1092             permission error code to the invoker.  Depending on the invoker,
1093             the result might be a dialog box asking the user for elevated
1094             permissions, or it might simply be a permission denied
1095             error.</para>
1096
1097           <para>Installer detection can be also turned off globally for the
1098             system using the security control panel, but GHC by default
1099             generates binaries that don't depend on the user having disabled
1100             installer detection.</para>
1101
1102           <para>The <option>-fno-gen-manifest</option> disables generation of
1103             the manifest file.  One reason to do this would be if you had
1104             a manifest file of your own, for example.</para>
1105
1106           <para>In the future, GHC might use the manifest file for more things,
1107             such as supplying the location of dependent DLLs.</para>
1108
1109           <para><option>-fno-gen-manifest</option> also implies
1110             <option>-fno-embed-manifest</option>, see below.</para>
1111         </listitem>
1112       </varlistentry>
1113
1114       <varlistentry>
1115         <term>
1116           <option>-fno-embed-manifest</option>
1117           <indexterm><primary><option>-fno-embed-manifest</option></primary>
1118           </indexterm>
1119         </term>
1120         <listitem>
1121           <para>The manifest file that GHC generates when linking a binary on
1122             Windows is also embedded in the executable itself, by default.
1123             This means that the binary can be distributed without having to
1124             supply the manifest file too.  The embedding is done by running
1125             <literal>windres</literal><indexterm><primary><literal>windres</literal></primary>
1126             </indexterm>; to see exactly what GHC does to embed the manifest,
1127             use the <option>-v</option> flag.  A GHC installation comes with
1128             its own copy of <literal>windres</literal> for this reason.</para>
1129
1130           <para>See also <option>-pgmwindres</option> (<xref
1131               linkend="replacing-phases" />) and
1132             <option>-optwindres</option> (<xref
1133                                             linkend="forcing-options-through"
1134               />).</para>
1135         </listitem>
1136       </varlistentry>
1137
1138       <varlistentry>
1139         <term>
1140           <option>-fno-shared-implib</option>
1141           <indexterm><primary><option>-fno-shared-implib</option></primary>
1142           </indexterm>
1143         </term>
1144         <listitem>
1145           <para>DLLs on Windows are typically linked to by linking to a corresponding
1146             <literal>.lib</literal> or <literal>.dll.a</literal> - the so-called import library.
1147             GHC will typically generate such a file for every DLL you create by compiling in
1148             <literal>-shared</literal> mode. However, sometimes you don't want to pay the
1149             disk-space cost of creating this import library, which can be substantial - it
1150             might require as much space as the code itself, as Haskell DLLs tend to export
1151             lots of symbols.</para>
1152
1153           <para>As long as you are happy to only be able to link to the DLL using
1154             <literal>GetProcAddress</literal> and friends, you can supply the
1155             <option>-fno-shared-implib</option> flag to disable the creation of the import
1156             library entirely.</para>
1157         </listitem>
1158       </varlistentry>
1159
1160       <varlistentry>
1161         <term>
1162           <option>-dylib-install-name <replaceable>path</replaceable></option>
1163           <indexterm><primary><option>-dylib-install-name</option></primary>
1164           </indexterm>
1165         </term>
1166         <listitem>
1167           <para>On Darwin/MacOS X, dynamic libraries are stamped at build time with an
1168               "install name", which is the ultimate install path of the library file.
1169               Any libraries or executables that subsequently link against it will pick
1170               up that path as their runtime search location for it. By default, ghc sets
1171               the install name to the location where the library is built. This option
1172               allows you to override it with the specified file path. (It passes
1173               <literal>-install_name</literal> to Apple's linker.) Ignored on other
1174               platforms.</para>
1175         </listitem>
1176       </varlistentry>
1177     </variablelist>
1178   </sect2>
1179
1180 </sect1>
1181
1182 <!-- Emacs stuff:
1183      ;;; Local Variables: ***
1184      ;;; sgml-parent-document: ("users_guide.xml" "book" "chapter" "sect1") ***
1185      ;;; End: ***
1186  -->