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