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