ba4d72eba62a9fd851d4c6f306fa21968625ad0f
[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>-pgmm</option> <replaceable>cmd</replaceable>
53 <indexterm><primary><option>-pgmm</option></primary></indexterm>
54 </term>
55 <listitem>
56 <para>Use <replaceable>cmd</replaceable> as the
57 mangler.</para>
58 </listitem>
59 </varlistentry>
60
61 <varlistentry>
62 <term>
63 <option>-pgms</option> <replaceable>cmd</replaceable>
64 <indexterm><primary><option>-pgms</option></primary></indexterm>
65 </term>
66 <listitem>
67 <para>Use <replaceable>cmd</replaceable> as the
68 splitter.</para>
69 </listitem>
70 </varlistentry>
71
72 <varlistentry>
73 <term>
74 <option>-pgma</option> <replaceable>cmd</replaceable>
75 <indexterm><primary><option>-pgma</option></primary></indexterm>
76 </term>
77 <listitem>
78 <para>Use <replaceable>cmd</replaceable> as the
79 assembler.</para>
80 </listitem>
81 </varlistentry>
82
83 <varlistentry>
84 <term>
85 <option>-pgml</option> <replaceable>cmd</replaceable>
86 <indexterm><primary><option>-pgml</option></primary></indexterm>
87 </term>
88 <listitem>
89 <para>Use <replaceable>cmd</replaceable> as the
90 linker.</para>
91 </listitem>
92 </varlistentry>
93
94 <varlistentry>
95 <term>
96 <option>-pgmdll</option> <replaceable>cmd</replaceable>
97 <indexterm><primary><option>-pgmdll</option></primary></indexterm>
98 </term>
99 <listitem>
100 <para>Use <replaceable>cmd</replaceable> as the DLL
101 generator.</para>
102 </listitem>
103 </varlistentry>
104
105 <varlistentry>
106 <term>
107 <option>-pgmF</option> <replaceable>cmd</replaceable>
108 <indexterm><primary><option>-pgmF</option></primary></indexterm>
109 </term>
110 <listitem>
111 <para>Use <replaceable>cmd</replaceable> as the
112 pre-processor (with <option>-F</option> only).</para>
113 </listitem>
114 </varlistentry>
115
116
117 </variablelist>
118 </sect2>
119
120 <sect2 id="forcing-options-through">
121 <title>Forcing options to a particular phase</title>
122 <indexterm><primary>forcing GHC-phase options</primary></indexterm>
123
124 <para>Options can be forced through to a particlar compilation
125 phase, using the following flags:</para>
126
127 <variablelist>
128 <varlistentry>
129 <term>
130 <option>-optL</option> <replaceable>option</replaceable>
131 <indexterm><primary><option>-optL</option></primary></indexterm>
132 </term>
133 <listitem>
134 <para>Pass <replaceable>option</replaceable> to the
135 literate pre-processor</para>
136 </listitem>
137 </varlistentry>
138 <varlistentry>
139 <term>
140 <option>-optP</option> <replaceable>option</replaceable>
141 <indexterm><primary><option>-optP</option></primary></indexterm>
142 </term>
143 <listitem>
144 <para>Pass <replaceable>option</replaceable> to CPP (makes
145 sense only if <option>-cpp</option> is also on).</para>
146 </listitem>
147 </varlistentry>
148 <varlistentry>
149 <term>
150 <option>-optF</option> <replaceable>option</replaceable>
151 <indexterm><primary><option>-optF</option></primary></indexterm>
152 </term>
153 <listitem>
154 <para>Pass <replaceable>option</replaceable> to the
155 custom pre-processor (see <xref linkend="pre-processor"/>).</para>
156 </listitem>
157 </varlistentry>
158 <varlistentry>
159 <term>
160 <option>-optc</option> <replaceable>option</replaceable>
161 <indexterm><primary><option>-optc</option></primary></indexterm>
162 </term>
163 <listitem>
164 <para>Pass <replaceable>option</replaceable> to the C compiler.</para>
165 </listitem>
166 </varlistentry>
167 <varlistentry>
168 <term>
169 <option>-optm</option> <replaceable>option</replaceable>
170 <indexterm><primary><option>-optm</option></primary></indexterm>
171 </term>
172 <listitem>
173 <para>Pass <replaceable>option</replaceable> to the mangler.</para>
174 </listitem>
175 </varlistentry>
176 <varlistentry>
177 <term>
178 <option>-opta</option> <replaceable>option</replaceable>
179 <indexterm><primary><option>-opta</option></primary></indexterm>
180 </term>
181 <listitem>
182 <para>Pass <replaceable>option</replaceable> to the assembler.</para>
183 </listitem>
184 </varlistentry>
185 <varlistentry>
186 <term>
187 <option>-optl</option> <replaceable>option</replaceable>
188 <indexterm><primary><option>-optl</option></primary></indexterm>
189 </term>
190 <listitem>
191 <para>Pass <replaceable>option</replaceable> to the linker.</para>
192 </listitem>
193 </varlistentry>
194 <varlistentry>
195 <term>
196 <option>-optdll</option> <replaceable>option</replaceable>
197 <indexterm><primary><option>-optdll</option></primary></indexterm>
198 </term>
199 <listitem>
200 <para>Pass <replaceable>option</replaceable> to the DLL generator.</para>
201 </listitem>
202 </varlistentry>
203 <varlistentry>
204 <term>
205 <option>-optdep</option> <replaceable>option</replaceable>
206 <indexterm><primary><option>-optdep</option></primary></indexterm>
207 </term>
208 <listitem>
209 <para>Pass <replaceable>option</replaceable> to the
210 dependency generator.</para>
211 </listitem>
212 </varlistentry>
213 </variablelist>
214
215 <para>So, for example, to force an <option>-Ewurble</option>
216 option to the assembler, you would tell the driver
217 <option>-opta-Ewurble</option> (the dash before the E is
218 required).</para>
219
220 <para>GHC is itself a Haskell program, so if you need to pass
221 options directly to GHC's runtime system you can enclose them in
222 <literal>+RTS ... -RTS</literal> (see <xref
223 linkend="runtime-control"/>).</para>
224
225 </sect2>
226
227 <sect2 id="c-pre-processor">
228 <title>Options affecting the C pre-processor</title>
229
230 <indexterm><primary>pre-processing: cpp</primary></indexterm>
231 <indexterm><primary>C pre-processor options</primary></indexterm>
232 <indexterm><primary>cpp, pre-processing with</primary></indexterm>
233
234 <variablelist>
235
236 <varlistentry>
237 <term>
238 <option>-cpp</option>
239 <indexterm><primary><option>-cpp</option></primary></indexterm>
240 </term>
241 <listitem>
242 <para>The C pre-processor <command>cpp</command> is run
243 over your Haskell code only if the <option>-cpp</option>
244 option <indexterm><primary>-cpp
245 option</primary></indexterm> is given. Unless you are
246 building a large system with significant doses of
247 conditional compilation, you really shouldn't need
248 it.</para>
249 </listitem>
250 </varlistentry>
251
252 <varlistentry>
253 <term>
254 <option>-D</option><replaceable>symbol</replaceable><optional>=<replaceable>value</replaceable></optional>
255 <indexterm><primary><option>-D</option></primary></indexterm>
256 </term>
257 <listitem>
258 <para>Define macro <replaceable>symbol</replaceable> in the
259 usual way. NB: does <emphasis>not</emphasis> affect
260 <option>-D</option> macros passed to the C&nbsp;compiler
261 when compiling via C! For those, use the
262 <option>-optc-Dfoo</option> hack&hellip; (see <xref
263 linkend="forcing-options-through"/>).</para>
264 </listitem>
265 </varlistentry>
266
267 <varlistentry>
268 <term>
269 <option>-U</option><replaceable>symbol</replaceable>
270 <indexterm><primary><option>-U</option></primary></indexterm>
271 </term>
272 <listitem>
273 <para> Undefine macro <replaceable>symbol</replaceable> in the
274 usual way.</para>
275 </listitem>
276 </varlistentry>
277
278 <varlistentry>
279 <term>
280 <option>-I</option><replaceable>dir</replaceable>
281 <indexterm><primary><option>-I</option></primary></indexterm>
282 </term>
283 <listitem>
284 <para> Specify a directory in which to look for
285 <literal>&num;include</literal> files, in the usual C
286 way.</para>
287 </listitem>
288 </varlistentry>
289 </variablelist>
290
291 <para>The GHC driver pre-defines several macros when processing
292 Haskell source code (<filename>.hs</filename> or
293 <filename>.lhs</filename> files).</para>
294
295 <para>The symbols defined by GHC are listed below. To check which
296 symbols are defined by your local GHC installation, the following
297 trick is useful:</para>
298
299 <screen>$ ghc -E -optP-dM -cpp foo.hs
300 $ cat foo.hspp</screen>
301
302 <para>(you need a file <filename>foo.hs</filename>, but it isn't
303 actually used).</para>
304
305 <variablelist>
306 <varlistentry>
307 <term>
308 <constant>&lowbar;&lowbar;HASKELL98&lowbar;&lowbar;</constant>
309 <indexterm><primary><literal>&lowbar;&lowbar;HASKELL98&lowbar;&lowbar;</literal></primary></indexterm>
310 </term>
311 <listitem>
312 <para>If defined, this means that GHC supports the
313 language defined by the Haskell 98 report.</para>
314 </listitem>
315 </varlistentry>
316
317 <varlistentry>
318 <term>
319 <constant>&lowbar;&lowbar;HASKELL&lowbar;&lowbar;=98</constant>
320 <indexterm><primary><constant>&lowbar;&lowbar;HASKELL&lowbar;&lowbar;=98</constant></primary></indexterm>
321 </term>
322 <listitem>
323 <para>In GHC 4.04 and later, the
324 <constant>&lowbar;&lowbar;HASKELL&lowbar;&lowbar;</constant>
325 macro is defined as having the value
326 <constant>98</constant>.</para>
327 </listitem>
328 </varlistentry>
329
330 <varlistentry>
331 <term>
332 <constant>&lowbar;&lowbar;HASKELL1&lowbar;&lowbar;</constant>
333 <indexterm><primary><constant>&lowbar;&lowbar;HASKELL1&lowbar;&lowbar;</constant></primary></indexterm>
334 </term>
335 <listitem>
336 <para>If defined to <replaceable>n</replaceable>, that
337 means GHC supports the Haskell language defined in the
338 Haskell report version <emphasis>1.n</emphasis>.
339 Currently 5. This macro is deprecated, and will probably
340 disappear in future versions.</para>
341 </listitem>
342 </varlistentry>
343
344 <varlistentry>
345 <term>
346 <constant>&lowbar;&lowbar;GLASGOW&lowbar;HASKELL&lowbar;&lowbar;</constant>
347 <indexterm><primary><constant>&lowbar;&lowbar;GLASGOW&lowbar;HASKELL&lowbar;&lowbar;</constant></primary></indexterm>
348 </term>
349 <listitem>
350 <para>For version
351 <literal><replaceable>x</replaceable>.<replaceable>y</replaceable>.<replaceable>z</replaceable></literal>
352 of GHC, the value of
353 <constant>&lowbar;&lowbar;GLASGOW&lowbar;HASKELL&lowbar;&lowbar;</constant>
354 is the integer <replaceable>xyy</replaceable> (if
355 <replaceable>y</replaceable> is a single digit, then a leading zero
356 is added, so for example in version 6.2 of GHC,
357 <literal>__GLASGOW_HASKELL__==602</literal>). More
358 information in <xref linkend="version-numbering"/>.</para>
359
360 <para>With any luck,
361 <constant>&lowbar;&lowbar;GLASGOW&lowbar;HASKELL&lowbar;&lowbar;</constant>
362 will be undefined in all other implementations that
363 support C-style pre-processing.</para>
364
365 <para>(For reference: the comparable symbols for other
366 systems are:
367 <constant>&lowbar;&lowbar;HUGS&lowbar;&lowbar;</constant>
368 for Hugs,
369 <constant>&lowbar;&lowbar;NHC&lowbar;&lowbar;</constant>
370 for nhc98, and
371 <constant>&lowbar;&lowbar;HBC&lowbar;&lowbar;</constant>
372 for hbc.)</para>
373
374 <para>NB. This macro is set when pre-processing both
375 Haskell source and C source, including the C source
376 generated from a Haskell module
377 (i.e. <filename>.hs</filename>, <filename>.lhs</filename>,
378 <filename>.c</filename> and <filename>.hc</filename>
379 files).</para>
380 </listitem>
381 </varlistentry>
382
383 <varlistentry>
384 <term>
385 <constant>&lowbar;&lowbar;CONCURRENT&lowbar;HASKELL&lowbar;&lowbar;</constant>
386 <indexterm><primary><constant>&lowbar;&lowbar;CONCURRENT&lowbar;HASKELL&lowbar;&lowbar;</constant></primary></indexterm>
387 </term>
388 <listitem>
389 <para>This symbol is defined when pre-processing Haskell
390 (input) and pre-processing C (GHC output). Since GHC from
391 verion 4.00 now supports concurrent haskell by default,
392 this symbol is always defined.</para>
393 </listitem>
394 </varlistentry>
395
396 <varlistentry>
397 <term>
398 <constant>&lowbar;&lowbar;PARALLEL&lowbar;HASKELL&lowbar;&lowbar;</constant>
399 <indexterm><primary><constant>&lowbar;&lowbar;PARALLEL&lowbar;HASKELL&lowbar;&lowbar;</constant></primary></indexterm>
400 </term>
401 <listitem>
402 <para>Only defined when <option>-parallel</option> is in
403 use! This symbol is defined when pre-processing Haskell
404 (input) and pre-processing C (GHC output).</para>
405 </listitem>
406 </varlistentry>
407
408 <varlistentry>
409 <term>
410 <constant><replaceable>os</replaceable>_HOST_OS=1</constant>
411 </term>
412 <listitem>
413 <para>This define allows conditional compilation based on
414 the Operating System, where<replaceable>os</replaceable> is
415 the name of the current Operating System
416 (eg. <literal>linux</literal>, <literal>mingw32</literal>
417 for Windows, <literal>solaris</literal>, etc.).</para>
418 </listitem>
419 </varlistentry>
420
421 <varlistentry>
422 <term>
423 <constant><replaceable>arch</replaceable>_HOST_ARCH=1</constant>
424 </term>
425 <listitem>
426 <para>This define allows conditional compilation based on
427 the host architecture, where<replaceable>arch</replaceable>
428 is the name of the current architecture
429 (eg. <literal>i386</literal>, <literal>x86_64</literal>,
430 <literal>powerpc</literal>, <literal>sparc</literal>,
431 etc.).</para>
432 </listitem>
433 </varlistentry>
434 </variablelist>
435
436 <sect3 id="cpp-string-gaps">
437 <title>CPP and string gaps</title>
438
439 <para>A small word of warning: <option>-cpp</option> is not
440 friendly to &ldquo;string gaps&rdquo;.<indexterm><primary>-cpp
441 vs string gaps</primary></indexterm><indexterm><primary>string
442 gaps vs -cpp</primary></indexterm>. In other words, strings
443 such as the following:</para>
444
445 <programlisting>strmod = "\
446 \ p \
447 \ "</programlisting>
448
449 <para>don't work with <option>-cpp</option>;
450 <filename>/usr/bin/cpp</filename> elides the backslash-newline
451 pairs.</para>
452
453 <para>However, it appears that if you add a space at the end
454 of the line, then <command>cpp</command> (at least GNU
455 <command>cpp</command> and possibly other
456 <command>cpp</command>s) leaves the backslash-space pairs
457 alone and the string gap works as expected.</para>
458 </sect3>
459 </sect2>
460
461 <sect2 id="pre-processor">
462 <title>Options affecting a Haskell pre-processor</title>
463
464 <indexterm><primary>pre-processing: custom</primary></indexterm>
465 <indexterm><primary>Pre-processor options</primary></indexterm>
466
467 <variablelist>
468 <varlistentry>
469 <term>
470 <option>-F</option>
471 <indexterm><primary><option>-F</option></primary></indexterm>
472 </term>
473 <listitem>
474 <para>A custom pre-processor is run over your Haskell
475 source file only if the <option>-F</option> option
476 <indexterm><primary>-F</primary></indexterm> is
477 given.</para>
478
479 <para>Running a custom pre-processor at compile-time is in
480 some settings appropriate and useful. The
481 <option>-F</option> option lets you run a pre-processor as
482 part of the overall GHC compilation pipeline, which has
483 the advantage over running a Haskell pre-processor
484 separately in that it works in interpreted mode and you
485 can continue to take reap the benefits of GHC's
486 recompilation checker.</para>
487
488 <para>The pre-processor is run just before the Haskell
489 compiler proper processes the Haskell input, but after the
490 literate markup has been stripped away and (possibly) the
491 C pre-processor has washed the Haskell input.</para>
492
493 <para>Use
494 <option>-pgmF&nbsp;<replaceable>cmd</replaceable></option>
495 to select the program to use as the preprocessor. When
496 invoked, the <replaceable>cmd</replaceable> pre-processor
497 is given at least three arguments on its command-line: the
498 first argument is the name of the original source file,
499 the second is the name of the file holding the input, and
500 the third is the name of the file where
501 <replaceable>cmd</replaceable> should write its output
502 to.</para>
503
504 <para>Additional arguments to the pre-processor can be
505 passed in using the <option>-optF</option> option. These
506 are fed to <replaceable>cmd</replaceable> on the command
507 line after the three standard input and output
508 arguments.</para>
509
510 <para>
511 An example of a pre-processor is to convert your source files to the
512 input encoding that GHC expects, i.e. create a script
513 <literal>convert.sh</literal> containing the lines:
514 </para>
515
516 <screen>#!/bin/sh
517 ( echo "{-# LINE 1 \"$2\" #-}" ; iconv -f l1 -t utf-8 $2 ) > $3</screen>
518
519 <para>and pass <literal>-F -pgmF convert.sh</literal> to GHC.
520 The <literal>-f l1</literal> option tells iconv to convert your
521 Latin-1 file, supplied in argument <literal>$2</literal>, while
522 the "-t utf-8" options tell iconv to return a UTF-8 encoded file.
523 The result is redirected into argument <literal>$3</literal>.
524 The <literal>echo "{-# LINE 1 \"$2\" #-}"</literal>
525 just makes sure that your error positions are reported as
526 in the original source file.</para>
527 </listitem>
528 </varlistentry>
529 </variablelist>
530 </sect2>
531
532 <sect2 id="options-C-compiler">
533 <title>Options affecting the C compiler (if applicable)</title>
534
535 <indexterm><primary>include-file options</primary></indexterm>
536 <indexterm><primary>C compiler options</primary></indexterm>
537 <indexterm><primary>GCC options</primary></indexterm>
538
539 <para>If you are compiling with lots of foreign calls, you may
540 need to tell the C&nbsp;compiler about some
541 <literal>&num;include</literal> files. The Right Way to do this is to
542 add an <literal>INCLUDE</literal> pragma to the top of your source file
543 (<xref linkend="include-pragma" />):</para>
544
545 <programlisting>{-# INCLUDE &lt;X/Xlib.h&gt; #-}</programlisting>
546
547 <para>Sometimes this isn't convenient. In those cases there's an
548 equivalent command-line option:</para>
549
550 <screen>% ghc -c '-#include &lt;X/Xlib.h&gt;' Xstuff.lhs</screen>
551
552 <indexterm><primary><option>-#include</option></primary>
553 </indexterm>
554
555 </sect2>
556
557 <sect2 id="options-codegen">
558 <title>Options affecting code generation</title>
559
560 <variablelist>
561 <varlistentry>
562 <term>
563 <option>-fasm</option>
564 <indexterm><primary><option>-fasm</option></primary></indexterm>
565 </term>
566 <listitem>
567 <para>Use GHC's native code generator rather than
568 compiling via C. This will compile faster (up to twice as
569 fast), but may produce code that is slightly slower than
570 compiling via C. <option>-fasm</option> is the default.</para>
571 </listitem>
572 </varlistentry>
573
574 <varlistentry>
575 <term>
576 <option>-fvia-C</option>
577 <indexterm><primary><option>-fvia-C</option></primary></indexterm>
578 </term>
579 <listitem>
580 <para>Compile via C instead of using the native code
581 generator. This is the default on architectures for which GHC
582 doesn't have a native code generator.</para>
583 </listitem>
584 </varlistentry>
585
586 <varlistentry>
587 <term>
588 <option>-fno-code</option>
589 <indexterm><primary><option>-fno-code</option></primary></indexterm>
590 </term>
591 <listitem>
592 <para>Omit code generation (and all later phases)
593 altogether. Might be of some use if you just want to see
594 dumps of the intermediate compilation phases.</para>
595 </listitem>
596 </varlistentry>
597
598 <varlistentry>
599 <term>
600 <option>-fPIC</option>
601 <indexterm><primary><option>-fPIC</option></primary></indexterm>
602 </term>
603 <listitem>
604 <para>Generate position-independent code (code that can be put into
605 shared libraries). This currently works on Mac OS X; it works on
606 PowerPC Linux when using the native code generator (-fasm).
607 It is not quite ready to be used yet for x86 Linux.
608 On Windows, position-independent code is never used,
609 and on PowerPC64 Linux, position-independent code is always used,
610 so the flag is a no-op on those platforms.</para>
611 </listitem>
612 </varlistentry>
613
614 <varlistentry>
615 <term>
616 <option>-dynamic</option>
617 </term>
618 <listitem>
619 <para>When generating code, assume that entities imported from a
620 different package will reside in a different shared library or
621 binary. This currently works on Mac OS X; it works on PowerPC Linux when
622 using the native code generator. As with <option>-fPIC</option>,
623 x86 Linux support is not quite ready yet. Windows is not supported,
624 and it is a no-op on PowerPC64 Linux.</para>
625 <para>Note that this option also causes GHC to use shared libraries
626 when linking.</para>
627 </listitem>
628 </varlistentry>
629 </variablelist>
630 </sect2>
631
632 <sect2 id="options-linker">
633 <title>Options affecting linking</title>
634
635 <indexterm><primary>linker options</primary></indexterm>
636 <indexterm><primary>ld options</primary></indexterm>
637
638
639 <para>GHC has to link your code with various libraries, possibly
640 including: user-supplied, GHC-supplied, and system-supplied
641 (<option>-lm</option> math library, for example).</para>
642
643 <variablelist>
644
645 <varlistentry>
646 <term>
647 <option>-l</option><replaceable>lib</replaceable>
648 <indexterm><primary><option>-l</option></primary></indexterm>
649 </term>
650 <listitem>
651 <para>Link in the <replaceable>lib</replaceable> library.
652 On Unix systems, this will be in a file called
653 <filename>lib<replaceable>lib</replaceable>.a</filename>
654 or
655 <filename>lib<replaceable>lib</replaceable>.so</filename>
656 which resides somewhere on the library directories path.</para>
657
658 <para>Because of the sad state of most UNIX linkers, the
659 order of such options does matter. If library
660 <replaceable>foo</replaceable> requires library
661 <replaceable>bar</replaceable>, then in general
662 <option>-l</option><replaceable>foo</replaceable> should
663 come <emphasis>before</emphasis>
664 <option>-l</option><replaceable>bar</replaceable> on the
665 command line.</para>
666
667 <para>There's one other gotcha to bear in mind when using
668 external libraries: if the library contains a
669 <literal>main()</literal> function, then this will be
670 linked in preference to GHC's own
671 <literal>main()</literal> function
672 (eg. <literal>libf2c</literal> and <literal>libl</literal>
673 have their own <literal>main()</literal>s). This is
674 because GHC's <literal>main()</literal> comes from the
675 <literal>HSrts</literal> library, which is normally
676 included <emphasis>after</emphasis> all the other
677 libraries on the linker's command line. To force GHC's
678 <literal>main()</literal> to be used in preference to any
679 other <literal>main()</literal>s from external libraries,
680 just add the option <option>-lHSrts</option> before any
681 other libraries on the command line.</para>
682 </listitem>
683 </varlistentry>
684
685 <varlistentry>
686 <term>
687 <option>-c</option>
688 <indexterm><primary><option>-c</option></primary></indexterm>
689 </term>
690 <listitem>
691 <para>Omits the link step. This option can be used with
692 <option>&ndash;&ndash;make</option> to avoid the automatic linking
693 that takes place if the program contains a <literal>Main</literal>
694 module.</para>
695 </listitem>
696 </varlistentry>
697
698 <varlistentry>
699 <term>
700 <option>-package</option> <replaceable>name</replaceable>
701 <indexterm><primary><option>-package</option></primary></indexterm>
702 </term>
703 <listitem>
704 <para>If you are using a Haskell &ldquo;package&rdquo;
705 (see <xref linkend="packages"/>), don't forget to add the
706 relevant <option>-package</option> option when linking the
707 program too: it will cause the appropriate libraries to be
708 linked in with the program. Forgetting the
709 <option>-package</option> option will likely result in
710 several pages of link errors.</para>
711 </listitem>
712 </varlistentry>
713
714 <varlistentry>
715 <term>
716 <option>-framework</option> <replaceable>name</replaceable>
717 <indexterm><primary><option>-framework</option></primary></indexterm>
718 </term>
719 <listitem>
720 <para>On Darwin/MacOS X only, link in the framework <replaceable>name</replaceable>.
721 This option corresponds to the <option>-framework</option> option for Apple's Linker.
722 Please note that frameworks and packages are two different things - frameworks don't
723 contain any haskell code. Rather, they are Apple's way of packaging shared libraries.
724 To link to Apple's &ldquo;Carbon&rdquo; API, for example, you'd use
725 <option>-framework Carbon</option>.
726 </para>
727 </listitem>
728 </varlistentry>
729
730 <varlistentry>
731 <term>
732 <option>-L</option><replaceable>dir</replaceable>
733 <indexterm><primary><option>-L</option></primary></indexterm>
734 </term>
735 <listitem>
736 <para>Where to find user-supplied libraries&hellip;
737 Prepend the directory <replaceable>dir</replaceable> to
738 the library directories path.</para>
739 </listitem>
740 </varlistentry>
741
742 <varlistentry>
743 <term>
744 <option>-framework-path</option><replaceable>dir</replaceable>
745 <indexterm><primary><option>-framework-path</option></primary></indexterm>
746 </term>
747 <listitem>
748 <para>On Darwin/MacOS X only, prepend the directory <replaceable>dir</replaceable> to
749 the framework directories path. This option corresponds to the <option>-F</option>
750 option for Apple's Linker (<option>-F</option> already means something else for GHC).</para>
751 </listitem>
752 </varlistentry>
753
754 <varlistentry>
755 <term>
756 <option>-split-objs</option>
757 <indexterm><primary><option>-split-objs</option></primary></indexterm>
758 </term>
759 <listitem>
760 <para>Tell the linker to split the single object file that
761 would normally be generated into multiple object files,
762 one per top-level Haskell function or type in the module.
763 This only makes sense for libraries, where it means that
764 executables linked against the library are smaller as they only
765 link against the object files that they need. However, assembling
766 all the sections separately is expensive, so this is slower than
767 compiling normally.
768 We use this feature for building GHC's libraries
769 (warning: don't use it unless you know what you're
770 doing!).</para>
771 </listitem>
772 </varlistentry>
773
774 <varlistentry>
775 <term>
776 <option>-static</option>
777 <indexterm><primary><option>-static</option></primary></indexterm>
778 </term>
779 <listitem>
780 <para>Tell the linker to avoid shared Haskell libraries,
781 if possible. This is the default.</para>
782 </listitem>
783 </varlistentry>
784
785 <varlistentry>
786 <term>
787 <option>-dynamic</option>
788 <indexterm><primary><option>-dynamic</option></primary></indexterm>
789 </term>
790 <listitem>
791 <para>Tell the linker to use shared Haskell libraries, if
792 available (this option is only supported on Mac OS X at the
793 moment, and also note that your distribution of GHC may
794 not have been supplied with shared libraries).</para>
795 <para>Note that this option also has an effect on
796 code generation (see above).</para>
797 </listitem>
798 </varlistentry>
799
800 <varlistentry>
801 <term>
802 <option>-main-is <replaceable>thing</replaceable></option>
803 <indexterm><primary><option>-main-is</option></primary></indexterm>
804 <indexterm><primary>specifying your own main function</primary></indexterm>
805 </term>
806 <listitem>
807 <para> The normal rule in Haskell is that your program must supply a <literal>main</literal>
808 function in module <literal>Main</literal>. When testing, it is often convenient
809 to change which function is the "main" one, and the <option>-main-is</option> flag
810 allows you to do so. The <replaceable>thing</replaceable> can be one of:
811 <itemizedlist>
812 <listitem><para>A lower-case identifier <literal>foo</literal>. GHC assumes that the main function is <literal>Main.foo</literal>.</para></listitem>
813 <listitem><para>An module name <literal>A</literal>. GHC assumes that the main function is <literal>A.main</literal>.</para></listitem>
814 <listitem><para>An qualified name <literal>A.foo</literal>. GHC assumes that the main function is <literal>A.foo</literal>.</para></listitem>
815 </itemizedlist>
816 Strictly speaking, <option>-main-is</option> is not a link-phase flag at all; it has no effect on the link step.
817 The flag must be specified when compiling the module containing the specified main function (e.g. module <literal>A</literal>
818 in the latter two items above). It has no effect for other modules,
819 and hence can safely be given to <literal>ghc --make</literal>.
820 However, if all the modules are otherwise up to date, you may need to force
821 recompilation both of the module where the new "main" is, and of the
822 module where the "main" function used to be;
823 <literal>ghc</literal> is not clever
824 enough to figure out that they both need recompiling. You can
825 force recompilation by removing the object file, or by using the
826 <option>-fforce-recomp</option> flag.
827 </para>
828 </listitem>
829 </varlistentry>
830
831 <varlistentry>
832 <term>
833 <option>-no-hs-main</option>
834 <indexterm><primary><option>-no-hs-main</option></primary></indexterm>
835 <indexterm><primary>linking Haskell libraries with foreign code</primary></indexterm>
836 </term>
837 <listitem>
838 <para>In the event you want to include ghc-compiled code
839 as part of another (non-Haskell) program, the RTS will not
840 be supplying its definition of <function>main()</function>
841 at link-time, you will have to. To signal that to the
842 compiler when linking, use
843 <option>-no-hs-main</option>. See also <xref linkend="using-own-main"/>.</para>
844
845 <para>Notice that since the command-line passed to the
846 linker is rather involved, you probably want to use
847 <command>ghc</command> to do the final link of your
848 `mixed-language' application. This is not a requirement
849 though, just try linking once with <option>-v</option> on
850 to see what options the driver passes through to the
851 linker.</para>
852
853 <para>The <option>-no-hs-main</option> flag can also be
854 used to persuade the compiler to do the link step in
855 <option>--make</option> mode when there is no Haskell
856 <literal>Main</literal> module present (normally the
857 compiler will not attempt linking when there is no
858 <literal>Main</literal>).</para>
859 </listitem>
860 </varlistentry>
861
862 <varlistentry>
863 <term>
864 <option>-debug</option>
865 <indexterm><primary><option>-debug</option></primary></indexterm>
866 </term>
867 <listitem>
868 <para>Link the program with a debugging version of the
869 runtime system. The debugging runtime turns on numerous
870 assertions and sanity checks, and provides extra options
871 for producing debugging output at runtime (run the program
872 with <literal>+RTS&nbsp;-?</literal> to see a list).</para>
873 </listitem>
874 </varlistentry>
875
876 <varlistentry>
877 <term>
878 <option>-threaded</option>
879 <indexterm><primary><option>-threaded</option></primary></indexterm>
880 </term>
881 <listitem>
882 <para>Link the program with the "threaded" version of the
883 runtime system. The threaded runtime system is so-called
884 because it manages multiple OS threads, as opposed to the
885 default runtime system which is purely
886 single-threaded.</para>
887
888 <para>Note that you do <emphasis>not</emphasis> need
889 <option>-threaded</option> in order to use concurrency; the
890 single-threaded runtime supports concurrency between Haskell
891 threads just fine.</para>
892
893 <para>The threaded runtime system provides the following
894 benefits:</para>
895
896 <itemizedlist>
897 <listitem>
898 <para>Parallelism<indexterm><primary>parallelism</primary></indexterm> on a multiprocessor<indexterm><primary>multiprocessor</primary></indexterm><indexterm><primary>SMP</primary></indexterm> or multicore<indexterm><primary>multicore</primary></indexterm>
899 machine. See <xref linkend="using-smp" />.</para>
900
901 <para>The ability to make a foreign call that does not
902 block all other Haskell threads.</para>
903
904 <para>The ability to invoke foreign exported Haskell
905 functions from multiple OS threads.</para>
906 </listitem>
907 </itemizedlist>
908
909 <para>With <option>-threaded</option>, calls to foreign
910 functions are made using the same OS thread that created the
911 Haskell thread (if it was created by a call to a foreign
912 exported Haskell function), or an arbitrary OS thread
913 otherwise (if the Haskell thread was created by
914 <literal>forkIO</literal>).</para>
915
916 <para>More details on the use of "bound threads" in the
917 threaded runtime can be found in the <ulink
918 url="../libraries/base/Control.Concurrent.html"><literal>Control.Concurrent</literal></ulink> module.</para>
919 </listitem>
920 </varlistentry>
921 </variablelist>
922 </sect2>
923
924 </sect1>
925
926 <!-- Emacs stuff:
927 ;;; Local Variables: ***
928 ;;; mode: xml ***
929 ;;; sgml-parent-document: ("users_guide.xml" "book" "chapter" "sect1") ***
930 ;;; End: ***
931 -->