ghc/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>-pgma</option> <replaceable>cmd</replaceable>
  53           <indexterm><primary><option>-pgma</option></primary></indexterm>
  54         </term>
  55         <listitem>
  56           <para>Use <replaceable>cmd</replaceable> as the
  57           assembler.</para>
  58         </listitem>
  59       </varlistentry>
  60
  61       <varlistentry>
  62         <term>
  63           <option>-pgml</option> <replaceable>cmd</replaceable>
  64           <indexterm><primary><option>-pgml</option></primary></indexterm>
  65         </term>
  66         <listitem>
  67           <para>Use <replaceable>cmd</replaceable> as the
  68           linker.</para>
  69         </listitem>
  70       </varlistentry>
  71
  72       <varlistentry>
  73         <term>
  74           <option>-pgmdll</option> <replaceable>cmd</replaceable>
  75           <indexterm><primary><option>-pgmdll</option></primary></indexterm>
  76         </term>
  77         <listitem>
  78           <para>Use <replaceable>cmd</replaceable> as the DLL
  79           generator.</para>
  80         </listitem>
  81       </varlistentry>
  82
  83       <varlistentry>
  84         <term>
  85           <option>-pgmdep</option> <replaceable>cmd</replaceable>
  86           <indexterm><primary><option>-pgmdep</option></primary></indexterm>
  87         </term>
  88         <listitem>
  89           <para>Use <replaceable>cmd</replaceable> as the dependency
  90           generator.</para>
  91         </listitem>
  92       </varlistentry>
  93
  94       <varlistentry>
  95         <term>
  96           <option>-pgmF</option> <replaceable>cmd</replaceable>
  97           <indexterm><primary><option>-pgmF</option></primary></indexterm>
  98         </term>
  99         <listitem>
 100           <para>Use <replaceable>cmd</replaceable> as the
 101           pre-processor (with <option>-F</option> only).</para>
 102         </listitem>
 103       </varlistentry>
 104
 105
 106     </variablelist>
 107   </sect2>
 108
 109   <sect2 id="forcing-options-through">
 110     <title>Forcing options to a particular phase</title>
 111     <indexterm><primary>forcing GHC-phase options</primary></indexterm>
 112
 113     <para>Options can be forced through to a particlar compilation
 114     phase, using the following flags:</para>
 115
 116     <variablelist>
 117       <varlistentry>
 118         <term>
 119           <option>-optL</option> <replaceable>option</replaceable>
 120           <indexterm><primary><option>-optL</option></primary></indexterm>
 121         </term>
 122         <listitem>
 123           <para>Pass <replaceable>option</replaceable> to the
 124           literate pre-processor</para>
 125         </listitem>
 126       </varlistentry>
 127       <varlistentry>
 128         <term>
 129           <option>-optP</option>  <replaceable>option</replaceable>
 130           <indexterm><primary><option>-optP</option></primary></indexterm>
 131         </term>
 132         <listitem>
 133           <para>Pass <replaceable>option</replaceable> to CPP (makes
 134           sense only if <option>-cpp</option> is also on).</para>
 135         </listitem>
 136       </varlistentry>
 137       <varlistentry>
 138         <term>
 139           <option>-optF</option> <replaceable>option</replaceable>
 140           <indexterm><primary><option>-optF</option></primary></indexterm>
 141         </term>
 142         <listitem>
 143           <para>Pass <replaceable>option</replaceable> to the
 144           custom pre-processor (see <xref linkend="pre-processor"/>).</para>
 145         </listitem>
 146       </varlistentry>
 147       <varlistentry>
 148         <term>
 149           <option>-optc</option> <replaceable>option</replaceable>
 150           <indexterm><primary><option>-optc</option></primary></indexterm>
 151         </term>
 152         <listitem>
 153           <para>Pass <replaceable>option</replaceable> to the C compiler.</para>
 154         </listitem>
 155       </varlistentry>
 156       <varlistentry>
 157         <term>
 158           <option>-opta</option>  <replaceable>option</replaceable>
 159           <indexterm><primary><option>-opta</option></primary></indexterm>
 160         </term>
 161         <listitem>
 162           <para>Pass <replaceable>option</replaceable> to the assembler.</para>
 163         </listitem>
 164       </varlistentry>
 165       <varlistentry>
 166         <term>
 167           <option>-optl</option> <replaceable>option</replaceable>
 168           <indexterm><primary><option>-optl</option></primary></indexterm>
 169         </term>
 170         <listitem>
 171           <para>Pass <replaceable>option</replaceable> to the linker.</para>
 172         </listitem>
 173       </varlistentry>
 174       <varlistentry>
 175         <term>
 176           <option>-optdll</option>  <replaceable>option</replaceable>
 177           <indexterm><primary><option>-optdll</option></primary></indexterm>
 178         </term>
 179         <listitem>
 180           <para>Pass <replaceable>option</replaceable> to the DLL generator.</para>
 181         </listitem>
 182       </varlistentry>
 183       <varlistentry>
 184         <term>
 185           <option>-optdep</option>  <replaceable>option</replaceable>
 186           <indexterm><primary><option>-optdep</option></primary></indexterm>
 187         </term>
 188         <listitem>
 189           <para>Pass <replaceable>option</replaceable> to the
 190           dependency generator.</para>
 191         </listitem>
 192       </varlistentry>
 193     </variablelist>
 194
 195     <para>So, for example, to force an <option>-Ewurble</option>
 196     option to the assembler, you would tell the driver
 197     <option>-opta-Ewurble</option> (the dash before the E is
 198     required).</para>
 199
 200     <para>GHC is itself a Haskell program, so if you need to pass
 201     options directly to GHC's runtime system you can enclose them in
 202     <literal>+RTS ... -RTS</literal> (see <xref
 203     linkend="runtime-control"/>).</para>
 204
 205   </sect2>
 206
 207   <sect2 id="c-pre-processor">
 208     <title>Options affecting the C pre-processor</title>
 209
 210     <indexterm><primary>pre-processing: cpp</primary></indexterm>
 211     <indexterm><primary>C pre-processor options</primary></indexterm>
 212     <indexterm><primary>cpp, pre-processing with</primary></indexterm>
 213
 214     <variablelist>
 215
 216       <varlistentry>
 217         <term>
 218           <option>-cpp</option>
 219           <indexterm><primary><option>-cpp</option></primary></indexterm>
 220         </term>
 221         <listitem>
 222           <para>The C pre-processor <command>cpp</command> is run
 223           over your Haskell code only if the <option>-cpp</option>
 224           option <indexterm><primary>-cpp
 225           option</primary></indexterm> is given.  Unless you are
 226           building a large system with significant doses of
 227           conditional compilation, you really shouldn't need
 228           it.</para>
 229         </listitem>
 230       </varlistentry>
 231
 232       <varlistentry>
 233         <term>
 234           <option>-D</option><replaceable>symbol</replaceable><optional>=<replaceable>value</replaceable></optional>
 235           <indexterm><primary><option>-D</option></primary></indexterm>
 236         </term>
 237         <listitem>
 238           <para>Define macro <replaceable>symbol</replaceable> in the
 239           usual way.  NB: does <emphasis>not</emphasis> affect
 240           <option>-D</option> macros passed to the C&nbsp;compiler
 241           when compiling via C!  For those, use the
 242           <option>-optc-Dfoo</option> hack&hellip; (see <xref
 243           linkend="forcing-options-through"/>).</para>
 244         </listitem>
 245       </varlistentry>
 246
 247       <varlistentry>
 248         <term>
 249           <option>-U</option><replaceable>symbol</replaceable>
 250           <indexterm><primary><option>-U</option></primary></indexterm>
 251         </term>
 252         <listitem>
 253           <para> Undefine macro <replaceable>symbol</replaceable> in the
 254           usual way.</para>
 255         </listitem>
 256       </varlistentry>
 257
 258       <varlistentry>
 259         <term>
 260           <option>-I</option><replaceable>dir</replaceable>
 261           <indexterm><primary><option>-I</option></primary></indexterm>
 262         </term>
 263         <listitem>
 264           <para> Specify a directory in which to look for
 265           <literal>&num;include</literal> files, in the usual C
 266           way.</para>
 267         </listitem>
 268       </varlistentry>
 269     </variablelist>
 270
 271     <para>The GHC driver pre-defines several macros when processing
 272     Haskell source code (<filename>.hs</filename> or
 273     <filename>.lhs</filename> files).</para>
 274
 275     <para>The symbols defined by GHC are listed below.  To check which
 276     symbols are defined by your local GHC installation, the following
 277     trick is useful:</para>
 278
 279 <screen>$ ghc -E -optP-dM -cpp foo.hs
 280 $ cat foo.hspp</screen>
 281
 282     <para>(you need a file <filename>foo.hs</filename>, but it isn't
 283     actually used).</para>
 284
 285     <variablelist>
 286       <varlistentry>
 287         <term>
 288           <constant>&lowbar;&lowbar;HASKELL98&lowbar;&lowbar;</constant>
 289           <indexterm><primary><literal>&lowbar;&lowbar;HASKELL98&lowbar;&lowbar;</literal></primary></indexterm>
 290         </term>
 291         <listitem>
 292           <para>If defined, this means that GHC supports the
 293           language defined by the Haskell 98 report.</para>
 294         </listitem>
 295       </varlistentry>
 296
 297       <varlistentry>
 298         <term>
 299           <constant>&lowbar;&lowbar;HASKELL&lowbar;&lowbar;=98</constant>
 300           <indexterm><primary><constant>&lowbar;&lowbar;HASKELL&lowbar;&lowbar;=98</constant></primary></indexterm>
 301         </term>
 302         <listitem>
 303           <para>In GHC 4.04 and later, the
 304           <constant>&lowbar;&lowbar;HASKELL&lowbar;&lowbar;</constant>
 305           macro is defined as having the value
 306           <constant>98</constant>.</para>
 307         </listitem>
 308       </varlistentry>
 309
 310       <varlistentry>
 311         <term>
 312           <constant>&lowbar;&lowbar;HASKELL1&lowbar;&lowbar;</constant>
 313           <indexterm><primary><constant>&lowbar;&lowbar;HASKELL1&lowbar;&lowbar;</constant></primary></indexterm>
 314         </term>
 315         <listitem>
 316           <para>If defined to <replaceable>n</replaceable>, that
 317           means GHC supports the Haskell language defined in the
 318           Haskell report version <emphasis>1.n</emphasis>.
 319           Currently 5.  This macro is deprecated, and will probably
 320           disappear in future versions.</para>
 321         </listitem>
 322       </varlistentry>
 323
 324       <varlistentry>
 325         <term>
 326           <constant>&lowbar;&lowbar;GLASGOW&lowbar;HASKELL&lowbar;&lowbar;</constant>
 327           <indexterm><primary><constant>&lowbar;&lowbar;GLASGOW&lowbar;HASKELL&lowbar;&lowbar;</constant></primary></indexterm>
 328         </term>
 329         <listitem>
 330           <para>For version
 331           <literal><replaceable>x</replaceable>.<replaceable>y</replaceable>.<replaceable>z</replaceable></literal>
 332           of GHC, the value of
 333           <constant>&lowbar;&lowbar;GLASGOW&lowbar;HASKELL&lowbar;&lowbar;</constant>
 334           is the integer <replaceable>xyy</replaceable> (if
 335         <replaceable>y</replaceable> is a single digit, then a leading zero
 336         is added, so for example in version 6.2 of GHC,
 337         <literal>__GLASGOW_HASKELL__==602</literal>).  More
 338           information in <xref linkend="version-numbering"/>.</para>
 339
 340           <para>With any luck,
 341           <constant>&lowbar;&lowbar;GLASGOW&lowbar;HASKELL&lowbar;&lowbar;</constant>
 342           will be undefined in all other implementations that
 343           support C-style pre-processing.</para>
 344
 345           <para>(For reference: the comparable symbols for other
 346           systems are:
 347           <constant>&lowbar;&lowbar;HUGS&lowbar;&lowbar;</constant>
 348           for Hugs,
 349           <constant>&lowbar;&lowbar;NHC&lowbar;&lowbar;</constant>
 350           for nhc98, and
 351           <constant>&lowbar;&lowbar;HBC&lowbar;&lowbar;</constant>
 352           for hbc.)</para>
 353
 354           <para>NB. This macro is set when pre-processing both
 355           Haskell source and C source, including the C source
 356           generated from a Haskell module
 357           (i.e. <filename>.hs</filename>, <filename>.lhs</filename>,
 358           <filename>.c</filename> and <filename>.hc</filename>
 359           files).</para>
 360         </listitem>
 361       </varlistentry>
 362
 363       <varlistentry>
 364       <term>
 365           <constant>&lowbar;&lowbar;CONCURRENT&lowbar;HASKELL&lowbar;&lowbar;</constant>
 366           <indexterm><primary><constant>&lowbar;&lowbar;CONCURRENT&lowbar;HASKELL&lowbar;&lowbar;</constant></primary></indexterm>
 367         </term>
 368       <listitem>
 369         <para>This symbol is defined when pre-processing Haskell
 370           (input) and pre-processing C (GHC output).  Since GHC from
 371           verion 4.00 now supports concurrent haskell by default,
 372           this symbol is always defined.</para>
 373         </listitem>
 374       </varlistentry>
 375
 376       <varlistentry>
 377         <term>
 378           <constant>&lowbar;&lowbar;PARALLEL&lowbar;HASKELL&lowbar;&lowbar;</constant>
 379           <indexterm><primary><constant>&lowbar;&lowbar;PARALLEL&lowbar;HASKELL&lowbar;&lowbar;</constant></primary></indexterm>
 380         </term>
 381         <listitem>
 382           <para>Only defined when <option>-parallel</option> is in
 383           use!  This symbol is defined when pre-processing Haskell
 384           (input) and pre-processing C (GHC output).</para>
 385         </listitem>
 386       </varlistentry>
 387
 388       <varlistentry>
 389         <term>
 390           <constant><replaceable>os</replaceable>_HOST_OS=1</constant>
 391         </term>
 392         <listitem>
 393           <para>This define allows conditional compilation based on
 394           the Operating System, where<replaceable>os</replaceable> is
 395           the name of the current Operating System
 396           (eg. <literal>linux</literal>, <literal>mingw32</literal>
 397           for Windows, <literal>solaris</literal>, etc.).</para>
 398         </listitem>
 399       </varlistentry>
 400
 401       <varlistentry>
 402         <term>
 403           <constant><replaceable>arch</replaceable>_HOST_ARCH=1</constant>
 404         </term>
 405         <listitem>
 406           <para>This define allows conditional compilation based on
 407           the host architecture, where<replaceable>arch</replaceable>
 408           is the name of the current architecture
 409           (eg. <literal>i386</literal>, <literal>x86_64</literal>,
 410           <literal>powerpc</literal>, <literal>sparc</literal>,
 411           etc.).</para>
 412         </listitem>
 413       </varlistentry>
 414     </variablelist>
 415
 416     <sect3 id="cpp-string-gaps">
 417       <title>CPP and string gaps</title>
 418
 419       <para>A small word of warning: <option>-cpp</option> is not
 420       friendly to &ldquo;string gaps&rdquo;.<indexterm><primary>-cpp
 421       vs string gaps</primary></indexterm><indexterm><primary>string
 422       gaps vs -cpp</primary></indexterm>.  In other words, strings
 423       such as the following:</para>
 424
 425 <programlisting>strmod = "\
 426 \ p \
 427 \ "</programlisting>
 428
 429       <para>don't work with <option>-cpp</option>;
 430       <filename>/usr/bin/cpp</filename> elides the backslash-newline
 431       pairs.</para>
 432
 433       <para>However, it appears that if you add a space at the end
 434       of the line, then <command>cpp</command> (at least GNU
 435       <command>cpp</command> and possibly other
 436       <command>cpp</command>s) leaves the backslash-space pairs
 437       alone and the string gap works as expected.</para>
 438     </sect3>
 439   </sect2>
 440
 441   <sect2 id="pre-processor">
 442     <title>Options affecting a Haskell pre-processor</title>
 443
 444     <indexterm><primary>pre-processing: custom</primary></indexterm>
 445     <indexterm><primary>Pre-processor options</primary></indexterm>
 446
 447     <variablelist>
 448       <varlistentry>
 449         <term>
 450           <option>-F</option>
 451           <indexterm><primary><option>-F</option></primary></indexterm>
 452         </term>
 453         <listitem>
 454           <para>A custom pre-processor is run over your Haskell
 455           source file only if the <option>-F</option> option
 456           <indexterm><primary>-F</primary></indexterm> is
 457           given.</para>
 458
 459           <para>Running a custom pre-processor at compile-time is in
 460           some settings appropriate and useful. The
 461           <option>-F</option> option lets you run a pre-processor as
 462           part of the overall GHC compilation pipeline, which has
 463           the advantage over running a Haskell pre-processor
 464           separately in that it works in interpreted mode and you
 465           can continue to take reap the benefits of GHC's
 466           recompilation checker.</para>
 467
 468           <para>The pre-processor is run just before the Haskell
 469           compiler proper processes the Haskell input, but after the
 470           literate markup has been stripped away and (possibly) the
 471           C pre-processor has washed the Haskell input.</para>
 472
 473           <para>Use
 474           <option>-pgmF&nbsp;<replaceable>cmd</replaceable></option>
 475           to select the program to use as the preprocessor.  When
 476           invoked, the <replaceable>cmd</replaceable> pre-processor
 477           is given at least three arguments on its command-line: the
 478           first argument is the name of the original source file,
 479           the second is the name of the file holding the input, and
 480           the third is the name of the file where
 481           <replaceable>cmd</replaceable> should write its output
 482           to.</para>
 483
 484           <para>Additional arguments to the pre-processor can be
 485           passed in using the <option>-optF</option> option. These
 486           are fed to <replaceable>cmd</replaceable> on the command
 487           line after the three standard input and output
 488           arguments.</para>
 489         </listitem>
 490       </varlistentry>
 491     </variablelist>
 492   </sect2>
 493
 494   <sect2 id="options-C-compiler">
 495     <title>Options affecting the C compiler (if applicable)</title>
 496
 497     <indexterm><primary>include-file options</primary></indexterm>
 498     <indexterm><primary>C compiler options</primary></indexterm>
 499     <indexterm><primary>GCC options</primary></indexterm>
 500
 501     <para>If you are compiling with lots of foreign calls, you may
 502     need to tell the C&nbsp;compiler about some
 503     <literal>&num;include</literal> files.  The Right Way to do this is to
 504       add an <literal>INCLUDE</literal> pragma to the top of your source file
 505       (<xref linkend="include-pragma" />):</para>
 506
 507 <programlisting>{-# INCLUDE &lt;X/Xlib.h&gt; #-}</programlisting>
 508
 509     <para>Sometimes this isn't convenient.  In those cases there's an
 510       equivalent command-line option:</para>
 511
 512 <screen>% ghc -c '-#include &lt;X/Xlib.h&gt;' Xstuff.lhs</screen>
 513
 514     <indexterm><primary><option>-#include</option></primary>
 515     </indexterm>
 516
 517   </sect2>
 518
 519   <sect2 id="options-codegen">
 520     <title>Options affecting code generation</title>
 521
 522     <variablelist>
 523       <varlistentry>
 524         <term>
 525           <option>-fasm</option>
 526           <indexterm><primary><option>-fasm</option></primary></indexterm>
 527         </term>
 528         <listitem>
 529           <para>Use GHC's native code generator rather than
 530           compiling via C.  This will compile faster (up to twice as
 531           fast), but may produce code that is slightly slower than
 532           compiling via C.  <option>-fasm</option> is the default
 533           when optimisation is off (see <xref
 534           linkend="options-optimise"/>).</para>
 535         </listitem>
 536       </varlistentry>
 537
 538       <varlistentry>
 539         <term>
 540           <option>-fvia-C</option>
 541           <indexterm><primary><option>-fvia-C</option></primary></indexterm>
 542         </term>
 543         <listitem>
 544           <para>Compile via C instead of using the native code
 545           generator.  This is default for optimised compilations,
 546           and on architectures for which GHC doesn't have a native
 547           code generator.</para>
 548         </listitem>
 549       </varlistentry>
 550
 551       <varlistentry>
 552         <term>
 553           <option>-fno-code</option>
 554           <indexterm><primary><option>-fno-code</option></primary></indexterm>
 555         </term>
 556         <listitem>
 557           <para>Omit code generation (and all later phases)
 558           altogether.  Might be of some use if you just want to see
 559           dumps of the intermediate compilation phases.</para>
 560         </listitem>
 561       </varlistentry>
 562
 563       <varlistentry>
 564         <term>
 565           <option>-fPIC</option>
 566           <indexterm><primary><option>-fPIC</option></primary></indexterm>
 567         </term>
 568         <listitem>
 569           <para>Generate position-independent code (code that can be put into
 570           shared libraries). This currently works on Mac OS X; it works on
 571           PowerPC Linux when using the native code generator (-fasm).
 572           It is not quite ready to be used yet for x86 Linux.
 573           On Windows, position-independent code is never used,
 574           and on PowerPC64 Linux, position-independent code is always used,
 575           so the flag is a no-op on those platforms.</para>
 576         </listitem>
 577       </varlistentry>
 578
 579       <varlistentry>
 580         <term>
 581           <option>-dynamic</option>
 582         </term>
 583         <listitem>
 584           <para>When generating code, assume that entities imported from a
 585           different package will reside in a different shared library or
 586           binary. This currently works on Mac OS X; it works on PowerPC Linux when
 587           using the native code generator. As with <option>-fPIC</option>,
 588           x86 Linux support is not quite ready yet. Windows is not supported,
 589           and it is a no-op on PowerPC64 Linux.</para>
 590           <para>Note that this option also causes GHC to use shared libraries
 591           when linking.</para>
 592         </listitem>
 593       </varlistentry>
 594     </variablelist>
 595   </sect2>
 596
 597   <sect2 id="options-linker">
 598     <title>Options affecting linking</title>
 599
 600     <indexterm><primary>linker options</primary></indexterm>
 601     <indexterm><primary>ld options</primary></indexterm>
 602
 603
 604     <para>GHC has to link your code with various libraries, possibly
 605     including: user-supplied, GHC-supplied, and system-supplied
 606     (<option>-lm</option> math library, for example).</para>
 607
 608     <variablelist>
 609
 610       <varlistentry>
 611         <term>
 612           <option>-l</option><replaceable>lib</replaceable>
 613           <indexterm><primary><option>-l</option></primary></indexterm>
 614         </term>
 615         <listitem>
 616           <para>Link in the <replaceable>lib</replaceable> library.
 617           On Unix systems, this will be in a file called
 618           <filename>lib<replaceable>lib</replaceable>.a</filename>
 619           or
 620           <filename>lib<replaceable>lib</replaceable>.so</filename>
 621           which resides somewhere on the library directories path.</para>
 622
 623           <para>Because of the sad state of most UNIX linkers, the
 624           order of such options does matter.  If library
 625           <replaceable>foo</replaceable> requires library
 626           <replaceable>bar</replaceable>, then in general
 627           <option>-l</option><replaceable>foo</replaceable> should
 628           come <emphasis>before</emphasis>
 629           <option>-l</option><replaceable>bar</replaceable> on the
 630           command line.</para>
 631
 632           <para>There's one other gotcha to bear in mind when using
 633           external libraries: if the library contains a
 634           <literal>main()</literal> function, then this will be
 635           linked in preference to GHC's own
 636           <literal>main()</literal> function
 637           (eg. <literal>libf2c</literal> and <literal>libl</literal>
 638           have their own <literal>main()</literal>s).  This is
 639           because GHC's <literal>main()</literal> comes from the
 640           <literal>HSrts</literal> library, which is normally
 641           included <emphasis>after</emphasis> all the other
 642           libraries on the linker's command line.  To force GHC's
 643           <literal>main()</literal> to be used in preference to any
 644           other <literal>main()</literal>s from external libraries,
 645           just add the option <option>-lHSrts</option> before any
 646           other libraries on the command line.</para>
 647         </listitem>
 648       </varlistentry>
 649
 650       <varlistentry>
 651         <term>
 652           <option>-c</option>
 653           <indexterm><primary><option>-c</option></primary></indexterm>
 654         </term>
 655         <listitem>
 656           <para>Omits the link step.  This option can be used with
 657             <option>&ndash;&ndash;make</option> to avoid the automatic linking
 658             that takes place if the program contains a <literal>Main</literal>
 659             module.</para>
 660         </listitem>
 661       </varlistentry>
 662
 663       <varlistentry>
 664         <term>
 665           <option>-package</option> <replaceable>name</replaceable>
 666           <indexterm><primary><option>-package</option></primary></indexterm>
 667         </term>
 668         <listitem>
 669           <para>If you are using a Haskell &ldquo;package&rdquo;
 670           (see <xref linkend="packages"/>), don't forget to add the
 671           relevant <option>-package</option> option when linking the
 672           program too: it will cause the appropriate libraries to be
 673           linked in with the program.  Forgetting the
 674           <option>-package</option> option will likely result in
 675           several pages of link errors.</para>
 676         </listitem>
 677       </varlistentry>
 678
 679       <varlistentry>
 680         <term>
 681           <option>-framework</option> <replaceable>name</replaceable>
 682           <indexterm><primary><option>-framework</option></primary></indexterm>
 683         </term>
 684         <listitem>
 685           <para>On Darwin/MacOS X only, link in the framework <replaceable>name</replaceable>.
 686           This option corresponds to the <option>-framework</option> option for Apple's Linker.
 687           Please note that frameworks and packages are two different things - frameworks don't
 688           contain any haskell code. Rather, they are Apple's way of packaging shared libraries.
 689           To link to Apple's &ldquo;Carbon&rdquo; API, for example, you'd use
 690           <option>-framework Carbon</option>.
 691           </para>
 692         </listitem>
 693       </varlistentry>
 694
 695       <varlistentry>
 696         <term>
 697           <option>-L</option><replaceable>dir</replaceable>
 698           <indexterm><primary><option>-L</option></primary></indexterm>
 699         </term>
 700         <listitem>
 701           <para>Where to find user-supplied libraries&hellip;
 702           Prepend the directory <replaceable>dir</replaceable> to
 703           the library directories path.</para>
 704         </listitem>
 705       </varlistentry>
 706
 707       <varlistentry>
 708         <term>
 709           <option>-framework-path</option><replaceable>dir</replaceable>
 710           <indexterm><primary><option>-framework-path</option></primary></indexterm>
 711         </term>
 712         <listitem>
 713           <para>On Darwin/MacOS X only, prepend the directory <replaceable>dir</replaceable> to
 714           the framework directories path. This option corresponds to the <option>-F</option>
 715           option for Apple's Linker (<option>-F</option> already means something else for GHC).</para>
 716         </listitem>
 717       </varlistentry>
 718
 719       <varlistentry>
 720         <term>
 721           <option>-split-objs</option>
 722           <indexterm><primary><option>-split-objs</option></primary></indexterm>
 723         </term>
 724         <listitem>
 725           <para>Tell the linker to split the single object file that
 726           would normally be generated into multiple object files,
 727           one per top-level Haskell function or type in the module.
 728           We use this feature for building GHC's libraries libraries
 729           (warning: don't use it unless you know what you're
 730           doing!).</para>
 731         </listitem>
 732       </varlistentry>
 733
 734       <varlistentry>
 735         <term>
 736           <option>-static</option>
 737           <indexterm><primary><option>-static</option></primary></indexterm>
 738         </term>
 739         <listitem>
 740           <para>Tell the linker to avoid shared Haskell libraries,
 741           if possible.  This is the default.</para>
 742         </listitem>
 743       </varlistentry>
 744
 745       <varlistentry>
 746         <term>
 747           <option>-dynamic</option>
 748           <indexterm><primary><option>-dynamic</option></primary></indexterm>
 749         </term>
 750         <listitem>
 751           <para>Tell the linker to use shared Haskell libraries, if
 752           available (this option is only supported on Mac OS X at the
 753           moment, and also note that your distribution of GHC may
 754           not have been supplied with shared libraries).</para>
 755           <para>Note that this option also has an effect on
 756           code generation (see above).</para>
 757         </listitem>
 758       </varlistentry>
 759
 760       <varlistentry>
 761         <term>
 762           <option>-main-is <replaceable>thing</replaceable></option>
 763           <indexterm><primary><option>-main-is</option></primary></indexterm>
 764           <indexterm><primary>specifying your own main function</primary></indexterm>
 765         </term>
 766         <listitem>
 767           <para> The normal rule in Haskell is that your program must supply a <literal>main</literal>
 768             function in module <literal>Main</literal>.  When testing, it is often convenient
 769             to change which function is the "main" one, and the <option>-main-is</option> flag
 770             allows you to do so.  The  <replaceable>thing</replaceable> can be one of:
 771             <itemizedlist>
 772         <listitem><para>A lower-case identifier <literal>foo</literal>.  GHC assumes that the main function is <literal>Main.foo</literal>.</para></listitem>
 773         <listitem><para>An module name <literal>A</literal>.  GHC assumes that the main function is <literal>A.main</literal>.</para></listitem>
 774         <listitem><para>An qualified name <literal>A.foo</literal>.  GHC assumes that the main function is <literal>A.foo</literal>.</para></listitem>
 775         </itemizedlist>
 776             Strictly speaking, <option>-main-is</option> is not a link-phase flag at all; it has no effect on the link step.
 777             The flag must be specified when compiling the module containing the specified main function (e.g. module <literal>A</literal>
 778             in the latter two items above).  It has no effect for other modules,
 779             and hence can safely be given to <literal>ghc --make</literal>.
 780             However, if all the modules are otherwise up to date, you may need to force
 781             recompilation both of the module where the new "main" is, and of the
 782             module where the "main" function used to be;
 783             <literal>ghc</literal> is not clever
 784             enough to figure out that they both need recompiling.  You can
 785             force recompilation by removing the object file, or by using the
 786             <option>-no-recomp</option> flag.
 787             </para>
 788         </listitem>
 789       </varlistentry>
 790
 791       <varlistentry>
 792         <term>
 793           <option>-no-hs-main</option>
 794           <indexterm><primary><option>-no-hs-main</option></primary></indexterm>
 795           <indexterm><primary>linking Haskell libraries with foreign code</primary></indexterm>
 796         </term>
 797         <listitem>
 798           <para>In the event you want to include ghc-compiled code
 799           as part of another (non-Haskell) program, the RTS will not
 800           be supplying its definition of <function>main()</function>
 801           at link-time, you will have to. To signal that to the
 802           compiler when linking, use
 803           <option>-no-hs-main</option>. See also <xref linkend="using-own-main"/>.</para>
 804
 805           <para>Notice that since the command-line passed to the
 806           linker is rather involved, you probably want to use
 807           <command>ghc</command> to do the final link of your
 808           `mixed-language' application. This is not a requirement
 809           though, just try linking once with <option>-v</option> on
 810           to see what options the driver passes through to the
 811           linker.</para>
 812
 813           <para>The <option>-no-hs-main</option> flag can also be
 814           used to persuade the compiler to do the link step in
 815           <option>--make</option> mode when there is no Haskell
 816           <literal>Main</literal> module present (normally the
 817           compiler will not attempt linking when there is no
 818           <literal>Main</literal>).</para>
 819         </listitem>
 820       </varlistentry>
 821
 822       <varlistentry>
 823         <term>
 824           <option>-debug</option>
 825           <indexterm><primary><option>-debug</option></primary></indexterm>
 826         </term>
 827         <listitem>
 828           <para>Link the program with a debugging version of the
 829           runtime system.  The debugging runtime turns on numerous
 830           assertions and sanity checks, and provides extra options
 831           for producing debugging output at runtime (run the program
 832           with <literal>+RTS&nbsp;-?</literal> to see a list).</para>
 833         </listitem>
 834       </varlistentry>
 835
 836       <varlistentry>
 837         <term>
 838           <option>-threaded</option>
 839           <indexterm><primary><option>-threaded</option></primary></indexterm>
 840         </term>
 841         <listitem>
 842           <para>Link the program with the "threaded" runtime system.
 843           This version of the runtime is designed to be used in
 844           programs that use multiple operating-system threads.  It
 845           supports calls to foreign-exported functions from multiple
 846           OS threads.  Calls to foreign functions are made using the
 847           same OS thread that created the Haskell thread (if it was
 848           created by a call-in), or an arbitrary OS thread otherwise
 849           (if the Haskell thread was created by
 850           <literal>forkIO</literal>).</para>
 851
 852           <para>More details on the use of "bound threads" in the
 853           threaded runtime can be found in the <ulink
 854           url="../libraries/base/Control.Concurrent.html"><literal>Control.Concurrent</literal></ulink> module.</para>
 855
 856           <para>The threaded RTS does <emphasis>not</emphasis>
 857           support using multiple CPUs to speed up execution of a
 858           multi-threaded Haskell program.  The GHC runtime platform
 859           is still single-threaded, but using the
 860           <option>-threaded</option> option it can be used safely in
 861           a multi-threaded environment.</para>
 862         </listitem>
 863       </varlistentry>
 864     </variablelist>
 865   </sect2>
 866
 867 </sect1>
 868
 869 <!-- Emacs stuff:
 870      ;;; Local Variables: ***
 871      ;;; mode: xml ***
 872      ;;; sgml-parent-document: ("users_guide.xml" "book" "chapter" "sect1") ***
 873      ;;; End: ***
 874  -->