Chapter 4. Using GHC

Table of Contents
4.1. Options overview
4.2. Static vs. Dynamic options
4.3. Meaningful file suffixes
4.4. Modes of operation
4.5. Help and verbosity options
4.6. Filenames and separate compilation
4.7. Warnings and sanity-checking
4.8. Packages
4.9. Optimisation (code improvement)
4.10. Options related to a particular phase
4.11. Using Concurrent Haskell
4.12. Using Parallel Haskell
4.13. Platform-specific Flags
4.14. Running a compiled program
4.15. Generating and compiling External Core Files
4.16. Debugging the compiler
4.17. Flag reference

4.1. Options overview

GHC's behaviour is controlled by options, which for historical reasons are also sometimes referred to as command-line flags or arguments. Options can be specified in three ways:

4.1.1. Command-line arguments

An invocation of GHC takes the following form:

ghc [argument...]

Command-line arguments are either options or file names.

Command-line options begin with -. They may not be grouped: -vO is different from -v -O. Options need not precede filenames: e.g., ghc *.o -o foo. All options are processed and then applied to all files; you cannot, for example, invoke ghc -c -O1 Foo.hs -O2 Bar.hs to apply different optimisation levels to the files Foo.hs and Bar.hs.

4.1.2. Command line options in source files

Sometimes it is useful to make the connection between a source file and the command-line options it requires quite tight. For instance, if a Haskell source file uses GHC extensions, it will always need to be compiled with the -fglasgow-exts option. Rather than maintaining the list of per-file options in a Makefile, it is possible to do this directly in the source file using the OPTIONS pragma :

{-# OPTIONS -fglasgow-exts #-}
module X where
...

OPTIONS pragmas are only looked for at the top of your source files, upto the first (non-literate,non-empty) line not containing OPTIONS. Multiple OPTIONS pragmas are recognised. Note that your command shell does not get to the source file options, they are just included literally in the array of command-line arguments the compiler driver maintains internally, so you'll be desperately disappointed if you try to glob etc. inside OPTIONS.

NOTE: the contents of OPTIONS are prepended to the command-line options, so you do have the ability to override OPTIONS settings via the command line.

It is not recommended to move all the contents of your Makefiles into your source files, but in some circumstances, the OPTIONS pragma is the Right Thing. (If you use -keep-hc-file-too and have OPTION flags in your module, the OPTIONS will get put into the generated .hc file).

4.1.3. Setting options in GHCi

Options may also be modified from within GHCi, using the :set command. See Section 3.7 for more details.