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