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