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
cmdUse cmd as the literate pre-processor.
-pgmP
cmdUse cmd as the C
pre-processor (with -cpp
only).
-pgmc
cmdUse cmd as the C compiler.
-pgma
cmdUse cmd as the assembler.
-pgml
cmdUse cmd as the linker.
-pgmdll
cmdUse cmd as the DLL generator.
-pgmdep
cmdUse cmd as the dependency generator.
-pgmF
cmdUse cmd as the
pre-processor (with -F
only).
Options can be forced through to a particlar compilation phase, using the following flags:
-optL
optionPass option to the literate pre-processor
-optP
optionPass option to CPP (makes
sense only if -cpp
is also on).
-optF
optionPass option to the custom pre-processor (see Section 4.10.4).
-optc
optionPass option to the C compiler.
-opta
optionPass option to the assembler.
-optl
optionPass option to the linker.
-optdll
optionPass option to the DLL generator.
-optdep
optionPass 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).
-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.
-D
symbol[=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).
-U
symbolUndefine macro symbol in the usual way.
-I
dirSpecify 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).
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.
-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. These
are fed to cmd on the command
line after the three standard input and output
arguments.
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
-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.
GHC has to link your code with various libraries, possibly
including: user-supplied, GHC-supplied, and system-supplied
(-lm
math library, for example).
-l
libLink 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
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
nameIf 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
nameOn 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
.
-L
dirWhere to find user-supplied libraries… Prepend the directory dir to the library directories path.
-framework-path
dirOn 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.
-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).
-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" runtime system. This version of the runtime is designed to be used in programs that use multiple operating-system threads. It supports calls to foreign-exported functions from multiple OS threads. Calls to foreign functions are made using the same OS thread that created the Haskell thread (if it was created by a call-in), or an arbitrary OS thread otherwise (if the Haskell thread was created by forkIO).
More details on the use of "bound threads" in the threaded runtime can be found in the Control.Concurrent module.
The threaded RTS does not
support using multiple CPUs to speed up execution of a
multi-threaded Haskell program. The GHC runtime platform
is still single-threaded, but using the
-threaded
option it can be used safely in
a multi-threaded environment.