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 phases:</para>
17 <sect2 id="forcing-options-through">
18 <title>Forcing options to a particular phase.</title>
19 <indexterm><primary>forcing GHC-phase options</primary></indexterm>
21 <para>Options can be forced through to a particlar compilation
22 phase, using the following flags:</para>
25 <para>So, for example, to force an <option>-Ewurble</option>
26 option to the assembler, you would tell the driver
27 <option>-opta-Ewurble</option> (the dash before the E is
30 <para>GHC is itself a Haskell program, so if you need to pass
31 options directly to GHC's runtime system you can enclose them in
32 <literal>+RTS ... -RTS</literal> (see <xref
33 linkend="runtime-control">).</para>
37 <sect2 id="c-pre-processor">
38 <title>Options affecting the C pre-processor</title>
40 <indexterm><primary>pre-processing: cpp</primary></indexterm>
41 <indexterm><primary>C pre-processor options</primary></indexterm>
42 <indexterm><primary>cpp, pre-processing with</primary></indexterm>
47 <term><option>-cpp</option></term>
48 <indexterm><primary><option>-cpp</option></primary></indexterm>
50 <para>The C pre-processor <command>cpp</command> is run
51 over your Haskell code only if the <option>-cpp</option>
52 option <indexterm><primary>-cpp
53 option</primary></indexterm> is given. Unless you are
54 building a large system with significant doses of
55 conditional compilation, you really shouldn't need
61 <term><option>-D</option><replaceable>symbol</replaceable><optional>=<replaceable>value</replaceable></optional></term>
62 <indexterm><primary><option>-D</option></primary></indexterm>
64 <para>Define macro <replaceable>symbol</replaceable> in the
65 usual way. NB: does <emphasis>not</emphasis> affect
66 <option>-D</option> macros passed to the C compiler
67 when compiling via C! For those, use the
68 <option>-optc-Dfoo</option> hack… (see <xref
69 linkend="forcing-options-through">).</para>
74 <term><option>-U</option><replaceable>symbol</replaceable></term>
75 <indexterm><primary><option>-U</option></primary></indexterm>
77 <para> Undefine macro <replaceable>symbol</replaceable> in the
83 <term><option>-I</option><replaceable>dir</replaceable></term>
84 <indexterm><primary><option>-I</option></primary></indexterm>
86 <para> Specify a directory in which to look for
87 <literal>#include</literal> files, in the usual C
93 <para>The GHC driver pre-defines several macros when processing
94 Haskell source code (<filename>.hs</filename> or
95 <filename>.lhs</filename> files):</para>
100 <term><constant>__HASKELL98__</constant></term>
101 <indexterm><primary><literal>__HASKELL98__</literal></primary></indexterm>
103 <para>If defined, this means that GHC supports the
104 language defined by the Haskell 98 report.</para>
109 <term><constant>__HASKELL__=98</constant></term>
110 <indexterm><primary><constant>__HASKELL__=98</constant></primary></indexterm>
112 <para>In GHC 4.04 and later, the
113 <constant>__HASKELL__</constant>
114 macro is defined as having the value
115 <constant>98</constant>.</para>
120 <term><constant>__HASKELL1__</constant></term>
121 <indexterm><primary><constant>__HASKELL1__
122 </constant></primary></indexterm>
124 <para>If defined to <replaceable>n</replaceable>, that
125 means GHC supports the Haskell language defined in the
126 Haskell report version <emphasis>1.n</emphasis>.
127 Currently 5. This macro is deprecated, and will probably
128 disappear in future versions.</para>
133 <term><constant>__GLASGOW_HASKELL__</constant></term>
134 <indexterm><primary><constant>__GLASGOW_HASKELL__</constant></primary></indexterm>
136 <para>For version <replaceable>n</replaceable> of the GHC
137 system, this will be <literal>#define</literal>d to
138 <replaceable>100n</replaceable>. For example, for version
139 5.00, it is 500.</para>
142 <constant>__GLASGOW_HASKELL__</constant>
143 will be undefined in all other implementations that
144 support C-style pre-processing.</para>
146 <para>(For reference: the comparable symbols for other
148 <constant>__HUGS__</constant>
150 <constant>__NHC__</constant>
152 <constant>__HBC__</constant>
153 for Chalmers.)</para>
155 <para>NB. This macro is set when pre-processing both
156 Haskell source and C source, including the C source
157 generated from a Haskell module
158 (i.e. <filename>.hs</filename>, <filename>.lhs</filename>,
159 <filename>.c</filename> and <filename>.hc</filename>
165 <term><constant>__CONCURRENT_HASKELL__</constant></term>
166 <indexterm><primary><constant>__CONCURRENT_HASKELL__</constant></primary></indexterm>
168 <para>This symbol is defined when pre-processing Haskell
169 (input) and pre-processing C (GHC output). Since GHC from
170 verion 4.00 now supports concurrent haskell by default,
171 this symbol is always defined.</para>
176 <term><constant>__PARALLEL_HASKELL__</constant></term>
177 <indexterm><primary><constant>__PARALLEL_HASKELL__</constant></primary></indexterm>
179 <para>Only defined when <option>-parallel</option> is in
180 use! This symbol is defined when pre-processing Haskell
181 (input) and pre-processing C (GHC output).</para>
186 <para>A small word of warning: <option>-cpp</option> is not
187 friendly to “string gaps”.<indexterm><primary>-cpp
188 vs string gaps</primary></indexterm><indexterm><primary>string
189 gaps vs -cpp</primary></indexterm>. In other words, strings
190 such as the following:</para>
198 <para>don't work with <option>-cpp</option>;
199 <filename>/usr/bin/cpp</filename> elides the backslash-newline
202 <para>However, it appears that if you add a space at the end of
203 the line, then <command>cpp</command> (at least GNU
204 <command>cpp</command> and possibly other
205 <command>cpp</command>s) leaves the backslash-space pairs alone
206 and the string gap works as expected.</para>
209 <sect2 id="options-C-compiler">
210 <title>Options affecting the C compiler (if applicable)</title>
212 <indexterm><primary>include-file options</primary></indexterm>
213 <indexterm><primary>C compiler options</primary></indexterm>
214 <indexterm><primary>GCC options</primary></indexterm>
216 <para>If you are compiling with lots of foreign calls, you may
217 need to tell the C compiler about some
218 <literal>#include</literal> files. There is no real pretty
219 way to do this, but you can use this hack from the
223 % ghc -c '-#include <X/Xlib.h>' Xstuff.lhs
228 <sect2 id="options-codegen">
229 <title>Options affecting code generation</title>
233 <term><option>-fasm</option></term>
234 <indexterm><primary><option>-fasm</option></primary></indexterm>
236 <para>Use GHC's native code generator rather than
237 compiling via C. This will compile faster (up to twice as
238 fast), but may produce code that is slightly slower than
239 compiling via C. <option>-fasm</option> is the default
240 when optimisation is off (see <xref
241 linkend="options-optimise">).</para>
246 <term><option>-fvia-C</option></term>
247 <indexterm><primary><option>-fvia-C</option></primary>
250 <para>Compile via C instead of using the native code
251 generator. This is default for optimised compilations,
252 and on architectures for which GHC doesn't have a native
253 code generator.</para>
258 <term><option>-fno-code</option></term>
259 <indexterm><primary><option>-fno-code</option></primary>
262 <para>Omit code generation (and all later phases)
263 altogether. Might be of some use if you just want to see
264 dumps of the intermediate compilation phases.</para>
270 <sect2 id="options-linker">
271 <title>Options affecting linking</title>
273 <indexterm><primary>linker options</primary></indexterm>
274 <indexterm><primary>ld options</primary></indexterm>
277 <para>GHC has to link your code with various libraries, possibly
278 including: user-supplied, GHC-supplied, and system-supplied
279 (<option>-lm</option> math library, for example).</para>
284 <term><option>-l</option><replaceable>lib</replaceable></term>
285 <indexterm><primary><option>-l</option></primary></indexterm>
287 <para>Link in the <replaceable>lib</replaceable> library.
288 On Unix systems, this will be in a file called
289 <filename>lib<replaceable>lib</replaceable>.a</filename>
291 <filename>lib<replaceable>lib</replaceable>.so</filename>
292 which resides somewhere on the library directories path.</para>
294 <para>Because of the sad state of most UNIX linkers, the
295 order of such options does matter. If library
296 <replaceable>foo</replaceable> requires library
297 <replaceable>bar</replaceable>, then in general
298 <option>-l</option><replaceable>foo</replaceable> should
299 come <emphasis>before</emphasis>
300 <option>-l</option><replaceable>bar</replaceable> on the
306 <term><option>-package</option> <replaceable>name</replaceable></term>
307 <indexterm><primary><option>-package</option></primary></indexterm>
309 <para>If you are using a Haskell “package”
310 (see <xref linkend="packages">), don't forget to add the
311 relevant <option>-package</option> option when linking the
312 program too: it will cause the appropriate libraries to be
313 linked in with the program. Forgetting the
314 <option>-package</option> option will likely result in
315 several pages of link errors.</para>
320 <term><option>-L</option><replaceable>dir</replaceable></term>
321 <indexterm><primary><option>-L</option></primary></indexterm>
323 <para>Where to find user-supplied libraries…
324 Prepend the directory <replaceable>dir</replaceable> to
325 the library directories path.</para>
330 <term><option>-split-objs</option></term>
331 <indexterm><primary><option>-split-objs</option></primary></indexterm>
333 <para>Tell the linker to split the single object file that
334 would normally be generated into multiple object files,
335 one per top-level Haskell function or type in the module.
336 We use this feature for building GHC's libraries libraries
337 (warning: don't use it unless you know what you're
343 <term><option>-static</option></term>
344 <indexterm><primary><option>-static</option></primary></indexterm>
346 <para>Tell the linker to avoid shared Haskell libraries,
347 if possible. This is the default.</para>
352 <term><option>-dynamic</option></term>
353 <indexterm><primary><option>-dynamic</option></primary></indexterm>
355 <para>Tell the linker to use shared Haskell libraries, if
356 available (this option is only supported on Windows at the
357 moment, and also note that your distribution of GHC may
358 not have been supplied with shared libraries).</para>
363 <term><option>-no-hs-main</option></term>
364 <indexterm><primary><option>-no-hs-main</option></primary></indexterm>
365 <indexterm><primary>linking Haskell libraries with foreign code</primary></indexterm>
367 <para>In the event you want to include ghc-compiled code
368 as part of another (non-Haskell) program, the RTS will not
369 be supplying its definition of <function>main()</function>
370 at link-time, you will have to. To signal that to the
371 driver script when linking, use
372 <option>-no-hs-main</option>.</para>
374 <para>Notice that since the command-line passed to the
375 linker is rather involved, you probably want to use
376 <command>ghc</command> to do the final link of your
377 `mixed-language' application. This is not a requirement
378 though, just try linking once with <option>-v</option> on
379 to see what options the driver passes through to the
389 ;;; Local Variables: ***
391 ;;; sgml-parent-document: ("users_guide.sgml" "book" "chapter") ***