1 <sect1 id="options-phases">
2 <title>Options related to a particular phase</title>
4 <sect2 id="replacing-phases">
5 <title>Replacing the program for one or more phases</title>
6 <indexterm><primary>phases, changing</primary></indexterm>
8 <para>You may specify that a different program be used for one
9 of the phases of the compilation system, in place of whatever
10 the <Command>ghc</Command> has wired into it. For example, you
11 might want to try a different assembler. The following options
12 allow you to change the external program used for a given
13 compilation phase:</para>
17 <term><option>-pgmL</option> <replaceable>cmd</replaceable></term>
18 <indexterm><primary><option>-pgmL</option></primary>
21 <para>Use <replaceable>cmd</replaceable> as the literate
27 <term><option>-pgmP</option> <replaceable>cmd</replaceable></term>
28 <indexterm><primary><option>-pgmP</option></primary>
31 <para>Use <replaceable>cmd</replaceable> as the C
32 pre-processor (with <option>-cpp</option> only).</para>
37 <term><option>-pgmc</option> <replaceable>cmd</replaceable></term>
38 <indexterm><primary><option>-pgmc</option></primary>
41 <para>Use <replaceable>cmd</replaceable> as the C
47 <term><option>-pgma</option> <replaceable>cmd</replaceable></term>
48 <indexterm><primary><option>-pgma</option></primary>
51 <para>Use <replaceable>cmd</replaceable> as the
57 <term><option>-pgml</option> <replaceable>cmd</replaceable></term>
58 <indexterm><primary><option>-pgml</option></primary>
61 <para>Use <replaceable>cmd</replaceable> as the
67 <term><option>-pgmdll</option> <replaceable>cmd</replaceable></term>
68 <indexterm><primary><option>-pgmdll</option></primary>
71 <para>Use <replaceable>cmd</replaceable> as the DLL
77 <term><option>-pgmdep</option> <replaceable>cmd</replaceable></term>
78 <indexterm><primary><option>-pgmdep</option></primary>
81 <para>Use <replaceable>cmd</replaceable> as the dependency
87 <term><option>-pgmF</option> <replaceable>cmd</replaceable></term>
88 <indexterm><primary><option>-pgmF</option></primary>
91 <para>Use <replaceable>cmd</replaceable> as the
92 pre-processor (with <option>-F</option> only).</para>
99 <sect2 id="forcing-options-through">
100 <title>Forcing options to a particular phase</title>
101 <indexterm><primary>forcing GHC-phase options</primary></indexterm>
103 <para>Options can be forced through to a particlar compilation
104 phase, using the following flags:</para>
108 <term><option>-optL</option> <replaceable>option</replaceable></term>
109 <indexterm><primary><option>-optL</option></primary>
112 <para>Pass <replaceable>option</replaceable> to the
113 literate pre-processor</para>
117 <term><option>-optP</option> <replaceable>option</replaceable></term>
118 <indexterm><primary><option>-optP</option></primary>
121 <para>Pass <replaceable>option</replaceable> to CPP (makes
122 sense only if <option>-cpp</option> is also on).</para>
126 <term><option>-optF</option> <replaceable>option</replaceable></term>
127 <indexterm><primary><option>-optF</option></primary>
130 <para>Pass <replaceable>option</replaceable> to the
131 custom pre-processor (see <xref linkend="pre-processor">).</para>
135 <term><option>-optc</option> <replaceable>option</replaceable></term>
136 <indexterm><primary><option>-optc</option></primary>
139 <para>Pass <replaceable>option</replaceable> to the C compiler.</para>
143 <term><option>-opta</option> <replaceable>option</replaceable></term>
144 <indexterm><primary><option>-opta</option></primary>
147 <para>Pass <replaceable>option</replaceable> to the assembler.</para>
151 <term><option>-optl</option> <replaceable>option</replaceable></term>
152 <indexterm><primary><option>-optl</option></primary>
155 <para>Pass <replaceable>option</replaceable> to the linker.</para>
159 <term><option>-optdll</option> <replaceable>option</replaceable></term>
160 <indexterm><primary><option>-optdll</option></primary>
163 <para>Pass <replaceable>option</replaceable> to the DLL generator.</para>
167 <term><option>-optdep</option> <replaceable>option</replaceable></term>
168 <indexterm><primary><option>-optdep</option></primary>
171 <para>Pass <replaceable>option</replaceable> to the
172 dependency generator.</para>
177 <para>So, for example, to force an <option>-Ewurble</option>
178 option to the assembler, you would tell the driver
179 <option>-opta-Ewurble</option> (the dash before the E is
182 <para>GHC is itself a Haskell program, so if you need to pass
183 options directly to GHC's runtime system you can enclose them in
184 <literal>+RTS ... -RTS</literal> (see <xref
185 linkend="runtime-control">).</para>
189 <sect2 id="c-pre-processor">
190 <title>Options affecting the C pre-processor</title>
192 <indexterm><primary>pre-processing: cpp</primary></indexterm>
193 <indexterm><primary>C pre-processor options</primary></indexterm>
194 <indexterm><primary>cpp, pre-processing with</primary></indexterm>
199 <term><option>-cpp</option></term>
200 <indexterm><primary><option>-cpp</option></primary></indexterm>
202 <para>The C pre-processor <command>cpp</command> is run
203 over your Haskell code only if the <option>-cpp</option>
204 option <indexterm><primary>-cpp
205 option</primary></indexterm> is given. Unless you are
206 building a large system with significant doses of
207 conditional compilation, you really shouldn't need
213 <term><option>-D</option><replaceable>symbol</replaceable><optional>=<replaceable>value</replaceable></optional></term>
214 <indexterm><primary><option>-D</option></primary></indexterm>
216 <para>Define macro <replaceable>symbol</replaceable> in the
217 usual way. NB: does <emphasis>not</emphasis> affect
218 <option>-D</option> macros passed to the C compiler
219 when compiling via C! For those, use the
220 <option>-optc-Dfoo</option> hack… (see <xref
221 linkend="forcing-options-through">).</para>
226 <term><option>-U</option><replaceable>symbol</replaceable></term>
227 <indexterm><primary><option>-U</option></primary></indexterm>
229 <para> Undefine macro <replaceable>symbol</replaceable> in the
235 <term><option>-I</option><replaceable>dir</replaceable></term>
236 <indexterm><primary><option>-I</option></primary></indexterm>
238 <para> Specify a directory in which to look for
239 <literal>#include</literal> files, in the usual C
245 <para>The GHC driver pre-defines several macros when processing
246 Haskell source code (<filename>.hs</filename> or
247 <filename>.lhs</filename> files):</para>
252 <term><constant>__HASKELL98__</constant></term>
253 <indexterm><primary><literal>__HASKELL98__</literal></primary></indexterm>
255 <para>If defined, this means that GHC supports the
256 language defined by the Haskell 98 report.</para>
261 <term><constant>__HASKELL__=98</constant></term>
262 <indexterm><primary><constant>__HASKELL__=98</constant></primary></indexterm>
264 <para>In GHC 4.04 and later, the
265 <constant>__HASKELL__</constant>
266 macro is defined as having the value
267 <constant>98</constant>.</para>
272 <term><constant>__HASKELL1__</constant></term>
273 <indexterm><primary><constant>__HASKELL1__
274 </constant></primary></indexterm>
276 <para>If defined to <replaceable>n</replaceable>, that
277 means GHC supports the Haskell language defined in the
278 Haskell report version <emphasis>1.n</emphasis>.
279 Currently 5. This macro is deprecated, and will probably
280 disappear in future versions.</para>
285 <term><constant>__GLASGOW_HASKELL__</constant></term>
286 <indexterm><primary><constant>__GLASGOW_HASKELL__</constant></primary></indexterm>
288 <para>For version <replaceable>n</replaceable> of the GHC
289 system, this will be <literal>#define</literal>d to
290 <replaceable>100n</replaceable>. For example, for version
291 5.00, it is 500.</para>
294 <constant>__GLASGOW_HASKELL__</constant>
295 will be undefined in all other implementations that
296 support C-style pre-processing.</para>
298 <para>(For reference: the comparable symbols for other
300 <constant>__HUGS__</constant>
302 <constant>__NHC__</constant>
304 <constant>__HBC__</constant>
305 for Chalmers.)</para>
307 <para>NB. This macro is set when pre-processing both
308 Haskell source and C source, including the C source
309 generated from a Haskell module
310 (i.e. <filename>.hs</filename>, <filename>.lhs</filename>,
311 <filename>.c</filename> and <filename>.hc</filename>
317 <term><constant>__CONCURRENT_HASKELL__</constant></term>
318 <indexterm><primary><constant>__CONCURRENT_HASKELL__</constant></primary></indexterm>
320 <para>This symbol is defined when pre-processing Haskell
321 (input) and pre-processing C (GHC output). Since GHC from
322 verion 4.00 now supports concurrent haskell by default,
323 this symbol is always defined.</para>
328 <term><constant>__PARALLEL_HASKELL__</constant></term>
329 <indexterm><primary><constant>__PARALLEL_HASKELL__</constant></primary></indexterm>
331 <para>Only defined when <option>-parallel</option> is in
332 use! This symbol is defined when pre-processing Haskell
333 (input) and pre-processing C (GHC output).</para>
338 <sect3 id="cpp-string-gaps">
339 <title>CPP and string gaps</title>
341 <para>A small word of warning: <option>-cpp</option> is not
342 friendly to “string gaps”.<indexterm><primary>-cpp
343 vs string gaps</primary></indexterm><indexterm><primary>string
344 gaps vs -cpp</primary></indexterm>. In other words, strings
345 such as the following:</para>
353 <para>don't work with <option>-cpp</option>;
354 <filename>/usr/bin/cpp</filename> elides the backslash-newline
357 <para>However, it appears that if you add a space at the end
358 of the line, then <command>cpp</command> (at least GNU
359 <command>cpp</command> and possibly other
360 <command>cpp</command>s) leaves the backslash-space pairs
361 alone and the string gap works as expected.</para>
365 <sect2 id="pre-processor">
366 <title>Options affecting a Haskell pre-processor</title>
368 <indexterm><primary>pre-processing: custom</primary></indexterm>
369 <indexterm><primary>Pre-processor options</primary></indexterm>
373 <term><option>-F</option></term>
374 <indexterm><primary><option>-F</option></primary></indexterm>
376 <para>A custom pre-processor is run over your Haskell
377 source file only if the <option>-F</option> option
378 <indexterm><primary>-F</primary></indexterm> is given.
381 Running a custom pre-processor at compile-time is in some
382 settings appropriate and useful. The <option>-F</option>
383 option lets you run a pre-processor as part of the overall
384 GHC compilation pipeline, which has the advantage over
385 running a Haskell pre-processor separately in that it
386 works in interpreted mode and you can continue to take
387 reap the benefits of GHC's recompilation checker.
390 The pre-processor is run just before the Haskell
391 compiler proper processes the Haskell input, but after
392 the literate markup has been stripped away and (possibly)
393 the C pre-processor has washed the Haskell input.
398 <term><option>-pgmF</option> <replaceable>cmd</replaceable></term>
399 <indexterm><primary><option>-pgmF</option> <replaceable>cmd</replaceable></primary></indexterm>
401 <para>Use <replaceable>cmd</replaceable> as the Haskell
402 pre-processor. When invoked, the
403 <replaceable>cmd</replaceable> pre-processor is given at
404 least three arguments on its command-line: the first
405 argument is the name of the original source file, the second
406 is the name of the file holding the input, and the third is
407 the name of the file where
408 <replaceable>cmd</replaceable> should write its output to.
410 <para>Additional arguments to the
411 <replaceable>cmd</replaceable> pre-processor can be passed
412 in using the <option>-optF</option> option. These are fed to
413 <replaceable>cmd</replaceable> on the command line after the
414 three standard input and output arguments.
421 <sect2 id="options-C-compiler">
422 <title>Options affecting the C compiler (if applicable)</title>
424 <indexterm><primary>include-file options</primary></indexterm>
425 <indexterm><primary>C compiler options</primary></indexterm>
426 <indexterm><primary>GCC options</primary></indexterm>
428 <para>If you are compiling with lots of foreign calls, you may
429 need to tell the C compiler about some
430 <literal>#include</literal> files. There is no real pretty
431 way to do this, but you can use this hack from the
435 % ghc -c '-#include <X/Xlib.h>' Xstuff.lhs
440 <sect2 id="options-codegen">
441 <title>Options affecting code generation</title>
445 <term><option>-fasm</option></term>
446 <indexterm><primary><option>-fasm</option></primary></indexterm>
448 <para>Use GHC's native code generator rather than
449 compiling via C. This will compile faster (up to twice as
450 fast), but may produce code that is slightly slower than
451 compiling via C. <option>-fasm</option> is the default
452 when optimisation is off (see <xref
453 linkend="options-optimise">).</para>
458 <term><option>-fvia-C</option></term>
459 <indexterm><primary><option>-fvia-C</option></primary>
462 <para>Compile via C instead of using the native code
463 generator. This is default for optimised compilations,
464 and on architectures for which GHC doesn't have a native
465 code generator.</para>
470 <term><option>-fno-code</option></term>
471 <indexterm><primary><option>-fno-code</option></primary>
474 <para>Omit code generation (and all later phases)
475 altogether. Might be of some use if you just want to see
476 dumps of the intermediate compilation phases.</para>
482 <sect2 id="options-linker">
483 <title>Options affecting linking</title>
485 <indexterm><primary>linker options</primary></indexterm>
486 <indexterm><primary>ld options</primary></indexterm>
489 <para>GHC has to link your code with various libraries, possibly
490 including: user-supplied, GHC-supplied, and system-supplied
491 (<option>-lm</option> math library, for example).</para>
496 <term><option>-l</option><replaceable>lib</replaceable></term>
497 <indexterm><primary><option>-l</option></primary></indexterm>
499 <para>Link in the <replaceable>lib</replaceable> library.
500 On Unix systems, this will be in a file called
501 <filename>lib<replaceable>lib</replaceable>.a</filename>
503 <filename>lib<replaceable>lib</replaceable>.so</filename>
504 which resides somewhere on the library directories path.</para>
506 <para>Because of the sad state of most UNIX linkers, the
507 order of such options does matter. If library
508 <replaceable>foo</replaceable> requires library
509 <replaceable>bar</replaceable>, then in general
510 <option>-l</option><replaceable>foo</replaceable> should
511 come <emphasis>before</emphasis>
512 <option>-l</option><replaceable>bar</replaceable> on the
515 <para>There's one other gotcha to bear in mind when using
516 external libraries: if the library contains a
517 <literal>main()</literal> function, then this will be
518 linked in preference to GHC's own
519 <literal>main()</literal> function
520 (eg. <literal>libf2c</literal> and <literal>libl</literal>
521 have their own <literal>main()</literal>s). This is
522 because GHC's <literal>main()</literal> comes from the
523 <literal>HSrts</literal> library, which is normally
524 included <emphasis>after</emphasis> all the other
525 libraries on the linker's command line. To force GHC's
526 <literal>main()</literal> to be used in preference to any
527 other <literal>main()</literal>s from external libraries,
528 just add the option <option>-lHSrts</option> before any
529 other libraries on the command line.</para>
534 <term><option>-no-link</option></term>
536 <primary><option>-no-link</option></primary>
539 <para>Omit the link step. This flag can be useful if you
540 want to avoid linking in <option>--make</option> mode,
541 where linking is normally done automatically if the program
542 contains a <literal>Main</literal> module.</para>
547 <term><option>-package</option> <replaceable>name</replaceable></term>
548 <indexterm><primary><option>-package</option></primary></indexterm>
550 <para>If you are using a Haskell “package”
551 (see <xref linkend="packages">), don't forget to add the
552 relevant <option>-package</option> option when linking the
553 program too: it will cause the appropriate libraries to be
554 linked in with the program. Forgetting the
555 <option>-package</option> option will likely result in
556 several pages of link errors.</para>
561 <term><option>-framework</option> <replaceable>name</replaceable></term>
562 <indexterm><primary><option>-framework</option></primary></indexterm>
564 <para>On Darwin/MacOS X only, link in the framework <replaceable>name</replaceable>.
565 This option corresponds to the <option>-framework</option> option for Apple's Linker.
566 Please note that frameworks and packages are two different things - frameworks don't
567 contain any haskell code. Rather, they are Apple's way of packaging shared libraries.
568 To link to Apple's “Carbon” API, for example, you'd use
569 <option>-framework Carbon</option>.
575 <term><option>-L</option><replaceable>dir</replaceable></term>
576 <indexterm><primary><option>-L</option></primary></indexterm>
578 <para>Where to find user-supplied libraries…
579 Prepend the directory <replaceable>dir</replaceable> to
580 the library directories path.</para>
585 <term><option>-framework-path</option><replaceable>dir</replaceable></term>
586 <indexterm><primary><option>-framework-path</option></primary></indexterm>
588 <para>On Darwin/MacOS X only, prepend the directory <replaceable>dir</replaceable> to
589 the framework directories path. This option corresponds to the <option>-F</option>
590 option for Apple's Linker (<option>-F</option> already means something else for GHC).</para>
595 <term><option>-split-objs</option></term>
596 <indexterm><primary><option>-split-objs</option></primary></indexterm>
598 <para>Tell the linker to split the single object file that
599 would normally be generated into multiple object files,
600 one per top-level Haskell function or type in the module.
601 We use this feature for building GHC's libraries libraries
602 (warning: don't use it unless you know what you're
608 <term><option>-static</option></term>
609 <indexterm><primary><option>-static</option></primary></indexterm>
611 <para>Tell the linker to avoid shared Haskell libraries,
612 if possible. This is the default.</para>
617 <term><option>-dynamic</option></term>
618 <indexterm><primary><option>-dynamic</option></primary></indexterm>
620 <para>Tell the linker to use shared Haskell libraries, if
621 available (this option is only supported on Windows at the
622 moment, and also note that your distribution of GHC may
623 not have been supplied with shared libraries).</para>
628 <term><option>-main-is <replaceable>thing</replaceable></option></term>
629 <indexterm><primary><option>-main-is</option></primary></indexterm>
630 <indexterm><primary>specifying your own main function</primary></indexterm>
632 <para> The normal rule in Haskell is that your program must supply a <literal>main</literal>
633 function in module <literal>Main</literal>. When testing, it is often convenient
634 to change which function is the "main" one, and the <option>-main-is</option> flag
635 allows you to do so. The <replaceable>thing</replaceable> can be one of:
637 <listitem><para>A lower-case identifier <literal>foo</literal>. GHC assumes that the main function is <literal>Main.foo</literal>.</para></listitem>
638 <listitem><para>An module name <literal>A</literal>. GHC assumes that the main function is <literal>A.main</literal>.</para></listitem>
639 <listitem><para>An qualified name <literal>A.foo</literal>. GHC assumes that the main function is <literal>A.foo</literal>.</para></listitem>
641 Strictly speaking, <option>-main-is</option> is not a link-phase flag at all; it has no effect on the link step.
642 The flag must be specified when compiling the module containing the specified main function (e.g. module <literal>A</literal>
643 in the latter two items above. It has no effect for other modules (and hence can safely be given to <literal>ghc --make</literal>).
649 <term><option>-no-hs-main</option></term>
650 <indexterm><primary><option>-no-hs-main</option></primary></indexterm>
651 <indexterm><primary>linking Haskell libraries with foreign code</primary></indexterm>
653 <para>In the event you want to include ghc-compiled code
654 as part of another (non-Haskell) program, the RTS will not
655 be supplying its definition of <function>main()</function>
656 at link-time, you will have to. To signal that to the
657 compiler when linking, use
658 <option>-no-hs-main</option>. See also <xref linkend="using-own-main">.</para>
660 <para>Notice that since the command-line passed to the
661 linker is rather involved, you probably want to use
662 <command>ghc</command> to do the final link of your
663 `mixed-language' application. This is not a requirement
664 though, just try linking once with <option>-v</option> on
665 to see what options the driver passes through to the
668 <para>The <option>-no-hs-main</option> flag can also be
669 used to persuade the compiler to do the link step in
670 <option>--make</option> mode when there is no Haskell
671 <literal>Main</literal> module present (normally the
672 compiler will not attempt linking when there is no
673 <literal>Main</literal>).</para>
678 <term><option>-debug</option></term>
679 <indexterm><primary><option>-debug</option></primary>
682 <para>Link the program with a debugging version of the
683 runtime system. The debugging runtime turns on numerous
684 assertions and sanity checks, and provides extra options
685 for producing debugging output at runtime (run the program
686 with <literal>+RTS -?</literal> to see a list).</para>
691 <term><option>-threaded</option></term>
692 <indexterm><primary><option>-threaded</option></primary>
695 <para>Link the program with the "threaded" runtime system.
696 This version of the runtime is designed to be used in
697 programs that use multiple operating-system threads. It
698 supports calls to foreign-exported functions from multiple
699 OS threads. Calls to foreign functions are made using the
700 same OS thread that created the Haskell thread (if it was
701 created by a call-in), or an arbitrary OS thread otherwise
702 (if the Haskell thread was created by
703 <literal>forkIO</literal>).</para>
705 <para>The threaded RTS does <emphasis>not</emphasis>
706 support using multiple CPUs to speed up execution of a
707 multi-threaded Haskell program. The GHC runtime platform
708 is still single-threaded, but using the
709 <option>-threaded</option> option it can be used safely in
710 a multi-threaded environment.</para>
720 ;;; Local Variables: ***
722 ;;; sgml-parent-document: ("users_guide.sgml" "book" "chapter") ***