5.11. Options related to a particular phase

5.11.1. Replacing the program for one or more phases

You may specify that a different program be used for one of the phases of the compilation system, in place of whatever the ghc has wired into it. For example, you might want to try a different assembler. The following options allow you to change the external program used for a given compilation phase:

-pgmL ⟨cmd⟩

Use ⟨cmd⟩ as the literate pre-processor.

-pgmP ⟨cmd⟩

Use ⟨cmd⟩ as the C pre-processor (with -cpp only).

-pgmc ⟨cmd⟩

Use ⟨cmd⟩ as the C compiler.

-pgmcxx ⟨cmd⟩

Use ⟨cmd⟩ as the C++ compiler.

-pgmlo ⟨cmd⟩

Use ⟨cmd⟩ as the LLVM optimiser.

-pgmlc ⟨cmd⟩

Use ⟨cmd⟩ as the LLVM compiler.

-pgms ⟨cmd⟩

Use ⟨cmd⟩ as the splitter.

-pgma ⟨cmd⟩

Use ⟨cmd⟩ as the assembler.

-pgml ⟨cmd⟩

Use ⟨cmd⟩ as the linker.

-pgmlm ⟨cmd⟩

Use ⟨cmd⟩ as the linker when merging object files (e.g. when generating joined objects for loading into GHCi).

-pgmdll ⟨cmd⟩

Use ⟨cmd⟩ as the DLL generator.

-pgmF ⟨cmd⟩

Use ⟨cmd⟩ as the pre-processor (with -F only).

-pgmotool ⟨cmd⟩

Use ⟨cmd⟩ as the program to inspect mach-o dynamic libraries and executables to read the dynamic library dependencies. We will compute the necessary runpath``s to embed for the dependencies based on the result of the ``otool call.

-pgminstall_name_tool ⟨cmd⟩

Use ⟨cmd⟩ as the program to inject runpath``s into mach-o dynamic libraries and executables.  As detected by the ``otool call.

-pgmwindres ⟨cmd⟩

Use ⟨cmd⟩ as the program to use for embedding manifests on Windows. Normally this is the program windres, which is supplied with a GHC installation. See -fno-embed-manifest in Options affecting linking.

-pgmi ⟨cmd⟩

Use ⟨cmd⟩ as the external interpreter command (see Running the interpreter in a separate process). Default: ghc-iserv-prof if -prof is enabled, ghc-iserv-dyn if -dynamic is enabled, or ghc-iserv otherwise.

5.11.2. Forcing options to a particular phase

Options can be forced through to a particular compilation phase, using the following flags:

-optL ⟨option⟩

Pass ⟨option⟩ to the literate pre-processor

-optP ⟨option⟩

Pass ⟨option⟩ to CPP (makes sense only if -cpp is also on).

-optF ⟨option⟩

Pass ⟨option⟩ to the custom pre-processor (see Options affecting a Haskell pre-processor).

-optc ⟨option⟩

Pass ⟨option⟩ to the C compiler.

-pgmc-supports-no-pie

Does the same thing as -pgml-supports-no-pie, which replaced it.

-pgml-supports-no-pie

When -pgml is used, GHC by default will never pass the -no-pie command line flag. The rationale is that it is not known whether the specified compiler used for linking (recall we use a C compiler to invoke the linker on our behalf) will support it. This flag can be used to indicate that -no-pie is supported. It has to be passed after -pgml.

This flag is not necessary when -pgmc is not used, since GHC remembers whether the default C compiler supports -no-pie in an internal settings file.

-optcxx ⟨option⟩

Pass ⟨option⟩ to the C++ compiler.

-optlo ⟨option⟩

Pass ⟨option⟩ to the LLVM optimiser.

-optlc ⟨option⟩

Pass ⟨option⟩ to the LLVM compiler.

-opta ⟨option⟩

Pass ⟨option⟩ to the assembler.

-optl ⟨option⟩

Pass ⟨option⟩ to the linker.

-optlm ⟨option⟩

Pass ⟨option⟩ to the linker when merging object files. In the case of a standard ld-style linker this should generally include the -r flag.

-optdll ⟨option⟩

Pass ⟨option⟩ to the DLL generator.

-optwindres ⟨option⟩

Pass ⟨option⟩ to windres when embedding manifests on Windows. See -fno-embed-manifest in Options affecting linking.

-opti ⟨option⟩

Pass ⟨option⟩ to the interpreter sub-process (see Running the interpreter in a separate process). A common use for this is to pass RTS options e.g., -opti+RTS -opti-A64m, or to enable verbosity with -opti-v to see what messages are being exchanged by GHC and the interpreter.

So, for example, to force an -Ewurble option to the assembler, you would tell the driver -opta-Ewurble (the dash before the E is required).

GHC is itself a Haskell program, so if you need to pass options directly to GHC’s runtime system you can enclose them in +RTS ... -RTS (see Runtime system (RTS) options).

5.11.3. Options affecting the C pre-processor

CPP

Since:6.8.1

The CPP language extension enables the C pre-processor. This can be turned into a command-line flag by prefixing it with -X; For example:

$ ghc -XCPP foo.hs

The CPP language extension can also be enabled using the LANGUAGE pragma; For example:

{-# LANGUAGE CPP #-}

-cpp

The C pre-processor cpp is run over your Haskell code if the -cpp option or -XCPP extension are given. Unless you are building a large system with significant doses of conditional compilation, you really shouldn’t need it.

-D⟨symbol⟩[=⟨value⟩]

Define macro ⟨symbol⟩ in the usual way. When no value is given, the value is taken to be 1. For instance, -DUSE_MYLIB is equivalent to -DUSE_MYLIB=1.

Note

-D⟨symbol⟩[=⟨value⟩] does not affect -D macros passed to the C compiler when compiling an unregisterised build! In this case use the -optc-Dfoo hack… (see Forcing options to a particular phase).

-U⟨symbol⟩

Undefine macro ⟨symbol⟩ in the usual way.

-I⟨dir⟩

Specify a directory in which to look for #include files, in the usual C way.

The GHC driver pre-defines several macros when processing Haskell source code (.hs or .lhs files).

5.11.3.1. Standard CPP macros

The symbols defined by GHC are listed below. To check which symbols are defined by your local GHC installation, the following trick is useful:

$ ghc -E -optP-dM -cpp foo.hs
$ cat foo.hspp

(you need a file foo.hs, but it isn’t actually used).

__GLASGOW_HASKELL__

For version x.y.z of GHC, the value of __GLASGOW_HASKELL__ is the integer ⟨xyy⟩ (if ⟨y⟩ is a single digit, then a leading zero is added, so for example in version 6.2 of GHC, __GLASGOW_HASKELL__==602). More information in GHC version numbering policy.

With any luck, __GLASGOW_HASKELL__ will be undefined in all other implementations that support C-style pre-processing.

Note

The comparable symbols for other systems are: __HUGS__ for Hugs, __NHC__ for nhc98, and __HBC__ for hbc).

NB. This macro is set when pre-processing both Haskell source and C source, including the C source generated from a Haskell module (i.e. .hs, .lhs, .c and .hc files).

__GLASGOW_HASKELL_FULL_VERSION__

__GLASGOW_HASKELL_PATCHLEVEL1__; __GLASGOW_HASKELL_PATCHLEVEL2__

These macros are available starting with GHC 7.10.1.

For three-part GHC version numbers x.y.z, the value of __GLASGOW_HASKELL_PATCHLEVEL1__ is the integer ⟨z⟩.

For four-part GHC version numbers x.y.z.z', the value of __GLASGOW_HASKELL_PATCHLEVEL1__ is the integer ⟨z⟩ while the value of __GLASGOW_HASKELL_PATCHLEVEL2__ is set to the integer ⟨z’⟩.

These macros are provided for allowing finer granularity than is provided by __GLASGOW_HASKELL__. Usually, this should not be necessary as it’s expected for most APIs to remain stable between patchlevel releases, but occasionally internal API changes are necessary to fix bugs. Also conditional compilation on the patchlevel can be useful for working around bugs in older releases.

Tip

These macros are set when pre-processing both Haskell source and C source, including the C source generated from a Haskell module (i.e. .hs, .lhs, .c and .hc files).

MIN_VERSION_GLASGOW_HASKELL(x,y,z,z')

This macro is available starting with GHC 7.10.1.

This macro is provided for convenience to write CPP conditionals testing whether the GHC version used is version x.y.z.z' or later.

If compatibility with Haskell compilers (including GHC prior to version 7.10.1) which do not define MIN_VERSION_GLASGOW_HASKELL is required, the presence of the MIN_VERSION_GLASGOW_HASKELL macro needs to be ensured before it is called, e.g.:

#if defined(MIN_VERSION_GLASGOW_HASKELL)
#if MIN_VERSION_GLASGOW_HASKELL(7,10,2,0)
/* code that applies only to GHC 7.10.2 or later */
#endif
#endif

Tip

This macro is set when pre-processing both Haskell source and C source, including the C source generated from a Haskell module (i.e. .hs, .lhs, .c and .hc files).

__GLASGOW_HASKELL_TH__

This is set to 1 when the compiler supports Template Haskell, and to 0 when not. The latter is the case for a stage-1 compiler during bootstrapping, or on architectures where the interpreter is not available.

__GLASGOW_HASKELL_LLVM__

Only defined when :ghc-flag:-fllvm` is specified. When GHC is using version x.y.z of LLVM, the value of __GLASGOW_HASKELL_LLVM__ is the integer ⟨xyy⟩ (if ⟨y⟩ is a single digit, then a leading zero is added, so for example when using version 3.7 of LLVM, __GLASGOW_HASKELL_LLVM__==307).

__PARALLEL_HASKELL__

Only defined when -parallel is in use! This symbol is defined when pre-processing Haskell (input) and pre-processing C (GHC output).

os_HOST_OS=1

This define allows conditional compilation based on the Operating System, where⟨os⟩ is the name of the current Operating System (eg. linux, mingw32 for Windows, solaris, etc.).

arch_HOST_ARCH=1

This define allows conditional compilation based on the host architecture, where⟨arch⟩ is the name of the current architecture (eg. i386, x86_64, powerpc, sparc, etc.).

VERSION_pkgname

This macro is available starting GHC 8.0. It is defined for every exposed package. This macro expands to a string recording the version of pkgname that is exposed for module import. It is identical in behavior to the VERSION_pkgname macros that Cabal defines.

MIN_VERSION_pkgname(x,y,z)

This macro is available starting GHC 8.0. It is defined for every exposed package. This macro is provided for convenience to write CPP conditionals testing if a package version is x.y.z or later. It is identical in behavior to the MIN_VERSION_pkgname macros that Cabal defines.

5.11.3.2. CPP and string gaps

A small word of warning: -cpp is not friendly to “string gaps”. In other words, strings such as the following:

strmod = "\
\ p \
\ "

don’t work with -cpp; /usr/bin/cpp elides the backslash-newline pairs.

However, it appears that if you add a space at the end of the line, then cpp (at least GNU cpp and possibly other cpps) leaves the backslash-space pairs alone and the string gap works as expected.

5.11.4. Options affecting a Haskell pre-processor

-F

A custom pre-processor is run over your Haskell source file only if the -F option is given.

Running a custom pre-processor at compile-time is in some settings appropriate and useful. The -F option lets you run a pre-processor as part of the overall GHC compilation pipeline, which has the advantage over running a Haskell pre-processor separately in that it works in interpreted mode and you can continue to take reap the benefits of GHC’s recompilation checker.

The pre-processor is run just before the Haskell compiler proper processes the Haskell input, but after the literate markup has been stripped away and (possibly) the C pre-processor has washed the Haskell input.

Use -pgmF ⟨cmd⟩ to select the program to use as the preprocessor. When invoked, the ⟨cmd⟩ pre-processor is given at least three arguments on its command-line: the first argument is the name of the original source file, the second is the name of the file holding the input, and the third is the name of the file where ⟨cmd⟩ should write its output to.

Additional arguments to the pre-processor can be passed in using the -optF ⟨option⟩ option. These are fed to ⟨cmd⟩ on the command line after the three standard input and output arguments.

An example of a pre-processor is to convert your source files to the input encoding that GHC expects, i.e. create a script convert.sh containing the lines:

#!/bin/sh
( echo "{-# LINE 1 \"$1\" #-}" ; iconv -f l1 -t utf-8 $2 ) > $3

and pass -F -pgmF convert.sh to GHC. The -f l1 option tells iconv to convert your Latin-1 file, supplied in argument $2, while the “-t utf-8” options tell iconv to return a UTF-8 encoded file. The result is redirected into argument $3. The echo "{-# LINE 1 \"$1\" #-}" just makes sure that your error positions are reported as in the original source file.

5.11.5. Options affecting code generation

-fasm

Use GHC’s native code generator rather than compiling via LLVM. -fasm is the default.

-fllvm

Compile via LLVM instead of using the native code generator. This will generally take slightly longer than the native code generator to compile. Produced code is generally the same speed or faster than the other two code generators. Compiling via LLVM requires LLVM’s opt and llc executables to be in PATH.

Note

Note that this GHC release expects an LLVM version between 11 and 16.

-fno-code

Omit code generation (and all later phases) altogether. This is useful if you’re only interested in type checking code.

If a module contains a Template Haskell splice then in --make mode, code generation will be automatically turned on for all dependencies. By default object files are generated but if ghc-flag:-fprefer-byte-code is enable then byte-code will be generated instead.

-fwrite-interface

Always write interface files. GHC will normally write interface files automatically, but this flag is useful with -fno-code, which normally suppresses generation of interface files. This is useful if you want to type check over multiple runs of GHC without compiling dependencies.

-fwrite-if-simplified-core

The interface file will contain all the bindings for a module. From this interface file we can restart code generation to produce byte-code.

The definition of bindings which are included in this depend on the optimisation level. Any definitions which are already included in an interface file (via an unfolding for an exported identifier) are reused.

-fobject-code

Generate object code. This is the default outside of GHCi, and can be used with GHCi to cause object code to be generated in preference to byte-code. Therefore this flag disables -fbyte-code-and-object-code.

-fbyte-code

Generate byte-code instead of object-code. This is the default in GHCi. Byte-code can currently only be used in the interactive interpreter, not saved to disk. This option is only useful for reversing the effect of -fobject-code.

-fbyte-code-and-object-code

Generate object code and byte-code. This is useful with the flags -fprefer-byte-code and -fwrite-if-simplified-core.

This flag implies -fwrite-if-simplified-core.

-fbyte-code and -fobject-code disable this flag as they specify that GHC should only write object code or byte-code respectively.

-fPIC

Generate position-independent code (code that can be put into shared libraries). This currently works on Linux x86 and x86-64. On Windows, position-independent code is never used so the flag is a no-op on that platform.

-fexternal-dynamic-refs

When generating code, assume that entities imported from a different module might be dynamically linked. This flag is enabled automatically by -dynamic.

-fPIE

Generate code in such a way to be linkable into a position-independent executable This currently works on Linux x86 and x86-64. On Windows, position-independent code is never used so the flag is a no-op on that platform. To link the final executable use -pie.

-dynamic

Build code for dynamic linking. This can reduce code size tremendously, but may slow-down cross-module calls of non-inlined functions. There can be some complications combining -shared with this flag relating to linking in the RTS under Linux. See %s10352.

Note that using this option when linking causes GHC to link against shared libraries.

-dynamic-too

Generates both dynamic and static object files in a single run of GHC. This option is functionally equivalent to running GHC twice, the second time adding -dynamic -osuf dyn_o -hisuf dyn_hi.

Although it is equivalent to running GHC twice, using -dynamic-too is more efficient, because the earlier phases of the compiler up to code generation are performed just once.

When using -dynamic-too, the options -dyno, -dynosuf, and -dynhisuf are the counterparts of -o, -osuf, and -hisuf respectively, but applying to the dynamic compilation.

-dynamic-too is ignored if -dynamic is also specified.

-split-objs

When using this option, the object file is split into many smaller objects. This feature is used when building libraries, so that a program statically linked against the library will pull in less of the library.

Since this uses platform specific techniques, it may not be available on all target platforms. See the --print-object-splitting-supported flag to check whether your GHC supports object splitting.

-fexpose-internal-symbols

Request that GHC emits verbose symbol tables which include local symbols for module-internal functions. These can be useful for tools like perf but increase object file sizes. This is implied by -g2 and above.

-fno-expose-internal-symbols suppresses all non-global symbol table entries, resulting in smaller object file sizes at the expense of debuggability.

-fprefer-byte-code

If a home package module has byte-code available then use that instead of and object file (if that’s available) to evaluate and run TH splices.

This is useful with flags such as -fbyte-code-and-object-code, which tells the compiler to generate byte-code, and -fwrite-if-simplified-core which allows byte-code to be generated from an interface file.

This flag also interacts with -fno-code, if this flag is enabled then any modules which are required to be compiled for Template Haskell evaluation will generate byte-code rather than object code.

5.11.6. Options affecting linking

GHC has to link your code with various libraries, possibly including: user-supplied, GHC-supplied, and system-supplied (-lm math library, for example).

-l ⟨lib⟩

Link in the ⟨lib⟩ library. On Unix systems, this will be in a file called liblib.a or liblib.so which resides somewhere on the library directories path.

Because of the sad state of most UNIX linkers, the order of such options does matter. If library ⟨foo⟩ requires library ⟨bar⟩, then in general -l ⟨foo⟩ should come before -l ⟨bar⟩ on the command line.

There’s one other gotcha to bear in mind when using external libraries: if the library contains a main() function, then this will be a link conflict with GHC’s own main() function (eg. libf2c and libl have their own main()s).

You can use an external main function if you initialize the RTS manually and pass -no-hs-main. See also Using your own main().

-c

Omits the link step. This option can be used with --make to avoid the automatic linking that takes place if the program contains a Main module.

-package ⟨name⟩

If you are using a Haskell “package” (see Packages), don’t forget to add the relevant -package option when linking the program too: it will cause the appropriate libraries to be linked in with the program. Forgetting the -package option will likely result in several pages of link errors.

-framework ⟨name⟩

On Darwin/OS X/iOS only, link in the framework ⟨name⟩. This option corresponds to the -framework option for Apple’s Linker. Please note that frameworks and packages are two different things - frameworks don’t contain any Haskell code. Rather, they are Apple’s way of packaging shared libraries. To link to Apple’s “Carbon” API, for example, you’d use -framework Carbon.

-staticlib

Implies:-flink-rts

Link all passed files into a static library suitable for linking. To control the name, use the -o ⟨file⟩ option as usual. The default name is liba.a.

-L ⟨dir⟩

Where to find user-supplied libraries… Prepend the directory ⟨dir⟩ to the library directories path.

-fuse-rpaths

This flag is enabled by default and will set the rpath of the linked object to the library directories of dependent packages.

When building binaries to distribute it can be useful to pass your own linker options to control the rpath and disable the automatic injection of rpath entries by disabling this flag.

-framework-path ⟨dir⟩

On Darwin/OS X/iOS only, prepend the directory ⟨dir⟩ to the framework directories path. This option corresponds to the -F option for Apple’s Linker (-F already means something else for GHC).

-fsplit-sections

-split-sections

Place each generated function or data item into its own section in the output file if the target supports arbitrary sections. The name of the function or the name of the data item determines the section’s name in the output file.

When linking, the linker can automatically remove all unreferenced sections and thus produce smaller executables.

-static

Tell the linker to avoid shared Haskell libraries, if possible. This is the default.

-dynamic

This flag tells GHC to link against shared Haskell libraries. This flag only affects the selection of dependent libraries, not the form of the current target (see -shared). See Using shared libraries on how to create them.

Note that this option also has an effect on code generation (see above).

-shared

Instead of creating an executable, GHC produces a shared object with this linker flag. Depending on the operating system target, this might be an ELF DSO, a Windows DLL, or a Mac OS dylib. GHC hides the operating system details beneath this uniform flag.

The flags -dynamic and -static control whether the resulting shared object links statically or dynamically to Haskell package libraries given as -package ⟨pkg⟩ option. Non-Haskell libraries are linked as gcc would regularly link it on your system, e.g. on most ELF system the linker uses the dynamic libraries when found.

Object files linked into shared objects must be compiled with -fPIC, see Options affecting code generation

When creating shared objects for Haskell packages, the shared object must be named properly, so that GHC recognizes the shared object when linking against this package. See shared object name mangling for details.

-dynload

This flag selects one of a number of modes for finding shared libraries at runtime. See Finding shared libraries at runtime for a description of each mode.

-flink-rts

When linking shared libraries (-shared) GHC does not automatically link the RTS. This is to allow choosing the RTS flavour (-threaded, -eventlog, etc) when linking an executable. However when the shared library is the intended product it is useful to be able to reverse this default. See Shared libraries that export a C API for an usage example.

When linking a static library (-staticlib) GHC links the RTS automatically, you can reverse this behaviour by reversing this flag: -fno-link-rts.

-main-is ⟨thing⟩

The normal rule in Haskell is that your program must supply a main function in module Main. When testing, it is often convenient to change which function is the “main” one, and the -main-is flag allows you to do so. The ⟨thing⟩ can be one of:

• A lower-case identifier foo. GHC assumes that the main function is Main.foo.
• A module name A. GHC assumes that the main function is A.main.
• A qualified name A.foo. GHC assumes that the main function is A.foo.

Strictly speaking, -main-is is not a link-phase flag at all; it has no effect on the link step. The flag must be specified when compiling the module containing the specified main function (e.g. module A in the latter two items above). It has no effect for other modules, and hence can safely be given to ghc --make. However, if all the modules are otherwise up to date, you may need to force recompilation both of the module where the new “main” is, and of the module where the “main” function used to be; ghc is not clever enough to figure out that they both need recompiling. You can force recompilation by removing the object file, or by using the -fforce-recomp flag.

-no-hs-main

In the event you want to include ghc-compiled code as part of another (non-Haskell) program, the RTS will not be supplying its definition of main() at link-time, you will have to. To signal that to the compiler when linking, use -no-hs-main. See also Using your own main().

Notice that since the command-line passed to the linker is rather involved, you probably want to use ghc to do the final link of your `mixed-language’ application. This is not a requirement though, just try linking once with -v on to see what options the driver passes through to the linker.

The -no-hs-main flag can also be used to persuade the compiler to do the link step in --make mode when there is no Haskell Main module present (normally the compiler will not attempt linking when there is no Main).

The flags -rtsopts[=⟨none|some|all|ignore|ignoreAll⟩] and -with-rtsopts=⟨opts⟩ have no effect when used with -no-hs-main, because they are implemented by changing the definition of main that GHC generates. See Using your own main() for how to get the effect of -rtsopts[=⟨none|some|all|ignore|ignoreAll⟩] and -with-rtsopts=⟨opts⟩ when using your own main.

-debug

Link the program with a debugging version of the runtime system. The debugging runtime turns on numerous assertions and sanity checks, and provides extra options for producing debugging output at runtime (run the program with +RTS -? to see a list).

-threaded

Link the program with the “threaded” version of the runtime system. The threaded runtime system is so-called because it manages multiple OS threads, as opposed to the default runtime system which is purely single-threaded.

Note that you do not need -threaded in order to use concurrency; the single-threaded runtime supports concurrency between Haskell threads just fine.

The threaded runtime system provides the following benefits:

• It enables the -N ⟨x⟩ RTS option to be used, which allows threads to run in parallel on a multiprocessor or multicore machine. See Using SMP parallelism.
• If a thread makes a foreign call (and the call is not marked unsafe), then other Haskell threads in the program will continue to run while the foreign call is in progress. Additionally, foreign exported Haskell functions may be called from multiple OS threads simultaneously. See Multi-threading and the FFI.

-eventlog

Since:Unconditionally enabled with 9.4 and later

Link the program with the “eventlog” version of the runtime system. A program linked in this way can generate a runtime trace of events (such as thread start/stop) to a binary file program.eventlog, which can then be interpreted later by various tools. See Tracing for more information.

Note that as of GHC 9.4 and later eventlog support is included in the RTS by default and the -eventlog is deprecated.

-rtsopts[=⟨none|some|all|ignore|ignoreAll⟩]

Default:some

This option affects the processing of RTS control options given either on the command line or via the GHCRTS environment variable. There are five possibilities:

-rtsopts=none

Disable all processing of RTS options. If +RTS appears anywhere on the command line, then the program will abort with an error message. If the GHCRTS environment variable is set, then the program will emit a warning message, GHCRTS will be ignored, and the program will run as normal.

-rtsopts=ignore

Disables all processing of RTS options. Unlike none this treats all RTS flags appearing on the command line the same way as regular arguments. (Passing them on to your program as arguments). GHCRTS options will be processed normally.

-rtsopts=ignoreAll

Same as ignore but also ignores GHCRTS.

-rtsopts=some

[this is the default setting] Enable only the “safe” RTS options: (Currently only -? and --info.) Any other RTS options on the command line or in the GHCRTS environment variable causes the program with to abort with an error message.

-rtsopts=all or just -rtsopts

Enable all RTS option processing, both on the command line and through the GHCRTS environment variable.

In GHC 6.12.3 and earlier, the default was to process all RTS options. However, since RTS options can be used to write logging data to arbitrary files under the security context of the running program, there is a potential security problem. For this reason, GHC 7.0.1 and later default to -rtsopts=some.

Note that -rtsopts has no effect when used with -no-hs-main; see Using your own main() for details.

-rtsopts does not affect RTS options passed via -with-rtsopts; those are used regardless of -rtsopts.

-with-rtsopts=⟨opts⟩

This option allows you to set the default RTS options at link-time. For example, -with-rtsopts="-H128m" sets the default heap size to 128MB. This will always be the default heap size for this program, unless the user overrides it. (Depending on the setting of the -rtsopts option, the user might not have the ability to change RTS options at run-time, in which case -with-rtsopts would be the only way to set them.)

Use the runtime flag --info on the executable program to see the options set with -with-rtsopts.

Note that -with-rtsopts has no effect when used with -no-hs-main; see Using your own main() for details.

-no-rtsopts-suggestions

This option disables RTS suggestions about linking with -rtsopts[=⟨none|some|all|ignore|ignoreAll⟩] when they are not available. These suggestions would be unhelpful if the users have installed Haskell programs through their package managers. With this option enabled, these suggestions will not appear. It is recommended for people distributing binaries to build with either -rtsopts or -no-rtsopts-suggestions.

-fno-gen-manifest

On Windows, GHC normally generates a manifest file when linking a binary. The manifest is placed in the file prog.exe.manifest` where ⟨prog.exe⟩ is the name of the executable. The manifest file currently serves just one purpose: it disables the “installer detection” in Windows Vista that attempts to elevate privileges for executables with certain names (e.g. names containing “install”, “setup” or “patch”). Without the manifest file to turn off installer detection, attempting to run an executable that Windows deems to be an installer will return a permission error code to the invoker. Depending on the invoker, the result might be a dialog box asking the user for elevated permissions, or it might simply be a permission denied error.

Installer detection can be also turned off globally for the system using the security control panel, but GHC by default generates binaries that don’t depend on the user having disabled installer detection.

The -fno-gen-manifest disables generation of the manifest file. One reason to do this would be if you had a manifest file of your own, for example.

In the future, GHC might use the manifest file for more things, such as supplying the location of dependent DLLs.

-fno-gen-manifest also implies -fno-embed-manifest, see below.

-fno-embed-manifest

The manifest file that GHC generates when linking a binary on Windows is also embedded in the executable itself, by default. This means that the binary can be distributed without having to supply the manifest file too. The embedding is done by running windres; to see exactly what GHC does to embed the manifest, use the -v flag. A GHC installation comes with its own copy of windres for this reason.

See also -pgmwindres ⟨cmd⟩ (Replacing the program for one or more phases) and -optwindres ⟨option⟩ (Forcing options to a particular phase).

-fno-shared-implib

DLLs on Windows are typically linked to by linking to a corresponding .lib or .dll.a — the so-called import library. GHC will typically generate such a file for every DLL you create by compiling in -shared mode. However, sometimes you don’t want to pay the disk-space cost of creating this import library, which can be substantial — it might require as much space as the code itself, as Haskell DLLs tend to export lots of symbols.

As long as you are happy to only be able to link to the DLL using GetProcAddress and friends, you can supply the -fno-shared-implib flag to disable the creation of the import library entirely.

-dylib-install-name ⟨path⟩

On Darwin/OS X, dynamic libraries are stamped at build time with an “install name”, which is the ultimate install path of the library file. Any libraries or executables that subsequently link against it will pick up that path as their runtime search location for it. By default, ghc sets the install name to the location where the library is built. This option allows you to override it with the specified file path. (It passes -install_name to Apple’s linker.) Ignored on other platforms.

-rdynamic

This instructs the linker to add all symbols, not only used ones, to the dynamic symbol table. Currently Linux and Windows/MinGW32 only. This is equivalent to using -optl -rdynamic on Linux, and -optl -export-all-symbols on Windows.

-fwhole-archive-hs-libs

When linking a binary executable, this inserts the flag -Wl,--whole-archive before any -l flags for Haskell libraries, and -Wl,--no-whole-archive afterwards (on OS X, the flag is -Wl,-all_load, there is no equivalent for -Wl,--no-whole-archive). This flag also disables the use of -Wl,--gc-sections (-Wl,-dead_strip on OS X).

This is for specialist applications that may require symbols defined in these Haskell libraries at runtime even though they aren’t referenced by any other code linked into the executable. If you’re using -fwhole-archive-hs-libs, you probably also want -rdynamic.

-pie

Since:8.2.2

This instructs the linker to produce a position-independent executable. This flag is only valid while producing executables and all object code being linked must have been produced with -fPIE.

Position independent executables are required by some platforms as they enable address-space layout randomization (ASLR), a common security measure. They can also be useful as they can be dynamically loaded and used as shared libraries by other executables.

Position independent executables should be dynamically-linked (e.g. built with -dynamic and only loaded into other dynamically-linked executables to ensure that only one libHSrts is present if loaded into the address space of another Haskell process.

Also, you may need to use the -rdynamic flag to ensure that that symbols are not dropped from your PIE objects.

-no-pie

If required, the C compiler will still produce a PIE. Otherwise, this is the default. Refer to -pie for more information about PIEs.

-fkeep-cafs

Since:8.8.1

Disables the RTS’s normal behaviour of garbage-collecting CAFs (Constant Applicative Forms, in other words top-level expressions). This option is useful for specialised applications that do runtime dynamic linking, where code dynamically linked in the future might require the value of a CAF that would otherwise be garbage-collected.

-fcompact-unwind

Default:on Since:9.4.1

This instructs the linker to produce an executable that supports Apple’s compact unwinding sections. These are used by C++ and Objective-C code to unwind the stack when an exception occurs.

In theory, the older __eh_frame section should also be usable for this purpose, but this does not always work.