phases, changing 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 -pgmL Use cmd as the literate pre-processor. -pgmP cmd -pgmP Use cmd as the C pre-processor (with -cpp only). -pgmc cmd -pgmc Use cmd as the C compiler. -pgmlo cmd -pgmlo Use cmd as the LLVM optimiser. -pgmlc cmd -pgmlc Use cmd as the LLVM compiler. -pgms cmd -pgms Use cmd as the splitter. -pgma cmd -pgma Use cmd as the assembler. -pgml cmd -pgml Use cmd as the linker. -pgmdll cmd -pgmdll Use cmd as the DLL generator. -pgmF cmd -pgmF Use cmd as the pre-processor (with -F only). -pgmwindres cmd -pgmwindres 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 . -pgmlibtool cmd -pgmlibtool Use cmd as the libtool command (when using -staticlib only). forcing GHC-phase options Options can be forced through to a particular compilation phase, using the following flags: -optL option -optL Pass option to the literate pre-processor -optP option -optP Pass option to CPP (makes sense only if -cpp is also on). -optF option -optF Pass option to the custom pre-processor (see ). -optc option -optc Pass option to the C compiler. -optlo option -optlo Pass option to the LLVM optimiser. -optlc option -optlc Pass option to the LLVM compiler. -opta option -opta Pass option to the assembler. -optl option -optl Pass option to the linker. -optdll option -optdll Pass option to the DLL generator. -optwindres option -optwindres Pass option to windres when embedding manifests on Windows. See -fno-embed-manifest in . 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 ). pre-processing: cpp C pre-processor options cpp, pre-processing with -cpp -cpp The C pre-processor cpp is run over your Haskell code only if the -cpp option -cpp option is given. Unless you are building a large system with significant doses of conditional compilation, you really shouldn't need it. -Dsymbol=value -D Define macro symbol in the usual way. NB: does not affect -D macros passed to the C compiler when compiling via C! For those, use the -optc-Dfoo hack… (see ). -Usymbol -U Undefine macro symbol in the usual way. -Idir -I 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). 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__ __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 . With any luck, __GLASGOW_HASKELL__ will be undefined in all other implementations that support C-style pre-processing. (For reference: 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_LLVM__ __GLASGOW_HASKELL_LLVM__ Only defined when -fllvm is specified. When GHC is using version x.y.z of LLVM, the value of __GLASGOW_HASKELL_LLVM__ is the integer xy. __PARALLEL_HASKELL__ __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, whereos 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, wherearch is the name of the current architecture (eg. i386, x86_64, powerpc, sparc, etc.). A small word of warning: -cpp is not friendly to “string gaps”.-cpp vs string gapsstring gaps vs -cpp. 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. pre-processing: custom Pre-processor options -F -F A custom pre-processor is run over your Haskell source file only if the -F option -F 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. 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 \"$2\" #-}" ; 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 \"$2\" #-}" just makes sure that your error positions are reported as in the original source file. -fasm -fasm Use GHC's native code generator rather than compiling via LLVM. -fasm is the default. -fllvm -fllvm Compile via LLVMinstead 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 to be on the path. -fno-code -fno-code Omit code generation (and all later phases) altogether. Might be of some use if you just want to see dumps of the intermediate compilation phases. -fobject-code -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 bytecode. -fbyte-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. -fPIC -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. -dynamic When generating code, assume that entities imported from a different package will reside in a different shared library or binary. Note that using this option when linking causes GHC to link against shared libraries. linker options ld options GHC has to link your code with various libraries, possibly including: user-supplied, GHC-supplied, and system-supplied (-lm math library, for example). -llib -l 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 -lfoo should come before -lbar 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 linked in preference to GHC's own main() function (eg. libf2c and libl have their own main()s). This is because GHC's main() comes from the HSrts library, which is normally included after all the other libraries on the linker's command line. To force GHC's main() to be used in preference to any other main()s from external libraries, just add the option -lHSrts before any other libraries on the command line. -c -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 -package If you are using a Haskell “package” (see ), 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 -framework 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 -staticlib On Darwin/OS X/iOS only, link all passed files into a static library suitable for linking into an iOS (when using a cross-compiler) or Mac Xcode project. To control the name, use the -o name option as usual. The default name is liba.a. This should nearly always be passed when compiling for iOS with a cross-compiler. -Ldir -L Where to find user-supplied libraries… Prepend the directory dir to the library directories path. -framework-pathdir -framework-path 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). -split-objs -split-objs Tell the linker to split the single object file that would normally be generated into multiple object files, one per top-level Haskell function or type in the module. This only makes sense for libraries, where it means that executables linked against the library are smaller as they only link against the object files that they need. However, assembling all the sections separately is expensive, so this is slower than compiling normally. We use this feature for building GHC's libraries (warning: don't use it unless you know what you're doing!). -static -static Tell the linker to avoid shared Haskell libraries, if possible. This is the default. -dynamic -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 on how to create them. Note that this option also has an effect on code generation (see above). -shared -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/-static control whether the resulting shared object links statically or dynamically to Haskell package libraries given as -package 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 When creating shared objects for Haskell packages, the shared object must be named properly, so that GHC recognizes the shared object when linked against this package. See shared object name mangling. -dynload -dynload This flag selects one of a number of modes for finding shared libraries at runtime. See for a description of each mode. -main-is thing -main-is specifying your own main function 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 -no-hs-main linking Haskell libraries with foreign code 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 . 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 and -with-rtsopts have no effect when used with -no-hs-main, because they are implemented by changing the definition of main that GHC generates. See for how to get the effect of -rtsopts and -with-rtsopts when using your own main. -debug -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 -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-NxRTS option RTS option to be used, which allows threads to run in parallelparallelism on a multiprocessormultiprocessorSMP or multicoremulticore machine. See . 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 . -eventlog -eventlog 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 for more information. -eventlog can be used with -threaded. It is implied by -debug. -rtsopts -rtsopts This option affects the processing of RTS control options given either on the command line or via the GHCRTS environment variable. There are three 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=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 -rtsops=some. Note that -rtsopts has no effect when used with -no-hs-main; see for details. -with-rtsopts -with-rtsopts 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.) Note that -with-rtsopts has no effect when used with -no-hs-main; see for details. -fno-gen-manifest -fno-gen-manifest On Windows, GHC normally generates a manifestmanifest 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"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 -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 windreswindres ; 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 () and -optwindres (). -fno-shared-implib -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 -dylib-install-name 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.