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