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