3.9. Options related to a particular phase

3.9.1. The C pre-processor

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.

-D<foo>:

Define macro <foo> 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 3.13.2).

-U<foo>:

Undefine macro <foo> 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):

__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. So, for version 4.00, it is 400.

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

Options other than the above can be forced through to the C pre-processor with the -opt flags (see Section 3.13.2).

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.

3.9.2. Options affecting the C compiler (if applicable)

At the moment, quite a few common C-compiler options are passed on quietly to the C compilation of Haskell-compiler-generated C files. THIS MAY CHANGE. Meanwhile, options so sent are:

-ansi do ANSI C (not K&R)
-pedantic be so
-dgcc-lint (hack) short for “make GCC very paranoid”

If you are compiling with lots of ccalls, etc., 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

3.9.3. Linking and consistency-checking

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

-l<FOO>:

Link in a library named lib<FOO>.a which resides somewhere on the library directories path.

Because of the sad state of most UNIX linkers, the order of such options does matter. Thus: ghc -lbar *.o is almost certainly wrong, because it will search libbar.a before it has collected unresolved symbols from the *.o files. ghc *.o -lbar is probably better.

The linker will of course be informed about some GHC-supplied libraries automatically; these are:

-l equivalent description
-lHSrts,-lHSclib basic runtime libraries
-lHS standard Prelude library
-lHS_cbits C support code for standard Prelude library
-lgmp GNU multi-precision library (for Integers)

-syslib <name>:

If you are using a Haskell “system library” (e.g., the POSIX library), just use the -syslib posix option, and the correct code should be linked in.

-L<dir>:

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

-static:

Tell the linker to avoid shared libraries.

-no-link-chk and -link-chk:

By default, immediately after linking an executable, GHC verifies that the pieces that went into it were compiled with compatible flags; a “consistency check”. (This is to avoid mysterious failures caused by non-meshing of incompatibly-compiled programs; e.g., if one .o file was compiled for a parallel machine and the others weren't.) You may turn off this check with -no-link-chk. You can turn it (back) on with -link-chk (the default).

-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 driver script when linking, use -no-hs-main.

Notice that since the command-line passed to the linker is rather involved, you probably want to use the ghc driver script 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.