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>-pgms</option> <replaceable>cmd</replaceable>
75 <indexterm><primary><option>-pgms</option></primary></indexterm>
78 <para>Use <replaceable>cmd</replaceable> as the
85 <option>-pgma</option> <replaceable>cmd</replaceable>
86 <indexterm><primary><option>-pgma</option></primary></indexterm>
89 <para>Use <replaceable>cmd</replaceable> as the
96 <option>-pgml</option> <replaceable>cmd</replaceable>
97 <indexterm><primary><option>-pgml</option></primary></indexterm>
100 <para>Use <replaceable>cmd</replaceable> as the
107 <option>-pgmdll</option> <replaceable>cmd</replaceable>
108 <indexterm><primary><option>-pgmdll</option></primary></indexterm>
111 <para>Use <replaceable>cmd</replaceable> as the DLL
118 <option>-pgmF</option> <replaceable>cmd</replaceable>
119 <indexterm><primary><option>-pgmF</option></primary></indexterm>
122 <para>Use <replaceable>cmd</replaceable> as the
123 pre-processor (with <option>-F</option> only).</para>
129 <option>-pgmwindres</option> <replaceable>cmd</replaceable>
130 <indexterm><primary><option>-pgmwindres</option></primary></indexterm>
133 <para>Use <replaceable>cmd</replaceable> as the
134 program to use for embedding manifests on Windows. Normally this
135 is the program <literal>windres</literal>, which is supplied with a
136 GHC installation. See <option>-fno-embed-manifest</option> in <xref
137 linkend="options-linker" />.</para>
143 <sect2 id="forcing-options-through">
144 <title>Forcing options to a particular phase</title>
145 <indexterm><primary>forcing GHC-phase options</primary></indexterm>
147 <para>Options can be forced through to a particular compilation
148 phase, using the following flags:</para>
153 <option>-optL</option> <replaceable>option</replaceable>
154 <indexterm><primary><option>-optL</option></primary></indexterm>
157 <para>Pass <replaceable>option</replaceable> to the
158 literate pre-processor</para>
163 <option>-optP</option> <replaceable>option</replaceable>
164 <indexterm><primary><option>-optP</option></primary></indexterm>
167 <para>Pass <replaceable>option</replaceable> to CPP (makes
168 sense only if <option>-cpp</option> is also on).</para>
173 <option>-optF</option> <replaceable>option</replaceable>
174 <indexterm><primary><option>-optF</option></primary></indexterm>
177 <para>Pass <replaceable>option</replaceable> to the
178 custom pre-processor (see <xref linkend="pre-processor"/>).</para>
183 <option>-optc</option> <replaceable>option</replaceable>
184 <indexterm><primary><option>-optc</option></primary></indexterm>
187 <para>Pass <replaceable>option</replaceable> to the C compiler.</para>
192 <option>-optlo</option> <replaceable>option</replaceable>
193 <indexterm><primary><option>-optlo</option></primary></indexterm>
196 <para>Pass <replaceable>option</replaceable> to the LLVM optimiser.</para>
201 <option>-optlc</option> <replaceable>option</replaceable>
202 <indexterm><primary><option>-optlc</option></primary></indexterm>
205 <para>Pass <replaceable>option</replaceable> to the LLVM compiler.</para>
210 <option>-optm</option> <replaceable>option</replaceable>
211 <indexterm><primary><option>-optm</option></primary></indexterm>
214 <para>Pass <replaceable>option</replaceable> to the mangler.</para>
219 <option>-opta</option> <replaceable>option</replaceable>
220 <indexterm><primary><option>-opta</option></primary></indexterm>
223 <para>Pass <replaceable>option</replaceable> to the assembler.</para>
228 <option>-optl</option> <replaceable>option</replaceable>
229 <indexterm><primary><option>-optl</option></primary></indexterm>
232 <para>Pass <replaceable>option</replaceable> to the linker.</para>
237 <option>-optdll</option> <replaceable>option</replaceable>
238 <indexterm><primary><option>-optdll</option></primary></indexterm>
241 <para>Pass <replaceable>option</replaceable> to the DLL generator.</para>
246 <option>-optwindres</option> <replaceable>option</replaceable>
247 <indexterm><primary><option>-optwindres</option></primary></indexterm>
250 <para>Pass <replaceable>option</replaceable> to
251 <literal>windres</literal> when embedding manifests on Windows.
252 See <option>-fno-embed-manifest</option> in <xref
253 linkend="options-linker" />.</para>
258 <para>So, for example, to force an <option>-Ewurble</option>
259 option to the assembler, you would tell the driver
260 <option>-opta-Ewurble</option> (the dash before the E is
263 <para>GHC is itself a Haskell program, so if you need to pass
264 options directly to GHC's runtime system you can enclose them in
265 <literal>+RTS ... -RTS</literal> (see <xref
266 linkend="runtime-control"/>).</para>
270 <sect2 id="c-pre-processor">
271 <title>Options affecting the C pre-processor</title>
273 <indexterm><primary>pre-processing: cpp</primary></indexterm>
274 <indexterm><primary>C pre-processor options</primary></indexterm>
275 <indexterm><primary>cpp, pre-processing with</primary></indexterm>
281 <option>-cpp</option>
282 <indexterm><primary><option>-cpp</option></primary></indexterm>
285 <para>The C pre-processor <command>cpp</command> is run
286 over your Haskell code only if the <option>-cpp</option>
287 option <indexterm><primary>-cpp
288 option</primary></indexterm> is given. Unless you are
289 building a large system with significant doses of
290 conditional compilation, you really shouldn't need
297 <option>-D</option><replaceable>symbol</replaceable><optional>=<replaceable>value</replaceable></optional>
298 <indexterm><primary><option>-D</option></primary></indexterm>
301 <para>Define macro <replaceable>symbol</replaceable> in the
302 usual way. NB: does <emphasis>not</emphasis> affect
303 <option>-D</option> macros passed to the C compiler
304 when compiling via C! For those, use the
305 <option>-optc-Dfoo</option> hack… (see <xref
306 linkend="forcing-options-through"/>).</para>
312 <option>-U</option><replaceable>symbol</replaceable>
313 <indexterm><primary><option>-U</option></primary></indexterm>
316 <para> Undefine macro <replaceable>symbol</replaceable> in the
323 <option>-I</option><replaceable>dir</replaceable>
324 <indexterm><primary><option>-I</option></primary></indexterm>
327 <para> Specify a directory in which to look for
328 <literal>#include</literal> files, in the usual C
334 <para>The GHC driver pre-defines several macros when processing
335 Haskell source code (<filename>.hs</filename> or
336 <filename>.lhs</filename> files).</para>
338 <para>The symbols defined by GHC are listed below. To check which
339 symbols are defined by your local GHC installation, the following
340 trick is useful:</para>
342 <screen>$ ghc -E -optP-dM -cpp foo.hs
343 $ cat foo.hspp</screen>
345 <para>(you need a file <filename>foo.hs</filename>, but it isn't
346 actually used).</para>
351 <constant>__GLASGOW_HASKELL__</constant>
352 <indexterm><primary><constant>__GLASGOW_HASKELL__</constant></primary></indexterm>
356 <literal><replaceable>x</replaceable>.<replaceable>y</replaceable>.<replaceable>z</replaceable></literal>
358 <constant>__GLASGOW_HASKELL__</constant>
359 is the integer <replaceable>xyy</replaceable> (if
360 <replaceable>y</replaceable> is a single digit, then a leading zero
361 is added, so for example in version 6.2 of GHC,
362 <literal>__GLASGOW_HASKELL__==602</literal>). More
363 information in <xref linkend="version-numbering"/>.</para>
366 <constant>__GLASGOW_HASKELL__</constant>
367 will be undefined in all other implementations that
368 support C-style pre-processing.</para>
370 <para>(For reference: the comparable symbols for other
372 <constant>__HUGS__</constant>
374 <constant>__NHC__</constant>
376 <constant>__HBC__</constant>
379 <para>NB. This macro is set when pre-processing both
380 Haskell source and C source, including the C source
381 generated from a Haskell module
382 (i.e. <filename>.hs</filename>, <filename>.lhs</filename>,
383 <filename>.c</filename> and <filename>.hc</filename>
390 <constant>__PARALLEL_HASKELL__</constant>
391 <indexterm><primary><constant>__PARALLEL_HASKELL__</constant></primary></indexterm>
394 <para>Only defined when <option>-parallel</option> is in
395 use! This symbol is defined when pre-processing Haskell
396 (input) and pre-processing C (GHC output).</para>
402 <constant><replaceable>os</replaceable>_HOST_OS=1</constant>
405 <para>This define allows conditional compilation based on
406 the Operating System, where<replaceable>os</replaceable> is
407 the name of the current Operating System
408 (eg. <literal>linux</literal>, <literal>mingw32</literal>
409 for Windows, <literal>solaris</literal>, etc.).</para>
415 <constant><replaceable>arch</replaceable>_HOST_ARCH=1</constant>
418 <para>This define allows conditional compilation based on
419 the host architecture, where<replaceable>arch</replaceable>
420 is the name of the current architecture
421 (eg. <literal>i386</literal>, <literal>x86_64</literal>,
422 <literal>powerpc</literal>, <literal>sparc</literal>,
428 <sect3 id="cpp-string-gaps">
429 <title>CPP and string gaps</title>
431 <para>A small word of warning: <option>-cpp</option> is not
432 friendly to “string gaps”.<indexterm><primary>-cpp
433 vs string gaps</primary></indexterm><indexterm><primary>string
434 gaps vs -cpp</primary></indexterm>. In other words, strings
435 such as the following:</para>
437 <programlisting>strmod = "\
441 <para>don't work with <option>-cpp</option>;
442 <filename>/usr/bin/cpp</filename> elides the backslash-newline
445 <para>However, it appears that if you add a space at the end
446 of the line, then <command>cpp</command> (at least GNU
447 <command>cpp</command> and possibly other
448 <command>cpp</command>s) leaves the backslash-space pairs
449 alone and the string gap works as expected.</para>
453 <sect2 id="pre-processor">
454 <title>Options affecting a Haskell pre-processor</title>
456 <indexterm><primary>pre-processing: custom</primary></indexterm>
457 <indexterm><primary>Pre-processor options</primary></indexterm>
463 <indexterm><primary><option>-F</option></primary></indexterm>
466 <para>A custom pre-processor is run over your Haskell
467 source file only if the <option>-F</option> option
468 <indexterm><primary>-F</primary></indexterm> is
471 <para>Running a custom pre-processor at compile-time is in
472 some settings appropriate and useful. The
473 <option>-F</option> option lets you run a pre-processor as
474 part of the overall GHC compilation pipeline, which has
475 the advantage over running a Haskell pre-processor
476 separately in that it works in interpreted mode and you
477 can continue to take reap the benefits of GHC's
478 recompilation checker.</para>
480 <para>The pre-processor is run just before the Haskell
481 compiler proper processes the Haskell input, but after the
482 literate markup has been stripped away and (possibly) the
483 C pre-processor has washed the Haskell input.</para>
486 <option>-pgmF <replaceable>cmd</replaceable></option>
487 to select the program to use as the preprocessor. When
488 invoked, the <replaceable>cmd</replaceable> pre-processor
489 is given at least three arguments on its command-line: the
490 first argument is the name of the original source file,
491 the second is the name of the file holding the input, and
492 the third is the name of the file where
493 <replaceable>cmd</replaceable> should write its output
496 <para>Additional arguments to the pre-processor can be
497 passed in using the <option>-optF</option> option. These
498 are fed to <replaceable>cmd</replaceable> on the command
499 line after the three standard input and output
503 An example of a pre-processor is to convert your source files to the
504 input encoding that GHC expects, i.e. create a script
505 <literal>convert.sh</literal> containing the lines:
509 ( echo "{-# LINE 1 \"$2\" #-}" ; iconv -f l1 -t utf-8 $2 ) > $3</screen>
511 <para>and pass <literal>-F -pgmF convert.sh</literal> to GHC.
512 The <literal>-f l1</literal> option tells iconv to convert your
513 Latin-1 file, supplied in argument <literal>$2</literal>, while
514 the "-t utf-8" options tell iconv to return a UTF-8 encoded file.
515 The result is redirected into argument <literal>$3</literal>.
516 The <literal>echo "{-# LINE 1 \"$2\" #-}"</literal>
517 just makes sure that your error positions are reported as
518 in the original source file.</para>
524 <sect2 id="options-codegen">
525 <title>Options affecting code generation</title>
530 <option>-fasm</option>
531 <indexterm><primary><option>-fasm</option></primary></indexterm>
534 <para>Use GHC's native code generator rather than
536 <option>-fasm</option> is the default.</para>
542 <option>-fllvm</option>
543 <indexterm><primary><option>-fllvm</option></primary></indexterm>
546 <para>Compile via LLVM instead of using the native code
547 generator. This will generally take slightly longer than the
548 native code generator to compile.
549 Produced code is generally the same speed or faster
550 than the other two code generators. Compiling via LLVM
551 requires LLVM version 2.7 or later to be on the path.</para>
557 <option>-fno-code</option>
558 <indexterm><primary><option>-fno-code</option></primary></indexterm>
561 <para>Omit code generation (and all later phases)
562 altogether. Might be of some use if you just want to see
563 dumps of the intermediate compilation phases.</para>
569 <option>-fobject-code</option>
570 <indexterm><primary><option>-fobject-code</option></primary></indexterm>
573 <para>Generate object code. This is the default outside of
574 GHCi, and can be used with GHCi to cause object code to be
575 generated in preference to bytecode.</para>
581 <option>-fbyte-code</option>
582 <indexterm><primary><option>-fbyte-code</option></primary></indexterm>
585 <para>Generate byte-code instead of object-code. This is
586 the default in GHCi. Byte-code can currently only be used
587 in the interactive interpreter, not saved to disk. This
588 option is only useful for reversing the effect of
589 <option>-fobject-code</option>.</para>
595 <option>-fPIC</option>
596 <indexterm><primary><option>-fPIC</option></primary></indexterm>
599 <para>Generate position-independent code (code that can be put into
600 shared libraries). This currently works on Linux x86 and x86-64 when
601 using the native code generator (-fasm).
602 On Windows, position-independent code is never used
603 so the flag is a no-op on that platform.</para>
609 <option>-dynamic</option>
612 <para>When generating code, assume that entities imported from a
613 different package will reside in a different shared library or
615 <para>Note that using this option when linking causes GHC to link
616 against shared libraries.</para>
622 <sect2 id="options-linker">
623 <title>Options affecting linking</title>
625 <indexterm><primary>linker options</primary></indexterm>
626 <indexterm><primary>ld options</primary></indexterm>
629 <para>GHC has to link your code with various libraries, possibly
630 including: user-supplied, GHC-supplied, and system-supplied
631 (<option>-lm</option> math library, for example).</para>
637 <option>-l</option><replaceable>lib</replaceable>
638 <indexterm><primary><option>-l</option></primary></indexterm>
641 <para>Link in the <replaceable>lib</replaceable> library.
642 On Unix systems, this will be in a file called
643 <filename>lib<replaceable>lib</replaceable>.a</filename>
645 <filename>lib<replaceable>lib</replaceable>.so</filename>
646 which resides somewhere on the library directories path.</para>
648 <para>Because of the sad state of most UNIX linkers, the
649 order of such options does matter. If library
650 <replaceable>foo</replaceable> requires library
651 <replaceable>bar</replaceable>, then in general
652 <option>-l</option><replaceable>foo</replaceable> should
653 come <emphasis>before</emphasis>
654 <option>-l</option><replaceable>bar</replaceable> on the
657 <para>There's one other gotcha to bear in mind when using
658 external libraries: if the library contains a
659 <literal>main()</literal> function, then this will be
660 linked in preference to GHC's own
661 <literal>main()</literal> function
662 (eg. <literal>libf2c</literal> and <literal>libl</literal>
663 have their own <literal>main()</literal>s). This is
664 because GHC's <literal>main()</literal> comes from the
665 <literal>HSrts</literal> library, which is normally
666 included <emphasis>after</emphasis> all the other
667 libraries on the linker's command line. To force GHC's
668 <literal>main()</literal> to be used in preference to any
669 other <literal>main()</literal>s from external libraries,
670 just add the option <option>-lHSrts</option> before any
671 other libraries on the command line.</para>
678 <indexterm><primary><option>-c</option></primary></indexterm>
681 <para>Omits the link step. This option can be used with
682 <option>––make</option> to avoid the automatic linking
683 that takes place if the program contains a <literal>Main</literal>
690 <option>-package</option> <replaceable>name</replaceable>
691 <indexterm><primary><option>-package</option></primary></indexterm>
694 <para>If you are using a Haskell “package”
695 (see <xref linkend="packages"/>), don't forget to add the
696 relevant <option>-package</option> option when linking the
697 program too: it will cause the appropriate libraries to be
698 linked in with the program. Forgetting the
699 <option>-package</option> option will likely result in
700 several pages of link errors.</para>
706 <option>-framework</option> <replaceable>name</replaceable>
707 <indexterm><primary><option>-framework</option></primary></indexterm>
710 <para>On Darwin/MacOS X only, link in the framework <replaceable>name</replaceable>.
711 This option corresponds to the <option>-framework</option> option for Apple's Linker.
712 Please note that frameworks and packages are two different things - frameworks don't
713 contain any haskell code. Rather, they are Apple's way of packaging shared libraries.
714 To link to Apple's “Carbon” API, for example, you'd use
715 <option>-framework Carbon</option>.
722 <option>-L</option><replaceable>dir</replaceable>
723 <indexterm><primary><option>-L</option></primary></indexterm>
726 <para>Where to find user-supplied libraries…
727 Prepend the directory <replaceable>dir</replaceable> to
728 the library directories path.</para>
734 <option>-framework-path</option><replaceable>dir</replaceable>
735 <indexterm><primary><option>-framework-path</option></primary></indexterm>
738 <para>On Darwin/MacOS X only, prepend the directory <replaceable>dir</replaceable> to
739 the framework directories path. This option corresponds to the <option>-F</option>
740 option for Apple's Linker (<option>-F</option> already means something else for GHC).</para>
746 <option>-split-objs</option>
747 <indexterm><primary><option>-split-objs</option></primary></indexterm>
750 <para>Tell the linker to split the single object file that
751 would normally be generated into multiple object files,
752 one per top-level Haskell function or type in the module.
753 This only makes sense for libraries, where it means that
754 executables linked against the library are smaller as they only
755 link against the object files that they need. However, assembling
756 all the sections separately is expensive, so this is slower than
758 We use this feature for building GHC's libraries
759 (warning: don't use it unless you know what you're
766 <option>-static</option>
767 <indexterm><primary><option>-static</option></primary></indexterm>
770 <para>Tell the linker to avoid shared Haskell libraries,
771 if possible. This is the default.</para>
777 <option>-dynamic</option>
778 <indexterm><primary><option>-dynamic</option></primary></indexterm>
781 <para>This flag tells GHC to link against shared Haskell libraries.
782 This flag only affects the selection of dependent libraries, not
783 the form of the current target (see -shared).
784 See <xref linkend="using-shared-libs" /> on how to
787 <para>Note that this option also has an effect on
788 code generation (see above).</para>
794 <option>-shared</option>
795 <indexterm><primary><option>-shared</option></primary></indexterm>
798 <para>Instead of creating an executable, GHC produces a
799 shared object with this linker flag. Depending on the
800 operating system target, this might be an ELF DSO, a Windows
801 DLL, or a Mac OS dylib. GHC hides the operating system
802 details beneath this uniform flag.</para>
804 <para>The flags <option>-dynamic</option>/<option>-static</option> control whether the
805 resulting shared object links statically or dynamically to
806 Haskell package libraries given as <option>-package</option> option. Non-Haskell
807 libraries are linked as gcc would regularly link it on your
808 system, e.g. on most ELF system the linker uses the dynamic
809 libraries when found.</para>
811 <para>Object files linked into shared objects must be
812 compiled with <option>-fPIC</option>, see <xref linkend="options-codegen" /></para>
814 <para>When creating shared objects for Haskell packages, the
815 shared object must be named properly, so that GHC recognizes
816 the shared object when linked against this package. See
817 shared object name mangling.</para>
823 <option>-dynload</option>
824 <indexterm><primary><option>-dynload</option></primary></indexterm>
828 This flag selects one of a number of modes for finding shared
829 libraries at runtime. See <xref linkend="finding-shared-libs"/> for
830 a description of each mode.
837 <option>-main-is <replaceable>thing</replaceable></option>
838 <indexterm><primary><option>-main-is</option></primary></indexterm>
839 <indexterm><primary>specifying your own main function</primary></indexterm>
842 <para> The normal rule in Haskell is that your program must supply a <literal>main</literal>
843 function in module <literal>Main</literal>. When testing, it is often convenient
844 to change which function is the "main" one, and the <option>-main-is</option> flag
845 allows you to do so. The <replaceable>thing</replaceable> can be one of:
847 <listitem><para>A lower-case identifier <literal>foo</literal>. GHC assumes that the main function is <literal>Main.foo</literal>.</para></listitem>
848 <listitem><para>An module name <literal>A</literal>. GHC assumes that the main function is <literal>A.main</literal>.</para></listitem>
849 <listitem><para>An qualified name <literal>A.foo</literal>. GHC assumes that the main function is <literal>A.foo</literal>.</para></listitem>
851 Strictly speaking, <option>-main-is</option> is not a link-phase flag at all; it has no effect on the link step.
852 The flag must be specified when compiling the module containing the specified main function (e.g. module <literal>A</literal>
853 in the latter two items above). It has no effect for other modules,
854 and hence can safely be given to <literal>ghc --make</literal>.
855 However, if all the modules are otherwise up to date, you may need to force
856 recompilation both of the module where the new "main" is, and of the
857 module where the "main" function used to be;
858 <literal>ghc</literal> is not clever
859 enough to figure out that they both need recompiling. You can
860 force recompilation by removing the object file, or by using the
861 <option>-fforce-recomp</option> flag.
868 <option>-no-hs-main</option>
869 <indexterm><primary><option>-no-hs-main</option></primary></indexterm>
870 <indexterm><primary>linking Haskell libraries with foreign code</primary></indexterm>
873 <para>In the event you want to include ghc-compiled code
874 as part of another (non-Haskell) program, the RTS will not
875 be supplying its definition of <function>main()</function>
876 at link-time, you will have to. To signal that to the
877 compiler when linking, use
878 <option>-no-hs-main</option>. See also <xref linkend="using-own-main"/>.</para>
880 <para>Notice that since the command-line passed to the
881 linker is rather involved, you probably want to use
882 <command>ghc</command> to do the final link of your
883 `mixed-language' application. This is not a requirement
884 though, just try linking once with <option>-v</option> on
885 to see what options the driver passes through to the
888 <para>The <option>-no-hs-main</option> flag can also be
889 used to persuade the compiler to do the link step in
890 <option>--make</option> mode when there is no Haskell
891 <literal>Main</literal> module present (normally the
892 compiler will not attempt linking when there is no
893 <literal>Main</literal>).</para>
899 <option>-debug</option>
900 <indexterm><primary><option>-debug</option></primary></indexterm>
903 <para>Link the program with a debugging version of the
904 runtime system. The debugging runtime turns on numerous
905 assertions and sanity checks, and provides extra options
906 for producing debugging output at runtime (run the program
907 with <literal>+RTS -?</literal> to see a list).</para>
913 <option>-threaded</option>
914 <indexterm><primary><option>-threaded</option></primary></indexterm>
917 <para>Link the program with the "threaded" version of the
918 runtime system. The threaded runtime system is so-called
919 because it manages multiple OS threads, as opposed to the
920 default runtime system which is purely
921 single-threaded.</para>
923 <para>Note that you do <emphasis>not</emphasis> need
924 <option>-threaded</option> in order to use concurrency; the
925 single-threaded runtime supports concurrency between Haskell
926 threads just fine.</para>
928 <para>The threaded runtime system provides the following
933 <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>
934 machine. See <xref linkend="using-smp" />.</para>
936 <para>The ability to make a foreign call that does not
937 block all other Haskell threads, and to invoke
938 foreign-exported Haskell functions from multiple OS
939 threads. See <xref linkend="ffi-threads" />.</para>
947 <option>-eventlog</option>
948 <indexterm><primary><option>-eventlog</option></primary></indexterm>
952 Link the program with the "eventlog" version of the
953 runtime system. A program linked in this way can generate
954 a runtime trace of events (such as thread start/stop) to a
956 <literal><replaceable>program</replaceable>.eventlog</literal>,
957 which can then be interpreted later by various tools. See
958 <xref linkend="rts-eventlog" /> for more information.
961 <option>-eventlog</option> can be used
962 with <option>-threaded</option>. It is implied
963 by <option>-debug</option>.
970 <option>-rtsopts</option>
971 <indexterm><primary><option>-rtsopts</option></primary></indexterm>
975 This option affects the processing of RTS control options given either
976 on the command line or via the <envar>GHCRTS</envar> environment variable.
977 There are three possibilities:
981 <term><option>-rtsopts=none</option></term>
984 Disable all processing of RTS options.
985 If <option>+RTS</option> appears anywhere on the command
986 line, then the program will abort with an error message.
987 If the <envar>GHCRTS</envar> environment variable is
988 set, then the program will emit a warning message,
989 <envar>GHCRTS</envar> will be ignored, and the program
995 <term><option>-rtsopts=some</option></term>
997 <para>[this is the default setting] Enable
998 only the "safe" RTS options: (Currently
999 only <option>-?</option>
1000 and <option>--info</option>.) Any other RTS options
1001 on the command line or in the <envar>GHCRTS</envar>
1002 environment variable causes the program with to abort
1003 with an error message.
1008 <term><option>-rtsopts=all</option>, or
1009 just <option>-rtsopts</option></term>
1012 Enable <emphasis>all</emphasis> RTS option
1013 processing, both on the command line and through
1014 the <envar>GHCRTS</envar> environment variable.
1020 In GHC 6.12.3 and earlier, the default was to process all
1021 RTS options. However, since RTS options can be used to
1022 write logging data to arbitrary files under the security
1023 context of the running program, there is a potential
1024 security problem. For this reason, GHC 7.0.1 and later
1025 default to <option>-rtsops=some</option>.
1032 <option>-with-rtsopts</option>
1033 <indexterm><primary><option>-with-rtsopts</option></primary></indexterm>
1037 This option allows you to set the default RTS options at link-time. For example,
1038 <option>-with-rtsopts="-H128m"</option> sets the default heap size to 128MB.
1039 This will always be the default heap size for this program, unless the user overrides it.
1040 (Depending on the setting of the <option>-rtsopts</option> option, the user might
1041 not have the ability to change RTS options at run-time, in which case
1042 <option>-with-rtsopts</option> would be the <emphasis>only</emphasis> way to set
1050 <option>-fno-gen-manifest</option>
1051 <indexterm><primary><option>-fno-gen-manifest</option></primary>
1055 <para>On Windows, GHC normally generates a
1056 <firstterm>manifest</firstterm><indexterm><primary>manifest</primary>
1057 </indexterm>file when linking a binary. The
1058 manifest is placed in the file
1059 <literal><replaceable>prog</replaceable>.exe.manifest</literal>
1060 where <replaceable>prog.exe</replaceable> is the name of the
1061 executable. The manifest file currently serves just one purpose:
1062 it disables the "installer detection"<indexterm><primary>installer detection</primary>
1063 </indexterm>in Windows Vista that
1064 attempts to elevate privileges for executables with certain names
1065 (e.g. names containing "install", "setup" or "patch"). Without the
1066 manifest file to turn off installer detection, attempting to run an
1067 executable that Windows deems to be an installer will return a
1068 permission error code to the invoker. Depending on the invoker,
1069 the result might be a dialog box asking the user for elevated
1070 permissions, or it might simply be a permission denied
1073 <para>Installer detection can be also turned off globally for the
1074 system using the security control panel, but GHC by default
1075 generates binaries that don't depend on the user having disabled
1076 installer detection.</para>
1078 <para>The <option>-fno-gen-manifest</option> disables generation of
1079 the manifest file. One reason to do this would be if you had
1080 a manifest file of your own, for example.</para>
1082 <para>In the future, GHC might use the manifest file for more things,
1083 such as supplying the location of dependent DLLs.</para>
1085 <para><option>-fno-gen-manifest</option> also implies
1086 <option>-fno-embed-manifest</option>, see below.</para>
1092 <option>-fno-embed-manifest</option>
1093 <indexterm><primary><option>-fno-embed-manifest</option></primary>
1097 <para>The manifest file that GHC generates when linking a binary on
1098 Windows is also embedded in the executable itself, by default.
1099 This means that the binary can be distributed without having to
1100 supply the manifest file too. The embedding is done by running
1101 <literal>windres</literal><indexterm><primary><literal>windres</literal></primary>
1102 </indexterm>; to see exactly what GHC does to embed the manifest,
1103 use the <option>-v</option> flag. A GHC installation comes with
1104 its own copy of <literal>windres</literal> for this reason.</para>
1106 <para>See also <option>-pgmwindres</option> (<xref
1107 linkend="replacing-phases" />) and
1108 <option>-optwindres</option> (<xref
1109 linkend="forcing-options-through"
1116 <option>-fno-shared-implib</option>
1117 <indexterm><primary><option>-fno-shared-implib</option></primary>
1121 <para>DLLs on Windows are typically linked to by linking to a corresponding
1122 <literal>.lib</literal> or <literal>.dll.a</literal> - the so-called import library.
1123 GHC will typically generate such a file for every DLL you create by compiling in
1124 <literal>-shared</literal> mode. However, sometimes you don't want to pay the
1125 disk-space cost of creating this import library, which can be substantial - it
1126 might require as much space as the code itself, as Haskell DLLs tend to export
1127 lots of symbols.</para>
1129 <para>As long as you are happy to only be able to link to the DLL using
1130 <literal>GetProcAddress</literal> and friends, you can supply the
1131 <option>-fno-shared-implib</option> flag to disable the creation of the import
1132 library entirely.</para>
1138 <option>-dylib-install-name <replaceable>path</replaceable></option>
1139 <indexterm><primary><option>-dylib-install-name</option></primary>
1143 <para>On Darwin/MacOS X, dynamic libraries are stamped at build time with an
1144 "install name", which is the ultimate install path of the library file.
1145 Any libraries or executables that subsequently link against it will pick
1146 up that path as their runtime search location for it. By default, ghc sets
1147 the install name to the location where the library is built. This option
1148 allows you to override it with the specified file path. (It passes
1149 <literal>-install_name</literal> to Apple's linker.) Ignored on other
1159 ;;; Local Variables: ***
1160 ;;; sgml-parent-document: ("users_guide.xml" "book" "chapter" "sect1") ***