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;HASKELL98&lowbar;&lowbar;</constant>
 363           <indexterm><primary><literal>&lowbar;&lowbar;HASKELL98&lowbar;&lowbar;</literal></primary></indexterm>
 364         </term>
 365         <listitem>
 366           <para>If defined, this means that GHC supports the
 367           language defined by the Haskell 98 report.</para>
 368         </listitem>
 369       </varlistentry>
 370
 371       <varlistentry>
 372         <term>
 373           <constant>&lowbar;&lowbar;HASKELL&lowbar;&lowbar;=98</constant>
 374           <indexterm><primary><constant>&lowbar;&lowbar;HASKELL&lowbar;&lowbar;=98</constant></primary></indexterm>
 375         </term>
 376         <listitem>
 377           <para>In GHC 4.04 and later, the
 378           <constant>&lowbar;&lowbar;HASKELL&lowbar;&lowbar;</constant>
 379           macro is defined as having the value
 380           <constant>98</constant>.</para>
 381         </listitem>
 382       </varlistentry>
 383
 384       <varlistentry>
 385         <term>
 386           <constant>&lowbar;&lowbar;HASKELL1&lowbar;&lowbar;</constant>
 387           <indexterm><primary><constant>&lowbar;&lowbar;HASKELL1&lowbar;&lowbar;</constant></primary></indexterm>
 388         </term>
 389         <listitem>
 390           <para>If defined to <replaceable>n</replaceable>, that
 391           means GHC supports the Haskell language defined in the
 392           Haskell report version <emphasis>1.n</emphasis>.
 393           Currently 5.  This macro is deprecated, and will probably
 394           disappear in future versions.</para>
 395         </listitem>
 396       </varlistentry>
 397
 398       <varlistentry>
 399         <term>
 400           <constant>&lowbar;&lowbar;GLASGOW&lowbar;HASKELL&lowbar;&lowbar;</constant>
 401           <indexterm><primary><constant>&lowbar;&lowbar;GLASGOW&lowbar;HASKELL&lowbar;&lowbar;</constant></primary></indexterm>
 402         </term>
 403         <listitem>
 404           <para>For version
 405           <literal><replaceable>x</replaceable>.<replaceable>y</replaceable>.<replaceable>z</replaceable></literal>
 406           of GHC, the value of
 407           <constant>&lowbar;&lowbar;GLASGOW&lowbar;HASKELL&lowbar;&lowbar;</constant>
 408           is the integer <replaceable>xyy</replaceable> (if
 409         <replaceable>y</replaceable> is a single digit, then a leading zero
 410         is added, so for example in version 6.2 of GHC,
 411         <literal>__GLASGOW_HASKELL__==602</literal>).  More
 412           information in <xref linkend="version-numbering"/>.</para>
 413
 414           <para>With any luck,
 415           <constant>&lowbar;&lowbar;GLASGOW&lowbar;HASKELL&lowbar;&lowbar;</constant>
 416           will be undefined in all other implementations that
 417           support C-style pre-processing.</para>
 418
 419           <para>(For reference: the comparable symbols for other
 420           systems are:
 421           <constant>&lowbar;&lowbar;HUGS&lowbar;&lowbar;</constant>
 422           for Hugs,
 423           <constant>&lowbar;&lowbar;NHC&lowbar;&lowbar;</constant>
 424           for nhc98, and
 425           <constant>&lowbar;&lowbar;HBC&lowbar;&lowbar;</constant>
 426           for hbc.)</para>
 427
 428           <para>NB. This macro is set when pre-processing both
 429           Haskell source and C source, including the C source
 430           generated from a Haskell module
 431           (i.e. <filename>.hs</filename>, <filename>.lhs</filename>,
 432           <filename>.c</filename> and <filename>.hc</filename>
 433           files).</para>
 434         </listitem>
 435       </varlistentry>
 436
 437       <varlistentry>
 438       <term>
 439           <constant>&lowbar;&lowbar;CONCURRENT&lowbar;HASKELL&lowbar;&lowbar;</constant>
 440           <indexterm><primary><constant>&lowbar;&lowbar;CONCURRENT&lowbar;HASKELL&lowbar;&lowbar;</constant></primary></indexterm>
 441         </term>
 442       <listitem>
 443         <para>This symbol is defined when pre-processing Haskell
 444           (input) and pre-processing C (GHC output).  Since GHC from
 445           version 4.00 now supports concurrent haskell by default,
 446           this symbol is always defined.</para>
 447         </listitem>
 448       </varlistentry>
 449
 450       <varlistentry>
 451         <term>
 452           <constant>&lowbar;&lowbar;PARALLEL&lowbar;HASKELL&lowbar;&lowbar;</constant>
 453           <indexterm><primary><constant>&lowbar;&lowbar;PARALLEL&lowbar;HASKELL&lowbar;&lowbar;</constant></primary></indexterm>
 454         </term>
 455         <listitem>
 456           <para>Only defined when <option>-parallel</option> is in
 457           use!  This symbol is defined when pre-processing Haskell
 458           (input) and pre-processing C (GHC output).</para>
 459         </listitem>
 460       </varlistentry>
 461
 462       <varlistentry>
 463         <term>
 464           <constant><replaceable>os</replaceable>_HOST_OS=1</constant>
 465         </term>
 466         <listitem>
 467           <para>This define allows conditional compilation based on
 468           the Operating System, where<replaceable>os</replaceable> is
 469           the name of the current Operating System
 470           (eg. <literal>linux</literal>, <literal>mingw32</literal>
 471           for Windows, <literal>solaris</literal>, etc.).</para>
 472         </listitem>
 473       </varlistentry>
 474
 475       <varlistentry>
 476         <term>
 477           <constant><replaceable>arch</replaceable>_HOST_ARCH=1</constant>
 478         </term>
 479         <listitem>
 480           <para>This define allows conditional compilation based on
 481           the host architecture, where<replaceable>arch</replaceable>
 482           is the name of the current architecture
 483           (eg. <literal>i386</literal>, <literal>x86_64</literal>,
 484           <literal>powerpc</literal>, <literal>sparc</literal>,
 485           etc.).</para>
 486         </listitem>
 487       </varlistentry>
 488     </variablelist>
 489
 490     <sect3 id="cpp-string-gaps">
 491       <title>CPP and string gaps</title>
 492
 493       <para>A small word of warning: <option>-cpp</option> is not
 494       friendly to &ldquo;string gaps&rdquo;.<indexterm><primary>-cpp
 495       vs string gaps</primary></indexterm><indexterm><primary>string
 496       gaps vs -cpp</primary></indexterm>.  In other words, strings
 497       such as the following:</para>
 498
 499 <programlisting>strmod = "\
 500 \ p \
 501 \ "</programlisting>
 502
 503       <para>don't work with <option>-cpp</option>;
 504       <filename>/usr/bin/cpp</filename> elides the backslash-newline
 505       pairs.</para>
 506
 507       <para>However, it appears that if you add a space at the end
 508       of the line, then <command>cpp</command> (at least GNU
 509       <command>cpp</command> and possibly other
 510       <command>cpp</command>s) leaves the backslash-space pairs
 511       alone and the string gap works as expected.</para>
 512     </sect3>
 513   </sect2>
 514
 515   <sect2 id="pre-processor">
 516     <title>Options affecting a Haskell pre-processor</title>
 517
 518     <indexterm><primary>pre-processing: custom</primary></indexterm>
 519     <indexterm><primary>Pre-processor options</primary></indexterm>
 520
 521     <variablelist>
 522       <varlistentry>
 523         <term>
 524           <option>-F</option>
 525           <indexterm><primary><option>-F</option></primary></indexterm>
 526         </term>
 527         <listitem>
 528           <para>A custom pre-processor is run over your Haskell
 529           source file only if the <option>-F</option> option
 530           <indexterm><primary>-F</primary></indexterm> is
 531           given.</para>
 532
 533           <para>Running a custom pre-processor at compile-time is in
 534           some settings appropriate and useful. The
 535           <option>-F</option> option lets you run a pre-processor as
 536           part of the overall GHC compilation pipeline, which has
 537           the advantage over running a Haskell pre-processor
 538           separately in that it works in interpreted mode and you
 539           can continue to take reap the benefits of GHC's
 540           recompilation checker.</para>
 541
 542           <para>The pre-processor is run just before the Haskell
 543           compiler proper processes the Haskell input, but after the
 544           literate markup has been stripped away and (possibly) the
 545           C pre-processor has washed the Haskell input.</para>
 546
 547           <para>Use
 548           <option>-pgmF&nbsp;<replaceable>cmd</replaceable></option>
 549           to select the program to use as the preprocessor.  When
 550           invoked, the <replaceable>cmd</replaceable> pre-processor
 551           is given at least three arguments on its command-line: the
 552           first argument is the name of the original source file,
 553           the second is the name of the file holding the input, and
 554           the third is the name of the file where
 555           <replaceable>cmd</replaceable> should write its output
 556           to.</para>
 557
 558           <para>Additional arguments to the pre-processor can be
 559           passed in using the <option>-optF</option> option. These
 560           are fed to <replaceable>cmd</replaceable> on the command
 561           line after the three standard input and output
 562           arguments.</para>
 563
 564           <para>
 565           An example of a pre-processor is to convert your source files to the
 566           input encoding that GHC expects, i.e. create a script
 567           <literal>convert.sh</literal> containing the lines:
 568           </para>
 569
 570 <screen>#!/bin/sh
 571 ( echo "{-# LINE 1 \"$2\" #-}" ; iconv -f l1 -t utf-8 $2 ) > $3</screen>
 572
 573           <para>and pass <literal>-F -pgmF convert.sh</literal> to GHC.
 574           The <literal>-f l1</literal> option tells iconv to convert your
 575           Latin-1 file, supplied in argument <literal>$2</literal>, while
 576           the "-t utf-8" options tell iconv to return a UTF-8 encoded file.
 577           The result is redirected into argument <literal>$3</literal>.
 578           The <literal>echo "{-# LINE 1 \"$2\" #-}"</literal>
 579           just makes sure that your error positions are reported as
 580           in the original source file.</para>
 581         </listitem>
 582       </varlistentry>
 583     </variablelist>
 584   </sect2>
 585
 586   <sect2 id="options-codegen">
 587     <title>Options affecting code generation</title>
 588
 589     <variablelist>
 590       <varlistentry>
 591         <term>
 592           <option>-fasm</option>
 593           <indexterm><primary><option>-fasm</option></primary></indexterm>
 594         </term>
 595         <listitem>
 596           <para>Use GHC's native code generator rather than
 597           compiling via C.  This will compile faster (up to twice as
 598           fast), but may produce code that is slightly slower than
 599           compiling via C.  <option>-fasm</option> is the default.</para>
 600         </listitem>
 601       </varlistentry>
 602
 603       <varlistentry>
 604         <term>
 605           <option>-fvia-C</option>
 606           <indexterm><primary><option>-fvia-C</option></primary></indexterm>
 607         </term>
 608         <listitem>
 609           <para>Compile via C instead of using the native code
 610           generator.  This is the default on architectures for which GHC
 611           doesn't have a native code generator.</para>
 612         </listitem>
 613       </varlistentry>
 614
 615       <varlistentry>
 616         <term>
 617           <option>-fllvm</option>
 618           <indexterm><primary><option>-fllvm</option></primary></indexterm>
 619         </term>
 620         <listitem>
 621           <para>Compile via LLVM instead of using the native code
 622           generator. This will generally take slightly longer than the
 623           native code generator to compile but quicker than compiling
 624           via C. Produced code is generally the same speed or faster
 625           than the other two code generators. Compiling via LLVM
 626           requires LLVM version 2.7 or later to be on the path.</para>
 627         </listitem>
 628       </varlistentry>
 629
 630       <varlistentry>
 631         <term>
 632           <option>-fno-code</option>
 633           <indexterm><primary><option>-fno-code</option></primary></indexterm>
 634         </term>
 635         <listitem>
 636           <para>Omit code generation (and all later phases)
 637           altogether.  Might be of some use if you just want to see
 638           dumps of the intermediate compilation phases.</para>
 639         </listitem>
 640       </varlistentry>
 641
 642       <varlistentry>
 643         <term>
 644           <option>-fobject-code</option>
 645           <indexterm><primary><option>-fobject-code</option></primary></indexterm>
 646         </term>
 647         <listitem>
 648           <para>Generate object code.  This is the default outside of
 649           GHCi, and can be used with GHCi to cause object code to be
 650           generated in preference to bytecode.</para>
 651         </listitem>
 652       </varlistentry>
 653
 654       <varlistentry>
 655         <term>
 656           <option>-fbyte-code</option>
 657           <indexterm><primary><option>-fbyte-code</option></primary></indexterm>
 658         </term>
 659         <listitem>
 660           <para>Generate byte-code instead of object-code.  This is
 661           the default in GHCi.  Byte-code can currently only be used
 662           in the interactive interpreter, not saved to disk.  This
 663           option is only useful for reversing the effect of
 664           <option>-fobject-code</option>.</para>
 665         </listitem>
 666       </varlistentry>
 667
 668       <varlistentry>
 669         <term>
 670           <option>-fPIC</option>
 671           <indexterm><primary><option>-fPIC</option></primary></indexterm>
 672         </term>
 673         <listitem>
 674           <para>Generate position-independent code (code that can be put into
 675           shared libraries). This currently works on Linux x86 and x86-64 when
 676           using the native code generator (-fasm).
 677           On Windows, position-independent code is never used
 678           so the flag is a no-op on that platform.</para>
 679         </listitem>
 680       </varlistentry>
 681
 682       <varlistentry>
 683         <term>
 684           <option>-dynamic</option>
 685         </term>
 686         <listitem>
 687           <para>When generating code, assume that entities imported from a
 688           different package will reside in a different shared library or
 689           binary.</para>
 690           <para>Note that using this option when linking causes GHC to link
 691           against shared libraries.</para>
 692         </listitem>
 693       </varlistentry>
 694     </variablelist>
 695   </sect2>
 696
 697   <sect2 id="options-linker">
 698     <title>Options affecting linking</title>
 699
 700     <indexterm><primary>linker options</primary></indexterm>
 701     <indexterm><primary>ld options</primary></indexterm>
 702
 703
 704     <para>GHC has to link your code with various libraries, possibly
 705     including: user-supplied, GHC-supplied, and system-supplied
 706     (<option>-lm</option> math library, for example).</para>
 707
 708     <variablelist>
 709
 710       <varlistentry>
 711         <term>
 712           <option>-l</option><replaceable>lib</replaceable>
 713           <indexterm><primary><option>-l</option></primary></indexterm>
 714         </term>
 715         <listitem>
 716           <para>Link in the <replaceable>lib</replaceable> library.
 717           On Unix systems, this will be in a file called
 718           <filename>lib<replaceable>lib</replaceable>.a</filename>
 719           or
 720           <filename>lib<replaceable>lib</replaceable>.so</filename>
 721           which resides somewhere on the library directories path.</para>
 722
 723           <para>Because of the sad state of most UNIX linkers, the
 724           order of such options does matter.  If library
 725           <replaceable>foo</replaceable> requires library
 726           <replaceable>bar</replaceable>, then in general
 727           <option>-l</option><replaceable>foo</replaceable> should
 728           come <emphasis>before</emphasis>
 729           <option>-l</option><replaceable>bar</replaceable> on the
 730           command line.</para>
 731
 732           <para>There's one other gotcha to bear in mind when using
 733           external libraries: if the library contains a
 734           <literal>main()</literal> function, then this will be
 735           linked in preference to GHC's own
 736           <literal>main()</literal> function
 737           (eg. <literal>libf2c</literal> and <literal>libl</literal>
 738           have their own <literal>main()</literal>s).  This is
 739           because GHC's <literal>main()</literal> comes from the
 740           <literal>HSrts</literal> library, which is normally
 741           included <emphasis>after</emphasis> all the other
 742           libraries on the linker's command line.  To force GHC's
 743           <literal>main()</literal> to be used in preference to any
 744           other <literal>main()</literal>s from external libraries,
 745           just add the option <option>-lHSrts</option> before any
 746           other libraries on the command line.</para>
 747         </listitem>
 748       </varlistentry>
 749
 750       <varlistentry>
 751         <term>
 752           <option>-c</option>
 753           <indexterm><primary><option>-c</option></primary></indexterm>
 754         </term>
 755         <listitem>
 756           <para>Omits the link step.  This option can be used with
 757             <option>&ndash;&ndash;make</option> to avoid the automatic linking
 758             that takes place if the program contains a <literal>Main</literal>
 759             module.</para>
 760         </listitem>
 761       </varlistentry>
 762
 763       <varlistentry>
 764         <term>
 765           <option>-package</option> <replaceable>name</replaceable>
 766           <indexterm><primary><option>-package</option></primary></indexterm>
 767         </term>
 768         <listitem>
 769           <para>If you are using a Haskell &ldquo;package&rdquo;
 770           (see <xref linkend="packages"/>), don't forget to add the
 771           relevant <option>-package</option> option when linking the
 772           program too: it will cause the appropriate libraries to be
 773           linked in with the program.  Forgetting the
 774           <option>-package</option> option will likely result in
 775           several pages of link errors.</para>
 776         </listitem>
 777       </varlistentry>
 778
 779       <varlistentry>
 780         <term>
 781           <option>-framework</option> <replaceable>name</replaceable>
 782           <indexterm><primary><option>-framework</option></primary></indexterm>
 783         </term>
 784         <listitem>
 785           <para>On Darwin/MacOS X only, link in the framework <replaceable>name</replaceable>.
 786           This option corresponds to the <option>-framework</option> option for Apple's Linker.
 787           Please note that frameworks and packages are two different things - frameworks don't
 788           contain any haskell code. Rather, they are Apple's way of packaging shared libraries.
 789           To link to Apple's &ldquo;Carbon&rdquo; API, for example, you'd use
 790           <option>-framework Carbon</option>.
 791           </para>
 792         </listitem>
 793       </varlistentry>
 794
 795       <varlistentry>
 796         <term>
 797           <option>-L</option><replaceable>dir</replaceable>
 798           <indexterm><primary><option>-L</option></primary></indexterm>
 799         </term>
 800         <listitem>
 801           <para>Where to find user-supplied libraries&hellip;
 802           Prepend the directory <replaceable>dir</replaceable> to
 803           the library directories path.</para>
 804         </listitem>
 805       </varlistentry>
 806
 807       <varlistentry>
 808         <term>
 809           <option>-framework-path</option><replaceable>dir</replaceable>
 810           <indexterm><primary><option>-framework-path</option></primary></indexterm>
 811         </term>
 812         <listitem>
 813           <para>On Darwin/MacOS X only, prepend the directory <replaceable>dir</replaceable> to
 814           the framework directories path. This option corresponds to the <option>-F</option>
 815           option for Apple's Linker (<option>-F</option> already means something else for GHC).</para>
 816         </listitem>
 817       </varlistentry>
 818
 819       <varlistentry>
 820         <term>
 821           <option>-split-objs</option>
 822           <indexterm><primary><option>-split-objs</option></primary></indexterm>
 823         </term>
 824         <listitem>
 825           <para>Tell the linker to split the single object file that
 826           would normally be generated into multiple object files,
 827           one per top-level Haskell function or type in the module.
 828           This only makes sense for libraries, where it means that
 829           executables linked against the library are smaller as they only
 830           link against the object files that they need. However, assembling
 831           all the sections separately is expensive, so this is slower than
 832           compiling normally.
 833           We use this feature for building GHC's libraries
 834           (warning: don't use it unless you know what you're
 835           doing!).</para>
 836         </listitem>
 837       </varlistentry>
 838
 839       <varlistentry>
 840         <term>
 841           <option>-static</option>
 842           <indexterm><primary><option>-static</option></primary></indexterm>
 843         </term>
 844         <listitem>
 845           <para>Tell the linker to avoid shared Haskell libraries,
 846           if possible.  This is the default.</para>
 847         </listitem>
 848       </varlistentry>
 849
 850       <varlistentry>
 851         <term>
 852           <option>-dynamic</option>
 853           <indexterm><primary><option>-dynamic</option></primary></indexterm>
 854         </term>
 855         <listitem>
 856           <para>This flag tells GHC to link against shared Haskell libraries.
 857           This flag only affects the selection of dependent libraries, not
 858           the form of the current target (see -shared).
 859           See <xref linkend="using-shared-libs" /> on how to
 860           create them.</para>
 861
 862           <para>Note that this option also has an effect on
 863           code generation (see above).</para>
 864         </listitem>
 865       </varlistentry>
 866
 867       <varlistentry>
 868         <term>
 869           <option>-shared</option>
 870           <indexterm><primary><option>-shared</option></primary></indexterm>
 871         </term>
 872         <listitem>
 873           <para>Instead of creating an executable, GHC produces a
 874           shared object with this linker flag. Depending on the
 875           operating system target, this might be an ELF DSO, a Windows
 876           DLL, or a Mac OS dylib. GHC hides the operating system
 877           details beneath this uniform flag.</para>
 878
 879           <para>The flags <option>-dynamic</option>/<option>-static</option> control whether the
 880           resulting shared object links statically or dynamically to
 881           Haskell package libraries given as <option>-package</option> option. Non-Haskell
 882           libraries are linked as gcc would regularly link it on your
 883           system, e.g. on most ELF system the linker uses the dynamic
 884           libraries when found.</para>
 885
 886           <para>Object files linked into shared objects must be
 887           compiled with <option>-fPIC</option>, see <xref linkend="options-codegen" /></para>
 888
 889           <para>When creating shared objects for Haskell packages, the
 890           shared object must be named properly, so that GHC recognizes
 891           the shared object when linked against this package. See
 892           shared object name mangling.</para>
 893         </listitem>
 894       </varlistentry>
 895
 896       <varlistentry>
 897         <term>
 898           <option>-dynload</option>
 899           <indexterm><primary><option>-dynload</option></primary></indexterm>
 900         </term>
 901         <listitem>
 902           <para>
 903             This flag selects one of a number of modes for finding shared
 904             libraries at runtime. See <xref linkend="finding-shared-libs"/> for
 905             a description of each mode.
 906           </para>
 907         </listitem>
 908       </varlistentry>
 909
 910       <varlistentry>
 911         <term>
 912           <option>-main-is <replaceable>thing</replaceable></option>
 913           <indexterm><primary><option>-main-is</option></primary></indexterm>
 914           <indexterm><primary>specifying your own main function</primary></indexterm>
 915         </term>
 916         <listitem>
 917           <para> The normal rule in Haskell is that your program must supply a <literal>main</literal>
 918             function in module <literal>Main</literal>.  When testing, it is often convenient
 919             to change which function is the "main" one, and the <option>-main-is</option> flag
 920             allows you to do so.  The  <replaceable>thing</replaceable> can be one of:
 921             <itemizedlist>
 922         <listitem><para>A lower-case identifier <literal>foo</literal>.  GHC assumes that the main function is <literal>Main.foo</literal>.</para></listitem>
 923         <listitem><para>An module name <literal>A</literal>.  GHC assumes that the main function is <literal>A.main</literal>.</para></listitem>
 924         <listitem><para>An qualified name <literal>A.foo</literal>.  GHC assumes that the main function is <literal>A.foo</literal>.</para></listitem>
 925         </itemizedlist>
 926             Strictly speaking, <option>-main-is</option> is not a link-phase flag at all; it has no effect on the link step.
 927             The flag must be specified when compiling the module containing the specified main function (e.g. module <literal>A</literal>
 928             in the latter two items above).  It has no effect for other modules,
 929             and hence can safely be given to <literal>ghc --make</literal>.
 930             However, if all the modules are otherwise up to date, you may need to force
 931             recompilation both of the module where the new "main" is, and of the
 932             module where the "main" function used to be;
 933             <literal>ghc</literal> is not clever
 934             enough to figure out that they both need recompiling.  You can
 935             force recompilation by removing the object file, or by using the
 936             <option>-fforce-recomp</option> flag.
 937             </para>
 938         </listitem>
 939       </varlistentry>
 940
 941       <varlistentry>
 942         <term>
 943           <option>-no-hs-main</option>
 944           <indexterm><primary><option>-no-hs-main</option></primary></indexterm>
 945           <indexterm><primary>linking Haskell libraries with foreign code</primary></indexterm>
 946         </term>
 947         <listitem>
 948           <para>In the event you want to include ghc-compiled code
 949           as part of another (non-Haskell) program, the RTS will not
 950           be supplying its definition of <function>main()</function>
 951           at link-time, you will have to. To signal that to the
 952           compiler when linking, use
 953           <option>-no-hs-main</option>. See also <xref linkend="using-own-main"/>.</para>
 954
 955           <para>Notice that since the command-line passed to the
 956           linker is rather involved, you probably want to use
 957           <command>ghc</command> to do the final link of your
 958           `mixed-language' application. This is not a requirement
 959           though, just try linking once with <option>-v</option> on
 960           to see what options the driver passes through to the
 961           linker.</para>
 962
 963           <para>The <option>-no-hs-main</option> flag can also be
 964           used to persuade the compiler to do the link step in
 965           <option>--make</option> mode when there is no Haskell
 966           <literal>Main</literal> module present (normally the
 967           compiler will not attempt linking when there is no
 968           <literal>Main</literal>).</para>
 969         </listitem>
 970       </varlistentry>
 971
 972       <varlistentry>
 973         <term>
 974           <option>-debug</option>
 975           <indexterm><primary><option>-debug</option></primary></indexterm>
 976         </term>
 977         <listitem>
 978           <para>Link the program with a debugging version of the
 979           runtime system.  The debugging runtime turns on numerous
 980           assertions and sanity checks, and provides extra options
 981           for producing debugging output at runtime (run the program
 982           with <literal>+RTS&nbsp;-?</literal> to see a list).</para>
 983         </listitem>
 984       </varlistentry>
 985
 986       <varlistentry>
 987         <term>
 988           <option>-threaded</option>
 989           <indexterm><primary><option>-threaded</option></primary></indexterm>
 990         </term>
 991         <listitem>
 992           <para>Link the program with the "threaded" version of the
 993           runtime system.  The threaded runtime system is so-called
 994           because it manages multiple OS threads, as opposed to the
 995           default runtime system which is purely
 996           single-threaded.</para>
 997
 998           <para>Note that you do <emphasis>not</emphasis> need
 999           <option>-threaded</option> in order to use concurrency; the
1000           single-threaded runtime supports concurrency between Haskell
1001           threads just fine.</para>
1002
1003           <para>The threaded runtime system provides the following
1004           benefits:</para>
1005
1006           <itemizedlist>
1007             <listitem>
1008               <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>
1009               machine.  See <xref linkend="using-smp" />.</para>
1010
1011               <para>The ability to make a foreign call that does not
1012               block all other Haskell threads, and to invoke
1013               foreign-exported Haskell functions from multiple OS
1014               threads. See <xref linkend="ffi-threads" />.</para>
1015             </listitem>
1016           </itemizedlist>
1017         </listitem>
1018       </varlistentry>
1019
1020       <varlistentry>
1021         <term>
1022           <option>-eventlog</option>
1023           <indexterm><primary><option>-eventlog</option></primary></indexterm>
1024         </term>
1025         <listitem>
1026           <para>
1027             Link the program with the "eventlog" version of the
1028             runtime system.  A program linked in this way can generate
1029             a runtime trace of events (such as thread start/stop) to a
1030             binary file
1031             <literal><replaceable>program</replaceable>.eventlog</literal>,
1032             which can then be interpreted later by various tools.  See
1033             <xref linkend="rts-eventlog" /> for more information.
1034           </para>
1035           <para>
1036             <option>-eventlog</option> can be used
1037             with <option>-threaded</option>.  It is implied
1038             by <option>-debug</option>.
1039           </para>
1040         </listitem>
1041       </varlistentry>
1042
1043       <varlistentry>
1044         <term>
1045           <option>-fno-gen-manifest</option>
1046           <indexterm><primary><option>-fno-gen-manifest</option></primary>
1047           </indexterm>
1048         </term>
1049         <listitem>
1050           <para>On Windows, GHC normally generates a
1051             <firstterm>manifest</firstterm><indexterm><primary>manifest</primary>
1052             </indexterm>file when linking a binary.  The
1053             manifest is placed in the file
1054             <literal><replaceable>prog</replaceable>.exe.manifest</literal>
1055             where <replaceable>prog.exe</replaceable> is the name of the
1056             executable.  The manifest file currently serves just one purpose:
1057             it disables the "installer detection"<indexterm><primary>installer detection</primary>
1058             </indexterm>in Windows Vista that
1059             attempts to elevate privileges for executables with certain names
1060             (e.g. names containing "install", "setup" or "patch").  Without the
1061             manifest file to turn off installer detection, attempting to run an
1062             executable that Windows deems to be an installer will return a
1063             permission error code to the invoker.  Depending on the invoker,
1064             the result might be a dialog box asking the user for elevated
1065             permissions, or it might simply be a permission denied
1066             error.</para>
1067
1068           <para>Installer detection can be also turned off globally for the
1069             system using the security control panel, but GHC by default
1070             generates binaries that don't depend on the user having disabled
1071             installer detection.</para>
1072
1073           <para>The <option>-fno-gen-manifest</option> disables generation of
1074             the manifest file.  One reason to do this would be if you had
1075             a manifest file of your own, for example.</para>
1076
1077           <para>In the future, GHC might use the manifest file for more things,
1078             such as supplying the location of dependent DLLs.</para>
1079
1080           <para><option>-fno-gen-manifest</option> also implies
1081             <option>-fno-embed-manifest</option>, see below.</para>
1082         </listitem>
1083       </varlistentry>
1084
1085       <varlistentry>
1086         <term>
1087           <option>-fno-embed-manifest</option>
1088           <indexterm><primary><option>-fno-embed-manifest</option></primary>
1089           </indexterm>
1090         </term>
1091         <listitem>
1092           <para>The manifest file that GHC generates when linking a binary on
1093             Windows is also embedded in the executable itself, by default.
1094             This means that the binary can be distributed without having to
1095             supply the manifest file too.  The embedding is done by running
1096             <literal>windres</literal><indexterm><primary><literal>windres</literal></primary>
1097             </indexterm>; to see exactly what GHC does to embed the manifest,
1098             use the <option>-v</option> flag.  A GHC installation comes with
1099             its own copy of <literal>windres</literal> for this reason.</para>
1100
1101           <para>See also <option>-pgmwindres</option> (<xref
1102               linkend="replacing-phases" />) and
1103             <option>-optwindres</option> (<xref
1104                                             linkend="forcing-options-through"
1105               />).</para>
1106         </listitem>
1107       </varlistentry>
1108
1109       <varlistentry>
1110         <term>
1111           <option>-fno-shared-implib</option>
1112           <indexterm><primary><option>-fno-shared-implib</option></primary>
1113           </indexterm>
1114         </term>
1115         <listitem>
1116           <para>DLLs on Windows are typically linked to by linking to a corresponding
1117             <literal>.lib</literal> or <literal>.dll.a</literal> - the so-called import library.
1118             GHC will typically generate such a file for every DLL you create by compiling in
1119             <literal>-shared</literal> mode. However, sometimes you don't want to pay the
1120             disk-space cost of creating this import library, which can be substantial - it
1121             might require as much space as the code itself, as Haskell DLLs tend to export
1122             lots of symbols.</para>
1123
1124           <para>As long as you are happy to only be able to link to the DLL using
1125             <literal>GetProcAddress</literal> and friends, you can supply the
1126             <option>-fno-shared-implib</option> flag to disable the creation of the import
1127             library entirely.</para>
1128         </listitem>
1129       </varlistentry>
1130
1131       <varlistentry>
1132         <term>
1133           <option>-dylib-install-name <replaceable>path</replaceable></option>
1134           <indexterm><primary><option>-dylib-install-name</option></primary>
1135           </indexterm>
1136         </term>
1137         <listitem>
1138           <para>On Darwin/MacOS X, dynamic libraries are stamped at build time with an
1139               "install name", which is the ultimate install path of the library file.
1140               Any libraries or executables that subsequently link against it will pick
1141               up that path as their runtime search location for it. By default, ghc sets
1142               the install name to the location where the library is built. This option
1143               allows you to override it with the specified file path. (It passes
1144               <literal>-install_name</literal> to Apple's linker.) Ignored on other
1145               platforms.</para>
1146         </listitem>
1147       </varlistentry>
1148     </variablelist>
1149   </sect2>
1150
1151 </sect1>
1152
1153 <!-- Emacs stuff:
1154      ;;; Local Variables: ***
1155      ;;; sgml-parent-document: ("users_guide.xml" "book" "chapter" "sect1") ***
1156      ;;; End: ***
1157  -->