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 <para>A small word of warning: <option>-cpp</option> is not
269 friendly to “string gaps”.<indexterm><primary>-cpp
270 vs string gaps</primary></indexterm><indexterm><primary>string
271 gaps vs -cpp</primary></indexterm>. In other words, strings
272 such as the following:</para>
280 <para>don't work with <option>-cpp</option>;
281 <filename>/usr/bin/cpp</filename> elides the backslash-newline
284 <para>However, it appears that if you add a space at the end of
285 the line, then <command>cpp</command> (at least GNU
286 <command>cpp</command> and possibly other
287 <command>cpp</command>s) leaves the backslash-space pairs alone
288 and the string gap works as expected.</para>
291 <sect2 id="pre-processor">
292 <title>Options affecting a Haskell pre-processor</title>
294 <indexterm><primary>pre-processing: custom</primary></indexterm>
295 <indexterm><primary>Pre-processor options</primary></indexterm>
299 <term><option>-F</option></term>
300 <indexterm><primary><option>-F</option></primary></indexterm>
302 <para>A custom pre-processor is run over your Haskell
303 source file only if the <option>-F</option> option
304 <indexterm><primary>-F</primary></indexterm> is given.
307 Running a custom pre-processor at compile-time is in some
308 settings appropriate and useful. The <option>-F</option>
309 option lets you run a pre-processor as part of the overall
310 GHC compilation pipeline, which has the advantage over
311 running a Haskell pre-processor separately in that it
312 works in interpreted mode and you can continue to take
313 reap the benefits of GHC's recompilation checker.
316 The pre-processor is run just before the Haskell
317 compiler proper processes the Haskell input, but after
318 the literate markup has been stripped away and (possibly)
319 the C pre-processor has washed the Haskell input.
324 <term><option>-pgmF</option> <replaceable>cmd</replaceable></term>
325 <indexterm><primary><option>-pgmF</option> <replaceable>cmd</replaceable></primary></indexterm>
327 <para>Use <replaceable>cmd</replaceable> as the Haskell
328 pre-processor. When invoked, the
329 <replaceable>cmd</replaceable> pre-processor is given at
330 least three arguments on its command-line: the first
331 argument is the name of the original source file, the second
332 is the name of the file holding the input, and the third is
333 the name of the file where
334 <replaceable>cmd</replaceable> should write its output to.
336 <para>Additional arguments to the
337 <replaceable>cmd</replaceable> pre-processor can be passed
338 in using the <option>-optF</option> option. These are fed to
339 <replaceable>cmd</replaceable> on the command line after the
340 three standard input and output arguments.
347 <sect2 id="options-C-compiler">
348 <title>Options affecting the C compiler (if applicable)</title>
350 <indexterm><primary>include-file options</primary></indexterm>
351 <indexterm><primary>C compiler options</primary></indexterm>
352 <indexterm><primary>GCC options</primary></indexterm>
354 <para>If you are compiling with lots of foreign calls, you may
355 need to tell the C compiler about some
356 <literal>#include</literal> files. There is no real pretty
357 way to do this, but you can use this hack from the
361 % ghc -c '-#include <X/Xlib.h>' Xstuff.lhs
366 <sect2 id="options-codegen">
367 <title>Options affecting code generation</title>
371 <term><option>-fasm</option></term>
372 <indexterm><primary><option>-fasm</option></primary></indexterm>
374 <para>Use GHC's native code generator rather than
375 compiling via C. This will compile faster (up to twice as
376 fast), but may produce code that is slightly slower than
377 compiling via C. <option>-fasm</option> is the default
378 when optimisation is off (see <xref
379 linkend="options-optimise">).</para>
384 <term><option>-fvia-C</option></term>
385 <indexterm><primary><option>-fvia-C</option></primary>
388 <para>Compile via C instead of using the native code
389 generator. This is default for optimised compilations,
390 and on architectures for which GHC doesn't have a native
391 code generator.</para>
396 <term><option>-fno-code</option></term>
397 <indexterm><primary><option>-fno-code</option></primary>
400 <para>Omit code generation (and all later phases)
401 altogether. Might be of some use if you just want to see
402 dumps of the intermediate compilation phases.</para>
408 <sect2 id="options-linker">
409 <title>Options affecting linking</title>
411 <indexterm><primary>linker options</primary></indexterm>
412 <indexterm><primary>ld options</primary></indexterm>
415 <para>GHC has to link your code with various libraries, possibly
416 including: user-supplied, GHC-supplied, and system-supplied
417 (<option>-lm</option> math library, for example).</para>
422 <term><option>-l</option><replaceable>lib</replaceable></term>
423 <indexterm><primary><option>-l</option></primary></indexterm>
425 <para>Link in the <replaceable>lib</replaceable> library.
426 On Unix systems, this will be in a file called
427 <filename>lib<replaceable>lib</replaceable>.a</filename>
429 <filename>lib<replaceable>lib</replaceable>.so</filename>
430 which resides somewhere on the library directories path.</para>
432 <para>Because of the sad state of most UNIX linkers, the
433 order of such options does matter. If library
434 <replaceable>foo</replaceable> requires library
435 <replaceable>bar</replaceable>, then in general
436 <option>-l</option><replaceable>foo</replaceable> should
437 come <emphasis>before</emphasis>
438 <option>-l</option><replaceable>bar</replaceable> on the
441 <para>There's one other gotcha to bear in mind when using
442 external libraries: if the library contains a
443 <literal>main()</literal> function, then this will be
444 linked in preference to GHC's own
445 <literal>main()</literal> function
446 (eg. <literal>libf2c</literal> and <literal>libl</literal>
447 have their own <literal>main()</literal>s). This is
448 because GHC's <literal>main()</literal> comes from the
449 <literal>HSrts</literal> library, which is normally
450 included <emphasis>after</emphasis> all the other
451 libraries on the linker's command line. To force GHC's
452 <literal>main()</literal> to be used in preference to any
453 other <literal>main()</literal>s from external libraries,
454 just add the option <option>-lHSrts</option> before any
455 other libraries on the command line.</para>
460 <term><option>-package</option> <replaceable>name</replaceable></term>
461 <indexterm><primary><option>-package</option></primary></indexterm>
463 <para>If you are using a Haskell “package”
464 (see <xref linkend="packages">), don't forget to add the
465 relevant <option>-package</option> option when linking the
466 program too: it will cause the appropriate libraries to be
467 linked in with the program. Forgetting the
468 <option>-package</option> option will likely result in
469 several pages of link errors.</para>
474 <term><option>-L</option><replaceable>dir</replaceable></term>
475 <indexterm><primary><option>-L</option></primary></indexterm>
477 <para>Where to find user-supplied libraries…
478 Prepend the directory <replaceable>dir</replaceable> to
479 the library directories path.</para>
484 <term><option>-split-objs</option></term>
485 <indexterm><primary><option>-split-objs</option></primary></indexterm>
487 <para>Tell the linker to split the single object file that
488 would normally be generated into multiple object files,
489 one per top-level Haskell function or type in the module.
490 We use this feature for building GHC's libraries libraries
491 (warning: don't use it unless you know what you're
497 <term><option>-static</option></term>
498 <indexterm><primary><option>-static</option></primary></indexterm>
500 <para>Tell the linker to avoid shared Haskell libraries,
501 if possible. This is the default.</para>
506 <term><option>-dynamic</option></term>
507 <indexterm><primary><option>-dynamic</option></primary></indexterm>
509 <para>Tell the linker to use shared Haskell libraries, if
510 available (this option is only supported on Windows at the
511 moment, and also note that your distribution of GHC may
512 not have been supplied with shared libraries).</para>
517 <term><option>-no-hs-main</option></term>
518 <indexterm><primary><option>-no-hs-main</option></primary></indexterm>
519 <indexterm><primary>linking Haskell libraries with foreign code</primary></indexterm>
521 <para>In the event you want to include ghc-compiled code
522 as part of another (non-Haskell) program, the RTS will not
523 be supplying its definition of <function>main()</function>
524 at link-time, you will have to. To signal that to the
525 driver script when linking, use
526 <option>-no-hs-main</option>.</para>
528 <para>Notice that since the command-line passed to the
529 linker is rather involved, you probably want to use
530 <command>ghc</command> to do the final link of your
531 `mixed-language' application. This is not a requirement
532 though, just try linking once with <option>-v</option> on
533 to see what options the driver passes through to the
543 ;;; Local Variables: ***
545 ;;; sgml-parent-document: ("users_guide.sgml" "book" "chapter") ***