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 particlar 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>-optdep</option> <replaceable>option</replaceable>
218 <indexterm><primary><option>-optdep</option></primary></indexterm>
221 <para>Pass <replaceable>option</replaceable> to the
222 dependency generator.</para>
227 <option>-optwindres</option> <replaceable>option</replaceable>
228 <indexterm><primary><option>-optwindres</option></primary></indexterm>
231 <para>Pass <replaceable>option</replaceable> to
232 <literal>windres</literal> when embedding manifests on Windows.
233 See <option>-fno-embed-manifest</option> in <xref
234 linkend="options-linker" />.</para>
239 <para>So, for example, to force an <option>-Ewurble</option>
240 option to the assembler, you would tell the driver
241 <option>-opta-Ewurble</option> (the dash before the E is
244 <para>GHC is itself a Haskell program, so if you need to pass
245 options directly to GHC's runtime system you can enclose them in
246 <literal>+RTS ... -RTS</literal> (see <xref
247 linkend="runtime-control"/>).</para>
251 <sect2 id="c-pre-processor">
252 <title>Options affecting the C pre-processor</title>
254 <indexterm><primary>pre-processing: cpp</primary></indexterm>
255 <indexterm><primary>C pre-processor options</primary></indexterm>
256 <indexterm><primary>cpp, pre-processing with</primary></indexterm>
262 <option>-cpp</option>
263 <indexterm><primary><option>-cpp</option></primary></indexterm>
266 <para>The C pre-processor <command>cpp</command> is run
267 over your Haskell code only if the <option>-cpp</option>
268 option <indexterm><primary>-cpp
269 option</primary></indexterm> is given. Unless you are
270 building a large system with significant doses of
271 conditional compilation, you really shouldn't need
278 <option>-D</option><replaceable>symbol</replaceable><optional>=<replaceable>value</replaceable></optional>
279 <indexterm><primary><option>-D</option></primary></indexterm>
282 <para>Define macro <replaceable>symbol</replaceable> in the
283 usual way. NB: does <emphasis>not</emphasis> affect
284 <option>-D</option> macros passed to the C compiler
285 when compiling via C! For those, use the
286 <option>-optc-Dfoo</option> hack… (see <xref
287 linkend="forcing-options-through"/>).</para>
293 <option>-U</option><replaceable>symbol</replaceable>
294 <indexterm><primary><option>-U</option></primary></indexterm>
297 <para> Undefine macro <replaceable>symbol</replaceable> in the
304 <option>-I</option><replaceable>dir</replaceable>
305 <indexterm><primary><option>-I</option></primary></indexterm>
308 <para> Specify a directory in which to look for
309 <literal>#include</literal> files, in the usual C
315 <para>The GHC driver pre-defines several macros when processing
316 Haskell source code (<filename>.hs</filename> or
317 <filename>.lhs</filename> files).</para>
319 <para>The symbols defined by GHC are listed below. To check which
320 symbols are defined by your local GHC installation, the following
321 trick is useful:</para>
323 <screen>$ ghc -E -optP-dM -cpp foo.hs
324 $ cat foo.hspp</screen>
326 <para>(you need a file <filename>foo.hs</filename>, but it isn't
327 actually used).</para>
332 <constant>__HASKELL98__</constant>
333 <indexterm><primary><literal>__HASKELL98__</literal></primary></indexterm>
336 <para>If defined, this means that GHC supports the
337 language defined by the Haskell 98 report.</para>
343 <constant>__HASKELL__=98</constant>
344 <indexterm><primary><constant>__HASKELL__=98</constant></primary></indexterm>
347 <para>In GHC 4.04 and later, the
348 <constant>__HASKELL__</constant>
349 macro is defined as having the value
350 <constant>98</constant>.</para>
356 <constant>__HASKELL1__</constant>
357 <indexterm><primary><constant>__HASKELL1__</constant></primary></indexterm>
360 <para>If defined to <replaceable>n</replaceable>, that
361 means GHC supports the Haskell language defined in the
362 Haskell report version <emphasis>1.n</emphasis>.
363 Currently 5. This macro is deprecated, and will probably
364 disappear in future versions.</para>
370 <constant>__GLASGOW_HASKELL__</constant>
371 <indexterm><primary><constant>__GLASGOW_HASKELL__</constant></primary></indexterm>
375 <literal><replaceable>x</replaceable>.<replaceable>y</replaceable>.<replaceable>z</replaceable></literal>
377 <constant>__GLASGOW_HASKELL__</constant>
378 is the integer <replaceable>xyy</replaceable> (if
379 <replaceable>y</replaceable> is a single digit, then a leading zero
380 is added, so for example in version 6.2 of GHC,
381 <literal>__GLASGOW_HASKELL__==602</literal>). More
382 information in <xref linkend="version-numbering"/>.</para>
385 <constant>__GLASGOW_HASKELL__</constant>
386 will be undefined in all other implementations that
387 support C-style pre-processing.</para>
389 <para>(For reference: the comparable symbols for other
391 <constant>__HUGS__</constant>
393 <constant>__NHC__</constant>
395 <constant>__HBC__</constant>
398 <para>NB. This macro is set when pre-processing both
399 Haskell source and C source, including the C source
400 generated from a Haskell module
401 (i.e. <filename>.hs</filename>, <filename>.lhs</filename>,
402 <filename>.c</filename> and <filename>.hc</filename>
409 <constant>__CONCURRENT_HASKELL__</constant>
410 <indexterm><primary><constant>__CONCURRENT_HASKELL__</constant></primary></indexterm>
413 <para>This symbol is defined when pre-processing Haskell
414 (input) and pre-processing C (GHC output). Since GHC from
415 verion 4.00 now supports concurrent haskell by default,
416 this symbol is always defined.</para>
422 <constant>__PARALLEL_HASKELL__</constant>
423 <indexterm><primary><constant>__PARALLEL_HASKELL__</constant></primary></indexterm>
426 <para>Only defined when <option>-parallel</option> is in
427 use! This symbol is defined when pre-processing Haskell
428 (input) and pre-processing C (GHC output).</para>
434 <constant><replaceable>os</replaceable>_HOST_OS=1</constant>
437 <para>This define allows conditional compilation based on
438 the Operating System, where<replaceable>os</replaceable> is
439 the name of the current Operating System
440 (eg. <literal>linux</literal>, <literal>mingw32</literal>
441 for Windows, <literal>solaris</literal>, etc.).</para>
447 <constant><replaceable>arch</replaceable>_HOST_ARCH=1</constant>
450 <para>This define allows conditional compilation based on
451 the host architecture, where<replaceable>arch</replaceable>
452 is the name of the current architecture
453 (eg. <literal>i386</literal>, <literal>x86_64</literal>,
454 <literal>powerpc</literal>, <literal>sparc</literal>,
460 <sect3 id="cpp-string-gaps">
461 <title>CPP and string gaps</title>
463 <para>A small word of warning: <option>-cpp</option> is not
464 friendly to “string gaps”.<indexterm><primary>-cpp
465 vs string gaps</primary></indexterm><indexterm><primary>string
466 gaps vs -cpp</primary></indexterm>. In other words, strings
467 such as the following:</para>
469 <programlisting>strmod = "\
473 <para>don't work with <option>-cpp</option>;
474 <filename>/usr/bin/cpp</filename> elides the backslash-newline
477 <para>However, it appears that if you add a space at the end
478 of the line, then <command>cpp</command> (at least GNU
479 <command>cpp</command> and possibly other
480 <command>cpp</command>s) leaves the backslash-space pairs
481 alone and the string gap works as expected.</para>
485 <sect2 id="pre-processor">
486 <title>Options affecting a Haskell pre-processor</title>
488 <indexterm><primary>pre-processing: custom</primary></indexterm>
489 <indexterm><primary>Pre-processor options</primary></indexterm>
495 <indexterm><primary><option>-F</option></primary></indexterm>
498 <para>A custom pre-processor is run over your Haskell
499 source file only if the <option>-F</option> option
500 <indexterm><primary>-F</primary></indexterm> is
503 <para>Running a custom pre-processor at compile-time is in
504 some settings appropriate and useful. The
505 <option>-F</option> option lets you run a pre-processor as
506 part of the overall GHC compilation pipeline, which has
507 the advantage over running a Haskell pre-processor
508 separately in that it works in interpreted mode and you
509 can continue to take reap the benefits of GHC's
510 recompilation checker.</para>
512 <para>The pre-processor is run just before the Haskell
513 compiler proper processes the Haskell input, but after the
514 literate markup has been stripped away and (possibly) the
515 C pre-processor has washed the Haskell input.</para>
518 <option>-pgmF <replaceable>cmd</replaceable></option>
519 to select the program to use as the preprocessor. When
520 invoked, the <replaceable>cmd</replaceable> pre-processor
521 is given at least three arguments on its command-line: the
522 first argument is the name of the original source file,
523 the second is the name of the file holding the input, and
524 the third is the name of the file where
525 <replaceable>cmd</replaceable> should write its output
528 <para>Additional arguments to the pre-processor can be
529 passed in using the <option>-optF</option> option. These
530 are fed to <replaceable>cmd</replaceable> on the command
531 line after the three standard input and output
535 An example of a pre-processor is to convert your source files to the
536 input encoding that GHC expects, i.e. create a script
537 <literal>convert.sh</literal> containing the lines:
541 ( echo "{-# LINE 1 \"$2\" #-}" ; iconv -f l1 -t utf-8 $2 ) > $3</screen>
543 <para>and pass <literal>-F -pgmF convert.sh</literal> to GHC.
544 The <literal>-f l1</literal> option tells iconv to convert your
545 Latin-1 file, supplied in argument <literal>$2</literal>, while
546 the "-t utf-8" options tell iconv to return a UTF-8 encoded file.
547 The result is redirected into argument <literal>$3</literal>.
548 The <literal>echo "{-# LINE 1 \"$2\" #-}"</literal>
549 just makes sure that your error positions are reported as
550 in the original source file.</para>
556 <sect2 id="options-C-compiler">
557 <title>Options affecting the C compiler (if applicable)</title>
559 <indexterm><primary>include-file options</primary></indexterm>
560 <indexterm><primary>C compiler options</primary></indexterm>
561 <indexterm><primary>GCC options</primary></indexterm>
563 <para>If you are compiling with lots of foreign calls, you may
564 need to tell the C compiler about some
565 <literal>#include</literal> files. The Right Way to do this is to
566 add an <literal>INCLUDE</literal> pragma to the top of your source file
567 (<xref linkend="include-pragma" />):</para>
569 <programlisting>{-# INCLUDE <X/Xlib.h> #-}</programlisting>
571 <para>Sometimes this isn't convenient. In those cases there's an
572 equivalent command-line option:</para>
574 <screen>% ghc -c '-#include <X/Xlib.h>' Xstuff.lhs</screen>
576 <indexterm><primary><option>-#include</option></primary>
581 <sect2 id="options-codegen">
582 <title>Options affecting code generation</title>
587 <option>-fasm</option>
588 <indexterm><primary><option>-fasm</option></primary></indexterm>
591 <para>Use GHC's native code generator rather than
592 compiling via C. This will compile faster (up to twice as
593 fast), but may produce code that is slightly slower than
594 compiling via C. <option>-fasm</option> is the default.</para>
600 <option>-fvia-C</option>
601 <indexterm><primary><option>-fvia-C</option></primary></indexterm>
604 <para>Compile via C instead of using the native code
605 generator. This is the default on architectures for which GHC
606 doesn't have a native code generator.</para>
612 <option>-fno-code</option>
613 <indexterm><primary><option>-fno-code</option></primary></indexterm>
616 <para>Omit code generation (and all later phases)
617 altogether. Might be of some use if you just want to see
618 dumps of the intermediate compilation phases.</para>
624 <option>-fobject-code</option>
625 <indexterm><primary><option>-fobject-code</option></primary></indexterm>
628 <para>Generate object code. This is the default outside of
629 GHCi, and can be used with GHCi to cause object code to be
630 generated in preference to bytecode.</para>
636 <option>-fbyte-code</option>
637 <indexterm><primary><option>-fbyte-code</option></primary></indexterm>
640 <para>Generate byte-code instead of object-code. This is
641 the default in GHCi. Byte-code can currently only be used
642 in the interactive interpreter, not saved to disk. This
643 option is only useful for reversing the effect of
644 <option>-fobject-code</option>.</para>
650 <option>-fPIC</option>
651 <indexterm><primary><option>-fPIC</option></primary></indexterm>
654 <para>Generate position-independent code (code that can be put into
655 shared libraries). This currently works on Mac OS X; it works on
656 PowerPC Linux when using the native code generator (-fasm).
657 It is not quite ready to be used yet for x86 Linux.
658 On Windows, position-independent code is never used,
659 and on PowerPC64 Linux, position-independent code is always used,
660 so the flag is a no-op on those platforms.</para>
666 <option>-dynamic</option>
669 <para>When generating code, assume that entities imported from a
670 different package will reside in a different shared library or
671 binary. This currently works on Mac OS X; it works on PowerPC Linux when
672 using the native code generator. As with <option>-fPIC</option>,
673 x86 Linux support is not quite ready yet. Windows is not supported,
674 and it is a no-op on PowerPC64 Linux.</para>
675 <para>Note that this option also causes GHC to use shared libraries
682 <sect2 id="options-linker">
683 <title>Options affecting linking</title>
685 <indexterm><primary>linker options</primary></indexterm>
686 <indexterm><primary>ld options</primary></indexterm>
689 <para>GHC has to link your code with various libraries, possibly
690 including: user-supplied, GHC-supplied, and system-supplied
691 (<option>-lm</option> math library, for example).</para>
697 <option>-l</option><replaceable>lib</replaceable>
698 <indexterm><primary><option>-l</option></primary></indexterm>
701 <para>Link in the <replaceable>lib</replaceable> library.
702 On Unix systems, this will be in a file called
703 <filename>lib<replaceable>lib</replaceable>.a</filename>
705 <filename>lib<replaceable>lib</replaceable>.so</filename>
706 which resides somewhere on the library directories path.</para>
708 <para>Because of the sad state of most UNIX linkers, the
709 order of such options does matter. If library
710 <replaceable>foo</replaceable> requires library
711 <replaceable>bar</replaceable>, then in general
712 <option>-l</option><replaceable>foo</replaceable> should
713 come <emphasis>before</emphasis>
714 <option>-l</option><replaceable>bar</replaceable> on the
717 <para>There's one other gotcha to bear in mind when using
718 external libraries: if the library contains a
719 <literal>main()</literal> function, then this will be
720 linked in preference to GHC's own
721 <literal>main()</literal> function
722 (eg. <literal>libf2c</literal> and <literal>libl</literal>
723 have their own <literal>main()</literal>s). This is
724 because GHC's <literal>main()</literal> comes from the
725 <literal>HSrts</literal> library, which is normally
726 included <emphasis>after</emphasis> all the other
727 libraries on the linker's command line. To force GHC's
728 <literal>main()</literal> to be used in preference to any
729 other <literal>main()</literal>s from external libraries,
730 just add the option <option>-lHSrts</option> before any
731 other libraries on the command line.</para>
738 <indexterm><primary><option>-c</option></primary></indexterm>
741 <para>Omits the link step. This option can be used with
742 <option>––make</option> to avoid the automatic linking
743 that takes place if the program contains a <literal>Main</literal>
750 <option>-package</option> <replaceable>name</replaceable>
751 <indexterm><primary><option>-package</option></primary></indexterm>
754 <para>If you are using a Haskell “package”
755 (see <xref linkend="packages"/>), don't forget to add the
756 relevant <option>-package</option> option when linking the
757 program too: it will cause the appropriate libraries to be
758 linked in with the program. Forgetting the
759 <option>-package</option> option will likely result in
760 several pages of link errors.</para>
766 <option>-framework</option> <replaceable>name</replaceable>
767 <indexterm><primary><option>-framework</option></primary></indexterm>
770 <para>On Darwin/MacOS X only, link in the framework <replaceable>name</replaceable>.
771 This option corresponds to the <option>-framework</option> option for Apple's Linker.
772 Please note that frameworks and packages are two different things - frameworks don't
773 contain any haskell code. Rather, they are Apple's way of packaging shared libraries.
774 To link to Apple's “Carbon” API, for example, you'd use
775 <option>-framework Carbon</option>.
782 <option>-L</option><replaceable>dir</replaceable>
783 <indexterm><primary><option>-L</option></primary></indexterm>
786 <para>Where to find user-supplied libraries…
787 Prepend the directory <replaceable>dir</replaceable> to
788 the library directories path.</para>
794 <option>-framework-path</option><replaceable>dir</replaceable>
795 <indexterm><primary><option>-framework-path</option></primary></indexterm>
798 <para>On Darwin/MacOS X only, prepend the directory <replaceable>dir</replaceable> to
799 the framework directories path. This option corresponds to the <option>-F</option>
800 option for Apple's Linker (<option>-F</option> already means something else for GHC).</para>
806 <option>-split-objs</option>
807 <indexterm><primary><option>-split-objs</option></primary></indexterm>
810 <para>Tell the linker to split the single object file that
811 would normally be generated into multiple object files,
812 one per top-level Haskell function or type in the module.
813 This only makes sense for libraries, where it means that
814 executables linked against the library are smaller as they only
815 link against the object files that they need. However, assembling
816 all the sections separately is expensive, so this is slower than
818 We use this feature for building GHC's libraries
819 (warning: don't use it unless you know what you're
826 <option>-static</option>
827 <indexterm><primary><option>-static</option></primary></indexterm>
830 <para>Tell the linker to avoid shared Haskell libraries,
831 if possible. This is the default.</para>
837 <option>-dynamic</option>
838 <indexterm><primary><option>-dynamic</option></primary></indexterm>
841 <para>Tell the linker to use shared Haskell libraries, if
842 available (this option is only supported on Mac OS X at the
843 moment, and also note that your distribution of GHC may
844 not have been supplied with shared libraries).</para>
845 <para>Note that this option also has an effect on
846 code generation (see above).</para>
852 <option>-main-is <replaceable>thing</replaceable></option>
853 <indexterm><primary><option>-main-is</option></primary></indexterm>
854 <indexterm><primary>specifying your own main function</primary></indexterm>
857 <para> The normal rule in Haskell is that your program must supply a <literal>main</literal>
858 function in module <literal>Main</literal>. When testing, it is often convenient
859 to change which function is the "main" one, and the <option>-main-is</option> flag
860 allows you to do so. The <replaceable>thing</replaceable> can be one of:
862 <listitem><para>A lower-case identifier <literal>foo</literal>. GHC assumes that the main function is <literal>Main.foo</literal>.</para></listitem>
863 <listitem><para>An module name <literal>A</literal>. GHC assumes that the main function is <literal>A.main</literal>.</para></listitem>
864 <listitem><para>An qualified name <literal>A.foo</literal>. GHC assumes that the main function is <literal>A.foo</literal>.</para></listitem>
866 Strictly speaking, <option>-main-is</option> is not a link-phase flag at all; it has no effect on the link step.
867 The flag must be specified when compiling the module containing the specified main function (e.g. module <literal>A</literal>
868 in the latter two items above). It has no effect for other modules,
869 and hence can safely be given to <literal>ghc --make</literal>.
870 However, if all the modules are otherwise up to date, you may need to force
871 recompilation both of the module where the new "main" is, and of the
872 module where the "main" function used to be;
873 <literal>ghc</literal> is not clever
874 enough to figure out that they both need recompiling. You can
875 force recompilation by removing the object file, or by using the
876 <option>-fforce-recomp</option> flag.
883 <option>-no-hs-main</option>
884 <indexterm><primary><option>-no-hs-main</option></primary></indexterm>
885 <indexterm><primary>linking Haskell libraries with foreign code</primary></indexterm>
888 <para>In the event you want to include ghc-compiled code
889 as part of another (non-Haskell) program, the RTS will not
890 be supplying its definition of <function>main()</function>
891 at link-time, you will have to. To signal that to the
892 compiler when linking, use
893 <option>-no-hs-main</option>. See also <xref linkend="using-own-main"/>.</para>
895 <para>Notice that since the command-line passed to the
896 linker is rather involved, you probably want to use
897 <command>ghc</command> to do the final link of your
898 `mixed-language' application. This is not a requirement
899 though, just try linking once with <option>-v</option> on
900 to see what options the driver passes through to the
903 <para>The <option>-no-hs-main</option> flag can also be
904 used to persuade the compiler to do the link step in
905 <option>--make</option> mode when there is no Haskell
906 <literal>Main</literal> module present (normally the
907 compiler will not attempt linking when there is no
908 <literal>Main</literal>).</para>
914 <option>-debug</option>
915 <indexterm><primary><option>-debug</option></primary></indexterm>
918 <para>Link the program with a debugging version of the
919 runtime system. The debugging runtime turns on numerous
920 assertions and sanity checks, and provides extra options
921 for producing debugging output at runtime (run the program
922 with <literal>+RTS -?</literal> to see a list).</para>
928 <option>-threaded</option>
929 <indexterm><primary><option>-threaded</option></primary></indexterm>
932 <para>Link the program with the "threaded" version of the
933 runtime system. The threaded runtime system is so-called
934 because it manages multiple OS threads, as opposed to the
935 default runtime system which is purely
936 single-threaded.</para>
938 <para>Note that you do <emphasis>not</emphasis> need
939 <option>-threaded</option> in order to use concurrency; the
940 single-threaded runtime supports concurrency between Haskell
941 threads just fine.</para>
943 <para>The threaded runtime system provides the following
948 <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>
949 machine. See <xref linkend="using-smp" />.</para>
951 <para>The ability to make a foreign call that does not
952 block all other Haskell threads.</para>
954 <para>The ability to invoke foreign exported Haskell
955 functions from multiple OS threads.</para>
959 <para>With <option>-threaded</option>, calls to foreign
960 functions are made using the same OS thread that created the
961 Haskell thread (if it was created by a call to a foreign
962 exported Haskell function), or an arbitrary OS thread
963 otherwise (if the Haskell thread was created by
964 <literal>forkIO</literal>).</para>
966 <para>More details on the use of "bound threads" in the
967 threaded runtime can be found in the <ulink
968 url="../libraries/base/Control.Concurrent.html"><literal>Control.Concurrent</literal></ulink> module.</para>
974 <option>-fno-gen-manifest</option>
975 <indexterm><primary><option>-fno-gen-manifest</option></primary>
979 <para>On Windows, GHC normally generates a
980 <firstterm>manifest</firstterm><indexterm><primary>manifest</primary>
981 </indexterm>file when linking a binary. The
982 manifest is placed in the file
983 <literal><replaceable>prog</replaceable>.exe.manifest</literal>
984 where <replaceable>prog.exe</replaceable> is the name of the
985 executable. The manifest file currently serves just one purpose:
986 it disables the "installer detection"<indexterm><primary>installer detection</primary>
987 </indexterm>in Windows Vista that
988 attempts to elevate privileges for executables with certain names
989 (e.g. names containing "install", "setup" or "patch"). Without the
990 manifest file to turn off installer detection, attempting to run an
991 executable that Windows deems to be an installer will return a
992 permission error code to the invoker. Depending on the invoker,
993 the result might be a dialog box asking the user for elevated
994 permissions, or it might simply be a permission denied
997 <para>Installer detection can be also turned off globally for the
998 system using the security control panel, but GHC by default
999 generates binaries that don't depend on the user having disabled
1000 installer detection.</para>
1002 <para>The <option>-fno-gen-manifest</option> disables generation of
1003 the manifest file. One reason to do this would be if you had
1004 a manifest file of your own, for example.</para>
1006 <para>In the future, GHC might use the manifest file for more things,
1007 such as supplying the location of dependent DLLs.</para>
1009 <para><option>-fno-gen-manifest</option> also implies
1010 <option>-fno-embed-manifest</option>, see below.</para>
1016 <option>-fno-embed-manifest</option>
1017 <indexterm><primary><option>-fno-embed-manifest</option></primary>
1021 <para>The manifest file that GHC generates when linking a binary on
1022 Windows is also embedded in the executable itself, by default.
1023 This means that the binary can be distributed without having to
1024 supply the manifest file too. The embedding is done by running
1025 <literal>windres</literal><indexterm><primary><literal>windres</literal></primary>
1026 </indexterm>; to see exactly what GHC does to embed the manifest,
1027 use the <option>-v</option> flag. A GHC installation comes with
1028 its own copy of <literal>windres</literal> for this reason.</para>
1030 <para>See also <option>-pgmwindres</option> (<xref
1031 linkend="replacing-phases" />) and
1032 <option>-optwindres</option> (<xref
1033 linkend="forcing-options-through"
1043 ;;; Local Variables: ***
1045 ;;; sgml-parent-document: ("users_guide.xml" "book" "chapter" "sect1") ***