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>
107 <para>So, for example, to force an <option>-Ewurble</option>
108 option to the assembler, you would tell the driver
109 <option>-opta-Ewurble</option> (the dash before the E is
112 <para>GHC is itself a Haskell program, so if you need to pass
113 options directly to GHC's runtime system you can enclose them in
114 <literal>+RTS ... -RTS</literal> (see <xref
115 linkend="runtime-control">).</para>
119 <sect2 id="c-pre-processor">
120 <title>Options affecting the C pre-processor</title>
122 <indexterm><primary>pre-processing: cpp</primary></indexterm>
123 <indexterm><primary>C pre-processor options</primary></indexterm>
124 <indexterm><primary>cpp, pre-processing with</primary></indexterm>
129 <term><option>-cpp</option></term>
130 <indexterm><primary><option>-cpp</option></primary></indexterm>
132 <para>The C pre-processor <command>cpp</command> is run
133 over your Haskell code only if the <option>-cpp</option>
134 option <indexterm><primary>-cpp
135 option</primary></indexterm> is given. Unless you are
136 building a large system with significant doses of
137 conditional compilation, you really shouldn't need
143 <term><option>-D</option><replaceable>symbol</replaceable><optional>=<replaceable>value</replaceable></optional></term>
144 <indexterm><primary><option>-D</option></primary></indexterm>
146 <para>Define macro <replaceable>symbol</replaceable> in the
147 usual way. NB: does <emphasis>not</emphasis> affect
148 <option>-D</option> macros passed to the C compiler
149 when compiling via C! For those, use the
150 <option>-optc-Dfoo</option> hack… (see <xref
151 linkend="forcing-options-through">).</para>
156 <term><option>-U</option><replaceable>symbol</replaceable></term>
157 <indexterm><primary><option>-U</option></primary></indexterm>
159 <para> Undefine macro <replaceable>symbol</replaceable> in the
165 <term><option>-I</option><replaceable>dir</replaceable></term>
166 <indexterm><primary><option>-I</option></primary></indexterm>
168 <para> Specify a directory in which to look for
169 <literal>#include</literal> files, in the usual C
175 <para>The GHC driver pre-defines several macros when processing
176 Haskell source code (<filename>.hs</filename> or
177 <filename>.lhs</filename> files):</para>
182 <term><constant>__HASKELL98__</constant></term>
183 <indexterm><primary><literal>__HASKELL98__</literal></primary></indexterm>
185 <para>If defined, this means that GHC supports the
186 language defined by the Haskell 98 report.</para>
191 <term><constant>__HASKELL__=98</constant></term>
192 <indexterm><primary><constant>__HASKELL__=98</constant></primary></indexterm>
194 <para>In GHC 4.04 and later, the
195 <constant>__HASKELL__</constant>
196 macro is defined as having the value
197 <constant>98</constant>.</para>
202 <term><constant>__HASKELL1__</constant></term>
203 <indexterm><primary><constant>__HASKELL1__
204 </constant></primary></indexterm>
206 <para>If defined to <replaceable>n</replaceable>, that
207 means GHC supports the Haskell language defined in the
208 Haskell report version <emphasis>1.n</emphasis>.
209 Currently 5. This macro is deprecated, and will probably
210 disappear in future versions.</para>
215 <term><constant>__GLASGOW_HASKELL__</constant></term>
216 <indexterm><primary><constant>__GLASGOW_HASKELL__</constant></primary></indexterm>
218 <para>For version <replaceable>n</replaceable> of the GHC
219 system, this will be <literal>#define</literal>d to
220 <replaceable>100n</replaceable>. For example, for version
221 5.00, it is 500.</para>
224 <constant>__GLASGOW_HASKELL__</constant>
225 will be undefined in all other implementations that
226 support C-style pre-processing.</para>
228 <para>(For reference: the comparable symbols for other
230 <constant>__HUGS__</constant>
232 <constant>__NHC__</constant>
234 <constant>__HBC__</constant>
235 for Chalmers.)</para>
237 <para>NB. This macro is set when pre-processing both
238 Haskell source and C source, including the C source
239 generated from a Haskell module
240 (i.e. <filename>.hs</filename>, <filename>.lhs</filename>,
241 <filename>.c</filename> and <filename>.hc</filename>
247 <term><constant>__CONCURRENT_HASKELL__</constant></term>
248 <indexterm><primary><constant>__CONCURRENT_HASKELL__</constant></primary></indexterm>
250 <para>This symbol is defined when pre-processing Haskell
251 (input) and pre-processing C (GHC output). Since GHC from
252 verion 4.00 now supports concurrent haskell by default,
253 this symbol is always defined.</para>
258 <term><constant>__PARALLEL_HASKELL__</constant></term>
259 <indexterm><primary><constant>__PARALLEL_HASKELL__</constant></primary></indexterm>
261 <para>Only defined when <option>-parallel</option> is in
262 use! This symbol is defined when pre-processing Haskell
263 (input) and pre-processing C (GHC output).</para>
268 <sect3 id="cpp-string-gaps">
269 <title>CPP and string gaps</title>
271 <para>A small word of warning: <option>-cpp</option> is not
272 friendly to “string gaps”.<indexterm><primary>-cpp
273 vs string gaps</primary></indexterm><indexterm><primary>string
274 gaps vs -cpp</primary></indexterm>. In other words, strings
275 such as the following:</para>
283 <para>don't work with <option>-cpp</option>;
284 <filename>/usr/bin/cpp</filename> elides the backslash-newline
287 <para>However, it appears that if you add a space at the end
288 of the line, then <command>cpp</command> (at least GNU
289 <command>cpp</command> and possibly other
290 <command>cpp</command>s) leaves the backslash-space pairs
291 alone and the string gap works as expected.</para>
295 <sect2 id="pre-processor">
296 <title>Options affecting a Haskell pre-processor</title>
298 <indexterm><primary>pre-processing: custom</primary></indexterm>
299 <indexterm><primary>Pre-processor options</primary></indexterm>
303 <term><option>-F</option></term>
304 <indexterm><primary><option>-F</option></primary></indexterm>
306 <para>A custom pre-processor is run over your Haskell
307 source file only if the <option>-F</option> option
308 <indexterm><primary>-F</primary></indexterm> is given.
311 Running a custom pre-processor at compile-time is in some
312 settings appropriate and useful. The <option>-F</option>
313 option lets you run a pre-processor as part of the overall
314 GHC compilation pipeline, which has the advantage over
315 running a Haskell pre-processor separately in that it
316 works in interpreted mode and you can continue to take
317 reap the benefits of GHC's recompilation checker.
320 The pre-processor is run just before the Haskell
321 compiler proper processes the Haskell input, but after
322 the literate markup has been stripped away and (possibly)
323 the C pre-processor has washed the Haskell input.
328 <term><option>-pgmF</option> <replaceable>cmd</replaceable></term>
329 <indexterm><primary><option>-pgmF</option> <replaceable>cmd</replaceable></primary></indexterm>
331 <para>Use <replaceable>cmd</replaceable> as the Haskell
332 pre-processor. When invoked, the
333 <replaceable>cmd</replaceable> pre-processor is given at
334 least three arguments on its command-line: the first
335 argument is the name of the original source file, the second
336 is the name of the file holding the input, and the third is
337 the name of the file where
338 <replaceable>cmd</replaceable> should write its output to.
340 <para>Additional arguments to the
341 <replaceable>cmd</replaceable> pre-processor can be passed
342 in using the <option>-optF</option> option. These are fed to
343 <replaceable>cmd</replaceable> on the command line after the
344 three standard input and output arguments.
351 <sect2 id="options-C-compiler">
352 <title>Options affecting the C compiler (if applicable)</title>
354 <indexterm><primary>include-file options</primary></indexterm>
355 <indexterm><primary>C compiler options</primary></indexterm>
356 <indexterm><primary>GCC options</primary></indexterm>
358 <para>If you are compiling with lots of foreign calls, you may
359 need to tell the C compiler about some
360 <literal>#include</literal> files. There is no real pretty
361 way to do this, but you can use this hack from the
365 % ghc -c '-#include <X/Xlib.h>' Xstuff.lhs
370 <sect2 id="options-codegen">
371 <title>Options affecting code generation</title>
375 <term><option>-fasm</option></term>
376 <indexterm><primary><option>-fasm</option></primary></indexterm>
378 <para>Use GHC's native code generator rather than
379 compiling via C. This will compile faster (up to twice as
380 fast), but may produce code that is slightly slower than
381 compiling via C. <option>-fasm</option> is the default
382 when optimisation is off (see <xref
383 linkend="options-optimise">).</para>
388 <term><option>-fvia-C</option></term>
389 <indexterm><primary><option>-fvia-C</option></primary>
392 <para>Compile via C instead of using the native code
393 generator. This is default for optimised compilations,
394 and on architectures for which GHC doesn't have a native
395 code generator.</para>
400 <term><option>-fno-code</option></term>
401 <indexterm><primary><option>-fno-code</option></primary>
404 <para>Omit code generation (and all later phases)
405 altogether. Might be of some use if you just want to see
406 dumps of the intermediate compilation phases.</para>
412 <sect2 id="options-linker">
413 <title>Options affecting linking</title>
415 <indexterm><primary>linker options</primary></indexterm>
416 <indexterm><primary>ld options</primary></indexterm>
419 <para>GHC has to link your code with various libraries, possibly
420 including: user-supplied, GHC-supplied, and system-supplied
421 (<option>-lm</option> math library, for example).</para>
426 <term><option>-l</option><replaceable>lib</replaceable></term>
427 <indexterm><primary><option>-l</option></primary></indexterm>
429 <para>Link in the <replaceable>lib</replaceable> library.
430 On Unix systems, this will be in a file called
431 <filename>lib<replaceable>lib</replaceable>.a</filename>
433 <filename>lib<replaceable>lib</replaceable>.so</filename>
434 which resides somewhere on the library directories path.</para>
436 <para>Because of the sad state of most UNIX linkers, the
437 order of such options does matter. If library
438 <replaceable>foo</replaceable> requires library
439 <replaceable>bar</replaceable>, then in general
440 <option>-l</option><replaceable>foo</replaceable> should
441 come <emphasis>before</emphasis>
442 <option>-l</option><replaceable>bar</replaceable> on the
445 <para>There's one other gotcha to bear in mind when using
446 external libraries: if the library contains a
447 <literal>main()</literal> function, then this will be
448 linked in preference to GHC's own
449 <literal>main()</literal> function
450 (eg. <literal>libf2c</literal> and <literal>libl</literal>
451 have their own <literal>main()</literal>s). This is
452 because GHC's <literal>main()</literal> comes from the
453 <literal>HSrts</literal> library, which is normally
454 included <emphasis>after</emphasis> all the other
455 libraries on the linker's command line. To force GHC's
456 <literal>main()</literal> to be used in preference to any
457 other <literal>main()</literal>s from external libraries,
458 just add the option <option>-lHSrts</option> before any
459 other libraries on the command line.</para>
464 <term><option>-no-link</option></term>
466 <primary><option>-no-link</option></primary>
469 <para>Omit the link step. This flag can be useful if you
470 want to avoid linking in <option>--make</option> mode,
471 where linking is normally done automatically if the program
472 contains a <literal>Main</literal> module.</para>
477 <term><option>-package</option> <replaceable>name</replaceable></term>
478 <indexterm><primary><option>-package</option></primary></indexterm>
480 <para>If you are using a Haskell “package”
481 (see <xref linkend="packages">), don't forget to add the
482 relevant <option>-package</option> option when linking the
483 program too: it will cause the appropriate libraries to be
484 linked in with the program. Forgetting the
485 <option>-package</option> option will likely result in
486 several pages of link errors.</para>
491 <term><option>-framework</option> <replaceable>name</replaceable></term>
492 <indexterm><primary><option>-framework</option></primary></indexterm>
494 <para>On Darwin/MacOS X only, link in the framework <replaceable>name</replaceable>.
495 This option corresponds to the <option>-framework</option> option for Apple's Linker.
496 Please note that frameworks and packages are two different things - frameworks don't
497 contain any haskell code. Rather, they are Apple's way of packaging shared libraries.
498 To link to Apple's “Carbon” API, for example, you'd use
499 <option>-framework Carbon</option>.
505 <term><option>-L</option><replaceable>dir</replaceable></term>
506 <indexterm><primary><option>-L</option></primary></indexterm>
508 <para>Where to find user-supplied libraries…
509 Prepend the directory <replaceable>dir</replaceable> to
510 the library directories path.</para>
515 <term><option>-framework-path</option><replaceable>dir</replaceable></term>
516 <indexterm><primary><option>-framework-path</option></primary></indexterm>
518 <para>On Darwin/MacOS X only, prepend the directory <replaceable>dir</replaceable> to
519 the framework directories path. This option corresponds to the <option>-F</option>
520 option for Apple's Linker (<option>-F</option> already means something else for GHC).</para>
525 <term><option>-split-objs</option></term>
526 <indexterm><primary><option>-split-objs</option></primary></indexterm>
528 <para>Tell the linker to split the single object file that
529 would normally be generated into multiple object files,
530 one per top-level Haskell function or type in the module.
531 We use this feature for building GHC's libraries libraries
532 (warning: don't use it unless you know what you're
538 <term><option>-static</option></term>
539 <indexterm><primary><option>-static</option></primary></indexterm>
541 <para>Tell the linker to avoid shared Haskell libraries,
542 if possible. This is the default.</para>
547 <term><option>-dynamic</option></term>
548 <indexterm><primary><option>-dynamic</option></primary></indexterm>
550 <para>Tell the linker to use shared Haskell libraries, if
551 available (this option is only supported on Windows at the
552 moment, and also note that your distribution of GHC may
553 not have been supplied with shared libraries).</para>
558 <term><option>-main-is <replaceable>thing</replaceable></option></term>
559 <indexterm><primary><option>-main-is</option></primary></indexterm>
560 <indexterm><primary>specifying your own main function</primary></indexterm>
562 <para> The normal rule in Haskell is that your program must supply a <literal>main</literal>
563 function in module <literal>Main</literal>. When testing, it is often convenient
564 to change which function is the "main" one, and the <option>-main-is</option> flag
565 allows you to do so. The <replaceable>thing</replaceable> can be one of:
567 <listitem><para>A lower-case identifier <literal>foo</literal>. GHC assumes that the main function is <literal>Main.foo</literal>.</para></listitem>
568 <listitem><para>An module name <literal>A</literal>. GHC assumes that the main function is <literal>A.main</literal>.</para></listitem>
569 <listitem><para>An qualified name <literal>A.foo</literal>. GHC assumes that the main function is <literal>A.foo</literal>.</para></listitem>
571 Strictly speaking, <option>-main-is</option> is not a link-phase flag at all; it has no effect on the link step.
572 The flag must be specified when compiling the module containing the specified main function (e.g. module <literal>A</literal>
573 in the latter two items above. It has no effect for other modules (and hence can safely be given to <literal>ghc --make</literal>).
579 <term><option>-no-hs-main</option></term>
580 <indexterm><primary><option>-no-hs-main</option></primary></indexterm>
581 <indexterm><primary>linking Haskell libraries with foreign code</primary></indexterm>
583 <para>In the event you want to include ghc-compiled code
584 as part of another (non-Haskell) program, the RTS will not
585 be supplying its definition of <function>main()</function>
586 at link-time, you will have to. To signal that to the
587 compiler when linking, use
588 <option>-no-hs-main</option>. See also <xref linkend="using-own-main">.</para>
590 <para>Notice that since the command-line passed to the
591 linker is rather involved, you probably want to use
592 <command>ghc</command> to do the final link of your
593 `mixed-language' application. This is not a requirement
594 though, just try linking once with <option>-v</option> on
595 to see what options the driver passes through to the
598 <para>The <option>-no-hs-main</option> flag can also be
599 used to persuade the compiler to do the link step in
600 <option>--make</option> mode when there is no Haskell
601 <literal>Main</literal> module present (normally the
602 compiler will not attempt linking when there is no
603 <literal>Main</literal>).</para>
612 ;;; Local Variables: ***
614 ;;; sgml-parent-document: ("users_guide.sgml" "book" "chapter") ***