The Glasgow Haskell Compiler User's Guide, Version 5.02

The GHC Team

Table of Contents
The Glasgow Haskell Compiler License
1. Introduction to GHC
1.1. Meta-information: Web sites, mailing lists, etc.
1.2. Reporting bugs in GHC
1.2.1. What to put in a bug report
1.3. GHC version numbering policy
1.4. Release notes for version 5.02
1.4.1. User-visible compiler changes
1.4.2. User-visible interpreter (GHCi) changes
1.4.3. User-visible library changes
1.4.4. New experimental features
1.4.5. Internal changes
2. Installing GHC
2.1. Installing on Unix-a-likes
2.1.1. When a platform-specific package is available
2.1.2. GHC binary distributions
2.2. Installing on Windows
2.2.1. Installing GHC
2.2.2. Installing ghc-win32 FAQ
2.3. The layout of installed files
2.3.1. Layout of the library directory
2.4. Building the documentation
2.4.1. Installing the DocBook tools from RPMs
2.4.2. Installing DocBook on FreeBSD
2.4.3. Installing from binaries on Windows
2.4.4. Installing the DocBook tools from source
2.4.5. Configuring the DocBook tools
2.4.6. Remaining problems
3. Using GHCi
3.1. Introduction to GHCi
3.2. Loading source files
3.2.1. Modules vs. filenames
3.2.2. Making changes and recompilation
3.3. Loading compiled code
3.4. Interactive evaluation at the prompt
3.4.1. What's really in scope at the prompt?
3.4.2. Using do-notation at the prompt
3.4.3. The it variable
3.5. Invoking GHCi
3.5.1. Packages
3.5.2. Extra libraries
3.6. GHCi commands
3.7. The :set command
3.7.1. GHCi options
3.7.2. Setting GHC command-line options in GHCi
3.8. The .ghci file
3.9. FAQ and Things To Watch Out For
4. Using GHC
4.1. Options overview
4.1.1. Command-line arguments
4.1.2. Command line options in source files
4.1.3. Setting options in GHCi
4.2. Static vs. Dynamic options
4.3. Meaningful file suffixes
4.4. Help and verbosity options
4.5. Using ghc ––make
4.6. GHC without ––make
4.7. Re-directing the compilation output(s)
4.7.1. Keeping Intermediate Files
4.7.2. Redirecting temporary files
4.8. Warnings and sanity-checking
4.9. Separate compilation
4.9.1. Interface files
4.9.2. Finding interface files
4.9.3. Other options related to interface files
4.9.4. The recompilation checker
4.9.5. Using make
4.9.6. How to compile mutually recursive modules
4.9.7. Orphan modules and instance declarations
4.10. Packages
4.10.1. Using a package
4.10.2. Maintaining a local set of packages
4.10.3. Building a package from Haskell source
4.10.4. Package management
4.11. Optimisation (code improvement)
4.11.1. -O*: convenient “packages” of optimisation flags.
4.11.2. -f*: platform-independent flags
4.12. Options related to a particular phase
4.12.1. Replacing the program for one or more phases
4.12.2. Forcing options to a particular phase
4.12.3. Options affecting the C pre-processor
4.12.4. Options affecting the C compiler (if applicable)
4.12.5. Options affecting code generation
4.12.6. Options affecting linking
4.13. Using Concurrent Haskell
4.14. Using Parallel Haskell
4.14.1. Dummy's guide to using PVM
4.14.2. Parallelism profiles
4.14.3. Other useful info about running parallel programs
4.14.4. RTS options for Concurrent/Parallel Haskell
4.15. Platform-specific Flags
4.16. Running a compiled program
4.16.1. Setting global RTS options
4.16.2. RTS options to control the garbage collector
4.16.3. RTS options for hackers, debuggers, and over-interested souls
4.16.4. “Hooks” to change RTS behaviour
4.17. Generating External Core Files
4.18. Debugging the compiler
4.18.1. Dumping out compiler intermediate structures
4.18.2. Checking for consistency
4.18.3. How to read Core syntax (from some -ddump flags)
4.18.4. Unregisterised compilation
4.19. Flag reference
4.19.1. Help and verbosity options (Section 4.4)
4.19.2. Which phases to run (Section 4.6)
4.19.3. Redirecting output (Section 4.7)
4.19.4. Keeping intermediate files (Section 4.7.1)
4.19.5. Temporary files (Section 4.7.2)
4.19.6. Finding imports (Section 4.9.2)
4.19.7. Interface file options (Section 4.9.3)
4.19.8. Recompilation checking (Section 4.9.4)
4.19.9. Interactive-mode options (Section 3.8)
4.19.10. Packages (Section 4.10)
4.19.11. Language options (Section 7.1)
4.19.12. Warnings (Section 4.8)
4.19.13. Optimisation levels (Section 4.11)
4.19.14. Individual optimisations (Section 4.11.2)
4.19.15. Profiling options (Chapter 5)
4.19.16. Parallelism options (Section 4.14)
4.19.17. C pre-processor options (Section 4.12.3)
4.19.18. C compiler options (Section 4.12.4)
4.19.19. Code generation options (Section 4.12.5)
4.19.20. Linking options (Section 4.12.6)
4.19.21. Replacing phases (Section 4.12.1)
4.19.22. Forcing options to particular phases (Section 4.12.2)
4.19.23. Platform-specific options (Section 4.15)
4.19.24. Compiler debugging options (Section 4.18)
4.19.25. Misc compiler options
5. Profiling
5.1. Cost centres and cost-centre stacks
5.1.1. Inserting cost centres by hand
5.1.2. Rules for attributing costs
5.2. Profiling memory usage
5.3. Graphical time/allocation profile
5.4. Compiler options for profiling
5.5. Runtime options for profiling
5.6. hp2ps––heap profile to PostScript
5.7. Using “ticky-ticky” profiling (for implementors)
6. Advice on: sooner, faster, smaller, stingier
6.1. Sooner: producing a program more quickly
6.2. Faster: producing a program that runs quicker
6.3. Smaller: producing a program that is smaller
6.4. Stingier: producing a program that gobbles less heap space
7. GHC Language Features
7.1. Language options
7.2. Unboxed types and primitive operations
7.2.1. Unboxed types
7.2.2. Unboxed Tuples
7.2.3. Character and numeric types
7.2.4. Comparison operations
7.2.5. Primitive-character operations
7.2.6. Primitive-Int operations
7.2.7. Primitive-Double and Float operations
7.2.8. Operations on/for Integers (interface to GMP)
7.2.9. Words and addresses
7.2.10. Arrays
7.2.11. Reading and writing
7.2.12. The state type
7.2.13. State of the world
7.2.14. Mutable arrays
7.2.15. Synchronizing variables (M-vars)
7.3. Primitive state-transformer monad
7.4. Primitive arrays, mutable and otherwise
7.5. Data types with no constructors
7.6. Pattern guards
7.7. Parallel List Comprehensions
7.8. Multi-parameter type classes
7.8.1. Types
7.8.2. Class declarations
7.8.3. Instance declarations
7.9. Implicit parameters
7.10. Functional dependencies
7.11. Explicit universal quantification
7.11.1. Universally-quantified data type fields
7.11.2. Construction
7.11.3. Pattern matching
7.11.4. The partial-application restriction
7.11.5. Type signatures
7.11.6. Type synonyms and hoisting
7.12. Existentially quantified data constructors
7.12.1. Why existential?
7.12.2. Type classes
7.12.3. Restrictions
7.13. Assertions
7.14. Scoped Type Variables
7.14.1. What a pattern type signature means
7.14.2. Scope and implicit quantification
7.14.3. Result type signatures
7.14.4. Where a pattern type signature can occur
7.15. Pragmas
7.15.1. INLINE pragma
7.15.2. NOINLINE pragma
7.15.3. SPECIALIZE pragma
7.15.4. SPECIALIZE instance pragma
7.15.5. LINE pragma
7.15.6. RULES pragma
7.15.7. DEPRECATED pragma
7.16. Rewrite rules
7.16.1. Syntax
7.16.2. Semantics
7.16.3. List fusion
7.16.4. Specialisation
7.16.5. Controlling what's going on
7.17. Generic classes
7.17.1. Using generics
7.17.2. Changes wrt the paper
7.17.3. Terminology and restrictions
7.17.4. Another example
7.18. Concurrent and Parallel Haskell
7.18.1. Features specific to Parallel Haskell
7.19. Haskell 98 vs. Glasgow Haskell: language non-compliance
7.19.1. Divergence from Haskell 98
7.19.2. GHC's interpretation of undefined behaviour in Haskell 98
8. Foreign function interface
8.1. Introduction
8.2. Calling foreign functions
8.2.1. Giving the external function a Haskell name
8.2.2. Naming the external function
8.2.3. Calling conventions
8.2.4. External function types
8.2.5. Type mapping
8.2.6. Some foreign import wrinkles
8.3. Invoking external functions via a pointer
8.4. Exposing Haskell functions
8.4.1. Exposing Haskell function values
8.4.2. Code addresses
8.5. Using the FFI with GHC
8.5.1. Using foreign export with GHC
8.5.2. Using function headers
9. What to do when something goes wrong
9.1. When the compiler “does the wrong thing”
9.2. When your program “does the wrong thing”
9.3. Hard-core debugging of GHC-compiled programs
10. Other Haskell utility programs
10.1. “Yacc for Haskell”: happy
10.2. Writing Haskell interfaces to C code: hsc2hs
10.2.1. Command line syntax
10.2.2. Input syntax
10.2.3. Custom constructs
11. Building and using Win32 DLLs
11.1. Linking with DLLs
11.2. Not linking with DLLs
11.3. Creating a DLL
11.4. Making DLLs to be called from other languages
List of Tables
8-1. Mapping of Haskell types to C types
PrevHomeNext
 The Glasgow Haskell Compiler License