4.10. Options related to a particular phase

4.10.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.

-pgma cmd

Use cmd as the assembler.

-pgml cmd

Use cmd as the linker.

-pgmdll cmd

Use cmd as the DLL generator.

-pgmdep cmd

Use cmd as the dependency generator.

-pgmF cmd

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

4.10.2. Forcing options to a particular phase

Options can be forced through to a particlar 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 Section 4.10.4).

-optc option

Pass option to the C compiler.

-opta option

Pass option to the assembler.

-optl option

Pass option to the linker.

-optdll option

Pass option to the DLL generator.

-optdep option

Pass option to the dependency generator.

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 Section 4.14).

4.10.3. Options affecting the C pre-processor

-cpp

The C pre-processor cpp is run over your Haskell code only if the -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]

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 Section 4.10.2).

-Usymbol

Undefine macro symbol in the usual way.

-Idir

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):

__HASKELL98__

If defined, this means that GHC supports the language defined by the Haskell 98 report.

__HASKELL__=98

In GHC 4.04 and later, the __HASKELL__ macro is defined as having the value 98.

__HASKELL1__

If defined to n, that means GHC supports the Haskell language defined in the Haskell report version 1.n. Currently 5. This macro is deprecated, and will probably disappear in future versions.

__GLASGOW_HASKELL__

For version n of the GHC system, this will be #defined to 100n. For example, for version 5.00, it is 500.

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 Chalmers.)

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).

__CONCURRENT_HASKELL__

This symbol is defined when pre-processing Haskell (input) and pre-processing C (GHC output). Since GHC from verion 4.00 now supports concurrent haskell by default, this symbol is always defined.

__PARALLEL_HASKELL__

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

4.10.3.1. 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.

4.10.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.

-pgmF cmd

Use cmd as the Haskell pre-processor. 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 cmd 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.

4.10.5. Options affecting the C compiler (if applicable)

If you are compiling with lots of foreign calls, you may need to tell the C compiler about some #include files. There is no real pretty way to do this, but you can use this hack from the command-line:

% ghc -c '-#include <X/Xlib.h>' Xstuff.lhs

4.10.6. Options affecting code generation

-fasm

Use GHC's native code generator rather than compiling via C. This will compile faster (up to twice as fast), but may produce code that is slightly slower than compiling via C. -fasm is the default when optimisation is off (see Section 4.9).

-fvia-C

Compile via C instead of using the native code generator. This is default for optimised compilations, and on architectures for which GHC doesn't have a native code generator.

-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.

4.10.7. 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).

-llib

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.

-no-link

Omit the link step. This flag can be useful if you want to avoid linking in --make mode, where linking is normally done automatically if the program contains a Main module.

-package name

If you are using a Haskell “package” (see Section 4.8), 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/MacOS X 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.

-Ldir

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

-framework-pathdir

On Darwin/MacOS X 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

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. We use this feature for building GHC's libraries libraries (warning: don't use it unless you know what you're doing!).

-static

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

-dynamic

Tell the linker to use shared Haskell libraries, if available (this option is only supported on Windows at the moment, and also note that your distribution of GHC may not have been supplied with shared libraries).

-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.

  • An module name A. GHC assumes that the main function is A.main.

  • An 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).

-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 Section 8.2.1.1.

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).