Chapter 5. Using GHC

Table of Contents

5.1. Options overview
5.1.1. Command-line arguments
5.1.2. Command line options in source files
5.1.3. Setting options in GHCi
5.2. Static, Dynamic, and Mode options
5.3. Meaningful file suffixes
5.4. Modes of operation
5.4.1. Using ghc ––make
5.4.2. Expression evaluation mode
5.4.3. Batch compiler mode
5.4.3.1. Overriding the default behaviour for a file
5.5. Help and verbosity options
5.6. Filenames and separate compilation
5.6.1. Haskell source files
5.6.2. Output files
5.6.3. The search path
5.6.4. Redirecting the compilation output(s)
5.6.5. Keeping Intermediate Files
5.6.6. Redirecting temporary files
5.6.7. Other options related to interface files
5.6.8. The recompilation checker
5.6.9. How to compile mutually recursive modules
5.6.10. Using make
5.6.11. Dependency generation
5.6.12. Orphan modules and instance declarations
5.7. Warnings and sanity-checking
5.8. Packages
5.8.1. Using Packages
5.8.2. The main package
5.8.3. Consequences of packages
5.8.4. Package Databases
5.8.4.1. The GHC_PACKAGE_PATH environment variable
5.8.5. Building a package from Haskell source
5.8.6. Package management (the ghc-pkg command)
5.8.7. InstalledPackageInfo: a package specification
5.9. Optimisation (code improvement)
5.9.1. -O*: convenient “packages” of optimisation flags.
5.9.2. -f*: platform-independent flags
5.10. Options related to a particular phase
5.10.1. Replacing the program for one or more phases
5.10.2. Forcing options to a particular phase
5.10.3. Options affecting the C pre-processor
5.10.3.1. CPP and string gaps
5.10.4. Options affecting a Haskell pre-processor
5.10.5. Options affecting the C compiler (if applicable)
5.10.6. Options affecting code generation
5.10.7. Options affecting linking
5.11. Using Concurrent Haskell
5.12. Using SMP parallelism
5.12.1. Options for SMP parallelism
5.12.2. Hints for using SMP parallelism
5.13. Platform-specific Flags
5.14. Running a compiled program
5.14.1. Setting global RTS options
5.14.2. Miscellaneous RTS options
5.14.3. RTS options to control the garbage collector
5.14.4. RTS options for concurrency and parallelism
5.14.5. RTS options for profiling
5.14.6. RTS options for hackers, debuggers, and over-interested souls
5.14.7. “Hooks” to change RTS behaviour
5.14.8. Getting information about the RTS
5.15. Generating and compiling External Core Files
5.16. Debugging the compiler
5.16.1. Dumping out compiler intermediate structures
5.16.2. Checking for consistency
5.16.3. How to read Core syntax (from some -ddump flags)
5.16.4. Unregisterised compilation
5.17. Flag reference
5.17.1. Help and verbosity options
5.17.2. Which phases to run
5.17.3. Alternative modes of operation
5.17.4. Redirecting output
5.17.5. Keeping intermediate files
5.17.6. Temporary files
5.17.7. Finding imports
5.17.8. Interface file options
5.17.9. Recompilation checking
5.17.10. Interactive-mode options
5.17.11. Packages
5.17.12. Language options
5.17.13. Warnings
5.17.14. Optimisation levels
5.17.15. Individual optimisations
5.17.16. Profiling options
5.17.17. Program coverage options
5.17.18. Haskell pre-processor options
5.17.19. C pre-processor options
5.17.20. C compiler options
5.17.21. Code generation options
5.17.22. Linking options
5.17.23. Replacing phases
5.17.24. Forcing options to particular phases
5.17.25. Platform-specific options
5.17.26. External core file options
5.17.27. Compiler debugging options
5.17.28. Misc compiler options

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

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

5.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_GHC pragma :

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

OPTIONS_GHC pragmas are only looked for at the top of your source files, upto the first (non-literate,non-empty) line not containing OPTIONS_GHC. Multiple OPTIONS_GHC pragmas are recognised. Do not put comments before, or on the same line as, the OPTIONS_GHC pragma.

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 maintains internally, so you'll be desperately disappointed if you try to glob etc. inside OPTIONS_GHC.

NOTE: the contents of OPTIONS_GHC are appended to the command-line options, so options given in the source file override those given on 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_GHC pragma is the Right Thing. (If you use -keep-hc-file and have OPTION flags in your module, the OPTIONS_GHC will get put into the generated .hc file).

5.1.3. Setting options in GHCi

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