The Glorious Glasgow Haskell Compilation System User's Guide, Version 6.4

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. How do I tell if I should report my bug?
1.2.2. What to put in a bug report
1.3. GHC version numbering policy
1.4. Release notes for version 6.4
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. 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 Installing What bundles there are Testing that GHC seems to be working
2.2. Installing on Windows
2.2.1. Installing GHC on Windows
2.2.2. Moving GHC around
2.2.3. Installing ghc-win32 FAQ
2.3. The layout of installed files
2.3.1. The binary directory
2.3.2. The library directory
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? Qualified names
3.4.2. Using do-notation at the prompt
3.4.3. The it variable
3.4.4. Type defaulting in GHCi
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. Modes of operation
4.4.1. Using ghc ––make
4.4.2. Expression evaluation mode
4.4.3. Batch compiler mode
4.5. Help and verbosity options
4.6. Filenames and separate compilation
4.6.1. Haskell source files
4.6.2. Output files
4.6.3. The search path
4.6.4. Redirecting the compilation output(s)
4.6.5. Keeping Intermediate Files
4.6.6. Redirecting temporary files
4.6.7. Other options related to interface files
4.6.8. The recompilation checker
4.6.9. How to compile mutually recursive modules
4.6.10. Using make
4.6.11. Dependency generation
4.6.12. Orphan modules and instance declarations
4.7. Warnings and sanity-checking
4.8. Packages
4.8.1. Using Packages
4.8.2. Package Databases
4.8.3. Building a package from Haskell source
4.8.4. Package management (the ghc-pkg command)
4.8.5. InstalledPackageInfo: a package specification
4.9. Optimisation (code improvement)
4.9.1. -O*: convenient “packages” of optimisation flags.
4.9.2. -f*: platform-independent flags
4.10. Options related to a particular phase
4.10.1. Replacing the program for one or more phases
4.10.2. Forcing options to a particular phase
4.10.3. Options affecting the C pre-processor CPP and string gaps
4.10.4. Options affecting a Haskell pre-processor
4.10.5. Options affecting the C compiler (if applicable)
4.10.6. Options affecting code generation
4.10.7. Options affecting linking
4.11. Using Concurrent Haskell
4.12. Using parallel Haskell
4.12.1. Dummy's guide to using PVM
4.12.2. parallelism profiles
4.12.3. Other useful info about running parallel programs
4.12.4. RTS options for Concurrent/parallel Haskell
4.13. Platform-specific Flags
4.14. Running a compiled program
4.14.1. Setting global RTS options
4.14.2. RTS options to control the garbage collector
4.14.3. RTS options for profiling and Concurrent/Parallel Haskell
4.14.4. RTS options for hackers, debuggers, and over-interested souls
4.14.5. “Hooks” to change RTS behaviour
4.15. Generating and compiling External Core Files
4.16. Debugging the compiler
4.16.1. Dumping out compiler intermediate structures
4.16.2. Checking for consistency
4.16.3. How to read Core syntax (from some -ddump flags)
4.16.4. Unregisterised compilation
4.17. Flag reference
4.17.1. Help and verbosity options
4.17.2. Which phases to run
4.17.3. Alternative modes of operation
4.17.4. Redirecting output
4.17.5. Keeping intermediate files
4.17.6. Temporary files
4.17.7. Finding imports
4.17.8. Interface file options
4.17.9. Recompilation checking
4.17.10. Interactive-mode options
4.17.11. Packages
4.17.12. Language options
4.17.13. Warnings
4.17.14. Optimisation levels
4.17.15. Individual optimisations
4.17.16. Profiling options
4.17.17. Parallelism options
4.17.18. C pre-processor options
4.17.19. C compiler options
4.17.20. Code generation options
4.17.21. Linking options
4.17.22. Replacing phases
4.17.23. Forcing options to particular phases
4.17.24. Platform-specific options
4.17.25. External core file options
4.17.26. Compiler debugging options
4.17.27. 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. Compiler options for profiling
5.3. Time and allocation profiling
5.4. Profiling memory usage
5.4.1. RTS options for heap profiling
5.4.2. Retainer Profiling Hints for using retainer profiling
5.4.3. Biographical Profiling
5.5. Graphical time/allocation profile
5.6. hp2ps––heap profile to PostScript
5.6.1. Manipulating the hp file
5.6.2. Zooming in on regions of your profile
5.6.3. Viewing the heap profile of a running program
5.6.4. Viewing a heap profile in real time
5.7. Using “ticky-ticky” profiling (for implementors)
6. Advice on: sooner, faster, smaller, thriftier
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. Thriftier: 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.3. Syntactic extensions
7.3.1. Hierarchical Modules
7.3.2. Pattern guards
7.3.3. The recursive do-notation
7.3.4. Parallel List Comprehensions
7.3.5. Rebindable syntax
7.4. Type system extensions
7.4.1. Data types and type synonyms Data types with no constructors Infix type constructors, classes, and type variables Liberalised type synonyms Existentially quantified data constructors
7.4.2. Class declarations Class method types
7.4.3. Type signatures The context of a type signature For-all hoisting
7.4.4. Instance declarations Overlapping instances Type synonyms in the instance head Undecidable instances
7.4.5. Implicit parameters Implicit-parameter type constraints Implicit-parameter bindings Implicit parameters and polymorphic recursion Implicit parameters and monomorphism
7.4.6. Linear implicit parameters Warnings Recursive functions
7.4.7. Functional dependencies
7.4.8. Explicitly-kinded quantification
7.4.9. Arbitrary-rank polymorphism Examples Type inference Implicit quantification
7.4.10. Scoped type variables What a scoped type variable means Scope and implicit quantification Declaration type signatures Where a pattern type signature can occur Result type signatures
7.4.11. Deriving clause for classes Typeable and Data
7.4.12. Generalised derived instances for newtypes Generalising the deriving clause A more precise specification
7.5. Generalised Algebraic Data Types
7.6. Template Haskell
7.6.1. Syntax
7.6.2. Using Template Haskell
7.6.3. A Template Haskell Worked Example
7.7. Arrow notation
7.7.1. do-notation for commands
7.7.2. Conditional commands
7.7.3. Defining your own control structures
7.7.4. Primitive constructs
7.7.5. Differences with the paper
7.7.6. Portability
7.8. Assertions
7.9. Pragmas
7.9.1. DEPRECATED pragma
7.9.2. INCLUDE pragma
7.9.3. INLINE and NOINLINE pragmas INLINE pragma NOINLINE pragma Phase control
7.9.4. LINE pragma
7.9.5. OPTIONS_GHC pragma
7.9.6. RULES pragma
7.9.7. SPECIALIZE pragma
7.9.8. SPECIALIZE instance pragma
7.9.9. UNPACK pragma
7.10. Rewrite rules
7.10.1. Syntax
7.10.2. Semantics
7.10.3. List fusion
7.10.4. Specialisation
7.10.5. Controlling what's going on
7.10.6. CORE pragma
7.11. Generic classes
7.11.1. Using generics
7.11.2. Changes wrt the paper
7.11.3. Terminology and restrictions
7.11.4. Another example
7.12. Concurrent and Parallel Haskell
7.12.1. Features specific to Parallel Haskell The Parallel interface (recommended) Underlying functions and primitives Scheduling policy for concurrent threads Scheduling policy for parallel threads
8. Foreign function interface (FFI)
8.1. GHC extensions to the FFI Addendum
8.1.1. Unboxed types
8.2. Using the FFI with GHC
8.2.1. Using foreign export and foreign import ccall "wrapper" with GHC Using your own main() Using foreign import ccall "wrapper" with GHC
8.2.2. Using function headers Finding Header files
8.2.3. Memory Allocation
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”
10. Other Haskell utility programs
10.1. Ctags and Etags for Haskell: hasktags
10.1.1. Using tags with your editor
10.2. “Yacc for Haskell”: happy
10.3. Writing Haskell interfaces to C code: hsc2hs
10.3.1. command line syntax
10.3.2. Input syntax
10.3.3. Custom constructs
11. Running GHC on Win32 systems
11.1. Starting GHC on Win32 platforms
11.2. Interacting with the terminal
11.3. Differences in library behaviour
11.4. Using GHC (and other GHC-compiled executables) with cygwin
11.4.1. Background
11.4.2. The problem
11.4.3. Things to do
11.5. Building and using Win32 DLLs
11.5.1. Linking with DLLs
11.5.2. Not linking with DLLs
11.5.3. Creating a DLL
11.5.4. Making DLLs to be called from other languages
12. Known bugs and infelicities
12.1. Haskell 98 vs. Glasgow Haskell: language non-compliance
12.1.1. Divergence from Haskell 98 Lexical syntax Context-free syntax Expressions and patterns Declarations and bindings Module system and interface files Numbers, basic types, and built-in classes In Prelude support
12.1.2. GHC's interpretation of undefined behaviour in Haskell 98
12.2. Known bugs or infelicities
12.2.1. Bugs in GHC
12.2.2. Bugs in GHCi (the interactive GHC)