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