Implement function-sections for Haskell code, #8405
[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 ``-split-sections``
617     .. index::
618        single: -split-sections
619
620     Place each generated function or data item into its own section in the
621     output file if the target supports arbitrary sections. The name of the
622     function or the name of the data item determines the section's name in the
623     output file.
624
625     When linking, the linker can automatically remove all unreferenced sections
626     and thus produce smaller executables. The effect is similar to
627     ``-split-objs``, but somewhat more efficient - the generated library files
628     are about 30% smaller than with ``-split-objs``.
629
630 ``-static``
631     .. index::
632        single: -static
633
634     Tell the linker to avoid shared Haskell libraries, if possible. This
635     is the default.
636
637 ``-dynamic``
638     .. index::
639        single: -dynamic
640
641     This flag tells GHC to link against shared Haskell libraries. This
642     flag only affects the selection of dependent libraries, not the form
643     of the current target (see -shared). See :ref:`using-shared-libs` on
644     how to create them.
645
646     Note that this option also has an effect on code generation (see
647     above).
648
649 ``-shared``
650     .. index::
651        single: -shared
652
653     Instead of creating an executable, GHC produces a shared object with
654     this linker flag. Depending on the operating system target, this
655     might be an ELF DSO, a Windows DLL, or a Mac OS dylib. GHC hides the
656     operating system details beneath this uniform flag.
657
658     The flags ``-dynamic``/``-static`` control whether the resulting
659     shared object links statically or dynamically to Haskell package
660     libraries given as ``-package`` option. Non-Haskell libraries are
661     linked as gcc would regularly link it on your system, e.g. on most
662     ELF system the linker uses the dynamic libraries when found.
663
664     Object files linked into shared objects must be compiled with
665     ``-fPIC``, see :ref:`options-codegen`
666
667     When creating shared objects for Haskell packages, the shared object
668     must be named properly, so that GHC recognizes the shared object
669     when linked against this package. See shared object name mangling.
670
671 ``-dynload``
672     .. index::
673        single: -dynload
674
675     This flag selects one of a number of modes for finding shared
676     libraries at runtime. See :ref:`finding-shared-libs` for a
677     description of each mode.
678
679 ``-main-is ⟨thing⟩``
680     .. index::
681        single: -main-is
682        single: specifying your own main function
683
684     The normal rule in Haskell is that your program must supply a
685     ``main`` function in module ``Main``. When testing, it is often
686     convenient to change which function is the "main" one, and the
687     ``-main-is`` flag allows you to do so. The ⟨thing⟩ can be one of:
688
689     -  A lower-case identifier ``foo``. GHC assumes that the main
690        function is ``Main.foo``.
691
692     -  A module name ``A``. GHC assumes that the main function is
693        ``A.main``.
694
695     -  A qualified name ``A.foo``. GHC assumes that the main function is
696        ``A.foo``.
697
698     Strictly speaking, ``-main-is`` is not a link-phase flag at all; it
699     has no effect on the link step. The flag must be specified when
700     compiling the module containing the specified main function (e.g.
701     module ``A`` in the latter two items above). It has no effect for
702     other modules, and hence can safely be given to ``ghc --make``.
703     However, if all the modules are otherwise up to date, you may need
704     to force recompilation both of the module where the new "main" is,
705     and of the module where the "main" function used to be; ``ghc`` is
706     not clever enough to figure out that they both need recompiling. You
707     can force recompilation by removing the object file, or by using the
708     ``-fforce-recomp`` flag.
709
710 ``-no-hs-main``
711     .. index::
712        single: -no-hs-main
713        single: linking Haskell libraries with foreign code
714
715     In the event you want to include ghc-compiled code as part of
716     another (non-Haskell) program, the RTS will not be supplying its
717     definition of ``main()`` at link-time, you will have to. To signal
718     that to the compiler when linking, use ``-no-hs-main``. See also
719     :ref:`using-own-main`.
720
721     Notice that since the command-line passed to the linker is rather
722     involved, you probably want to use ``ghc`` to do the final link of
723     your \`mixed-language' application. This is not a requirement
724     though, just try linking once with ``-v`` on to see what options the
725     driver passes through to the linker.
726
727     The ``-no-hs-main`` flag can also be used to persuade the compiler
728     to do the link step in ``--make`` mode when there is no Haskell
729     ``Main`` module present (normally the compiler will not attempt
730     linking when there is no ``Main``).
731
732     The flags ``-rtsopts`` and ``-with-rtsopts`` have no effect when
733     used with ``-no-hs-main``, because they are implemented by changing
734     the definition of ``main`` that GHC generates. See
735     :ref:`using-own-main` for how to get the effect of ``-rtsopts`` and
736     ``-with-rtsopts`` when using your own ``main``.
737
738 ``-debug``
739     .. index::
740        single: -debug
741
742     Link the program with a debugging version of the runtime system. The
743     debugging runtime turns on numerous assertions and sanity checks,
744     and provides extra options for producing debugging output at runtime
745     (run the program with ``+RTS -?`` to see a list).
746
747 ``-threaded``
748     .. index::
749        single: -threaded
750
751     Link the program with the "threaded" version of the runtime system.
752     The threaded runtime system is so-called because it manages multiple
753     OS threads, as opposed to the default runtime system which is purely
754     single-threaded.
755
756     Note that you do *not* need ``-threaded`` in order to use
757     concurrency; the single-threaded runtime supports concurrency
758     between Haskell threads just fine.
759
760     The threaded runtime system provides the following benefits:
761
762     -  It enables the ``-N``\ ``-Nx``\ RTS option RTS option to be used,
763        which allows threads to run in parallelparallelism on a
764        multiprocessormultiprocessorSMP or multicoremulticore machine.
765        See :ref:`using-smp`.
766
767     -  If a thread makes a foreign call (and the call is not marked
768        ``unsafe``), then other Haskell threads in the program will
769        continue to run while the foreign call is in progress.
770        Additionally, ``foreign export``\ ed Haskell functions may be
771        called from multiple OS threads simultaneously. See
772        :ref:`ffi-threads`.
773
774 ``-eventlog``
775     .. index::
776        single: -eventlog
777
778     Link the program with the "eventlog" version of the runtime system.
779     A program linked in this way can generate a runtime trace of events
780     (such as thread start/stop) to a binary file ``program.eventlog``,
781     which can then be interpreted later by various tools. See
782     :ref:`rts-eventlog` for more information.
783
784     ``-eventlog`` can be used with ``-threaded``. It is implied by
785     ``-debug``.
786
787 ``-rtsopts``
788     .. index::
789        single: -rtsopts
790
791     This option affects the processing of RTS control options given
792     either on the command line or via the ``GHCRTS`` environment
793     variable. There are three possibilities:
794
795     ``-rtsopts=none``
796         Disable all processing of RTS options. If ``+RTS`` appears
797         anywhere on the command line, then the program will abort with
798         an error message. If the ``GHCRTS`` environment variable is set,
799         then the program will emit a warning message, ``GHCRTS`` will be
800         ignored, and the program will run as normal.
801
802     ``-rtsopts=some``
803         [this is the default setting] Enable only the "safe" RTS
804         options: (Currently only ``-?`` and ``--info``.) Any other RTS
805         options on the command line or in the ``GHCRTS`` environment
806         variable causes the program with to abort with an error message.
807
808     ``-rtsopts=all`` or just ``-rtsopts``
809         Enable *all* RTS option processing, both on the command line and
810         through the ``GHCRTS`` environment variable.
811
812     In GHC 6.12.3 and earlier, the default was to process all RTS
813     options. However, since RTS options can be used to write logging
814     data to arbitrary files under the security context of the running
815     program, there is a potential security problem. For this reason, GHC
816     7.0.1 and later default to ``-rtsops=some``.
817
818     Note that ``-rtsopts`` has no effect when used with ``-no-hs-main``;
819     see :ref:`using-own-main` for details.
820
821 ``-with-rtsopts``
822     .. index::
823        single: -with-rtsopts
824
825     This option allows you to set the default RTS options at link-time.
826     For example, ``-with-rtsopts="-H128m"`` sets the default heap size
827     to 128MB. This will always be the default heap size for this
828     program, unless the user overrides it. (Depending on the setting of
829     the ``-rtsopts`` option, the user might not have the ability to
830     change RTS options at run-time, in which case ``-with-rtsopts``
831     would be the *only* way to set them.)
832
833     Note that ``-with-rtsopts`` has no effect when used with
834     ``-no-hs-main``; see :ref:`using-own-main` for details.
835
836 ``-no-rtsopts-suggestions``
837     .. index::
838        single: -no-rtsopts-suggestions
839
840     This option disables RTS suggestions about linking with ``-rtsopts``
841     when they are not available. These suggestions would be unhelpful if
842     the users have installed Haskell programs through their package
843     managers. With this option enabled, these suggestions will not
844     appear. It is recommended for people distributing binaries to build
845     with either ``-rtsopts`` or ``-no-rtsopts-suggestions``.
846
847 ``-fno-gen-manifest``
848     .. index::
849        single: -fno-gen-manifest
850
851     On Windows, GHC normally generates a manifestmanifest file when
852     linking a binary. The manifest is placed in the file
853     ``prog.exe.manifest`` where ⟨prog.exe⟩ is the name of the
854     executable. The manifest file currently serves just one purpose: it
855     disables the "installer detection"installer detectionin Windows
856     Vista that attempts to elevate privileges for executables with
857     certain names (e.g. names containing "install", "setup" or "patch").
858     Without the manifest file to turn off installer detection,
859     attempting to run an executable that Windows deems to be an
860     installer will return a permission error code to the invoker.
861     Depending on the invoker, the result might be a dialog box asking
862     the user for elevated permissions, or it might simply be a
863     permission denied error.
864
865     Installer detection can be also turned off globally for the system
866     using the security control panel, but GHC by default generates
867     binaries that don't depend on the user having disabled installer
868     detection.
869
870     The ``-fno-gen-manifest`` disables generation of the manifest file.
871     One reason to do this would be if you had a manifest file of your
872     own, for example.
873
874     In the future, GHC might use the manifest file for more things, such
875     as supplying the location of dependent DLLs.
876
877     ``-fno-gen-manifest`` also implies ``-fno-embed-manifest``, see
878     below.
879
880 ``-fno-embed-manifest``
881     .. index::
882        single: -fno-embed-manifest
883        single: windres
884
885     The manifest file that GHC generates when linking a binary on
886     Windows is also embedded in the executable itself, by default. This
887     means that the binary can be distributed without having to supply
888     the manifest file too. The embedding is done by running
889     ``windres``; to see exactly what GHC does to embed the
890     manifest, use the ``-v`` flag. A GHC installation comes with its own
891     copy of ``windres`` for this reason.
892
893     See also ``-pgmwindres`` (:ref:`replacing-phases`) and
894     ``-optwindres`` (:ref:`forcing-options-through`).
895
896 ``-fno-shared-implib``
897     .. index::
898        single: -fno-shared-implib
899
900     DLLs on Windows are typically linked to by linking to a
901     corresponding ``.lib`` or ``.dll.a`` — the so-called import library.
902     GHC will typically generate such a file for every DLL you create by
903     compiling in ``-shared`` mode. However, sometimes you don't want to
904     pay the disk-space cost of creating this import library, which can
905     be substantial — it might require as much space as the code itself,
906     as Haskell DLLs tend to export lots of symbols.
907
908     As long as you are happy to only be able to link to the DLL using
909     ``GetProcAddress`` and friends, you can supply the
910     ``-fno-shared-implib`` flag to disable the creation of the import
911     library entirely.
912
913 ``-dylib-install-name path``
914     .. index::
915        single: -dylib-install-name
916
917     On Darwin/OS X, dynamic libraries are stamped at build time with an
918     "install name", which is the ultimate install path of the library
919     file. Any libraries or executables that subsequently link against it
920     will pick up that path as their runtime search location for it. By
921     default, ghc sets the install name to the location where the library
922     is built. This option allows you to override it with the specified
923     file path. (It passes ``-install_name`` to Apple's linker.) Ignored
924     on other platforms.
925
926 ``-rdynamic``
927     .. index::
928        single: -rdynamic
929
930     This instructs the linker to add all symbols, not only used ones, to
931     the dynamic symbol table. Currently Linux and Windows/MinGW32 only.
932     This is equivalent to using ``-optl -rdynamic`` on Linux, and
933     ``-optl -export-all-symbols`` on Windows.