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