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>-pgmlo</option> <replaceable>cmd</replaceable>
53 <indexterm><primary><option>-pgmlo</option></primary></indexterm>
56 <para>Use <replaceable>cmd</replaceable> as the LLVM
63 <option>-pgmlc</option> <replaceable>cmd</replaceable>
64 <indexterm><primary><option>-pgmlc</option></primary></indexterm>
67 <para>Use <replaceable>cmd</replaceable> as the LLVM
74 <option>-pgmm</option> <replaceable>cmd</replaceable>
75 <indexterm><primary><option>-pgmm</option></primary></indexterm>
78 <para>Use <replaceable>cmd</replaceable> as the
85 <option>-pgms</option> <replaceable>cmd</replaceable>
86 <indexterm><primary><option>-pgms</option></primary></indexterm>
89 <para>Use <replaceable>cmd</replaceable> as the
96 <option>-pgma</option> <replaceable>cmd</replaceable>
97 <indexterm><primary><option>-pgma</option></primary></indexterm>
100 <para>Use <replaceable>cmd</replaceable> as the
107 <option>-pgml</option> <replaceable>cmd</replaceable>
108 <indexterm><primary><option>-pgml</option></primary></indexterm>
111 <para>Use <replaceable>cmd</replaceable> as the
118 <option>-pgmdll</option> <replaceable>cmd</replaceable>
119 <indexterm><primary><option>-pgmdll</option></primary></indexterm>
122 <para>Use <replaceable>cmd</replaceable> as the DLL
129 <option>-pgmF</option> <replaceable>cmd</replaceable>
130 <indexterm><primary><option>-pgmF</option></primary></indexterm>
133 <para>Use <replaceable>cmd</replaceable> as the
134 pre-processor (with <option>-F</option> only).</para>
140 <option>-pgmwindres</option> <replaceable>cmd</replaceable>
141 <indexterm><primary><option>-pgmwindres</option></primary></indexterm>
144 <para>Use <replaceable>cmd</replaceable> as the
145 program to use for embedding manifests on Windows. Normally this
146 is the program <literal>windres</literal>, which is supplied with a
147 GHC installation. See <option>-fno-embed-manifest</option> in <xref
148 linkend="options-linker" />.</para>
154 <sect2 id="forcing-options-through">
155 <title>Forcing options to a particular phase</title>
156 <indexterm><primary>forcing GHC-phase options</primary></indexterm>
158 <para>Options can be forced through to a particular compilation
159 phase, using the following flags:</para>
164 <option>-optL</option> <replaceable>option</replaceable>
165 <indexterm><primary><option>-optL</option></primary></indexterm>
168 <para>Pass <replaceable>option</replaceable> to the
169 literate pre-processor</para>
174 <option>-optP</option> <replaceable>option</replaceable>
175 <indexterm><primary><option>-optP</option></primary></indexterm>
178 <para>Pass <replaceable>option</replaceable> to CPP (makes
179 sense only if <option>-cpp</option> is also on).</para>
184 <option>-optF</option> <replaceable>option</replaceable>
185 <indexterm><primary><option>-optF</option></primary></indexterm>
188 <para>Pass <replaceable>option</replaceable> to the
189 custom pre-processor (see <xref linkend="pre-processor"/>).</para>
194 <option>-optc</option> <replaceable>option</replaceable>
195 <indexterm><primary><option>-optc</option></primary></indexterm>
198 <para>Pass <replaceable>option</replaceable> to the C compiler.</para>
203 <option>-optlo</option> <replaceable>option</replaceable>
204 <indexterm><primary><option>-optlo</option></primary></indexterm>
207 <para>Pass <replaceable>option</replaceable> to the LLVM optimiser.</para>
212 <option>-optlc</option> <replaceable>option</replaceable>
213 <indexterm><primary><option>-optlc</option></primary></indexterm>
216 <para>Pass <replaceable>option</replaceable> to the LLVM compiler.</para>
221 <option>-optm</option> <replaceable>option</replaceable>
222 <indexterm><primary><option>-optm</option></primary></indexterm>
225 <para>Pass <replaceable>option</replaceable> to the mangler.</para>
230 <option>-opta</option> <replaceable>option</replaceable>
231 <indexterm><primary><option>-opta</option></primary></indexterm>
234 <para>Pass <replaceable>option</replaceable> to the assembler.</para>
239 <option>-optl</option> <replaceable>option</replaceable>
240 <indexterm><primary><option>-optl</option></primary></indexterm>
243 <para>Pass <replaceable>option</replaceable> to the linker.</para>
248 <option>-optdll</option> <replaceable>option</replaceable>
249 <indexterm><primary><option>-optdll</option></primary></indexterm>
252 <para>Pass <replaceable>option</replaceable> to the DLL generator.</para>
257 <option>-optwindres</option> <replaceable>option</replaceable>
258 <indexterm><primary><option>-optwindres</option></primary></indexterm>
261 <para>Pass <replaceable>option</replaceable> to
262 <literal>windres</literal> when embedding manifests on Windows.
263 See <option>-fno-embed-manifest</option> in <xref
264 linkend="options-linker" />.</para>
269 <para>So, for example, to force an <option>-Ewurble</option>
270 option to the assembler, you would tell the driver
271 <option>-opta-Ewurble</option> (the dash before the E is
274 <para>GHC is itself a Haskell program, so if you need to pass
275 options directly to GHC's runtime system you can enclose them in
276 <literal>+RTS ... -RTS</literal> (see <xref
277 linkend="runtime-control"/>).</para>
281 <sect2 id="c-pre-processor">
282 <title>Options affecting the C pre-processor</title>
284 <indexterm><primary>pre-processing: cpp</primary></indexterm>
285 <indexterm><primary>C pre-processor options</primary></indexterm>
286 <indexterm><primary>cpp, pre-processing with</primary></indexterm>
292 <option>-cpp</option>
293 <indexterm><primary><option>-cpp</option></primary></indexterm>
296 <para>The C pre-processor <command>cpp</command> is run
297 over your Haskell code only if the <option>-cpp</option>
298 option <indexterm><primary>-cpp
299 option</primary></indexterm> is given. Unless you are
300 building a large system with significant doses of
301 conditional compilation, you really shouldn't need
308 <option>-D</option><replaceable>symbol</replaceable><optional>=<replaceable>value</replaceable></optional>
309 <indexterm><primary><option>-D</option></primary></indexterm>
312 <para>Define macro <replaceable>symbol</replaceable> in the
313 usual way. NB: does <emphasis>not</emphasis> affect
314 <option>-D</option> macros passed to the C compiler
315 when compiling via C! For those, use the
316 <option>-optc-Dfoo</option> hack… (see <xref
317 linkend="forcing-options-through"/>).</para>
323 <option>-U</option><replaceable>symbol</replaceable>
324 <indexterm><primary><option>-U</option></primary></indexterm>
327 <para> Undefine macro <replaceable>symbol</replaceable> in the
334 <option>-I</option><replaceable>dir</replaceable>
335 <indexterm><primary><option>-I</option></primary></indexterm>
338 <para> Specify a directory in which to look for
339 <literal>#include</literal> files, in the usual C
345 <para>The GHC driver pre-defines several macros when processing
346 Haskell source code (<filename>.hs</filename> or
347 <filename>.lhs</filename> files).</para>
349 <para>The symbols defined by GHC are listed below. To check which
350 symbols are defined by your local GHC installation, the following
351 trick is useful:</para>
353 <screen>$ ghc -E -optP-dM -cpp foo.hs
354 $ cat foo.hspp</screen>
356 <para>(you need a file <filename>foo.hs</filename>, but it isn't
357 actually used).</para>
362 <constant>__HASKELL98__</constant>
363 <indexterm><primary><literal>__HASKELL98__</literal></primary></indexterm>
366 <para>If defined, this means that GHC supports the
367 language defined by the Haskell 98 report.</para>
373 <constant>__HASKELL__=98</constant>
374 <indexterm><primary><constant>__HASKELL__=98</constant></primary></indexterm>
377 <para>In GHC 4.04 and later, the
378 <constant>__HASKELL__</constant>
379 macro is defined as having the value
380 <constant>98</constant>.</para>
386 <constant>__HASKELL1__</constant>
387 <indexterm><primary><constant>__HASKELL1__</constant></primary></indexterm>
390 <para>If defined to <replaceable>n</replaceable>, that
391 means GHC supports the Haskell language defined in the
392 Haskell report version <emphasis>1.n</emphasis>.
393 Currently 5. This macro is deprecated, and will probably
394 disappear in future versions.</para>
400 <constant>__GLASGOW_HASKELL__</constant>
401 <indexterm><primary><constant>__GLASGOW_HASKELL__</constant></primary></indexterm>
405 <literal><replaceable>x</replaceable>.<replaceable>y</replaceable>.<replaceable>z</replaceable></literal>
407 <constant>__GLASGOW_HASKELL__</constant>
408 is the integer <replaceable>xyy</replaceable> (if
409 <replaceable>y</replaceable> is a single digit, then a leading zero
410 is added, so for example in version 6.2 of GHC,
411 <literal>__GLASGOW_HASKELL__==602</literal>). More
412 information in <xref linkend="version-numbering"/>.</para>
415 <constant>__GLASGOW_HASKELL__</constant>
416 will be undefined in all other implementations that
417 support C-style pre-processing.</para>
419 <para>(For reference: the comparable symbols for other
421 <constant>__HUGS__</constant>
423 <constant>__NHC__</constant>
425 <constant>__HBC__</constant>
428 <para>NB. This macro is set when pre-processing both
429 Haskell source and C source, including the C source
430 generated from a Haskell module
431 (i.e. <filename>.hs</filename>, <filename>.lhs</filename>,
432 <filename>.c</filename> and <filename>.hc</filename>
439 <constant>__CONCURRENT_HASKELL__</constant>
440 <indexterm><primary><constant>__CONCURRENT_HASKELL__</constant></primary></indexterm>
443 <para>This symbol is defined when pre-processing Haskell
444 (input) and pre-processing C (GHC output). Since GHC from
445 version 4.00 now supports concurrent haskell by default,
446 this symbol is always defined.</para>
452 <constant>__PARALLEL_HASKELL__</constant>
453 <indexterm><primary><constant>__PARALLEL_HASKELL__</constant></primary></indexterm>
456 <para>Only defined when <option>-parallel</option> is in
457 use! This symbol is defined when pre-processing Haskell
458 (input) and pre-processing C (GHC output).</para>
464 <constant><replaceable>os</replaceable>_HOST_OS=1</constant>
467 <para>This define allows conditional compilation based on
468 the Operating System, where<replaceable>os</replaceable> is
469 the name of the current Operating System
470 (eg. <literal>linux</literal>, <literal>mingw32</literal>
471 for Windows, <literal>solaris</literal>, etc.).</para>
477 <constant><replaceable>arch</replaceable>_HOST_ARCH=1</constant>
480 <para>This define allows conditional compilation based on
481 the host architecture, where<replaceable>arch</replaceable>
482 is the name of the current architecture
483 (eg. <literal>i386</literal>, <literal>x86_64</literal>,
484 <literal>powerpc</literal>, <literal>sparc</literal>,
490 <sect3 id="cpp-string-gaps">
491 <title>CPP and string gaps</title>
493 <para>A small word of warning: <option>-cpp</option> is not
494 friendly to “string gaps”.<indexterm><primary>-cpp
495 vs string gaps</primary></indexterm><indexterm><primary>string
496 gaps vs -cpp</primary></indexterm>. In other words, strings
497 such as the following:</para>
499 <programlisting>strmod = "\
503 <para>don't work with <option>-cpp</option>;
504 <filename>/usr/bin/cpp</filename> elides the backslash-newline
507 <para>However, it appears that if you add a space at the end
508 of the line, then <command>cpp</command> (at least GNU
509 <command>cpp</command> and possibly other
510 <command>cpp</command>s) leaves the backslash-space pairs
511 alone and the string gap works as expected.</para>
515 <sect2 id="pre-processor">
516 <title>Options affecting a Haskell pre-processor</title>
518 <indexterm><primary>pre-processing: custom</primary></indexterm>
519 <indexterm><primary>Pre-processor options</primary></indexterm>
525 <indexterm><primary><option>-F</option></primary></indexterm>
528 <para>A custom pre-processor is run over your Haskell
529 source file only if the <option>-F</option> option
530 <indexterm><primary>-F</primary></indexterm> is
533 <para>Running a custom pre-processor at compile-time is in
534 some settings appropriate and useful. The
535 <option>-F</option> option lets you run a pre-processor as
536 part of the overall GHC compilation pipeline, which has
537 the advantage over running a Haskell pre-processor
538 separately in that it works in interpreted mode and you
539 can continue to take reap the benefits of GHC's
540 recompilation checker.</para>
542 <para>The pre-processor is run just before the Haskell
543 compiler proper processes the Haskell input, but after the
544 literate markup has been stripped away and (possibly) the
545 C pre-processor has washed the Haskell input.</para>
548 <option>-pgmF <replaceable>cmd</replaceable></option>
549 to select the program to use as the preprocessor. When
550 invoked, the <replaceable>cmd</replaceable> pre-processor
551 is given at least three arguments on its command-line: the
552 first argument is the name of the original source file,
553 the second is the name of the file holding the input, and
554 the third is the name of the file where
555 <replaceable>cmd</replaceable> should write its output
558 <para>Additional arguments to the pre-processor can be
559 passed in using the <option>-optF</option> option. These
560 are fed to <replaceable>cmd</replaceable> on the command
561 line after the three standard input and output
565 An example of a pre-processor is to convert your source files to the
566 input encoding that GHC expects, i.e. create a script
567 <literal>convert.sh</literal> containing the lines:
571 ( echo "{-# LINE 1 \"$2\" #-}" ; iconv -f l1 -t utf-8 $2 ) > $3</screen>
573 <para>and pass <literal>-F -pgmF convert.sh</literal> to GHC.
574 The <literal>-f l1</literal> option tells iconv to convert your
575 Latin-1 file, supplied in argument <literal>$2</literal>, while
576 the "-t utf-8" options tell iconv to return a UTF-8 encoded file.
577 The result is redirected into argument <literal>$3</literal>.
578 The <literal>echo "{-# LINE 1 \"$2\" #-}"</literal>
579 just makes sure that your error positions are reported as
580 in the original source file.</para>
586 <sect2 id="options-codegen">
587 <title>Options affecting code generation</title>
592 <option>-fasm</option>
593 <indexterm><primary><option>-fasm</option></primary></indexterm>
596 <para>Use GHC's native code generator rather than
597 compiling via C. This will compile faster (up to twice as
598 fast), but may produce code that is slightly slower than
599 compiling via C. <option>-fasm</option> is the default.</para>
605 <option>-fvia-C</option>
606 <indexterm><primary><option>-fvia-C</option></primary></indexterm>
609 <para>Compile via C instead of using the native code
610 generator. This is the default on architectures for which GHC
611 doesn't have a native code generator.</para>
617 <option>-fllvm</option>
618 <indexterm><primary><option>-fllvm</option></primary></indexterm>
621 <para>Compile via LLVM instead of using the native code
622 generator. This will generally take slightly longer than the
623 native code generator to compile but quicker than compiling
624 via C. Produced code is generally the same speed or faster
625 than the other two code generators. Compiling via LLVM
626 requires LLVM version 2.7 or later to be on the path.</para>
632 <option>-fno-code</option>
633 <indexterm><primary><option>-fno-code</option></primary></indexterm>
636 <para>Omit code generation (and all later phases)
637 altogether. Might be of some use if you just want to see
638 dumps of the intermediate compilation phases.</para>
644 <option>-fobject-code</option>
645 <indexterm><primary><option>-fobject-code</option></primary></indexterm>
648 <para>Generate object code. This is the default outside of
649 GHCi, and can be used with GHCi to cause object code to be
650 generated in preference to bytecode.</para>
656 <option>-fbyte-code</option>
657 <indexterm><primary><option>-fbyte-code</option></primary></indexterm>
660 <para>Generate byte-code instead of object-code. This is
661 the default in GHCi. Byte-code can currently only be used
662 in the interactive interpreter, not saved to disk. This
663 option is only useful for reversing the effect of
664 <option>-fobject-code</option>.</para>
670 <option>-fPIC</option>
671 <indexterm><primary><option>-fPIC</option></primary></indexterm>
674 <para>Generate position-independent code (code that can be put into
675 shared libraries). This currently works on Linux x86 and x86-64 when
676 using the native code generator (-fasm).
677 On Windows, position-independent code is never used
678 so the flag is a no-op on that platform.</para>
684 <option>-dynamic</option>
687 <para>When generating code, assume that entities imported from a
688 different package will reside in a different shared library or
690 <para>Note that using this option when linking causes GHC to link
691 against shared libraries.</para>
697 <sect2 id="options-linker">
698 <title>Options affecting linking</title>
700 <indexterm><primary>linker options</primary></indexterm>
701 <indexterm><primary>ld options</primary></indexterm>
704 <para>GHC has to link your code with various libraries, possibly
705 including: user-supplied, GHC-supplied, and system-supplied
706 (<option>-lm</option> math library, for example).</para>
712 <option>-l</option><replaceable>lib</replaceable>
713 <indexterm><primary><option>-l</option></primary></indexterm>
716 <para>Link in the <replaceable>lib</replaceable> library.
717 On Unix systems, this will be in a file called
718 <filename>lib<replaceable>lib</replaceable>.a</filename>
720 <filename>lib<replaceable>lib</replaceable>.so</filename>
721 which resides somewhere on the library directories path.</para>
723 <para>Because of the sad state of most UNIX linkers, the
724 order of such options does matter. If library
725 <replaceable>foo</replaceable> requires library
726 <replaceable>bar</replaceable>, then in general
727 <option>-l</option><replaceable>foo</replaceable> should
728 come <emphasis>before</emphasis>
729 <option>-l</option><replaceable>bar</replaceable> on the
732 <para>There's one other gotcha to bear in mind when using
733 external libraries: if the library contains a
734 <literal>main()</literal> function, then this will be
735 linked in preference to GHC's own
736 <literal>main()</literal> function
737 (eg. <literal>libf2c</literal> and <literal>libl</literal>
738 have their own <literal>main()</literal>s). This is
739 because GHC's <literal>main()</literal> comes from the
740 <literal>HSrts</literal> library, which is normally
741 included <emphasis>after</emphasis> all the other
742 libraries on the linker's command line. To force GHC's
743 <literal>main()</literal> to be used in preference to any
744 other <literal>main()</literal>s from external libraries,
745 just add the option <option>-lHSrts</option> before any
746 other libraries on the command line.</para>
753 <indexterm><primary><option>-c</option></primary></indexterm>
756 <para>Omits the link step. This option can be used with
757 <option>––make</option> to avoid the automatic linking
758 that takes place if the program contains a <literal>Main</literal>
765 <option>-package</option> <replaceable>name</replaceable>
766 <indexterm><primary><option>-package</option></primary></indexterm>
769 <para>If you are using a Haskell “package”
770 (see <xref linkend="packages"/>), don't forget to add the
771 relevant <option>-package</option> option when linking the
772 program too: it will cause the appropriate libraries to be
773 linked in with the program. Forgetting the
774 <option>-package</option> option will likely result in
775 several pages of link errors.</para>
781 <option>-framework</option> <replaceable>name</replaceable>
782 <indexterm><primary><option>-framework</option></primary></indexterm>
785 <para>On Darwin/MacOS X only, link in the framework <replaceable>name</replaceable>.
786 This option corresponds to the <option>-framework</option> option for Apple's Linker.
787 Please note that frameworks and packages are two different things - frameworks don't
788 contain any haskell code. Rather, they are Apple's way of packaging shared libraries.
789 To link to Apple's “Carbon” API, for example, you'd use
790 <option>-framework Carbon</option>.
797 <option>-L</option><replaceable>dir</replaceable>
798 <indexterm><primary><option>-L</option></primary></indexterm>
801 <para>Where to find user-supplied libraries…
802 Prepend the directory <replaceable>dir</replaceable> to
803 the library directories path.</para>
809 <option>-framework-path</option><replaceable>dir</replaceable>
810 <indexterm><primary><option>-framework-path</option></primary></indexterm>
813 <para>On Darwin/MacOS X only, prepend the directory <replaceable>dir</replaceable> to
814 the framework directories path. This option corresponds to the <option>-F</option>
815 option for Apple's Linker (<option>-F</option> already means something else for GHC).</para>
821 <option>-split-objs</option>
822 <indexterm><primary><option>-split-objs</option></primary></indexterm>
825 <para>Tell the linker to split the single object file that
826 would normally be generated into multiple object files,
827 one per top-level Haskell function or type in the module.
828 This only makes sense for libraries, where it means that
829 executables linked against the library are smaller as they only
830 link against the object files that they need. However, assembling
831 all the sections separately is expensive, so this is slower than
833 We use this feature for building GHC's libraries
834 (warning: don't use it unless you know what you're
841 <option>-static</option>
842 <indexterm><primary><option>-static</option></primary></indexterm>
845 <para>Tell the linker to avoid shared Haskell libraries,
846 if possible. This is the default.</para>
852 <option>-dynamic</option>
853 <indexterm><primary><option>-dynamic</option></primary></indexterm>
856 <para>This flag tells GHC to link against shared Haskell libraries.
857 This flag only affects the selection of dependent libraries, not
858 the form of the current target (see -shared).
859 See <xref linkend="using-shared-libs" /> on how to
862 <para>Note that this option also has an effect on
863 code generation (see above).</para>
869 <option>-shared</option>
870 <indexterm><primary><option>-shared</option></primary></indexterm>
873 <para>Instead of creating an executable, GHC produces a
874 shared object with this linker flag. Depending on the
875 operating system target, this might be an ELF DSO, a Windows
876 DLL, or a Mac OS dylib. GHC hides the operating system
877 details beneath this uniform flag.</para>
879 <para>The flags <option>-dynamic</option>/<option>-static</option> control whether the
880 resulting shared object links statically or dynamically to
881 Haskell package libraries given as <option>-package</option> option. Non-Haskell
882 libraries are linked as gcc would regularly link it on your
883 system, e.g. on most ELF system the linker uses the dynamic
884 libraries when found.</para>
886 <para>Object files linked into shared objects must be
887 compiled with <option>-fPIC</option>, see <xref linkend="options-codegen" /></para>
889 <para>When creating shared objects for Haskell packages, the
890 shared object must be named properly, so that GHC recognizes
891 the shared object when linked against this package. See
892 shared object name mangling.</para>
898 <option>-dynload</option>
899 <indexterm><primary><option>-dynload</option></primary></indexterm>
903 This flag selects one of a number of modes for finding shared
904 libraries at runtime. See <xref linkend="finding-shared-libs"/> for
905 a description of each mode.
912 <option>-main-is <replaceable>thing</replaceable></option>
913 <indexterm><primary><option>-main-is</option></primary></indexterm>
914 <indexterm><primary>specifying your own main function</primary></indexterm>
917 <para> The normal rule in Haskell is that your program must supply a <literal>main</literal>
918 function in module <literal>Main</literal>. When testing, it is often convenient
919 to change which function is the "main" one, and the <option>-main-is</option> flag
920 allows you to do so. The <replaceable>thing</replaceable> can be one of:
922 <listitem><para>A lower-case identifier <literal>foo</literal>. GHC assumes that the main function is <literal>Main.foo</literal>.</para></listitem>
923 <listitem><para>An module name <literal>A</literal>. GHC assumes that the main function is <literal>A.main</literal>.</para></listitem>
924 <listitem><para>An qualified name <literal>A.foo</literal>. GHC assumes that the main function is <literal>A.foo</literal>.</para></listitem>
926 Strictly speaking, <option>-main-is</option> is not a link-phase flag at all; it has no effect on the link step.
927 The flag must be specified when compiling the module containing the specified main function (e.g. module <literal>A</literal>
928 in the latter two items above). It has no effect for other modules,
929 and hence can safely be given to <literal>ghc --make</literal>.
930 However, if all the modules are otherwise up to date, you may need to force
931 recompilation both of the module where the new "main" is, and of the
932 module where the "main" function used to be;
933 <literal>ghc</literal> is not clever
934 enough to figure out that they both need recompiling. You can
935 force recompilation by removing the object file, or by using the
936 <option>-fforce-recomp</option> flag.
943 <option>-no-hs-main</option>
944 <indexterm><primary><option>-no-hs-main</option></primary></indexterm>
945 <indexterm><primary>linking Haskell libraries with foreign code</primary></indexterm>
948 <para>In the event you want to include ghc-compiled code
949 as part of another (non-Haskell) program, the RTS will not
950 be supplying its definition of <function>main()</function>
951 at link-time, you will have to. To signal that to the
952 compiler when linking, use
953 <option>-no-hs-main</option>. See also <xref linkend="using-own-main"/>.</para>
955 <para>Notice that since the command-line passed to the
956 linker is rather involved, you probably want to use
957 <command>ghc</command> to do the final link of your
958 `mixed-language' application. This is not a requirement
959 though, just try linking once with <option>-v</option> on
960 to see what options the driver passes through to the
963 <para>The <option>-no-hs-main</option> flag can also be
964 used to persuade the compiler to do the link step in
965 <option>--make</option> mode when there is no Haskell
966 <literal>Main</literal> module present (normally the
967 compiler will not attempt linking when there is no
968 <literal>Main</literal>).</para>
974 <option>-debug</option>
975 <indexterm><primary><option>-debug</option></primary></indexterm>
978 <para>Link the program with a debugging version of the
979 runtime system. The debugging runtime turns on numerous
980 assertions and sanity checks, and provides extra options
981 for producing debugging output at runtime (run the program
982 with <literal>+RTS -?</literal> to see a list).</para>
988 <option>-threaded</option>
989 <indexterm><primary><option>-threaded</option></primary></indexterm>
992 <para>Link the program with the "threaded" version of the
993 runtime system. The threaded runtime system is so-called
994 because it manages multiple OS threads, as opposed to the
995 default runtime system which is purely
996 single-threaded.</para>
998 <para>Note that you do <emphasis>not</emphasis> need
999 <option>-threaded</option> in order to use concurrency; the
1000 single-threaded runtime supports concurrency between Haskell
1001 threads just fine.</para>
1003 <para>The threaded runtime system provides the following
1008 <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>
1009 machine. See <xref linkend="using-smp" />.</para>
1011 <para>The ability to make a foreign call that does not
1012 block all other Haskell threads, and to invoke
1013 foreign-exported Haskell functions from multiple OS
1014 threads. See <xref linkend="ffi-threads" />.</para>
1022 <option>-eventlog</option>
1023 <indexterm><primary><option>-eventlog</option></primary></indexterm>
1027 Link the program with the "eventlog" version of the
1028 runtime system. A program linked in this way can generate
1029 a runtime trace of events (such as thread start/stop) to a
1031 <literal><replaceable>program</replaceable>.eventlog</literal>,
1032 which can then be interpreted later by various tools. See
1033 <xref linkend="rts-eventlog" /> for more information.
1036 <option>-eventlog</option> can be used
1037 with <option>-threaded</option>. It is implied
1038 by <option>-debug</option>.
1045 <option>-fno-gen-manifest</option>
1046 <indexterm><primary><option>-fno-gen-manifest</option></primary>
1050 <para>On Windows, GHC normally generates a
1051 <firstterm>manifest</firstterm><indexterm><primary>manifest</primary>
1052 </indexterm>file when linking a binary. The
1053 manifest is placed in the file
1054 <literal><replaceable>prog</replaceable>.exe.manifest</literal>
1055 where <replaceable>prog.exe</replaceable> is the name of the
1056 executable. The manifest file currently serves just one purpose:
1057 it disables the "installer detection"<indexterm><primary>installer detection</primary>
1058 </indexterm>in Windows Vista that
1059 attempts to elevate privileges for executables with certain names
1060 (e.g. names containing "install", "setup" or "patch"). Without the
1061 manifest file to turn off installer detection, attempting to run an
1062 executable that Windows deems to be an installer will return a
1063 permission error code to the invoker. Depending on the invoker,
1064 the result might be a dialog box asking the user for elevated
1065 permissions, or it might simply be a permission denied
1068 <para>Installer detection can be also turned off globally for the
1069 system using the security control panel, but GHC by default
1070 generates binaries that don't depend on the user having disabled
1071 installer detection.</para>
1073 <para>The <option>-fno-gen-manifest</option> disables generation of
1074 the manifest file. One reason to do this would be if you had
1075 a manifest file of your own, for example.</para>
1077 <para>In the future, GHC might use the manifest file for more things,
1078 such as supplying the location of dependent DLLs.</para>
1080 <para><option>-fno-gen-manifest</option> also implies
1081 <option>-fno-embed-manifest</option>, see below.</para>
1087 <option>-fno-embed-manifest</option>
1088 <indexterm><primary><option>-fno-embed-manifest</option></primary>
1092 <para>The manifest file that GHC generates when linking a binary on
1093 Windows is also embedded in the executable itself, by default.
1094 This means that the binary can be distributed without having to
1095 supply the manifest file too. The embedding is done by running
1096 <literal>windres</literal><indexterm><primary><literal>windres</literal></primary>
1097 </indexterm>; to see exactly what GHC does to embed the manifest,
1098 use the <option>-v</option> flag. A GHC installation comes with
1099 its own copy of <literal>windres</literal> for this reason.</para>
1101 <para>See also <option>-pgmwindres</option> (<xref
1102 linkend="replacing-phases" />) and
1103 <option>-optwindres</option> (<xref
1104 linkend="forcing-options-through"
1111 <option>-fno-shared-implib</option>
1112 <indexterm><primary><option>-fno-shared-implib</option></primary>
1116 <para>DLLs on Windows are typically linked to by linking to a corresponding
1117 <literal>.lib</literal> or <literal>.dll.a</literal> - the so-called import library.
1118 GHC will typically generate such a file for every DLL you create by compiling in
1119 <literal>-shared</literal> mode. However, sometimes you don't want to pay the
1120 disk-space cost of creating this import library, which can be substantial - it
1121 might require as much space as the code itself, as Haskell DLLs tend to export
1122 lots of symbols.</para>
1124 <para>As long as you are happy to only be able to link to the DLL using
1125 <literal>GetProcAddress</literal> and friends, you can supply the
1126 <option>-fno-shared-implib</option> flag to disable the creation of the import
1127 library entirely.</para>
1133 <option>-dylib-install-name <replaceable>path</replaceable></option>
1134 <indexterm><primary><option>-dylib-install-name</option></primary>
1138 <para>On Darwin/MacOS X, dynamic libraries are stamped at build time with an
1139 "install name", which is the ultimate install path of the library file.
1140 Any libraries or executables that subsequently link against it will pick
1141 up that path as their runtime search location for it. By default, ghc sets
1142 the install name to the location where the library is built. This option
1143 allows you to override it with the specified file path. (It passes
1144 <literal>-install_name</literal> to Apple's linker.) Ignored on other
1154 ;;; Local Variables: ***
1155 ;;; sgml-parent-document: ("users_guide.xml" "book" "chapter" "sect1") ***