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>-pgmm</option> <replaceable>cmd</replaceable>
  53           <indexterm><primary><option>-pgmm</option></primary></indexterm>
  54         </term>
  55         <listitem>
  56           <para>Use <replaceable>cmd</replaceable> as the
  57           mangler.</para>
  58         </listitem>
  59       </varlistentry>
  60
  61       <varlistentry>
  62         <term>
  63           <option>-pgms</option> <replaceable>cmd</replaceable>
  64           <indexterm><primary><option>-pgms</option></primary></indexterm>
  65         </term>
  66         <listitem>
  67           <para>Use <replaceable>cmd</replaceable> as the
  68           splitter.</para>
  69         </listitem>
  70       </varlistentry>
  71
  72       <varlistentry>
  73         <term>
  74           <option>-pgma</option> <replaceable>cmd</replaceable>
  75           <indexterm><primary><option>-pgma</option></primary></indexterm>
  76         </term>
  77         <listitem>
  78           <para>Use <replaceable>cmd</replaceable> as the
  79           assembler.</para>
  80         </listitem>
  81       </varlistentry>
  82
  83       <varlistentry>
  84         <term>
  85           <option>-pgml</option> <replaceable>cmd</replaceable>
  86           <indexterm><primary><option>-pgml</option></primary></indexterm>
  87         </term>
  88         <listitem>
  89           <para>Use <replaceable>cmd</replaceable> as the
  90           linker.</para>
  91         </listitem>
  92       </varlistentry>
  93
  94       <varlistentry>
  95         <term>
  96           <option>-pgmdll</option> <replaceable>cmd</replaceable>
  97           <indexterm><primary><option>-pgmdll</option></primary></indexterm>
  98         </term>
  99         <listitem>
 100           <para>Use <replaceable>cmd</replaceable> as the DLL
 101           generator.</para>
 102         </listitem>
 103       </varlistentry>
 104
 105       <varlistentry>
 106         <term>
 107           <option>-pgmF</option> <replaceable>cmd</replaceable>
 108           <indexterm><primary><option>-pgmF</option></primary></indexterm>
 109         </term>
 110         <listitem>
 111           <para>Use <replaceable>cmd</replaceable> as the
 112           pre-processor (with <option>-F</option> only).</para>
 113         </listitem>
 114       </varlistentry>
 115
 116       <varlistentry>
 117         <term>
 118           <option>-pgmwindres</option> <replaceable>cmd</replaceable>
 119           <indexterm><primary><option>-pgmwindres</option></primary></indexterm>
 120         </term>
 121         <listitem>
 122           <para>Use <replaceable>cmd</replaceable> as the
 123           program to use for embedding manifests on Windows.  Normally this
 124             is the program <literal>windres</literal>, which is supplied with a
 125             GHC installation. See <option>-fno-embed-manifest</option> in <xref
 126               linkend="options-linker" />.</para>
 127         </listitem>
 128       </varlistentry>
 129     </variablelist>
 130   </sect2>
 131
 132   <sect2 id="forcing-options-through">
 133     <title>Forcing options to a particular phase</title>
 134     <indexterm><primary>forcing GHC-phase options</primary></indexterm>
 135
 136     <para>Options can be forced through to a particular compilation
 137     phase, using the following flags:</para>
 138
 139     <variablelist>
 140       <varlistentry>
 141         <term>
 142           <option>-optL</option> <replaceable>option</replaceable>
 143           <indexterm><primary><option>-optL</option></primary></indexterm>
 144         </term>
 145         <listitem>
 146           <para>Pass <replaceable>option</replaceable> to the
 147           literate pre-processor</para>
 148         </listitem>
 149       </varlistentry>
 150       <varlistentry>
 151         <term>
 152           <option>-optP</option>  <replaceable>option</replaceable>
 153           <indexterm><primary><option>-optP</option></primary></indexterm>
 154         </term>
 155         <listitem>
 156           <para>Pass <replaceable>option</replaceable> to CPP (makes
 157           sense only if <option>-cpp</option> is also on).</para>
 158         </listitem>
 159       </varlistentry>
 160       <varlistentry>
 161         <term>
 162           <option>-optF</option> <replaceable>option</replaceable>
 163           <indexterm><primary><option>-optF</option></primary></indexterm>
 164         </term>
 165         <listitem>
 166           <para>Pass <replaceable>option</replaceable> to the
 167           custom pre-processor (see <xref linkend="pre-processor"/>).</para>
 168         </listitem>
 169       </varlistentry>
 170       <varlistentry>
 171         <term>
 172           <option>-optc</option> <replaceable>option</replaceable>
 173           <indexterm><primary><option>-optc</option></primary></indexterm>
 174         </term>
 175         <listitem>
 176           <para>Pass <replaceable>option</replaceable> to the C compiler.</para>
 177         </listitem>
 178       </varlistentry>
 179       <varlistentry>
 180         <term>
 181           <option>-optm</option>  <replaceable>option</replaceable>
 182           <indexterm><primary><option>-optm</option></primary></indexterm>
 183         </term>
 184         <listitem>
 185           <para>Pass <replaceable>option</replaceable> to the mangler.</para>
 186         </listitem>
 187       </varlistentry>
 188       <varlistentry>
 189         <term>
 190           <option>-opta</option>  <replaceable>option</replaceable>
 191           <indexterm><primary><option>-opta</option></primary></indexterm>
 192         </term>
 193         <listitem>
 194           <para>Pass <replaceable>option</replaceable> to the assembler.</para>
 195         </listitem>
 196       </varlistentry>
 197       <varlistentry>
 198         <term>
 199           <option>-optl</option> <replaceable>option</replaceable>
 200           <indexterm><primary><option>-optl</option></primary></indexterm>
 201         </term>
 202         <listitem>
 203           <para>Pass <replaceable>option</replaceable> to the linker.</para>
 204         </listitem>
 205       </varlistentry>
 206       <varlistentry>
 207         <term>
 208           <option>-optdll</option>  <replaceable>option</replaceable>
 209           <indexterm><primary><option>-optdll</option></primary></indexterm>
 210         </term>
 211         <listitem>
 212           <para>Pass <replaceable>option</replaceable> to the DLL generator.</para>
 213         </listitem>
 214       </varlistentry>
 215       <varlistentry>
 216         <term>
 217           <option>-optwindres</option>  <replaceable>option</replaceable>
 218           <indexterm><primary><option>-optwindres</option></primary></indexterm>
 219         </term>
 220         <listitem>
 221           <para>Pass <replaceable>option</replaceable> to
 222             <literal>windres</literal> when embedding manifests on Windows.
 223             See <option>-fno-embed-manifest</option> in <xref
 224               linkend="options-linker" />.</para>
 225         </listitem>
 226       </varlistentry>
 227     </variablelist>
 228
 229     <para>So, for example, to force an <option>-Ewurble</option>
 230     option to the assembler, you would tell the driver
 231     <option>-opta-Ewurble</option> (the dash before the E is
 232     required).</para>
 233
 234     <para>GHC is itself a Haskell program, so if you need to pass
 235     options directly to GHC's runtime system you can enclose them in
 236     <literal>+RTS ... -RTS</literal> (see <xref
 237     linkend="runtime-control"/>).</para>
 238
 239   </sect2>
 240
 241   <sect2 id="c-pre-processor">
 242     <title>Options affecting the C pre-processor</title>
 243
 244     <indexterm><primary>pre-processing: cpp</primary></indexterm>
 245     <indexterm><primary>C pre-processor options</primary></indexterm>
 246     <indexterm><primary>cpp, pre-processing with</primary></indexterm>
 247
 248     <variablelist>
 249
 250       <varlistentry>
 251         <term>
 252           <option>-cpp</option>
 253           <indexterm><primary><option>-cpp</option></primary></indexterm>
 254         </term>
 255         <listitem>
 256           <para>The C pre-processor <command>cpp</command> is run
 257           over your Haskell code only if the <option>-cpp</option>
 258           option <indexterm><primary>-cpp
 259           option</primary></indexterm> is given.  Unless you are
 260           building a large system with significant doses of
 261           conditional compilation, you really shouldn't need
 262           it.</para>
 263         </listitem>
 264       </varlistentry>
 265
 266       <varlistentry>
 267         <term>
 268           <option>-D</option><replaceable>symbol</replaceable><optional>=<replaceable>value</replaceable></optional>
 269           <indexterm><primary><option>-D</option></primary></indexterm>
 270         </term>
 271         <listitem>
 272           <para>Define macro <replaceable>symbol</replaceable> in the
 273           usual way.  NB: does <emphasis>not</emphasis> affect
 274           <option>-D</option> macros passed to the C&nbsp;compiler
 275           when compiling via C!  For those, use the
 276           <option>-optc-Dfoo</option> hack&hellip; (see <xref
 277           linkend="forcing-options-through"/>).</para>
 278         </listitem>
 279       </varlistentry>
 280
 281       <varlistentry>
 282         <term>
 283           <option>-U</option><replaceable>symbol</replaceable>
 284           <indexterm><primary><option>-U</option></primary></indexterm>
 285         </term>
 286         <listitem>
 287           <para> Undefine macro <replaceable>symbol</replaceable> in the
 288           usual way.</para>
 289         </listitem>
 290       </varlistentry>
 291
 292       <varlistentry>
 293         <term>
 294           <option>-I</option><replaceable>dir</replaceable>
 295           <indexterm><primary><option>-I</option></primary></indexterm>
 296         </term>
 297         <listitem>
 298           <para> Specify a directory in which to look for
 299           <literal>&num;include</literal> files, in the usual C
 300           way.</para>
 301         </listitem>
 302       </varlistentry>
 303     </variablelist>
 304
 305     <para>The GHC driver pre-defines several macros when processing
 306     Haskell source code (<filename>.hs</filename> or
 307     <filename>.lhs</filename> files).</para>
 308
 309     <para>The symbols defined by GHC are listed below.  To check which
 310     symbols are defined by your local GHC installation, the following
 311     trick is useful:</para>
 312
 313 <screen>$ ghc -E -optP-dM -cpp foo.hs
 314 $ cat foo.hspp</screen>
 315
 316     <para>(you need a file <filename>foo.hs</filename>, but it isn't
 317     actually used).</para>
 318
 319     <variablelist>
 320       <varlistentry>
 321         <term>
 322           <constant>&lowbar;&lowbar;HASKELL98&lowbar;&lowbar;</constant>
 323           <indexterm><primary><literal>&lowbar;&lowbar;HASKELL98&lowbar;&lowbar;</literal></primary></indexterm>
 324         </term>
 325         <listitem>
 326           <para>If defined, this means that GHC supports the
 327           language defined by the Haskell 98 report.</para>
 328         </listitem>
 329       </varlistentry>
 330
 331       <varlistentry>
 332         <term>
 333           <constant>&lowbar;&lowbar;HASKELL&lowbar;&lowbar;=98</constant>
 334           <indexterm><primary><constant>&lowbar;&lowbar;HASKELL&lowbar;&lowbar;=98</constant></primary></indexterm>
 335         </term>
 336         <listitem>
 337           <para>In GHC 4.04 and later, the
 338           <constant>&lowbar;&lowbar;HASKELL&lowbar;&lowbar;</constant>
 339           macro is defined as having the value
 340           <constant>98</constant>.</para>
 341         </listitem>
 342       </varlistentry>
 343
 344       <varlistentry>
 345         <term>
 346           <constant>&lowbar;&lowbar;HASKELL1&lowbar;&lowbar;</constant>
 347           <indexterm><primary><constant>&lowbar;&lowbar;HASKELL1&lowbar;&lowbar;</constant></primary></indexterm>
 348         </term>
 349         <listitem>
 350           <para>If defined to <replaceable>n</replaceable>, that
 351           means GHC supports the Haskell language defined in the
 352           Haskell report version <emphasis>1.n</emphasis>.
 353           Currently 5.  This macro is deprecated, and will probably
 354           disappear in future versions.</para>
 355         </listitem>
 356       </varlistentry>
 357
 358       <varlistentry>
 359         <term>
 360           <constant>&lowbar;&lowbar;GLASGOW&lowbar;HASKELL&lowbar;&lowbar;</constant>
 361           <indexterm><primary><constant>&lowbar;&lowbar;GLASGOW&lowbar;HASKELL&lowbar;&lowbar;</constant></primary></indexterm>
 362         </term>
 363         <listitem>
 364           <para>For version
 365           <literal><replaceable>x</replaceable>.<replaceable>y</replaceable>.<replaceable>z</replaceable></literal>
 366           of GHC, the value of
 367           <constant>&lowbar;&lowbar;GLASGOW&lowbar;HASKELL&lowbar;&lowbar;</constant>
 368           is the integer <replaceable>xyy</replaceable> (if
 369         <replaceable>y</replaceable> is a single digit, then a leading zero
 370         is added, so for example in version 6.2 of GHC,
 371         <literal>__GLASGOW_HASKELL__==602</literal>).  More
 372           information in <xref linkend="version-numbering"/>.</para>
 373
 374           <para>With any luck,
 375           <constant>&lowbar;&lowbar;GLASGOW&lowbar;HASKELL&lowbar;&lowbar;</constant>
 376           will be undefined in all other implementations that
 377           support C-style pre-processing.</para>
 378
 379           <para>(For reference: the comparable symbols for other
 380           systems are:
 381           <constant>&lowbar;&lowbar;HUGS&lowbar;&lowbar;</constant>
 382           for Hugs,
 383           <constant>&lowbar;&lowbar;NHC&lowbar;&lowbar;</constant>
 384           for nhc98, and
 385           <constant>&lowbar;&lowbar;HBC&lowbar;&lowbar;</constant>
 386           for hbc.)</para>
 387
 388           <para>NB. This macro is set when pre-processing both
 389           Haskell source and C source, including the C source
 390           generated from a Haskell module
 391           (i.e. <filename>.hs</filename>, <filename>.lhs</filename>,
 392           <filename>.c</filename> and <filename>.hc</filename>
 393           files).</para>
 394         </listitem>
 395       </varlistentry>
 396
 397       <varlistentry>
 398       <term>
 399           <constant>&lowbar;&lowbar;CONCURRENT&lowbar;HASKELL&lowbar;&lowbar;</constant>
 400           <indexterm><primary><constant>&lowbar;&lowbar;CONCURRENT&lowbar;HASKELL&lowbar;&lowbar;</constant></primary></indexterm>
 401         </term>
 402       <listitem>
 403         <para>This symbol is defined when pre-processing Haskell
 404           (input) and pre-processing C (GHC output).  Since GHC from
 405           version 4.00 now supports concurrent haskell by default,
 406           this symbol is always defined.</para>
 407         </listitem>
 408       </varlistentry>
 409
 410       <varlistentry>
 411         <term>
 412           <constant>&lowbar;&lowbar;PARALLEL&lowbar;HASKELL&lowbar;&lowbar;</constant>
 413           <indexterm><primary><constant>&lowbar;&lowbar;PARALLEL&lowbar;HASKELL&lowbar;&lowbar;</constant></primary></indexterm>
 414         </term>
 415         <listitem>
 416           <para>Only defined when <option>-parallel</option> is in
 417           use!  This symbol is defined when pre-processing Haskell
 418           (input) and pre-processing C (GHC output).</para>
 419         </listitem>
 420       </varlistentry>
 421
 422       <varlistentry>
 423         <term>
 424           <constant><replaceable>os</replaceable>_HOST_OS=1</constant>
 425         </term>
 426         <listitem>
 427           <para>This define allows conditional compilation based on
 428           the Operating System, where<replaceable>os</replaceable> is
 429           the name of the current Operating System
 430           (eg. <literal>linux</literal>, <literal>mingw32</literal>
 431           for Windows, <literal>solaris</literal>, etc.).</para>
 432         </listitem>
 433       </varlistentry>
 434
 435       <varlistentry>
 436         <term>
 437           <constant><replaceable>arch</replaceable>_HOST_ARCH=1</constant>
 438         </term>
 439         <listitem>
 440           <para>This define allows conditional compilation based on
 441           the host architecture, where<replaceable>arch</replaceable>
 442           is the name of the current architecture
 443           (eg. <literal>i386</literal>, <literal>x86_64</literal>,
 444           <literal>powerpc</literal>, <literal>sparc</literal>,
 445           etc.).</para>
 446         </listitem>
 447       </varlistentry>
 448     </variablelist>
 449
 450     <sect3 id="cpp-string-gaps">
 451       <title>CPP and string gaps</title>
 452
 453       <para>A small word of warning: <option>-cpp</option> is not
 454       friendly to &ldquo;string gaps&rdquo;.<indexterm><primary>-cpp
 455       vs string gaps</primary></indexterm><indexterm><primary>string
 456       gaps vs -cpp</primary></indexterm>.  In other words, strings
 457       such as the following:</para>
 458
 459 <programlisting>strmod = "\
 460 \ p \
 461 \ "</programlisting>
 462
 463       <para>don't work with <option>-cpp</option>;
 464       <filename>/usr/bin/cpp</filename> elides the backslash-newline
 465       pairs.</para>
 466
 467       <para>However, it appears that if you add a space at the end
 468       of the line, then <command>cpp</command> (at least GNU
 469       <command>cpp</command> and possibly other
 470       <command>cpp</command>s) leaves the backslash-space pairs
 471       alone and the string gap works as expected.</para>
 472     </sect3>
 473   </sect2>
 474
 475   <sect2 id="pre-processor">
 476     <title>Options affecting a Haskell pre-processor</title>
 477
 478     <indexterm><primary>pre-processing: custom</primary></indexterm>
 479     <indexterm><primary>Pre-processor options</primary></indexterm>
 480
 481     <variablelist>
 482       <varlistentry>
 483         <term>
 484           <option>-F</option>
 485           <indexterm><primary><option>-F</option></primary></indexterm>
 486         </term>
 487         <listitem>
 488           <para>A custom pre-processor is run over your Haskell
 489           source file only if the <option>-F</option> option
 490           <indexterm><primary>-F</primary></indexterm> is
 491           given.</para>
 492
 493           <para>Running a custom pre-processor at compile-time is in
 494           some settings appropriate and useful. The
 495           <option>-F</option> option lets you run a pre-processor as
 496           part of the overall GHC compilation pipeline, which has
 497           the advantage over running a Haskell pre-processor
 498           separately in that it works in interpreted mode and you
 499           can continue to take reap the benefits of GHC's
 500           recompilation checker.</para>
 501
 502           <para>The pre-processor is run just before the Haskell
 503           compiler proper processes the Haskell input, but after the
 504           literate markup has been stripped away and (possibly) the
 505           C pre-processor has washed the Haskell input.</para>
 506
 507           <para>Use
 508           <option>-pgmF&nbsp;<replaceable>cmd</replaceable></option>
 509           to select the program to use as the preprocessor.  When
 510           invoked, the <replaceable>cmd</replaceable> pre-processor
 511           is given at least three arguments on its command-line: the
 512           first argument is the name of the original source file,
 513           the second is the name of the file holding the input, and
 514           the third is the name of the file where
 515           <replaceable>cmd</replaceable> should write its output
 516           to.</para>
 517
 518           <para>Additional arguments to the pre-processor can be
 519           passed in using the <option>-optF</option> option. These
 520           are fed to <replaceable>cmd</replaceable> on the command
 521           line after the three standard input and output
 522           arguments.</para>
 523
 524           <para>
 525           An example of a pre-processor is to convert your source files to the
 526           input encoding that GHC expects, i.e. create a script
 527           <literal>convert.sh</literal> containing the lines:
 528           </para>
 529
 530 <screen>#!/bin/sh
 531 ( echo "{-# LINE 1 \"$2\" #-}" ; iconv -f l1 -t utf-8 $2 ) > $3</screen>
 532
 533           <para>and pass <literal>-F -pgmF convert.sh</literal> to GHC.
 534           The <literal>-f l1</literal> option tells iconv to convert your
 535           Latin-1 file, supplied in argument <literal>$2</literal>, while
 536           the "-t utf-8" options tell iconv to return a UTF-8 encoded file.
 537           The result is redirected into argument <literal>$3</literal>.
 538           The <literal>echo "{-# LINE 1 \"$2\" #-}"</literal>
 539           just makes sure that your error positions are reported as
 540           in the original source file.</para>
 541         </listitem>
 542       </varlistentry>
 543     </variablelist>
 544   </sect2>
 545
 546   <sect2 id="options-codegen">
 547     <title>Options affecting code generation</title>
 548
 549     <variablelist>
 550       <varlistentry>
 551         <term>
 552           <option>-fasm</option>
 553           <indexterm><primary><option>-fasm</option></primary></indexterm>
 554         </term>
 555         <listitem>
 556           <para>Use GHC's native code generator rather than
 557           compiling via C.  This will compile faster (up to twice as
 558           fast), but may produce code that is slightly slower than
 559           compiling via C.  <option>-fasm</option> is the default.</para>
 560         </listitem>
 561       </varlistentry>
 562
 563       <varlistentry>
 564         <term>
 565           <option>-fvia-C</option>
 566           <indexterm><primary><option>-fvia-C</option></primary></indexterm>
 567         </term>
 568         <listitem>
 569           <para>Compile via C instead of using the native code
 570           generator.  This is the default on architectures for which GHC
 571           doesn't have a native code generator.</para>
 572         </listitem>
 573       </varlistentry>
 574
 575       <varlistentry>
 576         <term>
 577           <option>-fno-code</option>
 578           <indexterm><primary><option>-fno-code</option></primary></indexterm>
 579         </term>
 580         <listitem>
 581           <para>Omit code generation (and all later phases)
 582           altogether.  Might be of some use if you just want to see
 583           dumps of the intermediate compilation phases.</para>
 584         </listitem>
 585       </varlistentry>
 586
 587       <varlistentry>
 588         <term>
 589           <option>-fobject-code</option>
 590           <indexterm><primary><option>-fobject-code</option></primary></indexterm>
 591         </term>
 592         <listitem>
 593           <para>Generate object code.  This is the default outside of
 594           GHCi, and can be used with GHCi to cause object code to be
 595           generated in preference to bytecode.</para>
 596         </listitem>
 597       </varlistentry>
 598
 599       <varlistentry>
 600         <term>
 601           <option>-fbyte-code</option>
 602           <indexterm><primary><option>-fbyte-code</option></primary></indexterm>
 603         </term>
 604         <listitem>
 605           <para>Generate byte-code instead of object-code.  This is
 606           the default in GHCi.  Byte-code can currently only be used
 607           in the interactive interpreter, not saved to disk.  This
 608           option is only useful for reversing the effect of
 609           <option>-fobject-code</option>.</para>
 610         </listitem>
 611       </varlistentry>
 612
 613       <varlistentry>
 614         <term>
 615           <option>-fPIC</option>
 616           <indexterm><primary><option>-fPIC</option></primary></indexterm>
 617         </term>
 618         <listitem>
 619           <para>Generate position-independent code (code that can be put into
 620           shared libraries). This currently works on Linux x86 and x86-64 when
 621           using the native code generator (-fasm).
 622           On Windows, position-independent code is never used
 623           so the flag is a no-op on that platform.</para>
 624         </listitem>
 625       </varlistentry>
 626
 627       <varlistentry>
 628         <term>
 629           <option>-dynamic</option>
 630         </term>
 631         <listitem>
 632           <para>When generating code, assume that entities imported from a
 633           different package will reside in a different shared library or
 634           binary.</para>
 635           <para>Note that using this option when linking causes GHC to link
 636           against shared libraries.</para>
 637         </listitem>
 638       </varlistentry>
 639     </variablelist>
 640   </sect2>
 641
 642   <sect2 id="options-linker">
 643     <title>Options affecting linking</title>
 644
 645     <indexterm><primary>linker options</primary></indexterm>
 646     <indexterm><primary>ld options</primary></indexterm>
 647
 648
 649     <para>GHC has to link your code with various libraries, possibly
 650     including: user-supplied, GHC-supplied, and system-supplied
 651     (<option>-lm</option> math library, for example).</para>
 652
 653     <variablelist>
 654
 655       <varlistentry>
 656         <term>
 657           <option>-l</option><replaceable>lib</replaceable>
 658           <indexterm><primary><option>-l</option></primary></indexterm>
 659         </term>
 660         <listitem>
 661           <para>Link in the <replaceable>lib</replaceable> library.
 662           On Unix systems, this will be in a file called
 663           <filename>lib<replaceable>lib</replaceable>.a</filename>
 664           or
 665           <filename>lib<replaceable>lib</replaceable>.so</filename>
 666           which resides somewhere on the library directories path.</para>
 667
 668           <para>Because of the sad state of most UNIX linkers, the
 669           order of such options does matter.  If library
 670           <replaceable>foo</replaceable> requires library
 671           <replaceable>bar</replaceable>, then in general
 672           <option>-l</option><replaceable>foo</replaceable> should
 673           come <emphasis>before</emphasis>
 674           <option>-l</option><replaceable>bar</replaceable> on the
 675           command line.</para>
 676
 677           <para>There's one other gotcha to bear in mind when using
 678           external libraries: if the library contains a
 679           <literal>main()</literal> function, then this will be
 680           linked in preference to GHC's own
 681           <literal>main()</literal> function
 682           (eg. <literal>libf2c</literal> and <literal>libl</literal>
 683           have their own <literal>main()</literal>s).  This is
 684           because GHC's <literal>main()</literal> comes from the
 685           <literal>HSrts</literal> library, which is normally
 686           included <emphasis>after</emphasis> all the other
 687           libraries on the linker's command line.  To force GHC's
 688           <literal>main()</literal> to be used in preference to any
 689           other <literal>main()</literal>s from external libraries,
 690           just add the option <option>-lHSrts</option> before any
 691           other libraries on the command line.</para>
 692         </listitem>
 693       </varlistentry>
 694
 695       <varlistentry>
 696         <term>
 697           <option>-c</option>
 698           <indexterm><primary><option>-c</option></primary></indexterm>
 699         </term>
 700         <listitem>
 701           <para>Omits the link step.  This option can be used with
 702             <option>&ndash;&ndash;make</option> to avoid the automatic linking
 703             that takes place if the program contains a <literal>Main</literal>
 704             module.</para>
 705         </listitem>
 706       </varlistentry>
 707
 708       <varlistentry>
 709         <term>
 710           <option>-package</option> <replaceable>name</replaceable>
 711           <indexterm><primary><option>-package</option></primary></indexterm>
 712         </term>
 713         <listitem>
 714           <para>If you are using a Haskell &ldquo;package&rdquo;
 715           (see <xref linkend="packages"/>), don't forget to add the
 716           relevant <option>-package</option> option when linking the
 717           program too: it will cause the appropriate libraries to be
 718           linked in with the program.  Forgetting the
 719           <option>-package</option> option will likely result in
 720           several pages of link errors.</para>
 721         </listitem>
 722       </varlistentry>
 723
 724       <varlistentry>
 725         <term>
 726           <option>-framework</option> <replaceable>name</replaceable>
 727           <indexterm><primary><option>-framework</option></primary></indexterm>
 728         </term>
 729         <listitem>
 730           <para>On Darwin/MacOS X only, link in the framework <replaceable>name</replaceable>.
 731           This option corresponds to the <option>-framework</option> option for Apple's Linker.
 732           Please note that frameworks and packages are two different things - frameworks don't
 733           contain any haskell code. Rather, they are Apple's way of packaging shared libraries.
 734           To link to Apple's &ldquo;Carbon&rdquo; API, for example, you'd use
 735           <option>-framework Carbon</option>.
 736           </para>
 737         </listitem>
 738       </varlistentry>
 739
 740       <varlistentry>
 741         <term>
 742           <option>-L</option><replaceable>dir</replaceable>
 743           <indexterm><primary><option>-L</option></primary></indexterm>
 744         </term>
 745         <listitem>
 746           <para>Where to find user-supplied libraries&hellip;
 747           Prepend the directory <replaceable>dir</replaceable> to
 748           the library directories path.</para>
 749         </listitem>
 750       </varlistentry>
 751
 752       <varlistentry>
 753         <term>
 754           <option>-framework-path</option><replaceable>dir</replaceable>
 755           <indexterm><primary><option>-framework-path</option></primary></indexterm>
 756         </term>
 757         <listitem>
 758           <para>On Darwin/MacOS X only, prepend the directory <replaceable>dir</replaceable> to
 759           the framework directories path. This option corresponds to the <option>-F</option>
 760           option for Apple's Linker (<option>-F</option> already means something else for GHC).</para>
 761         </listitem>
 762       </varlistentry>
 763
 764       <varlistentry>
 765         <term>
 766           <option>-split-objs</option>
 767           <indexterm><primary><option>-split-objs</option></primary></indexterm>
 768         </term>
 769         <listitem>
 770           <para>Tell the linker to split the single object file that
 771           would normally be generated into multiple object files,
 772           one per top-level Haskell function or type in the module.
 773           This only makes sense for libraries, where it means that
 774           executables linked against the library are smaller as they only
 775           link against the object files that they need. However, assembling
 776           all the sections separately is expensive, so this is slower than
 777           compiling normally.
 778           We use this feature for building GHC's libraries
 779           (warning: don't use it unless you know what you're
 780           doing!).</para>
 781         </listitem>
 782       </varlistentry>
 783
 784       <varlistentry>
 785         <term>
 786           <option>-static</option>
 787           <indexterm><primary><option>-static</option></primary></indexterm>
 788         </term>
 789         <listitem>
 790           <para>Tell the linker to avoid shared Haskell libraries,
 791           if possible.  This is the default.</para>
 792         </listitem>
 793       </varlistentry>
 794
 795       <varlistentry>
 796         <term>
 797           <option>-dynamic</option>
 798           <indexterm><primary><option>-dynamic</option></primary></indexterm>
 799         </term>
 800         <listitem>
 801           <para>This flag tells GHC to link against shared Haskell libraries.
 802           This flag only affects the selection of dependent libraries, not
 803           the form of the current target (see -shared).
 804           See <xref linkend="using-shared-libs" /> on how to
 805           create them.</para>
 806
 807           <para>Note that this option also has an effect on
 808           code generation (see above).</para>
 809         </listitem>
 810       </varlistentry>
 811
 812       <varlistentry>
 813         <term>
 814           <option>-shared</option>
 815           <indexterm><primary><option>-shared</option></primary></indexterm>
 816         </term>
 817         <listitem>
 818           <para>Instead of creating an executable, GHC produces a
 819           shared object with this linker flag. Depending on the
 820           operating system target, this might be an ELF DSO, a Windows
 821           DLL, or a Mac OS dylib. GHC hides the operating system
 822           details beneath this uniform flag.</para>
 823
 824           <para>The flags <option>-dynamic</option>/<option>-static</option> control whether the
 825           resulting shared object links statically or dynamically to
 826           Haskell package libraries given as <option>-package</option> option. Non-Haskell
 827           libraries are linked as gcc would regularly link it on your
 828           system, e.g. on most ELF system the linker uses the dynamic
 829           libraries when found.</para>
 830
 831           <para>Object files linked into shared objects must be
 832           compiled with <option>-fPIC</option>, see <xref linkend="options-codegen" /></para>
 833
 834           <para>When creating shared objects for Haskell packages, the
 835           shared object must be named properly, so that GHC recognizes
 836           the shared object when linked against this package. See
 837           shared object name mangling.</para>
 838         </listitem>
 839       </varlistentry>
 840
 841       <varlistentry>
 842         <term>
 843           <option>-dynload</option>
 844           <indexterm><primary><option>-dynload</option></primary></indexterm>
 845         </term>
 846         <listitem>
 847           <para>
 848             This flag selects one of a number of modes for finding shared
 849             libraries at runtime. See <xref linkend="finding-shared-libs"/> for
 850             a description of each mode.
 851           </para>
 852         </listitem>
 853       </varlistentry>
 854
 855       <varlistentry>
 856         <term>
 857           <option>-main-is <replaceable>thing</replaceable></option>
 858           <indexterm><primary><option>-main-is</option></primary></indexterm>
 859           <indexterm><primary>specifying your own main function</primary></indexterm>
 860         </term>
 861         <listitem>
 862           <para> The normal rule in Haskell is that your program must supply a <literal>main</literal>
 863             function in module <literal>Main</literal>.  When testing, it is often convenient
 864             to change which function is the "main" one, and the <option>-main-is</option> flag
 865             allows you to do so.  The  <replaceable>thing</replaceable> can be one of:
 866             <itemizedlist>
 867         <listitem><para>A lower-case identifier <literal>foo</literal>.  GHC assumes that the main function is <literal>Main.foo</literal>.</para></listitem>
 868         <listitem><para>An module name <literal>A</literal>.  GHC assumes that the main function is <literal>A.main</literal>.</para></listitem>
 869         <listitem><para>An qualified name <literal>A.foo</literal>.  GHC assumes that the main function is <literal>A.foo</literal>.</para></listitem>
 870         </itemizedlist>
 871             Strictly speaking, <option>-main-is</option> is not a link-phase flag at all; it has no effect on the link step.
 872             The flag must be specified when compiling the module containing the specified main function (e.g. module <literal>A</literal>
 873             in the latter two items above).  It has no effect for other modules,
 874             and hence can safely be given to <literal>ghc --make</literal>.
 875             However, if all the modules are otherwise up to date, you may need to force
 876             recompilation both of the module where the new "main" is, and of the
 877             module where the "main" function used to be;
 878             <literal>ghc</literal> is not clever
 879             enough to figure out that they both need recompiling.  You can
 880             force recompilation by removing the object file, or by using the
 881             <option>-fforce-recomp</option> flag.
 882             </para>
 883         </listitem>
 884       </varlistentry>
 885
 886       <varlistentry>
 887         <term>
 888           <option>-no-hs-main</option>
 889           <indexterm><primary><option>-no-hs-main</option></primary></indexterm>
 890           <indexterm><primary>linking Haskell libraries with foreign code</primary></indexterm>
 891         </term>
 892         <listitem>
 893           <para>In the event you want to include ghc-compiled code
 894           as part of another (non-Haskell) program, the RTS will not
 895           be supplying its definition of <function>main()</function>
 896           at link-time, you will have to. To signal that to the
 897           compiler when linking, use
 898           <option>-no-hs-main</option>. See also <xref linkend="using-own-main"/>.</para>
 899
 900           <para>Notice that since the command-line passed to the
 901           linker is rather involved, you probably want to use
 902           <command>ghc</command> to do the final link of your
 903           `mixed-language' application. This is not a requirement
 904           though, just try linking once with <option>-v</option> on
 905           to see what options the driver passes through to the
 906           linker.</para>
 907
 908           <para>The <option>-no-hs-main</option> flag can also be
 909           used to persuade the compiler to do the link step in
 910           <option>--make</option> mode when there is no Haskell
 911           <literal>Main</literal> module present (normally the
 912           compiler will not attempt linking when there is no
 913           <literal>Main</literal>).</para>
 914         </listitem>
 915       </varlistentry>
 916
 917       <varlistentry>
 918         <term>
 919           <option>-debug</option>
 920           <indexterm><primary><option>-debug</option></primary></indexterm>
 921         </term>
 922         <listitem>
 923           <para>Link the program with a debugging version of the
 924           runtime system.  The debugging runtime turns on numerous
 925           assertions and sanity checks, and provides extra options
 926           for producing debugging output at runtime (run the program
 927           with <literal>+RTS&nbsp;-?</literal> to see a list).</para>
 928         </listitem>
 929       </varlistentry>
 930
 931       <varlistentry>
 932         <term>
 933           <option>-threaded</option>
 934           <indexterm><primary><option>-threaded</option></primary></indexterm>
 935         </term>
 936         <listitem>
 937           <para>Link the program with the "threaded" version of the
 938           runtime system.  The threaded runtime system is so-called
 939           because it manages multiple OS threads, as opposed to the
 940           default runtime system which is purely
 941           single-threaded.</para>
 942
 943           <para>Note that you do <emphasis>not</emphasis> need
 944           <option>-threaded</option> in order to use concurrency; the
 945           single-threaded runtime supports concurrency between Haskell
 946           threads just fine.</para>
 947
 948           <para>The threaded runtime system provides the following
 949           benefits:</para>
 950
 951           <itemizedlist>
 952             <listitem>
 953               <para>Parallelism<indexterm><primary>parallelism</primary></indexterm> on a multiprocessor<indexterm><primary>multiprocessor</primary></indexterm><indexterm><primary>SMP</primary></indexterm> or multicore<indexterm><primary>multicore</primary></indexterm>
 954               machine.  See <xref linkend="using-smp" />.</para>
 955
 956               <para>The ability to make a foreign call that does not
 957               block all other Haskell threads, and to invoke
 958               foreign-exported Haskell functions from multiple OS
 959               threads. See <xref linkend="ffi-threads" />.</para>
 960             </listitem>
 961           </itemizedlist>
 962         </listitem>
 963       </varlistentry>
 964
 965       <varlistentry>
 966         <term>
 967           <option>-fno-gen-manifest</option>
 968           <indexterm><primary><option>-fno-gen-manifest</option></primary>
 969           </indexterm>
 970         </term>
 971         <listitem>
 972           <para>On Windows, GHC normally generates a
 973             <firstterm>manifest</firstterm><indexterm><primary>manifest</primary>
 974             </indexterm>file when linking a binary.  The
 975             manifest is placed in the file
 976             <literal><replaceable>prog</replaceable>.exe.manifest</literal>
 977             where <replaceable>prog.exe</replaceable> is the name of the
 978             executable.  The manifest file currently serves just one purpose:
 979             it disables the "installer detection"<indexterm><primary>installer detection</primary>
 980             </indexterm>in Windows Vista that
 981             attempts to elevate privileges for executables with certain names
 982             (e.g. names containing "install", "setup" or "patch").  Without the
 983             manifest file to turn off installer detection, attempting to run an
 984             executable that Windows deems to be an installer will return a
 985             permission error code to the invoker.  Depending on the invoker,
 986             the result might be a dialog box asking the user for elevated
 987             permissions, or it might simply be a permission denied
 988             error.</para>
 989
 990           <para>Installer detection can be also turned off globally for the
 991             system using the security control panel, but GHC by default
 992             generates binaries that don't depend on the user having disabled
 993             installer detection.</para>
 994
 995           <para>The <option>-fno-gen-manifest</option> disables generation of
 996             the manifest file.  One reason to do this would be if you had
 997             a manifest file of your own, for example.</para>
 998
 999           <para>In the future, GHC might use the manifest file for more things,
1000             such as supplying the location of dependent DLLs.</para>
1001
1002           <para><option>-fno-gen-manifest</option> also implies
1003             <option>-fno-embed-manifest</option>, see below.</para>
1004         </listitem>
1005       </varlistentry>
1006
1007       <varlistentry>
1008         <term>
1009           <option>-fno-embed-manifest</option>
1010           <indexterm><primary><option>-fno-embed-manifest</option></primary>
1011           </indexterm>
1012         </term>
1013         <listitem>
1014           <para>The manifest file that GHC generates when linking a binary on
1015             Windows is also embedded in the executable itself, by default.
1016             This means that the binary can be distributed without having to
1017             supply the manifest file too.  The embedding is done by running
1018             <literal>windres</literal><indexterm><primary><literal>windres</literal></primary>
1019             </indexterm>; to see exactly what GHC does to embed the manifest,
1020             use the <option>-v</option> flag.  A GHC installation comes with
1021             its own copy of <literal>windres</literal> for this reason.</para>
1022
1023           <para>See also <option>-pgmwindres</option> (<xref
1024               linkend="replacing-phases" />) and
1025             <option>-optwindres</option> (<xref
1026                                             linkend="forcing-options-through"
1027               />).</para>
1028         </listitem>
1029       </varlistentry>
1030
1031       <varlistentry>
1032         <term>
1033           <option>-fno-shared-implib</option>
1034           <indexterm><primary><option>-fno-shared-implib</option></primary>
1035           </indexterm>
1036         </term>
1037         <listitem>
1038           <para>DLLs on Windows are typically linked to by linking to a corresponding
1039             <literal>.lib</literal> or <literal>.dll.a</literal> - the so-called import library.
1040             GHC will typically generate such a file for every DLL you create by compiling in
1041             <literal>-shared</literal> mode. However, sometimes you don't want to pay the
1042             disk-space cost of creating this import library, which can be substantial - it
1043             might require as much space as the code itself, as Haskell DLLs tend to export
1044             lots of symbols.</para>
1045
1046           <para>As long as you are happy to only be able to link to the DLL using
1047             <literal>GetProcAddress</literal> and friends, you can supply the
1048             <option>-fno-shared-implib</option> flag to disable the creation of the import
1049             library entirely.</para>
1050         </listitem>
1051       </varlistentry>
1052     </variablelist>
1053   </sect2>
1054
1055 </sect1>
1056
1057 <!-- Emacs stuff:
1058      ;;; Local Variables: ***
1059      ;;; mode: xml ***
1060      ;;; sgml-parent-document: ("users_guide.xml" "book" "chapter" "sect1") ***
1061      ;;; End: ***
1062  -->