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>
259 <sect2 id="options-linker">
260 <title>Options affecting linking</title>
262 <indexterm><primary>linker options</primary></indexterm>
263 <indexterm><primary>ld options</primary></indexterm>
266 <para>GHC has to link your code with various libraries, possibly
267 including: user-supplied, GHC-supplied, and system-supplied
268 (<option>-lm</option> math library, for example).</para>
273 <term><option>-l</option><replaceable>lib</replaceable></term>
274 <indexterm><primary><option>-l</option></primary></indexterm>
276 <para>Link in the <replaceable>lib</replaceable> library.
277 On Unix systems, this will be in a file called
278 <filename>lib<replaceable>lib</replaceable>.a</filename>
280 <filename>lib<replaceable>lib</replaceable>.so</filename>
281 which resides somewhere on the library directories path.</para>
283 <para>Because of the sad state of most UNIX linkers, the
284 order of such options does matter. If library
285 <replaceable>foo</replaceable> requires library
286 <replaceable>bar</replaceable>, then in general
287 <option>-l</option><replaceable>foo</replaceable> should
288 come <emphasis>before</emphasis>
289 <option>-l</option><replaceable>bar</replaceable> on the
295 <term><option>-package</option> <replaceable>name</replaceable></term>
296 <indexterm><primary><option>-package</option></primary></indexterm>
298 <para>If you are using a Haskell “package”
299 (see <xref linkend="packages">), don't forget to add the
300 relevant <option>-package</option> option when linking the
301 program too: it will cause the appropriate libraries to be
302 linked in with the program. Forgetting the
303 <option>-package</option> option will likely result in
304 several pages of link errors.</para>
309 <term><option>-L</option><replaceable>dir</replaceable></term>
310 <indexterm><primary><option>-L</option></primary></indexterm>
312 <para>Where to find user-supplied libraries…
313 Prepend the directory <replaceable>dir</replaceable> to
314 the library directories path.</para>
319 <term><option>-split-objs</option></term>
320 <indexterm><primary><option>-split-objs</option></primary></indexterm>
322 <para>Tell the linker to split the single object file that
323 would normally be generated into multiple object files,
324 one per top-level Haskell function or type in the module.
325 We use this feature for building GHC's libraries libraries
326 (warning: don't use it unless you know what you're
332 <term><option>-static</option></term>
333 <indexterm><primary><option>-static</option></primary></indexterm>
335 <para>Tell the linker to avoid shared Haskell libraries,
336 if possible. This is the default.</para>
341 <term><option>-dynamic</option></term>
342 <indexterm><primary><option>-dynamic</option></primary></indexterm>
344 <para>Tell the linker to use shared Haskell libraries, if
345 available (this option is only supported on Windows at the
346 moment, and also note that your distribution of GHC may
347 not have been supplied with shared libraries).</para>
352 <term><option>-no-hs-main</option></term>
353 <indexterm><primary><option>-no-hs-main</option></primary></indexterm>
354 <indexterm><primary>linking Haskell libraries with foreign code</primary></indexterm>
356 <para>In the event you want to include ghc-compiled code
357 as part of another (non-Haskell) program, the RTS will not
358 be supplying its definition of <function>main()</function>
359 at link-time, you will have to. To signal that to the
360 driver script when linking, use
361 <option>-no-hs-main</option>.</para>
363 <para>Notice that since the command-line passed to the
364 linker is rather involved, you probably want to use
365 <command>ghc</command> to do the final link of your
366 `mixed-language' application. This is not a requirement
367 though, just try linking once with <option>-v</option> on
368 to see what options the driver passes through to the
378 ;;; Local Variables: ***
380 ;;; sgml-parent-document: ("users_guide.sgml" "book" "chapter") ***