ghc/docs/users_guide/phases.xml

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