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>__HBC__</constant>
151 for Chalmers.)</para>
153 <para>NB. This macro is set when pre-processing both
154 Haskell source and C source, including the C source
155 generated from a Haskell module
156 (i.e. <filename>.hs</filename>, <filename>.lhs</filename>,
157 <filename>.c</filename> and <filename>.hc</filename>
163 <term><constant>__CONCURRENT_HASKELL__</constant></term>
164 <indexterm><primary><constant>__CONCURRENT_HASKELL__</constant></primary></indexterm>
166 <para>This symbol is defined when pre-processing Haskell
167 (input) and pre-processing C (GHC output). Since GHC from
168 verion 4.00 now supports concurrent haskell by default,
169 this symbol is always defined.</para>
174 <term><constant>__PARALLEL_HASKELL__</constant></term>
175 <indexterm><primary><constant>__PARALLEL_HASKELL__</constant></primary></indexterm>
177 <para>Only defined when <option>-parallel</option> is in
178 use! This symbol is defined when pre-processing Haskell
179 (input) and pre-processing C (GHC output).</para>
184 <para>A small word of warning: <option>-cpp</option> is not
185 friendly to “string gaps”.<indexterm><primary>-cpp
186 vs string gaps</primary></indexterm><indexterm><primary>string
187 gaps vs -cpp</primary></indexterm>. In other words, strings
188 such as the following:</para>
196 <para>don't work with <option>-cpp</option>;
197 <filename>/usr/bin/cpp</filename> elides the backslash-newline
200 <para>However, it appears that if you add a space at the end of
201 the line, then <command>cpp</command> (at least GNU
202 <command>cpp</command> and possibly other
203 <command>cpp</command>s) leaves the backslash-space pairs alone
204 and the string gap works as expected.</para>
207 <sect2 id="options-C-compiler">
208 <title>Options affecting the C compiler (if applicable)</title>
210 <indexterm><primary>include-file options</primary></indexterm>
211 <indexterm><primary>C compiler options</primary></indexterm>
212 <indexterm><primary>GCC options</primary></indexterm>
214 <para>If you are compiling with lots of foreign calls, you may
215 need to tell the C compiler about some
216 <literal>#include</literal> files. There is no real pretty
217 way to do this, but you can use this hack from the
221 % ghc -c '-#include <X/Xlib.h>' Xstuff.lhs
226 <sect2 id="options-codegen">
227 <title>Options affecting code generation</title>
231 <term><option>-fasm</option></term>
232 <indexterm><primary><option>-fasm</option></primary></indexterm>
234 <para>Use GHC's native code generator rather than
235 compiling via C. This will compile faster (up to twice as
236 fast), but may produce code that is slightly slower than
237 compiling via C. <option>-fasm</option> is the default
238 when optimisation is off (see <xref
239 linkend="options-optimise">).</para>
244 <term><option>-fvia-C</option></term>
245 <indexterm><primary><option>-fvia-C</option></primary>
248 <para>Compile via C instead of using the native code
249 generator. This is default for optimised compilations,
250 and on architectures for which GHC doesn't have a native
251 code generator.</para>
257 <sect2 id="options-linker">
258 <title>Options affecting linking</title>
260 <indexterm><primary>linker options</primary></indexterm>
261 <indexterm><primary>ld options</primary></indexterm>
264 <para>GHC has to link your code with various libraries, possibly
265 including: user-supplied, GHC-supplied, and system-supplied
266 (<option>-lm</option> math library, for example).</para>
271 <term><option>-l</option><replaceable>lib</replaceable></term>
272 <indexterm><primary><option>-l</option></primary></indexterm>
274 <para>Link in the <replaceable>lib</replaceable> library.
275 On Unix systems, this will be in a file called
276 <filename>lib<replaceable>lib</replaceable>.a</filename>
278 <filename>lib<replaceable>lib</replaceable>.so</filename>
279 which resides somewhere on the library directories path.</para>
281 <para>Because of the sad state of most UNIX linkers, the
282 order of such options does matter. If library
283 <replaceable>foo</replaceable> requires library
284 <replaceable>bar</replaceable>, then in general
285 <option>-l</option><replaceable>foo</replaceable> should
286 come <emphasis>before</emphasis>
287 <option>-l</option><replaceable>bar</replaceable> on the
293 <term><option>-package</option> <replaceable>name</replaceable></term>
294 <indexterm><primary><option>-package</option></primary></indexterm>
296 <para>If you are using a Haskell “package”
297 (see <xref linkend="packages">), don't forget to add the
298 relevant <option>-package</option> option when linking the
299 program too: it will cause the appropriate libraries to be
300 linked in with the program. Forgetting the
301 <option>-package</option> option will likely result in
302 several pages of link errors.</para>
307 <term><option>-L</option><replaceable>dir</replaceable></term>
308 <indexterm><primary><option>-L</option></primary></indexterm>
310 <para>Where to find user-supplied libraries…
311 Prepend the directory <replaceable>dir</replaceable> to
312 the library directories path.</para>
317 <term><option>-split-objs</option></term>
318 <indexterm><primary><option>-split-objs</option></primary></indexterm>
320 <para>Tell the linker to split the single object file that
321 would normally be generated into multiple object files,
322 one per top-level Haskell function or type in the module.
323 We use this feature for building GHC's libraries libraries
324 (warning: don't use it unless you know what you're
330 <term><option>-static</option></term>
331 <indexterm><primary><option>-static</option></primary></indexterm>
333 <para>Tell the linker to avoid shared Haskell libraries,
334 if possible. This is the default.</para>
339 <term><option>-dynamic</option></term>
340 <indexterm><primary><option>-dynamic</option></primary></indexterm>
342 <para>Tell the linker to use shared Haskell libraries, if
343 available (this option is only supported on Windows at the
344 moment, and also note that your distribution of GHC may
345 not have been supplied with shared libraries).</para>
350 <term><option>-no-hs-main</option></term>
351 <indexterm><primary><option>-no-hs-main</option></primary></indexterm>
352 <indexterm><primary>linking Haskell libraries with foreign code</primary></indexterm>
354 <para>In the event you want to include ghc-compiled code
355 as part of another (non-Haskell) program, the RTS will not
356 be supplying its definition of <function>main()</function>
357 at link-time, you will have to. To signal that to the
358 driver script when linking, use
359 <option>-no-hs-main</option>.</para>
361 <para>Notice that since the command-line passed to the
362 linker is rather involved, you probably want to use
363 <command>ghc</command> to do the final link of your
364 `mixed-language' application. This is not a requirement
365 though, just try linking once with <option>-v</option> on
366 to see what options the driver passes through to the
376 ;;; Local Variables: ***
378 ;;; sgml-parent-document: ("users_guide.sgml" "book" "chapter") ***