docs/users_guide/phases.xml

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