ghc/docs/users_guide/phases.xml

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