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