90489e84d25a46df2036cf26f70266e7410f18b7
[ghc.git] / docs / users_guide / phases.xml
1 <?xml version="1.0" encoding="iso-8859-1"?>
2 <sect1 id="options-phases">
3 <title>Options related to a particular phase</title>
4
5 <sect2 id="replacing-phases">
6 <title>Replacing the program for one or more phases</title>
7 <indexterm><primary>phases, changing</primary></indexterm>
8
9 <para>You may specify that a different program be used for one
10 of the phases of the compilation system, in place of whatever
11 the <command>ghc</command> has wired into it. For example, you
12 might want to try a different assembler. The following options
13 allow you to change the external program used for a given
14 compilation phase:</para>
15
16 <variablelist>
17 <varlistentry>
18 <term>
19 <option>-pgmL</option> <replaceable>cmd</replaceable>
20 <indexterm><primary><option>-pgmL</option></primary></indexterm>
21 </term>
22 <listitem>
23 <para>Use <replaceable>cmd</replaceable> as the literate
24 pre-processor.</para>
25 </listitem>
26 </varlistentry>
27
28 <varlistentry>
29 <term>
30 <option>-pgmP</option> <replaceable>cmd</replaceable>
31 <indexterm><primary><option>-pgmP</option></primary></indexterm>
32 </term>
33 <listitem>
34 <para>Use <replaceable>cmd</replaceable> as the C
35 pre-processor (with <option>-cpp</option> only).</para>
36 </listitem>
37 </varlistentry>
38
39 <varlistentry>
40 <term>
41 <option>-pgmc</option> <replaceable>cmd</replaceable>
42 <indexterm><primary><option>-pgmc</option></primary></indexterm>
43 </term>
44 <listitem>
45 <para>Use <replaceable>cmd</replaceable> as the C
46 compiler.</para>
47 </listitem>
48 </varlistentry>
49
50 <varlistentry>
51 <term>
52 <option>-pgmlo</option> <replaceable>cmd</replaceable>
53 <indexterm><primary><option>-pgmlo</option></primary></indexterm>
54 </term>
55 <listitem>
56 <para>Use <replaceable>cmd</replaceable> as the LLVM
57 optimiser.</para>
58 </listitem>
59 </varlistentry>
60
61 <varlistentry>
62 <term>
63 <option>-pgmlc</option> <replaceable>cmd</replaceable>
64 <indexterm><primary><option>-pgmlc</option></primary></indexterm>
65 </term>
66 <listitem>
67 <para>Use <replaceable>cmd</replaceable> as the LLVM
68 compiler.</para>
69 </listitem>
70 </varlistentry>
71
72 <varlistentry>
73 <term>
74 <option>-pgms</option> <replaceable>cmd</replaceable>
75 <indexterm><primary><option>-pgms</option></primary></indexterm>
76 </term>
77 <listitem>
78 <para>Use <replaceable>cmd</replaceable> as the
79 splitter.</para>
80 </listitem>
81 </varlistentry>
82
83 <varlistentry>
84 <term>
85 <option>-pgma</option> <replaceable>cmd</replaceable>
86 <indexterm><primary><option>-pgma</option></primary></indexterm>
87 </term>
88 <listitem>
89 <para>Use <replaceable>cmd</replaceable> as the
90 assembler.</para>
91 </listitem>
92 </varlistentry>
93
94 <varlistentry>
95 <term>
96 <option>-pgml</option> <replaceable>cmd</replaceable>
97 <indexterm><primary><option>-pgml</option></primary></indexterm>
98 </term>
99 <listitem>
100 <para>Use <replaceable>cmd</replaceable> as the
101 linker.</para>
102 </listitem>
103 </varlistentry>
104
105 <varlistentry>
106 <term>
107 <option>-pgmdll</option> <replaceable>cmd</replaceable>
108 <indexterm><primary><option>-pgmdll</option></primary></indexterm>
109 </term>
110 <listitem>
111 <para>Use <replaceable>cmd</replaceable> as the DLL
112 generator.</para>
113 </listitem>
114 </varlistentry>
115
116 <varlistentry>
117 <term>
118 <option>-pgmF</option> <replaceable>cmd</replaceable>
119 <indexterm><primary><option>-pgmF</option></primary></indexterm>
120 </term>
121 <listitem>
122 <para>Use <replaceable>cmd</replaceable> as the
123 pre-processor (with <option>-F</option> only).</para>
124 </listitem>
125 </varlistentry>
126
127 <varlistentry>
128 <term>
129 <option>-pgmwindres</option> <replaceable>cmd</replaceable>
130 <indexterm><primary><option>-pgmwindres</option></primary></indexterm>
131 </term>
132 <listitem>
133 <para>Use <replaceable>cmd</replaceable> as the
134 program to use for embedding manifests on Windows. Normally this
135 is the program <literal>windres</literal>, which is supplied with a
136 GHC installation. See <option>-fno-embed-manifest</option> in <xref
137 linkend="options-linker" />.</para>
138 </listitem>
139 </varlistentry>
140 </variablelist>
141 </sect2>
142
143 <sect2 id="forcing-options-through">
144 <title>Forcing options to a particular phase</title>
145 <indexterm><primary>forcing GHC-phase options</primary></indexterm>
146
147 <para>Options can be forced through to a particular compilation
148 phase, using the following flags:</para>
149
150 <variablelist>
151 <varlistentry>
152 <term>
153 <option>-optL</option> <replaceable>option</replaceable>
154 <indexterm><primary><option>-optL</option></primary></indexterm>
155 </term>
156 <listitem>
157 <para>Pass <replaceable>option</replaceable> to the
158 literate pre-processor</para>
159 </listitem>
160 </varlistentry>
161 <varlistentry>
162 <term>
163 <option>-optP</option> <replaceable>option</replaceable>
164 <indexterm><primary><option>-optP</option></primary></indexterm>
165 </term>
166 <listitem>
167 <para>Pass <replaceable>option</replaceable> to CPP (makes
168 sense only if <option>-cpp</option> is also on).</para>
169 </listitem>
170 </varlistentry>
171 <varlistentry>
172 <term>
173 <option>-optF</option> <replaceable>option</replaceable>
174 <indexterm><primary><option>-optF</option></primary></indexterm>
175 </term>
176 <listitem>
177 <para>Pass <replaceable>option</replaceable> to the
178 custom pre-processor (see <xref linkend="pre-processor"/>).</para>
179 </listitem>
180 </varlistentry>
181 <varlistentry>
182 <term>
183 <option>-optc</option> <replaceable>option</replaceable>
184 <indexterm><primary><option>-optc</option></primary></indexterm>
185 </term>
186 <listitem>
187 <para>Pass <replaceable>option</replaceable> to the C compiler.</para>
188 </listitem>
189 </varlistentry>
190 <varlistentry>
191 <term>
192 <option>-optlo</option> <replaceable>option</replaceable>
193 <indexterm><primary><option>-optlo</option></primary></indexterm>
194 </term>
195 <listitem>
196 <para>Pass <replaceable>option</replaceable> to the LLVM optimiser.</para>
197 </listitem>
198 </varlistentry>
199 <varlistentry>
200 <term>
201 <option>-optlc</option> <replaceable>option</replaceable>
202 <indexterm><primary><option>-optlc</option></primary></indexterm>
203 </term>
204 <listitem>
205 <para>Pass <replaceable>option</replaceable> to the LLVM compiler.</para>
206 </listitem>
207 </varlistentry>
208 <varlistentry>
209 <term>
210 <option>-optm</option> <replaceable>option</replaceable>
211 <indexterm><primary><option>-optm</option></primary></indexterm>
212 </term>
213 <listitem>
214 <para>Pass <replaceable>option</replaceable> to the mangler.</para>
215 </listitem>
216 </varlistentry>
217 <varlistentry>
218 <term>
219 <option>-opta</option> <replaceable>option</replaceable>
220 <indexterm><primary><option>-opta</option></primary></indexterm>
221 </term>
222 <listitem>
223 <para>Pass <replaceable>option</replaceable> to the assembler.</para>
224 </listitem>
225 </varlistentry>
226 <varlistentry>
227 <term>
228 <option>-optl</option> <replaceable>option</replaceable>
229 <indexterm><primary><option>-optl</option></primary></indexterm>
230 </term>
231 <listitem>
232 <para>Pass <replaceable>option</replaceable> to the linker.</para>
233 </listitem>
234 </varlistentry>
235 <varlistentry>
236 <term>
237 <option>-optdll</option> <replaceable>option</replaceable>
238 <indexterm><primary><option>-optdll</option></primary></indexterm>
239 </term>
240 <listitem>
241 <para>Pass <replaceable>option</replaceable> to the DLL generator.</para>
242 </listitem>
243 </varlistentry>
244 <varlistentry>
245 <term>
246 <option>-optwindres</option> <replaceable>option</replaceable>
247 <indexterm><primary><option>-optwindres</option></primary></indexterm>
248 </term>
249 <listitem>
250 <para>Pass <replaceable>option</replaceable> to
251 <literal>windres</literal> when embedding manifests on Windows.
252 See <option>-fno-embed-manifest</option> in <xref
253 linkend="options-linker" />.</para>
254 </listitem>
255 </varlistentry>
256 </variablelist>
257
258 <para>So, for example, to force an <option>-Ewurble</option>
259 option to the assembler, you would tell the driver
260 <option>-opta-Ewurble</option> (the dash before the E is
261 required).</para>
262
263 <para>GHC is itself a Haskell program, so if you need to pass
264 options directly to GHC's runtime system you can enclose them in
265 <literal>+RTS ... -RTS</literal> (see <xref
266 linkend="runtime-control"/>).</para>
267
268 </sect2>
269
270 <sect2 id="c-pre-processor">
271 <title>Options affecting the C pre-processor</title>
272
273 <indexterm><primary>pre-processing: cpp</primary></indexterm>
274 <indexterm><primary>C pre-processor options</primary></indexterm>
275 <indexterm><primary>cpp, pre-processing with</primary></indexterm>
276
277 <variablelist>
278
279 <varlistentry>
280 <term>
281 <option>-cpp</option>
282 <indexterm><primary><option>-cpp</option></primary></indexterm>
283 </term>
284 <listitem>
285 <para>The C pre-processor <command>cpp</command> is run
286 over your Haskell code only if the <option>-cpp</option>
287 option <indexterm><primary>-cpp
288 option</primary></indexterm> is given. Unless you are
289 building a large system with significant doses of
290 conditional compilation, you really shouldn't need
291 it.</para>
292 </listitem>
293 </varlistentry>
294
295 <varlistentry>
296 <term>
297 <option>-D</option><replaceable>symbol</replaceable><optional>=<replaceable>value</replaceable></optional>
298 <indexterm><primary><option>-D</option></primary></indexterm>
299 </term>
300 <listitem>
301 <para>Define macro <replaceable>symbol</replaceable> in the
302 usual way. NB: does <emphasis>not</emphasis> affect
303 <option>-D</option> macros passed to the C&nbsp;compiler
304 when compiling via C! For those, use the
305 <option>-optc-Dfoo</option> hack&hellip; (see <xref
306 linkend="forcing-options-through"/>).</para>
307 </listitem>
308 </varlistentry>
309
310 <varlistentry>
311 <term>
312 <option>-U</option><replaceable>symbol</replaceable>
313 <indexterm><primary><option>-U</option></primary></indexterm>
314 </term>
315 <listitem>
316 <para> Undefine macro <replaceable>symbol</replaceable> in the
317 usual way.</para>
318 </listitem>
319 </varlistentry>
320
321 <varlistentry>
322 <term>
323 <option>-I</option><replaceable>dir</replaceable>
324 <indexterm><primary><option>-I</option></primary></indexterm>
325 </term>
326 <listitem>
327 <para> Specify a directory in which to look for
328 <literal>&num;include</literal> files, in the usual C
329 way.</para>
330 </listitem>
331 </varlistentry>
332 </variablelist>
333
334 <para>The GHC driver pre-defines several macros when processing
335 Haskell source code (<filename>.hs</filename> or
336 <filename>.lhs</filename> files).</para>
337
338 <para>The symbols defined by GHC are listed below. To check which
339 symbols are defined by your local GHC installation, the following
340 trick is useful:</para>
341
342 <screen>$ ghc -E -optP-dM -cpp foo.hs
343 $ cat foo.hspp</screen>
344
345 <para>(you need a file <filename>foo.hs</filename>, but it isn't
346 actually used).</para>
347
348 <variablelist>
349 <varlistentry>
350 <term>
351 <constant>&lowbar;&lowbar;GLASGOW&lowbar;HASKELL&lowbar;&lowbar;</constant>
352 <indexterm><primary><constant>&lowbar;&lowbar;GLASGOW&lowbar;HASKELL&lowbar;&lowbar;</constant></primary></indexterm>
353 </term>
354 <listitem>
355 <para>For version
356 <literal><replaceable>x</replaceable>.<replaceable>y</replaceable>.<replaceable>z</replaceable></literal>
357 of GHC, the value of
358 <constant>&lowbar;&lowbar;GLASGOW&lowbar;HASKELL&lowbar;&lowbar;</constant>
359 is the integer <replaceable>xyy</replaceable> (if
360 <replaceable>y</replaceable> is a single digit, then a leading zero
361 is added, so for example in version 6.2 of GHC,
362 <literal>__GLASGOW_HASKELL__==602</literal>). More
363 information in <xref linkend="version-numbering"/>.</para>
364
365 <para>With any luck,
366 <constant>&lowbar;&lowbar;GLASGOW&lowbar;HASKELL&lowbar;&lowbar;</constant>
367 will be undefined in all other implementations that
368 support C-style pre-processing.</para>
369
370 <para>(For reference: the comparable symbols for other
371 systems are:
372 <constant>&lowbar;&lowbar;HUGS&lowbar;&lowbar;</constant>
373 for Hugs,
374 <constant>&lowbar;&lowbar;NHC&lowbar;&lowbar;</constant>
375 for nhc98, and
376 <constant>&lowbar;&lowbar;HBC&lowbar;&lowbar;</constant>
377 for hbc.)</para>
378
379 <para>NB. This macro is set when pre-processing both
380 Haskell source and C source, including the C source
381 generated from a Haskell module
382 (i.e. <filename>.hs</filename>, <filename>.lhs</filename>,
383 <filename>.c</filename> and <filename>.hc</filename>
384 files).</para>
385 </listitem>
386 </varlistentry>
387
388 <varlistentry>
389 <term>
390 <constant>&lowbar;&lowbar;GLASGOW&lowbar;HASKELL&lowbar;LLVM&lowbar;&lowbar;</constant>
391 <indexterm><primary><constant>&lowbar;&lowbar;GLASGOW&lowbar;HASKELL&lowbar;LLVM&lowbar;&lowbar;</constant></primary></indexterm>
392 </term>
393 <listitem>
394 <para>Only defined when <option>-fllvm</option> is specified. When GHC
395 is using version
396 <literal><replaceable>x</replaceable>.<replaceable>y</replaceable>.<replaceable>z</replaceable></literal>
397 of LLVM, the value of
398 <constant>&lowbar;&lowbar;GLASGOW&lowbar;HASKELL&lowbar;LLVM&lowbar;&lowbar;</constant>
399 is the integer <replaceable>xy</replaceable>.</para>
400 </listitem>
401 </varlistentry>
402
403 <varlistentry>
404 <term>
405 <constant>&lowbar;&lowbar;PARALLEL&lowbar;HASKELL&lowbar;&lowbar;</constant>
406 <indexterm><primary><constant>&lowbar;&lowbar;PARALLEL&lowbar;HASKELL&lowbar;&lowbar;</constant></primary></indexterm>
407 </term>
408 <listitem>
409 <para>Only defined when <option>-parallel</option> is in
410 use! This symbol is defined when pre-processing Haskell
411 (input) and pre-processing C (GHC output).</para>
412 </listitem>
413 </varlistentry>
414
415 <varlistentry>
416 <term>
417 <constant><replaceable>os</replaceable>_HOST_OS=1</constant>
418 </term>
419 <listitem>
420 <para>This define allows conditional compilation based on
421 the Operating System, where<replaceable>os</replaceable> is
422 the name of the current Operating System
423 (eg. <literal>linux</literal>, <literal>mingw32</literal>
424 for Windows, <literal>solaris</literal>, etc.).</para>
425 </listitem>
426 </varlistentry>
427
428 <varlistentry>
429 <term>
430 <constant><replaceable>arch</replaceable>_HOST_ARCH=1</constant>
431 </term>
432 <listitem>
433 <para>This define allows conditional compilation based on
434 the host architecture, where<replaceable>arch</replaceable>
435 is the name of the current architecture
436 (eg. <literal>i386</literal>, <literal>x86_64</literal>,
437 <literal>powerpc</literal>, <literal>sparc</literal>,
438 etc.).</para>
439 </listitem>
440 </varlistentry>
441 </variablelist>
442
443 <sect3 id="cpp-string-gaps">
444 <title>CPP and string gaps</title>
445
446 <para>A small word of warning: <option>-cpp</option> is not
447 friendly to &ldquo;string gaps&rdquo;.<indexterm><primary>-cpp
448 vs string gaps</primary></indexterm><indexterm><primary>string
449 gaps vs -cpp</primary></indexterm>. In other words, strings
450 such as the following:</para>
451
452 <programlisting>strmod = "\
453 \ p \
454 \ "</programlisting>
455
456 <para>don't work with <option>-cpp</option>;
457 <filename>/usr/bin/cpp</filename> elides the backslash-newline
458 pairs.</para>
459
460 <para>However, it appears that if you add a space at the end
461 of the line, then <command>cpp</command> (at least GNU
462 <command>cpp</command> and possibly other
463 <command>cpp</command>s) leaves the backslash-space pairs
464 alone and the string gap works as expected.</para>
465 </sect3>
466 </sect2>
467
468 <sect2 id="pre-processor">
469 <title>Options affecting a Haskell pre-processor</title>
470
471 <indexterm><primary>pre-processing: custom</primary></indexterm>
472 <indexterm><primary>Pre-processor options</primary></indexterm>
473
474 <variablelist>
475 <varlistentry>
476 <term>
477 <option>-F</option>
478 <indexterm><primary><option>-F</option></primary></indexterm>
479 </term>
480 <listitem>
481 <para>A custom pre-processor is run over your Haskell
482 source file only if the <option>-F</option> option
483 <indexterm><primary>-F</primary></indexterm> is
484 given.</para>
485
486 <para>Running a custom pre-processor at compile-time is in
487 some settings appropriate and useful. The
488 <option>-F</option> option lets you run a pre-processor as
489 part of the overall GHC compilation pipeline, which has
490 the advantage over running a Haskell pre-processor
491 separately in that it works in interpreted mode and you
492 can continue to take reap the benefits of GHC's
493 recompilation checker.</para>
494
495 <para>The pre-processor is run just before the Haskell
496 compiler proper processes the Haskell input, but after the
497 literate markup has been stripped away and (possibly) the
498 C pre-processor has washed the Haskell input.</para>
499
500 <para>Use
501 <option>-pgmF&nbsp;<replaceable>cmd</replaceable></option>
502 to select the program to use as the preprocessor. When
503 invoked, the <replaceable>cmd</replaceable> pre-processor
504 is given at least three arguments on its command-line: the
505 first argument is the name of the original source file,
506 the second is the name of the file holding the input, and
507 the third is the name of the file where
508 <replaceable>cmd</replaceable> should write its output
509 to.</para>
510
511 <para>Additional arguments to the pre-processor can be
512 passed in using the <option>-optF</option> option. These
513 are fed to <replaceable>cmd</replaceable> on the command
514 line after the three standard input and output
515 arguments.</para>
516
517 <para>
518 An example of a pre-processor is to convert your source files to the
519 input encoding that GHC expects, i.e. create a script
520 <literal>convert.sh</literal> containing the lines:
521 </para>
522
523 <screen>#!/bin/sh
524 ( echo "{-# LINE 1 \"$2\" #-}" ; iconv -f l1 -t utf-8 $2 ) > $3</screen>
525
526 <para>and pass <literal>-F -pgmF convert.sh</literal> to GHC.
527 The <literal>-f l1</literal> option tells iconv to convert your
528 Latin-1 file, supplied in argument <literal>$2</literal>, while
529 the "-t utf-8" options tell iconv to return a UTF-8 encoded file.
530 The result is redirected into argument <literal>$3</literal>.
531 The <literal>echo "{-# LINE 1 \"$2\" #-}"</literal>
532 just makes sure that your error positions are reported as
533 in the original source file.</para>
534 </listitem>
535 </varlistentry>
536 </variablelist>
537 </sect2>
538
539 <sect2 id="options-codegen">
540 <title>Options affecting code generation</title>
541
542 <variablelist>
543 <varlistentry>
544 <term>
545 <option>-fasm</option>
546 <indexterm><primary><option>-fasm</option></primary></indexterm>
547 </term>
548 <listitem>
549 <para>Use GHC's <link linkend="native-code-gen">native code generator
550 </link>rather than compiling via LLVM.
551 <option>-fasm</option> is the default.</para>
552 </listitem>
553 </varlistentry>
554
555 <varlistentry>
556 <term>
557 <option>-fllvm</option>
558 <indexterm><primary><option>-fllvm</option></primary></indexterm>
559 </term>
560 <listitem>
561 <para>Compile via <link linkend="llvm-code-gen">LLVM</link>instead
562 of using the native code generator. This will generally take slightly
563 longer than the native code generator to compile. Produced code is
564 generally the same speed or faster than the other two code
565 generators. Compiling via LLVM requires LLVM to be on the
566 path.</para>
567 </listitem>
568 </varlistentry>
569
570 <varlistentry>
571 <term>
572 <option>-fno-code</option>
573 <indexterm><primary><option>-fno-code</option></primary></indexterm>
574 </term>
575 <listitem>
576 <para>Omit code generation (and all later phases)
577 altogether. Might be of some use if you just want to see
578 dumps of the intermediate compilation phases.</para>
579 </listitem>
580 </varlistentry>
581
582 <varlistentry>
583 <term>
584 <option>-fobject-code</option>
585 <indexterm><primary><option>-fobject-code</option></primary></indexterm>
586 </term>
587 <listitem>
588 <para>Generate object code. This is the default outside of
589 GHCi, and can be used with GHCi to cause object code to be
590 generated in preference to bytecode.</para>
591 </listitem>
592 </varlistentry>
593
594 <varlistentry>
595 <term>
596 <option>-fbyte-code</option>
597 <indexterm><primary><option>-fbyte-code</option></primary></indexterm>
598 </term>
599 <listitem>
600 <para>Generate byte-code instead of object-code. This is
601 the default in GHCi. Byte-code can currently only be used
602 in the interactive interpreter, not saved to disk. This
603 option is only useful for reversing the effect of
604 <option>-fobject-code</option>.</para>
605 </listitem>
606 </varlistentry>
607
608 <varlistentry>
609 <term>
610 <option>-fPIC</option>
611 <indexterm><primary><option>-fPIC</option></primary></indexterm>
612 </term>
613 <listitem>
614 <para>Generate position-independent code (code that can be put into
615 shared libraries). This currently works on Linux x86 and x86-64. On
616 Windows, position-independent code is never used so the flag is a
617 no-op on that platform.</para>
618 </listitem>
619 </varlistentry>
620
621 <varlistentry>
622 <term>
623 <option>-dynamic</option>
624 </term>
625 <listitem>
626 <para>When generating code, assume that entities imported from a
627 different package will reside in a different shared library or
628 binary.</para>
629 <para>Note that using this option when linking causes GHC to link
630 against shared libraries.</para>
631 </listitem>
632 </varlistentry>
633 </variablelist>
634 </sect2>
635
636 <sect2 id="options-linker">
637 <title>Options affecting linking</title>
638
639 <indexterm><primary>linker options</primary></indexterm>
640 <indexterm><primary>ld options</primary></indexterm>
641
642
643 <para>GHC has to link your code with various libraries, possibly
644 including: user-supplied, GHC-supplied, and system-supplied
645 (<option>-lm</option> math library, for example).</para>
646
647 <variablelist>
648
649 <varlistentry>
650 <term>
651 <option>-l</option><replaceable>lib</replaceable>
652 <indexterm><primary><option>-l</option></primary></indexterm>
653 </term>
654 <listitem>
655 <para>Link in the <replaceable>lib</replaceable> library.
656 On Unix systems, this will be in a file called
657 <filename>lib<replaceable>lib</replaceable>.a</filename>
658 or
659 <filename>lib<replaceable>lib</replaceable>.so</filename>
660 which resides somewhere on the library directories path.</para>
661
662 <para>Because of the sad state of most UNIX linkers, the
663 order of such options does matter. If library
664 <replaceable>foo</replaceable> requires library
665 <replaceable>bar</replaceable>, then in general
666 <option>-l</option><replaceable>foo</replaceable> should
667 come <emphasis>before</emphasis>
668 <option>-l</option><replaceable>bar</replaceable> on the
669 command line.</para>
670
671 <para>There's one other gotcha to bear in mind when using
672 external libraries: if the library contains a
673 <literal>main()</literal> function, then this will be
674 linked in preference to GHC's own
675 <literal>main()</literal> function
676 (eg. <literal>libf2c</literal> and <literal>libl</literal>
677 have their own <literal>main()</literal>s). This is
678 because GHC's <literal>main()</literal> comes from the
679 <literal>HSrts</literal> library, which is normally
680 included <emphasis>after</emphasis> all the other
681 libraries on the linker's command line. To force GHC's
682 <literal>main()</literal> to be used in preference to any
683 other <literal>main()</literal>s from external libraries,
684 just add the option <option>-lHSrts</option> before any
685 other libraries on the command line.</para>
686 </listitem>
687 </varlistentry>
688
689 <varlistentry>
690 <term>
691 <option>-c</option>
692 <indexterm><primary><option>-c</option></primary></indexterm>
693 </term>
694 <listitem>
695 <para>Omits the link step. This option can be used with
696 <option>--make</option> to avoid the automatic linking
697 that takes place if the program contains a <literal>Main</literal>
698 module.</para>
699 </listitem>
700 </varlistentry>
701
702 <varlistentry>
703 <term>
704 <option>-package</option> <replaceable>name</replaceable>
705 <indexterm><primary><option>-package</option></primary></indexterm>
706 </term>
707 <listitem>
708 <para>If you are using a Haskell &ldquo;package&rdquo;
709 (see <xref linkend="packages"/>), don't forget to add the
710 relevant <option>-package</option> option when linking the
711 program too: it will cause the appropriate libraries to be
712 linked in with the program. Forgetting the
713 <option>-package</option> option will likely result in
714 several pages of link errors.</para>
715 </listitem>
716 </varlistentry>
717
718 <varlistentry>
719 <term>
720 <option>-framework</option> <replaceable>name</replaceable>
721 <indexterm><primary><option>-framework</option></primary></indexterm>
722 </term>
723 <listitem>
724 <para>On Darwin/MacOS X only, link in the framework <replaceable>name</replaceable>.
725 This option corresponds to the <option>-framework</option> option for Apple's Linker.
726 Please note that frameworks and packages are two different things - frameworks don't
727 contain any haskell code. Rather, they are Apple's way of packaging shared libraries.
728 To link to Apple's &ldquo;Carbon&rdquo; API, for example, you'd use
729 <option>-framework Carbon</option>.
730 </para>
731 </listitem>
732 </varlistentry>
733
734 <varlistentry>
735 <term>
736 <option>-L</option><replaceable>dir</replaceable>
737 <indexterm><primary><option>-L</option></primary></indexterm>
738 </term>
739 <listitem>
740 <para>Where to find user-supplied libraries&hellip;
741 Prepend the directory <replaceable>dir</replaceable> to
742 the library directories path.</para>
743 </listitem>
744 </varlistentry>
745
746 <varlistentry>
747 <term>
748 <option>-framework-path</option><replaceable>dir</replaceable>
749 <indexterm><primary><option>-framework-path</option></primary></indexterm>
750 </term>
751 <listitem>
752 <para>On Darwin/MacOS X only, prepend the directory <replaceable>dir</replaceable> to
753 the framework directories path. This option corresponds to the <option>-F</option>
754 option for Apple's Linker (<option>-F</option> already means something else for GHC).</para>
755 </listitem>
756 </varlistentry>
757
758 <varlistentry>
759 <term>
760 <option>-split-objs</option>
761 <indexterm><primary><option>-split-objs</option></primary></indexterm>
762 </term>
763 <listitem>
764 <para>Tell the linker to split the single object file that
765 would normally be generated into multiple object files,
766 one per top-level Haskell function or type in the module.
767 This only makes sense for libraries, where it means that
768 executables linked against the library are smaller as they only
769 link against the object files that they need. However, assembling
770 all the sections separately is expensive, so this is slower than
771 compiling normally.
772 We use this feature for building GHC's libraries
773 (warning: don't use it unless you know what you're
774 doing!).</para>
775 </listitem>
776 </varlistentry>
777
778 <varlistentry>
779 <term>
780 <option>-static</option>
781 <indexterm><primary><option>-static</option></primary></indexterm>
782 </term>
783 <listitem>
784 <para>Tell the linker to avoid shared Haskell libraries,
785 if possible. This is the default.</para>
786 </listitem>
787 </varlistentry>
788
789 <varlistentry>
790 <term>
791 <option>-dynamic</option>
792 <indexterm><primary><option>-dynamic</option></primary></indexterm>
793 </term>
794 <listitem>
795 <para>This flag tells GHC to link against shared Haskell libraries.
796 This flag only affects the selection of dependent libraries, not
797 the form of the current target (see -shared).
798 See <xref linkend="using-shared-libs" /> on how to
799 create them.</para>
800
801 <para>Note that this option also has an effect on
802 code generation (see above).</para>
803 </listitem>
804 </varlistentry>
805
806 <varlistentry>
807 <term>
808 <option>-shared</option>
809 <indexterm><primary><option>-shared</option></primary></indexterm>
810 </term>
811 <listitem>
812 <para>Instead of creating an executable, GHC produces a
813 shared object with this linker flag. Depending on the
814 operating system target, this might be an ELF DSO, a Windows
815 DLL, or a Mac OS dylib. GHC hides the operating system
816 details beneath this uniform flag.</para>
817
818 <para>The flags <option>-dynamic</option>/<option>-static</option> control whether the
819 resulting shared object links statically or dynamically to
820 Haskell package libraries given as <option>-package</option> option. Non-Haskell
821 libraries are linked as gcc would regularly link it on your
822 system, e.g. on most ELF system the linker uses the dynamic
823 libraries when found.</para>
824
825 <para>Object files linked into shared objects must be
826 compiled with <option>-fPIC</option>, see <xref linkend="options-codegen" /></para>
827
828 <para>When creating shared objects for Haskell packages, the
829 shared object must be named properly, so that GHC recognizes
830 the shared object when linked against this package. See
831 shared object name mangling.</para>
832 </listitem>
833 </varlistentry>
834
835 <varlistentry>
836 <term>
837 <option>-dynload</option>
838 <indexterm><primary><option>-dynload</option></primary></indexterm>
839 </term>
840 <listitem>
841 <para>
842 This flag selects one of a number of modes for finding shared
843 libraries at runtime. See <xref linkend="finding-shared-libs"/> for
844 a description of each mode.
845 </para>
846 </listitem>
847 </varlistentry>
848
849 <varlistentry>
850 <term>
851 <option>-main-is <replaceable>thing</replaceable></option>
852 <indexterm><primary><option>-main-is</option></primary></indexterm>
853 <indexterm><primary>specifying your own main function</primary></indexterm>
854 </term>
855 <listitem>
856 <para> The normal rule in Haskell is that your program must supply a <literal>main</literal>
857 function in module <literal>Main</literal>. When testing, it is often convenient
858 to change which function is the "main" one, and the <option>-main-is</option> flag
859 allows you to do so. The <replaceable>thing</replaceable> can be one of:
860 <itemizedlist>
861 <listitem><para>A lower-case identifier <literal>foo</literal>. GHC assumes that the main function is <literal>Main.foo</literal>.</para></listitem>
862 <listitem><para>A module name <literal>A</literal>. GHC assumes that the main function is <literal>A.main</literal>.</para></listitem>
863 <listitem><para>A qualified name <literal>A.foo</literal>. GHC assumes that the main function is <literal>A.foo</literal>.</para></listitem>
864 </itemizedlist>
865 Strictly speaking, <option>-main-is</option> is not a link-phase flag at all; it has no effect on the link step.
866 The flag must be specified when compiling the module containing the specified main function (e.g. module <literal>A</literal>
867 in the latter two items above). It has no effect for other modules,
868 and hence can safely be given to <literal>ghc --make</literal>.
869 However, if all the modules are otherwise up to date, you may need to force
870 recompilation both of the module where the new "main" is, and of the
871 module where the "main" function used to be;
872 <literal>ghc</literal> is not clever
873 enough to figure out that they both need recompiling. You can
874 force recompilation by removing the object file, or by using the
875 <option>-fforce-recomp</option> flag.
876 </para>
877 </listitem>
878 </varlistentry>
879
880 <varlistentry>
881 <term>
882 <option>-no-hs-main</option>
883 <indexterm><primary><option>-no-hs-main</option></primary></indexterm>
884 <indexterm><primary>linking Haskell libraries with foreign code</primary></indexterm>
885 </term>
886 <listitem>
887 <para>In the event you want to include ghc-compiled code
888 as part of another (non-Haskell) program, the RTS will not
889 be supplying its definition of <function>main()</function>
890 at link-time, you will have to. To signal that to the
891 compiler when linking, use
892 <option>-no-hs-main</option>. See also <xref linkend="using-own-main"/>.</para>
893
894 <para>Notice that since the command-line passed to the
895 linker is rather involved, you probably want to use
896 <command>ghc</command> to do the final link of your
897 `mixed-language' application. This is not a requirement
898 though, just try linking once with <option>-v</option> on
899 to see what options the driver passes through to the
900 linker.</para>
901
902 <para>The <option>-no-hs-main</option> flag can also be
903 used to persuade the compiler to do the link step in
904 <option>--make</option> mode when there is no Haskell
905 <literal>Main</literal> module present (normally the
906 compiler will not attempt linking when there is no
907 <literal>Main</literal>).</para>
908
909 <para>The flags <option>-rtsopts</option>
910 and <option>-with-rtsopts</option> have no effect when
911 used with <option>-no-hs-main</option>, because they are
912 implemented by changing the definition
913 of <literal>main</literal> that GHC generates. See
914 <xref linkend="using-own-main" /> for how to get the
915 effect of <option>-rtsopts</option>
916 and <option>-with-rtsopts</option> when using your
917 own <literal>main</literal>.
918 </para>
919
920 </listitem>
921 </varlistentry>
922
923 <varlistentry>
924 <term>
925 <option>-debug</option>
926 <indexterm><primary><option>-debug</option></primary></indexterm>
927 </term>
928 <listitem>
929 <para>Link the program with a debugging version of the
930 runtime system. The debugging runtime turns on numerous
931 assertions and sanity checks, and provides extra options
932 for producing debugging output at runtime (run the program
933 with <literal>+RTS&nbsp;-?</literal> to see a list).</para>
934 </listitem>
935 </varlistentry>
936
937 <varlistentry>
938 <term>
939 <option>-threaded</option>
940 <indexterm><primary><option>-threaded</option></primary></indexterm>
941 </term>
942 <listitem>
943 <para>Link the program with the "threaded" version of the
944 runtime system. The threaded runtime system is so-called
945 because it manages multiple OS threads, as opposed to the
946 default runtime system which is purely
947 single-threaded.</para>
948
949 <para>Note that you do <emphasis>not</emphasis> need
950 <option>-threaded</option> in order to use concurrency; the
951 single-threaded runtime supports concurrency between Haskell
952 threads just fine.</para>
953
954 <para>The threaded runtime system provides the following
955 benefits:</para>
956
957 <itemizedlist>
958 <listitem>
959 <para>It enables the <option>-N</option><indexterm><primary><option>-N<replaceable>x</replaceable></option></primary><secondary>RTS option</secondary></indexterm> RTS option to be
960 used, which allows threads to run in
961 parallel<indexterm><primary>parallelism</primary></indexterm>
962 on a
963 multiprocessor<indexterm><primary>multiprocessor</primary></indexterm><indexterm><primary>SMP</primary></indexterm>
964 or
965 multicore<indexterm><primary>multicore</primary></indexterm>
966 machine. See <xref linkend="using-smp" />.</para>
967 </listitem>
968 <listitem>
969 <para>If a thread makes a foreign call (and the call is
970 not marked <literal>unsafe</literal>), then other
971 Haskell threads in the program will continue to run
972 while the foreign call is in progress.
973 Additionally, <literal>foreign export</literal>ed
974 Haskell functions may be called from multiple OS
975 threads simultaneously. See
976 <xref linkend="ffi-threads" />.</para>
977 </listitem>
978 </itemizedlist>
979 </listitem>
980 </varlistentry>
981
982 <varlistentry>
983 <term>
984 <option>-eventlog</option>
985 <indexterm><primary><option>-eventlog</option></primary></indexterm>
986 </term>
987 <listitem>
988 <para>
989 Link the program with the "eventlog" version of the
990 runtime system. A program linked in this way can generate
991 a runtime trace of events (such as thread start/stop) to a
992 binary file
993 <literal><replaceable>program</replaceable>.eventlog</literal>,
994 which can then be interpreted later by various tools. See
995 <xref linkend="rts-eventlog" /> for more information.
996 </para>
997 <para>
998 <option>-eventlog</option> can be used
999 with <option>-threaded</option>. It is implied
1000 by <option>-debug</option>.
1001 </para>
1002 </listitem>
1003 </varlistentry>
1004
1005 <varlistentry>
1006 <term>
1007 <option>-rtsopts</option>
1008 <indexterm><primary><option>-rtsopts</option></primary></indexterm>
1009 </term>
1010 <listitem>
1011 <para>
1012 This option affects the processing of RTS control options given either
1013 on the command line or via the <envar>GHCRTS</envar> environment variable.
1014 There are three possibilities:
1015 </para>
1016 <variablelist>
1017 <varlistentry>
1018 <term><option>-rtsopts=none</option></term>
1019 <listitem>
1020 <para>
1021 Disable all processing of RTS options.
1022 If <option>+RTS</option> appears anywhere on the command
1023 line, then the program will abort with an error message.
1024 If the <envar>GHCRTS</envar> environment variable is
1025 set, then the program will emit a warning message,
1026 <envar>GHCRTS</envar> will be ignored, and the program
1027 will run as normal.
1028 </para>
1029 </listitem>
1030 </varlistentry>
1031 <varlistentry>
1032 <term><option>-rtsopts=some</option></term>
1033 <listitem>
1034 <para>&lsqb;this is the default setting&rsqb; Enable
1035 only the "safe" RTS options: (Currently
1036 only <option>-?</option>
1037 and <option>--info</option>.) Any other RTS options
1038 on the command line or in the <envar>GHCRTS</envar>
1039 environment variable causes the program with to abort
1040 with an error message.
1041 </para>
1042 </listitem>
1043 </varlistentry>
1044 <varlistentry>
1045 <term><option>-rtsopts=all</option>, or
1046 just <option>-rtsopts</option></term>
1047 <listitem>
1048 <para>
1049 Enable <emphasis>all</emphasis> RTS option
1050 processing, both on the command line and through
1051 the <envar>GHCRTS</envar> environment variable.
1052 </para>
1053 </listitem>
1054 </varlistentry>
1055 </variablelist>
1056 <para>
1057 In GHC 6.12.3 and earlier, the default was to process all
1058 RTS options. However, since RTS options can be used to
1059 write logging data to arbitrary files under the security
1060 context of the running program, there is a potential
1061 security problem. For this reason, GHC 7.0.1 and later
1062 default to <option>-rtsops=some</option>.
1063 </para>
1064
1065 <para>
1066 Note that <option>-rtsopts</option> has no effect when
1067 used with <option>-no-hs-main</option>; see
1068 <xref linkend="using-own-main" /> for details.
1069 </para>
1070 </listitem>
1071 </varlistentry>
1072
1073 <varlistentry>
1074 <term>
1075 <option>-with-rtsopts</option>
1076 <indexterm><primary><option>-with-rtsopts</option></primary></indexterm>
1077 </term>
1078 <listitem>
1079 <para>
1080 This option allows you to set the default RTS options at link-time. For example,
1081 <option>-with-rtsopts="-H128m"</option> sets the default heap size to 128MB.
1082 This will always be the default heap size for this program, unless the user overrides it.
1083 (Depending on the setting of the <option>-rtsopts</option> option, the user might
1084 not have the ability to change RTS options at run-time, in which case
1085 <option>-with-rtsopts</option> would be the <emphasis>only</emphasis> way to set
1086 them.)
1087 </para>
1088
1089 <para>
1090 Note that <option>-with-rtsopts</option> has no effect when
1091 used with <option>-no-hs-main</option>; see
1092 <xref linkend="using-own-main" /> for details.
1093 </para>
1094 </listitem>
1095 </varlistentry>
1096
1097 <varlistentry>
1098 <term>
1099 <option>-fno-gen-manifest</option>
1100 <indexterm><primary><option>-fno-gen-manifest</option></primary>
1101 </indexterm>
1102 </term>
1103 <listitem>
1104 <para>On Windows, GHC normally generates a
1105 <firstterm>manifest</firstterm><indexterm><primary>manifest</primary>
1106 </indexterm> file when linking a binary. The
1107 manifest is placed in the file
1108 <literal><replaceable>prog</replaceable>.exe.manifest</literal>
1109 where <replaceable>prog.exe</replaceable> is the name of the
1110 executable. The manifest file currently serves just one purpose:
1111 it disables the "installer detection"<indexterm><primary>installer detection</primary>
1112 </indexterm>in Windows Vista that
1113 attempts to elevate privileges for executables with certain names
1114 (e.g. names containing "install", "setup" or "patch"). Without the
1115 manifest file to turn off installer detection, attempting to run an
1116 executable that Windows deems to be an installer will return a
1117 permission error code to the invoker. Depending on the invoker,
1118 the result might be a dialog box asking the user for elevated
1119 permissions, or it might simply be a permission denied
1120 error.</para>
1121
1122 <para>Installer detection can be also turned off globally for the
1123 system using the security control panel, but GHC by default
1124 generates binaries that don't depend on the user having disabled
1125 installer detection.</para>
1126
1127 <para>The <option>-fno-gen-manifest</option> disables generation of
1128 the manifest file. One reason to do this would be if you had
1129 a manifest file of your own, for example.</para>
1130
1131 <para>In the future, GHC might use the manifest file for more things,
1132 such as supplying the location of dependent DLLs.</para>
1133
1134 <para><option>-fno-gen-manifest</option> also implies
1135 <option>-fno-embed-manifest</option>, see below.</para>
1136 </listitem>
1137 </varlistentry>
1138
1139 <varlistentry>
1140 <term>
1141 <option>-fno-embed-manifest</option>
1142 <indexterm><primary><option>-fno-embed-manifest</option></primary>
1143 </indexterm>
1144 </term>
1145 <listitem>
1146 <para>The manifest file that GHC generates when linking a binary on
1147 Windows is also embedded in the executable itself, by default.
1148 This means that the binary can be distributed without having to
1149 supply the manifest file too. The embedding is done by running
1150 <literal>windres</literal><indexterm><primary><literal>windres</literal></primary>
1151 </indexterm>; to see exactly what GHC does to embed the manifest,
1152 use the <option>-v</option> flag. A GHC installation comes with
1153 its own copy of <literal>windres</literal> for this reason.</para>
1154
1155 <para>See also <option>-pgmwindres</option> (<xref
1156 linkend="replacing-phases" />) and
1157 <option>-optwindres</option> (<xref
1158 linkend="forcing-options-through"
1159 />).</para>
1160 </listitem>
1161 </varlistentry>
1162
1163 <varlistentry>
1164 <term>
1165 <option>-fno-shared-implib</option>
1166 <indexterm><primary><option>-fno-shared-implib</option></primary>
1167 </indexterm>
1168 </term>
1169 <listitem>
1170 <para>DLLs on Windows are typically linked to by linking to a corresponding
1171 <literal>.lib</literal> or <literal>.dll.a</literal> - the so-called import library.
1172 GHC will typically generate such a file for every DLL you create by compiling in
1173 <literal>-shared</literal> mode. However, sometimes you don't want to pay the
1174 disk-space cost of creating this import library, which can be substantial - it
1175 might require as much space as the code itself, as Haskell DLLs tend to export
1176 lots of symbols.</para>
1177
1178 <para>As long as you are happy to only be able to link to the DLL using
1179 <literal>GetProcAddress</literal> and friends, you can supply the
1180 <option>-fno-shared-implib</option> flag to disable the creation of the import
1181 library entirely.</para>
1182 </listitem>
1183 </varlistentry>
1184
1185 <varlistentry>
1186 <term>
1187 <option>-dylib-install-name <replaceable>path</replaceable></option>
1188 <indexterm><primary><option>-dylib-install-name</option></primary>
1189 </indexterm>
1190 </term>
1191 <listitem>
1192 <para>On Darwin/MacOS X, dynamic libraries are stamped at build time with an
1193 "install name", which is the ultimate install path of the library file.
1194 Any libraries or executables that subsequently link against it will pick
1195 up that path as their runtime search location for it. By default, ghc sets
1196 the install name to the location where the library is built. This option
1197 allows you to override it with the specified file path. (It passes
1198 <literal>-install_name</literal> to Apple's linker.) Ignored on other
1199 platforms.</para>
1200 </listitem>
1201 </varlistentry>
1202 </variablelist>
1203 </sect2>
1204
1205 </sect1>
1206
1207 <!-- Emacs stuff:
1208 ;;; Local Variables: ***
1209 ;;; sgml-parent-document: ("users_guide.xml" "book" "chapter" "sect1") ***
1210 ;;; End: ***
1211 -->