Options related to a particular phaseReplacing the program for one or more phasesphases, changingYou 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:cmdUse cmd as the literate
pre-processor.cmdUse cmd as the C
pre-processor (with only).cmdUse cmd as the C
compiler.cmdUse cmd as the
mangler.cmdUse cmd as the
splitter.cmdUse cmd as the
assembler.cmdUse cmd as the
linker.cmdUse cmd as the DLL
generator.cmdUse cmd as the
pre-processor (with only).Forcing options to a particular phaseforcing GHC-phase optionsOptions can be forced through to a particlar compilation
phase, using the following flags:optionPass option to the
literate pre-processoroptionPass option to CPP (makes
sense only if is also on).optionPass option to the
custom pre-processor (see ).optionPass option to the C compiler.optionPass option to the mangler.optionPass option to the assembler.optionPass option to the linker.optionPass option to the DLL generator.optionPass option to the
dependency generator.So, for example, to force an
option to the assembler, you would tell the driver
(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 ).Options affecting the C pre-processorpre-processing: cppC pre-processor optionscpp, pre-processing withThe C pre-processor cpp is run
over your Haskell code only if the
option -cpp
option is given. Unless you are
building a large system with significant doses of
conditional compilation, you really shouldn't need
it.symbol=valueDefine macro symbol in the
usual way. NB: does not affect
macros passed to the C compiler
when compiling via C! For those, use the
hack… (see ).symbol Undefine macro symbol in the
usual way.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).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).__HASKELL98____HASKELL98__If defined, this means that GHC supports the
language defined by the Haskell 98 report.__HASKELL__=98__HASKELL__=98In GHC 4.04 and later, the
__HASKELL__
macro is defined as having the value
98.__HASKELL1____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____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).__CONCURRENT_HASKELL____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____PARALLEL_HASKELL__Only defined when is in
use! This symbol is defined when pre-processing Haskell
(input) and pre-processing C (GHC output).os_HOST_OS=1This 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=1This define allows conditional compilation based on
the host architecture, wherearch
is the name of the current architecture
(eg. i386, x86_64,
powerpc, sparc,
etc.).CPP and string gapsA small word of warning: 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 ;
/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.Options affecting a Haskell pre-processorpre-processing: customPre-processor optionsA custom pre-processor is run over your Haskell
source file only if the option
-F is
given.Running a custom pre-processor at compile-time is in
some settings appropriate and useful. The
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
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 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 ) > $3and 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.Options affecting the C compiler (if applicable)include-file optionsC compiler optionsGCC optionsIf you are compiling with lots of foreign calls, you may
need to tell the C compiler about some
#include files. The Right Way to do this is to
add an INCLUDE pragma to the top of your source file
():{-# INCLUDE <X/Xlib.h> #-}Sometimes this isn't convenient. In those cases there's an
equivalent command-line option:% ghc -c '-#include <X/Xlib.h>' Xstuff.lhsOptions affecting code generationUse 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. is the default.Compile via C instead of using the native code
generator. This is the default on architectures for which GHC
doesn't have a native code generator.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.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.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
.Generate position-independent code (code that can be put into
shared libraries). This currently works on Mac OS X; it works on
PowerPC Linux when using the native code generator (-fasm).
It is not quite ready to be used yet for x86 Linux.
On Windows, position-independent code is never used,
and on PowerPC64 Linux, position-independent code is always used,
so the flag is a no-op on those platforms.When generating code, assume that entities imported from a
different package will reside in a different shared library or
binary. This currently works on Mac OS X; it works on PowerPC Linux when
using the native code generator. As with ,
x86 Linux support is not quite ready yet. Windows is not supported,
and it is a no-op on PowerPC64 Linux.Note that this option also causes GHC to use shared libraries
when linking.Options affecting linkinglinker optionsld optionsGHC has to link your code with various libraries, possibly
including: user-supplied, GHC-supplied, and system-supplied
( math library, for example).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
foo should
come beforebar 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 before any
other libraries on the command line.Omits the link step. This option can be used with
to avoid the automatic linking
that takes place if the program contains a Main
module.nameIf you are using a Haskell “package”
(see ), don't forget to add the
relevant option when linking the
program too: it will cause the appropriate libraries to be
linked in with the program. Forgetting the
option will likely result in
several pages of link errors.nameOn Darwin/MacOS X only, link in the framework name.
This option corresponds to the 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
.
dirWhere to find user-supplied libraries…
Prepend the directory dir to
the library directories path.dirOn Darwin/MacOS X only, prepend the directory dir to
the framework directories path. This option corresponds to the
option for Apple's Linker ( already means something else for GHC).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!).Tell the linker to avoid shared Haskell libraries,
if possible. This is the default.Tell the linker to use shared Haskell libraries, if
available (this option is only supported on Mac OS X at the
moment, and also note that your distribution of GHC may
not have been supplied with shared libraries).Note that this option also has an effect on
code generation (see above).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 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, 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
flag.
linking Haskell libraries with foreign codeIn 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
. 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 on
to see what options the driver passes through to the
linker.The flag can also be
used to persuade the compiler to do the link step in
mode when there is no Haskell
Main module present (normally the
compiler will not attempt linking when there is no
Main).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).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
in order to use concurrency; the
single-threaded runtime supports concurrency between Haskell
threads just fine.The threaded runtime system provides the following
benefits:Parallelismparallelism on a multiprocessormultiprocessorSMP or multicoremulticore
machine. See .The ability to make a foreign call that does not
block all other Haskell threads.The ability to invoke foreign exported Haskell
functions from multiple OS threads.With , calls to foreign
functions are made using the same OS thread that created the
Haskell thread (if it was created by a call to a foreign
exported Haskell function), 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.