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