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