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