1 <?xml version="1.0" encoding="iso-8859-1"?>
2 <sect1 id="options-phases">
3 <title>Options related to a particular phase</title>
5 <sect2 id="replacing-phases">
6 <title>Replacing the program for one or more phases</title>
7 <indexterm><primary>phases, changing</primary></indexterm>
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>
19 <option>-pgmL</option> <replaceable>cmd</replaceable>
20 <indexterm><primary><option>-pgmL</option></primary></indexterm>
23 <para>Use <replaceable>cmd</replaceable> as the literate
30 <option>-pgmP</option> <replaceable>cmd</replaceable>
31 <indexterm><primary><option>-pgmP</option></primary></indexterm>
34 <para>Use <replaceable>cmd</replaceable> as the C
35 pre-processor (with <option>-cpp</option> only).</para>
41 <option>-pgmc</option> <replaceable>cmd</replaceable>
42 <indexterm><primary><option>-pgmc</option></primary></indexterm>
45 <para>Use <replaceable>cmd</replaceable> as the C
52 <option>-pgmm</option> <replaceable>cmd</replaceable>
53 <indexterm><primary><option>-pgmm</option></primary></indexterm>
56 <para>Use <replaceable>cmd</replaceable> as the
63 <option>-pgms</option> <replaceable>cmd</replaceable>
64 <indexterm><primary><option>-pgms</option></primary></indexterm>
67 <para>Use <replaceable>cmd</replaceable> as the
74 <option>-pgma</option> <replaceable>cmd</replaceable>
75 <indexterm><primary><option>-pgma</option></primary></indexterm>
78 <para>Use <replaceable>cmd</replaceable> as the
85 <option>-pgml</option> <replaceable>cmd</replaceable>
86 <indexterm><primary><option>-pgml</option></primary></indexterm>
89 <para>Use <replaceable>cmd</replaceable> as the
96 <option>-pgmdll</option> <replaceable>cmd</replaceable>
97 <indexterm><primary><option>-pgmdll</option></primary></indexterm>
100 <para>Use <replaceable>cmd</replaceable> as the DLL
107 <option>-pgmF</option> <replaceable>cmd</replaceable>
108 <indexterm><primary><option>-pgmF</option></primary></indexterm>
111 <para>Use <replaceable>cmd</replaceable> as the
112 pre-processor (with <option>-F</option> only).</para>
118 <option>-pgmwindres</option> <replaceable>cmd</replaceable>
119 <indexterm><primary><option>-pgmwindres</option></primary></indexterm>
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>
132 <sect2 id="forcing-options-through">
133 <title>Forcing options to a particular phase</title>
134 <indexterm><primary>forcing GHC-phase options</primary></indexterm>
136 <para>Options can be forced through to a particular compilation
137 phase, using the following flags:</para>
142 <option>-optL</option> <replaceable>option</replaceable>
143 <indexterm><primary><option>-optL</option></primary></indexterm>
146 <para>Pass <replaceable>option</replaceable> to the
147 literate pre-processor</para>
152 <option>-optP</option> <replaceable>option</replaceable>
153 <indexterm><primary><option>-optP</option></primary></indexterm>
156 <para>Pass <replaceable>option</replaceable> to CPP (makes
157 sense only if <option>-cpp</option> is also on).</para>
162 <option>-optF</option> <replaceable>option</replaceable>
163 <indexterm><primary><option>-optF</option></primary></indexterm>
166 <para>Pass <replaceable>option</replaceable> to the
167 custom pre-processor (see <xref linkend="pre-processor"/>).</para>
172 <option>-optc</option> <replaceable>option</replaceable>
173 <indexterm><primary><option>-optc</option></primary></indexterm>
176 <para>Pass <replaceable>option</replaceable> to the C compiler.</para>
181 <option>-optm</option> <replaceable>option</replaceable>
182 <indexterm><primary><option>-optm</option></primary></indexterm>
185 <para>Pass <replaceable>option</replaceable> to the mangler.</para>
190 <option>-opta</option> <replaceable>option</replaceable>
191 <indexterm><primary><option>-opta</option></primary></indexterm>
194 <para>Pass <replaceable>option</replaceable> to the assembler.</para>
199 <option>-optl</option> <replaceable>option</replaceable>
200 <indexterm><primary><option>-optl</option></primary></indexterm>
203 <para>Pass <replaceable>option</replaceable> to the linker.</para>
208 <option>-optdll</option> <replaceable>option</replaceable>
209 <indexterm><primary><option>-optdll</option></primary></indexterm>
212 <para>Pass <replaceable>option</replaceable> to the DLL generator.</para>
217 <option>-optwindres</option> <replaceable>option</replaceable>
218 <indexterm><primary><option>-optwindres</option></primary></indexterm>
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>
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
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>
241 <sect2 id="c-pre-processor">
242 <title>Options affecting the C pre-processor</title>
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>
252 <option>-cpp</option>
253 <indexterm><primary><option>-cpp</option></primary></indexterm>
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
268 <option>-D</option><replaceable>symbol</replaceable><optional>=<replaceable>value</replaceable></optional>
269 <indexterm><primary><option>-D</option></primary></indexterm>
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 compiler
275 when compiling via C! For those, use the
276 <option>-optc-Dfoo</option> hack… (see <xref
277 linkend="forcing-options-through"/>).</para>
283 <option>-U</option><replaceable>symbol</replaceable>
284 <indexterm><primary><option>-U</option></primary></indexterm>
287 <para> Undefine macro <replaceable>symbol</replaceable> in the
294 <option>-I</option><replaceable>dir</replaceable>
295 <indexterm><primary><option>-I</option></primary></indexterm>
298 <para> Specify a directory in which to look for
299 <literal>#include</literal> files, in the usual C
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>
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>
313 <screen>$ ghc -E -optP-dM -cpp foo.hs
314 $ cat foo.hspp</screen>
316 <para>(you need a file <filename>foo.hs</filename>, but it isn't
317 actually used).</para>
322 <constant>__HASKELL98__</constant>
323 <indexterm><primary><literal>__HASKELL98__</literal></primary></indexterm>
326 <para>If defined, this means that GHC supports the
327 language defined by the Haskell 98 report.</para>
333 <constant>__HASKELL__=98</constant>
334 <indexterm><primary><constant>__HASKELL__=98</constant></primary></indexterm>
337 <para>In GHC 4.04 and later, the
338 <constant>__HASKELL__</constant>
339 macro is defined as having the value
340 <constant>98</constant>.</para>
346 <constant>__HASKELL1__</constant>
347 <indexterm><primary><constant>__HASKELL1__</constant></primary></indexterm>
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>
360 <constant>__GLASGOW_HASKELL__</constant>
361 <indexterm><primary><constant>__GLASGOW_HASKELL__</constant></primary></indexterm>
365 <literal><replaceable>x</replaceable>.<replaceable>y</replaceable>.<replaceable>z</replaceable></literal>
367 <constant>__GLASGOW_HASKELL__</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>
375 <constant>__GLASGOW_HASKELL__</constant>
376 will be undefined in all other implementations that
377 support C-style pre-processing.</para>
379 <para>(For reference: the comparable symbols for other
381 <constant>__HUGS__</constant>
383 <constant>__NHC__</constant>
385 <constant>__HBC__</constant>
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>
399 <constant>__CONCURRENT_HASKELL__</constant>
400 <indexterm><primary><constant>__CONCURRENT_HASKELL__</constant></primary></indexterm>
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>
412 <constant>__PARALLEL_HASKELL__</constant>
413 <indexterm><primary><constant>__PARALLEL_HASKELL__</constant></primary></indexterm>
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>
424 <constant><replaceable>os</replaceable>_HOST_OS=1</constant>
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>
437 <constant><replaceable>arch</replaceable>_HOST_ARCH=1</constant>
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>,
450 <sect3 id="cpp-string-gaps">
451 <title>CPP and string gaps</title>
453 <para>A small word of warning: <option>-cpp</option> is not
454 friendly to “string gaps”.<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>
459 <programlisting>strmod = "\
463 <para>don't work with <option>-cpp</option>;
464 <filename>/usr/bin/cpp</filename> elides the backslash-newline
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>
475 <sect2 id="pre-processor">
476 <title>Options affecting a Haskell pre-processor</title>
478 <indexterm><primary>pre-processing: custom</primary></indexterm>
479 <indexterm><primary>Pre-processor options</primary></indexterm>
485 <indexterm><primary><option>-F</option></primary></indexterm>
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
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>
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>
508 <option>-pgmF <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
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
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:
531 ( echo "{-# LINE 1 \"$2\" #-}" ; iconv -f l1 -t utf-8 $2 ) > $3</screen>
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>
546 <sect2 id="options-codegen">
547 <title>Options affecting code generation</title>
552 <option>-fasm</option>
553 <indexterm><primary><option>-fasm</option></primary></indexterm>
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>
565 <option>-fvia-C</option>
566 <indexterm><primary><option>-fvia-C</option></primary></indexterm>
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>
577 <option>-fno-code</option>
578 <indexterm><primary><option>-fno-code</option></primary></indexterm>
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>
589 <option>-fobject-code</option>
590 <indexterm><primary><option>-fobject-code</option></primary></indexterm>
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>
601 <option>-fbyte-code</option>
602 <indexterm><primary><option>-fbyte-code</option></primary></indexterm>
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>
615 <option>-fPIC</option>
616 <indexterm><primary><option>-fPIC</option></primary></indexterm>
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>
629 <option>-dynamic</option>
632 <para>When generating code, assume that entities imported from a
633 different package will reside in a different shared library or
635 <para>Note that using this option when linking causes GHC to link
636 against shared libraries.</para>
642 <sect2 id="options-linker">
643 <title>Options affecting linking</title>
645 <indexterm><primary>linker options</primary></indexterm>
646 <indexterm><primary>ld options</primary></indexterm>
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>
657 <option>-l</option><replaceable>lib</replaceable>
658 <indexterm><primary><option>-l</option></primary></indexterm>
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>
665 <filename>lib<replaceable>lib</replaceable>.so</filename>
666 which resides somewhere on the library directories path.</para>
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
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>
698 <indexterm><primary><option>-c</option></primary></indexterm>
701 <para>Omits the link step. This option can be used with
702 <option>––make</option> to avoid the automatic linking
703 that takes place if the program contains a <literal>Main</literal>
710 <option>-package</option> <replaceable>name</replaceable>
711 <indexterm><primary><option>-package</option></primary></indexterm>
714 <para>If you are using a Haskell “package”
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>
726 <option>-framework</option> <replaceable>name</replaceable>
727 <indexterm><primary><option>-framework</option></primary></indexterm>
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 “Carbon” API, for example, you'd use
735 <option>-framework Carbon</option>.
742 <option>-L</option><replaceable>dir</replaceable>
743 <indexterm><primary><option>-L</option></primary></indexterm>
746 <para>Where to find user-supplied libraries…
747 Prepend the directory <replaceable>dir</replaceable> to
748 the library directories path.</para>
754 <option>-framework-path</option><replaceable>dir</replaceable>
755 <indexterm><primary><option>-framework-path</option></primary></indexterm>
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>
766 <option>-split-objs</option>
767 <indexterm><primary><option>-split-objs</option></primary></indexterm>
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
778 We use this feature for building GHC's libraries
779 (warning: don't use it unless you know what you're
786 <option>-static</option>
787 <indexterm><primary><option>-static</option></primary></indexterm>
790 <para>Tell the linker to avoid shared Haskell libraries,
791 if possible. This is the default.</para>
797 <option>-dynamic</option>
798 <indexterm><primary><option>-dynamic</option></primary></indexterm>
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
807 <para>Note that this option also has an effect on
808 code generation (see above).</para>
814 <option>-shared</option>
815 <indexterm><primary><option>-shared</option></primary></indexterm>
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>
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>
831 <para>Object files linked into shared objects must be
832 compiled with <option>-fPIC</option>, see <xref linkend="options-codegen" /></para>
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>
843 <option>-dynload</option>
844 <indexterm><primary><option>-dynload</option></primary></indexterm>
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.
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>
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:
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>
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.
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>
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>
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
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>
919 <option>-debug</option>
920 <indexterm><primary><option>-debug</option></primary></indexterm>
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 -?</literal> to see a list).</para>
933 <option>-threaded</option>
934 <indexterm><primary><option>-threaded</option></primary></indexterm>
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>
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>
948 <para>The threaded runtime system provides the following
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>
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>
967 <option>-fno-gen-manifest</option>
968 <indexterm><primary><option>-fno-gen-manifest</option></primary>
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
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>
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>
999 <para>In the future, GHC might use the manifest file for more things,
1000 such as supplying the location of dependent DLLs.</para>
1002 <para><option>-fno-gen-manifest</option> also implies
1003 <option>-fno-embed-manifest</option>, see below.</para>
1009 <option>-fno-embed-manifest</option>
1010 <indexterm><primary><option>-fno-embed-manifest</option></primary>
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>
1023 <para>See also <option>-pgmwindres</option> (<xref
1024 linkend="replacing-phases" />) and
1025 <option>-optwindres</option> (<xref
1026 linkend="forcing-options-through"
1033 <option>-fno-shared-implib</option>
1034 <indexterm><primary><option>-fno-shared-implib</option></primary>
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>
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>
1058 ;;; Local Variables: ***
1060 ;;; sgml-parent-document: ("users_guide.xml" "book" "chapter" "sect1") ***