ghc/docs/users_guide/phases.sgml

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