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.
-pgmlo
cmd
Use cmd
as the LLVM
optimiser.
-pgmlc
cmd
Use cmd
as the LLVM
compiler.
-pgmm
cmd
Use cmd
as the
mangler.
-pgms
cmd
Use cmd
as the
splitter.
-pgma
cmd
Use cmd
as the
assembler.
-pgml
cmd
Use cmd
as the
linker.
-pgmdll
cmd
Use cmd
as the DLL
generator.
-pgmF
cmd
Use cmd
as the
pre-processor (with -F
only).
-pgmwindres
cmd
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 Section 4.11.6, “Options affecting linking”.
Options can be forced through to a particular 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.11.4, “Options affecting a Haskell pre-processor”).
-optc
option
Pass option
to the C compiler.
-optlo
option
Pass option
to the LLVM optimiser.
-optlc
option
Pass option
to the LLVM compiler.
-optm
option
Pass option
to the mangler.
-opta
option
Pass option
to the assembler.
-optl
option
Pass option
to the linker.
-optdll
option
Pass option
to the DLL generator.
-optwindres
option
Pass option
to
windres
when embedding manifests on Windows.
See -fno-embed-manifest
in Section 4.11.6, “Options affecting linking”.
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.16, “Running a compiled program”).
-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.11.2, “Forcing options to a particular phase”).
-U
symbol
Undefine macro symbol
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).
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__
For version
of GHC, the value of
x
.y
.z
__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 Section 1.4, “GHC version numbering policy”.
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).
__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”.. 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
to select the program to use as the preprocessor. When
invoked, the cmd
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
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.
-fvia-C
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.
-fllvm
Compile via LLVM instead of using the native code generator. This will generally take slightly longer than the native code generator to compile but quicker than compiling via C. Produced code is generally the same speed or faster than the other two code generators. Compiling via LLVM requires LLVM version 2.7 or later to be on the path.
-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
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
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
Generate position-independent code (code that can be put into shared libraries). This currently works on Linux x86 and x86-64 when using the native code generator (-fasm). 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.
GHC has to link your code with various libraries, possibly
including: user-supplied, GHC-supplied, and system-supplied
(-lm
math library, for example).
-l
lib
Link in the lib
library.
On Unix systems, this will be in a file called
lib
or
lib
.alib
which resides somewhere on the library directories path.lib
.so
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.
-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
If you are using a Haskell “package”
(see Section 4.9, “
Packages
”), 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
.
-L
dir
Where to find user-supplied libraries…
Prepend the directory dir
to
the library directories path.
-framework-path
dir
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. 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
Tell the linker to avoid shared Haskell libraries, if possible. This is the default.
-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 Section 4.12, “Using shared libraries” on how to create them.
Note that this option also has an effect on code generation (see above).
-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 Section 4.11.5, “Options affecting code generation”
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
This flag selects one of a number of modes for finding shared libraries at runtime. See Section 4.12.4, “Finding shared libraries at runtime” for a description of each mode.
-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
.
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
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, “Using your own main()
”.
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" 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:
Parallelism on a multiprocessor or multicore machine. See Section 4.14, “Using SMP parallelism”.
The ability to make a foreign call that does not block all other Haskell threads, and to invoke foreign-exported Haskell functions from multiple OS threads. See Section 8.2.4, “Multi-threading and the FFI”.
-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
,
which can then be interpreted later by various tools. See
Section 4.16.6, “Tracing” for more information.
program
.eventlog
-eventlog
can be used
with -threaded
. It is implied
by -debug
.
-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
.
-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.)
-fno-gen-manifest
On Windows, GHC normally generates a
manifestfile when linking a binary. The
manifest is placed in the file
where prog
.exe.manifestprog.exe
is the name of the
executable. The manifest file currently serves just one purpose:
it disables the "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
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
windres
; 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
(Section 4.11.1, “Replacing the program for one or more phases”) and
-optwindres
(Section 4.11.2, “Forcing options to a particular phase”).
-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
On Darwin/MacOS 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.