5.10. Options related to a particular phase
Prev | Chapter 5. Using GHC | Next

## 5.10. Options related to a particular phase

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

`-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 5.10.7, “Options affecting linking”.

### 5.10.2. Forcing options to a particular phase

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 5.10.4, “Options affecting a Haskell pre-processor”).

`-optc` `option`

  Pass `option` to the C 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.

`-optdep` `option`

  Pass `option` to the dependency generator.

`-optwindres` `option`

  Pass `option` to `windres` when embedding manifests on Windows. See `-fno-embed-manifest` in Section 5.10.7, “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 5.14, “Running a compiled program”).

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

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

`__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 ``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 Section 1.3, “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).

`__CONCURRENT_HASKELL__`

  This symbol is defined when pre-processing Haskell (input) and pre-processing C (GHC output). Since GHC from version 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).

``os`_HOST_OS=1`

  This define allows conditional compilation based on the Operating System, where`os` 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, where`arch` is the name of the current architecture (eg. `i386`, `x86_64`, `powerpc`, `sparc`, etc.).

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

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

  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.

  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.

### 5.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. The Right Way to do this is to add an `INCLUDE` pragma to the top of your source file (Section 8.12.3, “INCLUDE pragma”):

    {-# 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.lhs

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

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

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

`-dynamic`

  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 `-fPIC`, 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.

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

`-l` `lib`

  Link in the `lib` library. On Unix systems, this will be in a file called `lib`lib`.a` or `lib`lib`.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.

`-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 5.8, “ 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`

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

`-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 9.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 5.12, “Using SMP parallelism”.

    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 `-threaded`, 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.

`-fno-gen-manifest`

  On Windows, GHC normally generates a manifestfile when linking a binary. The manifest is placed in the file ``prog`.exe.manifest` where `prog.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 5.10.1, “Replacing the program for one or more phases”) and `-optwindres` (Section 5.10.2, “Forcing options to a particular phase”).

Prev | Up | Next
5.9. Optimisation (code improvement) | Home | 5.11. Using Concurrent Haskell