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
 490           <para>
 491           An example of a pre-processor is to convert your source files to the
 492           input encoding that GHC expects, i.e. create a script
 493           <literal>convert.sh</literal> containing the lines:
 494           </para>
 495
 496 <screen>#!/bin/sh
 497 ( echo "{-# LINE 1 \"$2\" #-}" ; iconv -f l1 -t utf-8 $2 ) > $3</screen>
 498
 499           <para>and pass <literal>-F -pgmF convert.sh</literal> to GHC.
 500           The <literal>-f l1</literal> option tells iconv to convert your
 501           Latin-1 file, supplied in argument <literal>$2</literal>, while
 502           the "-t utf-8" options tell iconv to return a UTF-8 encoded file.
 503           The result is redirected into argument <literal>$3</literal>.
 504           The <literal>echo "{-# LINE 1 \"$2\" #-}"</literal>
 505           just makes sure that your error positions are reported as
 506           in the original source file.</para>
 507         </listitem>
 508       </varlistentry>
 509     </variablelist>
 510   </sect2>
 511
 512   <sect2 id="options-C-compiler">
 513     <title>Options affecting the C compiler (if applicable)</title>
 514
 515     <indexterm><primary>include-file options</primary></indexterm>
 516     <indexterm><primary>C compiler options</primary></indexterm>
 517     <indexterm><primary>GCC options</primary></indexterm>
 518
 519     <para>If you are compiling with lots of foreign calls, you may
 520     need to tell the C&nbsp;compiler about some
 521     <literal>&num;include</literal> files.  The Right Way to do this is to
 522       add an <literal>INCLUDE</literal> pragma to the top of your source file
 523       (<xref linkend="include-pragma" />):</para>
 524
 525 <programlisting>{-# INCLUDE &lt;X/Xlib.h&gt; #-}</programlisting>
 526
 527     <para>Sometimes this isn't convenient.  In those cases there's an
 528       equivalent command-line option:</para>
 529
 530 <screen>% ghc -c '-#include &lt;X/Xlib.h&gt;' Xstuff.lhs</screen>
 531
 532     <indexterm><primary><option>-#include</option></primary>
 533     </indexterm>
 534
 535   </sect2>
 536
 537   <sect2 id="options-codegen">
 538     <title>Options affecting code generation</title>
 539
 540     <variablelist>
 541       <varlistentry>
 542         <term>
 543           <option>-fasm</option>
 544           <indexterm><primary><option>-fasm</option></primary></indexterm>
 545         </term>
 546         <listitem>
 547           <para>Use GHC's native code generator rather than
 548           compiling via C.  This will compile faster (up to twice as
 549           fast), but may produce code that is slightly slower than
 550           compiling via C.  <option>-fasm</option> is the default
 551           when optimisation is off (see <xref
 552           linkend="options-optimise"/>).</para>
 553         </listitem>
 554       </varlistentry>
 555
 556       <varlistentry>
 557         <term>
 558           <option>-fvia-C</option>
 559           <indexterm><primary><option>-fvia-C</option></primary></indexterm>
 560         </term>
 561         <listitem>
 562           <para>Compile via C instead of using the native code
 563           generator.  This is default for optimised compilations,
 564           and on architectures for which GHC doesn't have a native
 565           code generator.</para>
 566         </listitem>
 567       </varlistentry>
 568
 569       <varlistentry>
 570         <term>
 571           <option>-fno-code</option>
 572           <indexterm><primary><option>-fno-code</option></primary></indexterm>
 573         </term>
 574         <listitem>
 575           <para>Omit code generation (and all later phases)
 576           altogether.  Might be of some use if you just want to see
 577           dumps of the intermediate compilation phases.</para>
 578         </listitem>
 579       </varlistentry>
 580
 581       <varlistentry>
 582         <term>
 583           <option>-fPIC</option>
 584           <indexterm><primary><option>-fPIC</option></primary></indexterm>
 585         </term>
 586         <listitem>
 587           <para>Generate position-independent code (code that can be put into
 588           shared libraries). This currently works on Mac OS X; it works on
 589           PowerPC Linux when using the native code generator (-fasm).
 590           It is not quite ready to be used yet for x86 Linux.
 591           On Windows, position-independent code is never used,
 592           and on PowerPC64 Linux, position-independent code is always used,
 593           so the flag is a no-op on those platforms.</para>
 594         </listitem>
 595       </varlistentry>
 596
 597       <varlistentry>
 598         <term>
 599           <option>-dynamic</option>
 600         </term>
 601         <listitem>
 602           <para>When generating code, assume that entities imported from a
 603           different package will reside in a different shared library or
 604           binary. This currently works on Mac OS X; it works on PowerPC Linux when
 605           using the native code generator. As with <option>-fPIC</option>,
 606           x86 Linux support is not quite ready yet. Windows is not supported,
 607           and it is a no-op on PowerPC64 Linux.</para>
 608           <para>Note that this option also causes GHC to use shared libraries
 609           when linking.</para>
 610         </listitem>
 611       </varlistentry>
 612     </variablelist>
 613   </sect2>
 614
 615   <sect2 id="options-linker">
 616     <title>Options affecting linking</title>
 617
 618     <indexterm><primary>linker options</primary></indexterm>
 619     <indexterm><primary>ld options</primary></indexterm>
 620
 621
 622     <para>GHC has to link your code with various libraries, possibly
 623     including: user-supplied, GHC-supplied, and system-supplied
 624     (<option>-lm</option> math library, for example).</para>
 625
 626     <variablelist>
 627
 628       <varlistentry>
 629         <term>
 630           <option>-l</option><replaceable>lib</replaceable>
 631           <indexterm><primary><option>-l</option></primary></indexterm>
 632         </term>
 633         <listitem>
 634           <para>Link in the <replaceable>lib</replaceable> library.
 635           On Unix systems, this will be in a file called
 636           <filename>lib<replaceable>lib</replaceable>.a</filename>
 637           or
 638           <filename>lib<replaceable>lib</replaceable>.so</filename>
 639           which resides somewhere on the library directories path.</para>
 640
 641           <para>Because of the sad state of most UNIX linkers, the
 642           order of such options does matter.  If library
 643           <replaceable>foo</replaceable> requires library
 644           <replaceable>bar</replaceable>, then in general
 645           <option>-l</option><replaceable>foo</replaceable> should
 646           come <emphasis>before</emphasis>
 647           <option>-l</option><replaceable>bar</replaceable> on the
 648           command line.</para>
 649
 650           <para>There's one other gotcha to bear in mind when using
 651           external libraries: if the library contains a
 652           <literal>main()</literal> function, then this will be
 653           linked in preference to GHC's own
 654           <literal>main()</literal> function
 655           (eg. <literal>libf2c</literal> and <literal>libl</literal>
 656           have their own <literal>main()</literal>s).  This is
 657           because GHC's <literal>main()</literal> comes from the
 658           <literal>HSrts</literal> library, which is normally
 659           included <emphasis>after</emphasis> all the other
 660           libraries on the linker's command line.  To force GHC's
 661           <literal>main()</literal> to be used in preference to any
 662           other <literal>main()</literal>s from external libraries,
 663           just add the option <option>-lHSrts</option> before any
 664           other libraries on the command line.</para>
 665         </listitem>
 666       </varlistentry>
 667
 668       <varlistentry>
 669         <term>
 670           <option>-c</option>
 671           <indexterm><primary><option>-c</option></primary></indexterm>
 672         </term>
 673         <listitem>
 674           <para>Omits the link step.  This option can be used with
 675             <option>&ndash;&ndash;make</option> to avoid the automatic linking
 676             that takes place if the program contains a <literal>Main</literal>
 677             module.</para>
 678         </listitem>
 679       </varlistentry>
 680
 681       <varlistentry>
 682         <term>
 683           <option>-package</option> <replaceable>name</replaceable>
 684           <indexterm><primary><option>-package</option></primary></indexterm>
 685         </term>
 686         <listitem>
 687           <para>If you are using a Haskell &ldquo;package&rdquo;
 688           (see <xref linkend="packages"/>), don't forget to add the
 689           relevant <option>-package</option> option when linking the
 690           program too: it will cause the appropriate libraries to be
 691           linked in with the program.  Forgetting the
 692           <option>-package</option> option will likely result in
 693           several pages of link errors.</para>
 694         </listitem>
 695       </varlistentry>
 696
 697       <varlistentry>
 698         <term>
 699           <option>-framework</option> <replaceable>name</replaceable>
 700           <indexterm><primary><option>-framework</option></primary></indexterm>
 701         </term>
 702         <listitem>
 703           <para>On Darwin/MacOS X only, link in the framework <replaceable>name</replaceable>.
 704           This option corresponds to the <option>-framework</option> option for Apple's Linker.
 705           Please note that frameworks and packages are two different things - frameworks don't
 706           contain any haskell code. Rather, they are Apple's way of packaging shared libraries.
 707           To link to Apple's &ldquo;Carbon&rdquo; API, for example, you'd use
 708           <option>-framework Carbon</option>.
 709           </para>
 710         </listitem>
 711       </varlistentry>
 712
 713       <varlistentry>
 714         <term>
 715           <option>-L</option><replaceable>dir</replaceable>
 716           <indexterm><primary><option>-L</option></primary></indexterm>
 717         </term>
 718         <listitem>
 719           <para>Where to find user-supplied libraries&hellip;
 720           Prepend the directory <replaceable>dir</replaceable> to
 721           the library directories path.</para>
 722         </listitem>
 723       </varlistentry>
 724
 725       <varlistentry>
 726         <term>
 727           <option>-framework-path</option><replaceable>dir</replaceable>
 728           <indexterm><primary><option>-framework-path</option></primary></indexterm>
 729         </term>
 730         <listitem>
 731           <para>On Darwin/MacOS X only, prepend the directory <replaceable>dir</replaceable> to
 732           the framework directories path. This option corresponds to the <option>-F</option>
 733           option for Apple's Linker (<option>-F</option> already means something else for GHC).</para>
 734         </listitem>
 735       </varlistentry>
 736
 737       <varlistentry>
 738         <term>
 739           <option>-split-objs</option>
 740           <indexterm><primary><option>-split-objs</option></primary></indexterm>
 741         </term>
 742         <listitem>
 743           <para>Tell the linker to split the single object file that
 744           would normally be generated into multiple object files,
 745           one per top-level Haskell function or type in the module.
 746           This only makes sense for libraries, where it means that
 747           executables linked against the library are smaller as they only
 748           link against the object files that they need. However, assembling
 749           all the sections separately is expensive, so this is slower than
 750           compiling normally.
 751           We use this feature for building GHC's libraries
 752           (warning: don't use it unless you know what you're
 753           doing!).</para>
 754         </listitem>
 755       </varlistentry>
 756
 757       <varlistentry>
 758         <term>
 759           <option>-static</option>
 760           <indexterm><primary><option>-static</option></primary></indexterm>
 761         </term>
 762         <listitem>
 763           <para>Tell the linker to avoid shared Haskell libraries,
 764           if possible.  This is the default.</para>
 765         </listitem>
 766       </varlistentry>
 767
 768       <varlistentry>
 769         <term>
 770           <option>-dynamic</option>
 771           <indexterm><primary><option>-dynamic</option></primary></indexterm>
 772         </term>
 773         <listitem>
 774           <para>Tell the linker to use shared Haskell libraries, if
 775           available (this option is only supported on Mac OS X at the
 776           moment, and also note that your distribution of GHC may
 777           not have been supplied with shared libraries).</para>
 778           <para>Note that this option also has an effect on
 779           code generation (see above).</para>
 780         </listitem>
 781       </varlistentry>
 782
 783       <varlistentry>
 784         <term>
 785           <option>-main-is <replaceable>thing</replaceable></option>
 786           <indexterm><primary><option>-main-is</option></primary></indexterm>
 787           <indexterm><primary>specifying your own main function</primary></indexterm>
 788         </term>
 789         <listitem>
 790           <para> The normal rule in Haskell is that your program must supply a <literal>main</literal>
 791             function in module <literal>Main</literal>.  When testing, it is often convenient
 792             to change which function is the "main" one, and the <option>-main-is</option> flag
 793             allows you to do so.  The  <replaceable>thing</replaceable> can be one of:
 794             <itemizedlist>
 795         <listitem><para>A lower-case identifier <literal>foo</literal>.  GHC assumes that the main function is <literal>Main.foo</literal>.</para></listitem>
 796         <listitem><para>An module name <literal>A</literal>.  GHC assumes that the main function is <literal>A.main</literal>.</para></listitem>
 797         <listitem><para>An qualified name <literal>A.foo</literal>.  GHC assumes that the main function is <literal>A.foo</literal>.</para></listitem>
 798         </itemizedlist>
 799             Strictly speaking, <option>-main-is</option> is not a link-phase flag at all; it has no effect on the link step.
 800             The flag must be specified when compiling the module containing the specified main function (e.g. module <literal>A</literal>
 801             in the latter two items above).  It has no effect for other modules,
 802             and hence can safely be given to <literal>ghc --make</literal>.
 803             However, if all the modules are otherwise up to date, you may need to force
 804             recompilation both of the module where the new "main" is, and of the
 805             module where the "main" function used to be;
 806             <literal>ghc</literal> is not clever
 807             enough to figure out that they both need recompiling.  You can
 808             force recompilation by removing the object file, or by using the
 809             <option>-fforce-recomp</option> flag.
 810             </para>
 811         </listitem>
 812       </varlistentry>
 813
 814       <varlistentry>
 815         <term>
 816           <option>-no-hs-main</option>
 817           <indexterm><primary><option>-no-hs-main</option></primary></indexterm>
 818           <indexterm><primary>linking Haskell libraries with foreign code</primary></indexterm>
 819         </term>
 820         <listitem>
 821           <para>In the event you want to include ghc-compiled code
 822           as part of another (non-Haskell) program, the RTS will not
 823           be supplying its definition of <function>main()</function>
 824           at link-time, you will have to. To signal that to the
 825           compiler when linking, use
 826           <option>-no-hs-main</option>. See also <xref linkend="using-own-main"/>.</para>
 827
 828           <para>Notice that since the command-line passed to the
 829           linker is rather involved, you probably want to use
 830           <command>ghc</command> to do the final link of your
 831           `mixed-language' application. This is not a requirement
 832           though, just try linking once with <option>-v</option> on
 833           to see what options the driver passes through to the
 834           linker.</para>
 835
 836           <para>The <option>-no-hs-main</option> flag can also be
 837           used to persuade the compiler to do the link step in
 838           <option>--make</option> mode when there is no Haskell
 839           <literal>Main</literal> module present (normally the
 840           compiler will not attempt linking when there is no
 841           <literal>Main</literal>).</para>
 842         </listitem>
 843       </varlistentry>
 844
 845       <varlistentry>
 846         <term>
 847           <option>-debug</option>
 848           <indexterm><primary><option>-debug</option></primary></indexterm>
 849         </term>
 850         <listitem>
 851           <para>Link the program with a debugging version of the
 852           runtime system.  The debugging runtime turns on numerous
 853           assertions and sanity checks, and provides extra options
 854           for producing debugging output at runtime (run the program
 855           with <literal>+RTS&nbsp;-?</literal> to see a list).</para>
 856         </listitem>
 857       </varlistentry>
 858
 859       <varlistentry>
 860         <term>
 861           <option>-threaded</option>
 862           <indexterm><primary><option>-threaded</option></primary></indexterm>
 863         </term>
 864         <listitem>
 865           <para>Link the program with the "threaded" version of the
 866           runtime system.  The threaded runtime system is so-called
 867           because it manages multiple OS threads, as opposed to the
 868           default runtime system which is purely
 869           single-threaded.</para>
 870
 871           <para>Note that you do <emphasis>not</emphasis> need
 872           <option>-threaded</option> in order to use concurrency; the
 873           single-threaded runtime supports concurrency between Haskell
 874           threads just fine.</para>
 875
 876           <para>The threaded runtime system provides the following
 877           benefits:</para>
 878
 879           <itemizedlist>
 880             <listitem>
 881               <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>
 882               machine.  See <xref linkend="sec-using-smp" />.</para>
 883
 884               <para>The ability to make a foreign call that does not
 885               block all other Haskell threads.</para>
 886
 887               <para>The ability to invoke foreign exported Haskell
 888               functions from multiple OS threads.</para>
 889             </listitem>
 890           </itemizedlist>
 891
 892           <para>With <option>-threaded</option>, calls to foreign
 893           functions are made using the same OS thread that created the
 894           Haskell thread (if it was created by a call to a foreign
 895           exported Haskell function), or an arbitrary OS thread
 896           otherwise (if the Haskell thread was created by
 897           <literal>forkIO</literal>).</para>
 898
 899           <para>More details on the use of "bound threads" in the
 900           threaded runtime can be found in the <ulink
 901           url="../libraries/base/Control.Concurrent.html"><literal>Control.Concurrent</literal></ulink> module.</para>
 902         </listitem>
 903       </varlistentry>
 904     </variablelist>
 905   </sect2>
 906
 907 </sect1>
 908
 909 <!-- Emacs stuff:
 910      ;;; Local Variables: ***
 911      ;;; mode: xml ***
 912      ;;; sgml-parent-document: ("users_guide.xml" "book" "chapter" "sect1") ***
 913      ;;; End: ***
 914  -->