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