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>
44 <para>The C pre-processor <command>cpp</command> is run over
45 your Haskell code only if the <option>-cpp</option> option
46 <indexterm><primary>-cpp option</primary></indexterm> is given.
47 Unless you are building a large system with significant doses of
48 conditional compilation, you really shouldn't need it.</para>
53 <term><option>-D</option><replaceable>symbol</replaceable><optional>=<replaceable>value</replaceable></optional></term>
54 <indexterm><primary><option>-D</option></primary></indexterm>
56 <para>Define macro <replaceable>symbol</replaceable> in the
57 usual way. NB: does <emphasis>not</emphasis> affect
58 <option>-D</option> macros passed to the C compiler
59 when compiling via C! For those, use the
60 <option>-optc-Dfoo</option> hack… (see <xref
61 linkend="forcing-options-through">).</para>
66 <term><option>-U</option><replaceable>symbol</replaceable></term>
67 <indexterm><primary><option>-U</option></primary></indexterm>
69 <para> Undefine macro <replaceable>symbol</replaceable> in the
75 <term><option>-I</option><replaceable>dir</replaceable></term>
76 <indexterm><primary><option>-I</option></primary></indexterm>
78 <para> Specify a directory in which to look for
79 <literal>#include</literal> files, in the usual C
85 <para>The GHC driver pre-defines several macros when processing
86 Haskell source code (<filename>.hs</filename> or
87 <filename>.lhs</filename> files):</para>
92 <term><constant>__HASKELL98__</constant></term>
93 <indexterm><primary><literal>__HASKELL98__</literal></primary></indexterm>
95 <para>If defined, this means that GHC supports the
96 language defined by the Haskell 98 report.</para>
101 <term><constant>__HASKELL__=98</constant></term>
102 <indexterm><primary><constant>__HASKELL__=98</constant></primary></indexterm>
104 <para>In GHC 4.04 and later, the
105 <constant>__HASKELL__</constant>
106 macro is defined as having the value
107 <constant>98</constant>.</para>
112 <term><constant>__HASKELL1__</constant></term>
113 <indexterm><primary><constant>__HASKELL1__
114 </constant></primary></indexterm>
116 <para>If defined to <replaceable>n</replaceable>, that
117 means GHC supports the Haskell language defined in the
118 Haskell report version <emphasis>1.n</emphasis>.
119 Currently 5. This macro is deprecated, and will probably
120 disappear in future versions.</para>
125 <term><constant>__GLASGOW_HASKELL__</constant></term>
126 <indexterm><primary><constant>__GLASGOW_HASKELL__</constant></primary></indexterm>
128 <para>For version <replaceable>n</replaceable> of the GHC
129 system, this will be <literal>#define</literal>d to
130 <replaceable>100n</replaceable>. For example, for version
131 5.00, it is 500.</para>
134 <constant>__GLASGOW_HASKELL__</constant>
135 will be undefined in all other implementations that
136 support C-style pre-processing.</para>
138 <para>(For reference: the comparable symbols for other
140 <constant>__HUGS__</constant>
142 <constant>__HBC__</constant>
143 for Chalmers.)</para>
145 <para>NB. This macro is set when pre-processing both
146 Haskell source and C source, including the C source
147 generated from a Haskell module
148 (i.e. <filename>.hs</filename>, <filename>.lhs</filename>,
149 <filename>.c</filename> and <filename>.hc</filename>
155 <term><constant>__CONCURRENT_HASKELL__</constant></term>
156 <indexterm><primary><constant>__CONCURRENT_HASKELL__</constant></primary></indexterm>
158 <para>This symbol is defined when pre-processing Haskell
159 (input) and pre-processing C (GHC output). Since GHC from
160 verion 4.00 now supports concurrent haskell by default,
161 this symbol is always defined.</para>
166 <term><constant>__PARALLEL_HASKELL__</constant></term>
167 <indexterm><primary><constant>__PARALLEL_HASKELL__</constant></primary></indexterm>
169 <para>Only defined when <option>-parallel</option> is in
170 use! This symbol is defined when pre-processing Haskell
171 (input) and pre-processing C (GHC output).</para>
176 <para>A small word of warning: <option>-cpp</option> is not
177 friendly to “string gaps”.<indexterm><primary>-cpp
178 vs string gaps</primary></indexterm><indexterm><primary>string
179 gaps vs -cpp</primary></indexterm>. In other words, strings
180 such as the following:</para>
188 <para>don't work with <option>-cpp</option>;
189 <filename>/usr/bin/cpp</filename> elides the backslash-newline
192 <para>However, it appears that if you add a space at the end of
193 the line, then <command>cpp</command> (at least GNU
194 <command>cpp</command> and possibly other
195 <command>cpp</command>s) leaves the backslash-space pairs alone
196 and the string gap works as expected.</para>
199 <sect2 id="options-C-compiler">
200 <title>Options affecting the C compiler (if applicable)</title>
202 <indexterm><primary>include-file options</primary></indexterm>
203 <indexterm><primary>C compiler options</primary></indexterm>
204 <indexterm><primary>GCC options</primary></indexterm>
207 <tgroup cols=3 align=left colsep=1 rowsep=1>
211 <entry>Description</entry>
212 <entry>Static/Dynamic</entry>
213 <entry>Reverse</entry>
218 <entry><option>-#include</option> <replaceable>file</replaceable></entry>
219 <entry>Include <replaceable>file</replaceable> when
220 compiling the <filename>.hc</filename> file</entry>
221 <entry>dynamic</entry>
228 <para>If you are compiling with lots of foreign calls, you may
229 need to tell the C compiler about some
230 <literal>#include</literal> files. There is no real pretty
231 way to do this, but you can use this hack from the
235 % ghc -c '-#include <X/Xlib.h>' Xstuff.lhs
240 <sect2 id="options-linker">
241 <title>Options affecting linking</title>
243 <indexterm><primary>linker options</primary></indexterm>
244 <indexterm><primary>ld options</primary></indexterm>
247 <para>GHC has to link your code with various libraries, possibly
248 including: user-supplied, GHC-supplied, and system-supplied
249 (<option>-lm</option> math library, for example).</para>
254 <term><option>-l</option><replaceable>lib</replaceable></term>
255 <indexterm><primary><option>-l</option></primary></indexterm>
257 <para>Link in the <replaceable>lib</replaceable> library.
258 On Unix systems, this will be in a file called
259 <filename>lib<replaceable>lib</replaceable>.a</filename>
261 <filename>lib<replaceable>lib</replaceable>.so</filename>
262 which resides somewhere on the library directories path.</para>
264 <para>Because of the sad state of most UNIX linkers, the
265 order of such options does matter. If library
266 <replaceable>foo</replaceable> requires library
267 <replaceable>bar</replaceable>, then in general
268 <option>-l</option><replaceable>foo</replaceable> should
269 come <emphasis>before</emphasis>
270 <option>-l</option><replaceable>bar</replaceable> on the
276 <term><option>-package</option> <replaceable>name</replaceable></term>
277 <indexterm><primary><option>-package</option></primary></indexterm>
279 <para>If you are using a Haskell “package”
280 (see <xref linkend="packages">), don't forget to add the
281 relevant <option>-package</option> option when linking the
282 program too: it will cause the appropriate libraries to be
283 linked in with the program. Forgetting the
284 <option>-package</option> option will likely result in
285 several pages of link errors.</para>
290 <term><option>-L</option><replaceable>dir</replaceable></term>
291 <indexterm><primary><option>-L</option></primary></indexterm>
293 <para>Where to find user-supplied libraries…
294 Prepend the directory <replaceable>dir</replaceable> to
295 the library directories path.</para>
300 <term><option>-split-objs</option></term>
301 <indexterm><primary><option>-split-objs</option></primary></indexterm>
303 <para>Tell the linker to split the single object file that
304 would normally be generated into multiple object files,
305 one per top-level Haskell function or type in the module.
306 We use this feature for building GHC's libraries libraries
307 (warning: don't use it unless you know what you're
313 <term><option>-static</option></term>
314 <indexterm><primary><option>-static</option></primary></indexterm>
316 <para>Tell the linker to avoid shared Haskell libraries,
317 if possible. This is the default.</para>
322 <term><option>-dynamic</option></term>
323 <indexterm><primary><option>-dynamic</option></primary></indexterm>
325 <para>Tell the linker to use shared Haskell libraries, if
326 available (this option is only supported on Windows at the
327 moment, and also note that your distribution of GHC may
328 not have been supplied with shared libraries).</para>
333 <term><option>-no-hs-main</option></term>
334 <indexterm><primary><option>-no-hs-main</option></primary></indexterm>
335 <indexterm><primary>linking Haskell libraries with foreign code</primary></indexterm>
337 <para>In the event you want to include ghc-compiled code
338 as part of another (non-Haskell) program, the RTS will not
339 be supplying its definition of <function>main()</function>
340 at link-time, you will have to. To signal that to the
341 driver script when linking, use
342 <option>-no-hs-main</option>.</para>
344 <para>Notice that since the command-line passed to the
345 linker is rather involved, you probably want to use
346 <command>ghc</command> to do the final link of your
347 `mixed-language' application. This is not a requirement
348 though, just try linking once with <option>-v</option> on
349 to see what options the driver passes through to the
359 ;;; Local Variables: ***
361 ;;; sgml-parent-document: ("users_guide.sgml" "book" "chapter") ***