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