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

The GHC Team


Table of Contents

The Glasgow Haskell Compiler License
1. Introduction to GHC
1.1. Obtaining GHC
1.2. Meta-information: Web sites, mailing lists, etc.
1.3. Reporting bugs in GHC
1.4. GHC version numbering policy
1.5. Release notes for version 6.12.1
1.5.1. Highlights
1.5.2. Language changes
1.5.3. Warnings
1.5.4. Runtime system
1.5.5. Build system
1.5.6. Compiler
1.5.7. GHCi
1.5.8. Template Haskell
1.5.9. Package Handling
1.5.10. Libraries
1.5.10.1. array
1.5.10.2. base
1.5.10.3. bytestring
1.5.10.4. Cabal
1.5.10.5. containers
1.5.10.6. directory
1.5.10.7. dph (dph-base, dph-par, dph-prim-interface, dph-prim-par, dph-prim-seq, dph-seq)
1.5.10.8. extensible-exceptions
1.5.10.9. filepath
1.5.10.10. ghc-binary
1.5.10.11. ghc-prim
1.5.10.12. haskell98
1.5.10.13. hpc
1.5.10.14. integer-gmp
1.5.10.15. integer-simple
1.5.10.16. old-locale
1.5.10.17. old-time
1.5.10.18. packedstring
1.5.10.19. pretty
1.5.10.20. process
1.5.10.21. random
1.5.10.22. syb
1.5.10.23. template-haskell
1.5.10.24. time
1.5.10.25. unix
1.5.10.26. Win32
2. Using GHCi
2.1. Introduction to GHCi
2.2. Loading source files
2.2.1. Modules vs. filenames
2.2.2. Making changes and recompilation
2.3. Loading compiled code
2.4. Interactive evaluation at the prompt
2.4.1. I/O actions at the prompt
2.4.2. Using do-notation at the prompt
2.4.3. What's really in scope at the prompt?
2.4.3.1. :module and :load
2.4.3.2. Qualified names
2.4.3.3. The :main and :run commands
2.4.4. The it variable
2.4.5. Type defaulting in GHCi
2.5. The GHCi Debugger
2.5.1. Breakpoints and inspecting variables
2.5.1.1. Setting breakpoints
2.5.1.2. Listing and deleting breakpoints
2.5.2. Single-stepping
2.5.3. Nested breakpoints
2.5.4. The _result variable
2.5.5. Tracing and history
2.5.6. Debugging exceptions
2.5.7. Example: inspecting functions
2.5.8. Limitations
2.6. Invoking GHCi
2.6.1. Packages
2.6.2. Extra libraries
2.7. GHCi commands
2.8. The :set command
2.8.1. GHCi options
2.8.2. Setting GHC command-line options in GHCi
2.9. The .ghci file
2.10. Compiling to object code inside GHCi
2.11. FAQ and Things To Watch Out For
3. Using runghc
3.1. Flags
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, Dynamic, and Mode 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.4.3.1. Overriding the default behaviour for a file
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. The main package
4.8.3. Consequences of packages for the Haskell language
4.8.4. Package Databases
4.8.4.1. The GHC_PACKAGE_PATH environment variable
4.8.5. Package IDs, dependencies, and broken packages
4.8.6. Package management (the ghc-pkg command)
4.8.7. Building a package from Haskell source
4.8.8. 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
4.10.3.1. CPP and string gaps
4.10.4. Options affecting a Haskell pre-processor
4.10.5. Options affecting code generation
4.10.6. Options affecting linking
4.11. Using shared libraries
4.11.1. Building programs that use shared libraries
4.11.2. Shared libraries for Haskell packages
4.11.3. Shared libraries that export a C API
4.11.4. Finding shared libraries at runtime
4.12. Using Concurrent Haskell
4.13. Using SMP parallelism
4.13.1. Compile-time options for SMP parallelism
4.13.2. RTS options for SMP parallelism
4.13.3. Hints for using SMP parallelism
4.14. Platform-specific Flags
4.15. Running a compiled program
4.15.1. Setting global RTS options
4.15.2. Miscellaneous RTS options
4.15.3. RTS options to control the garbage collector
4.15.4. RTS options for concurrency and parallelism
4.15.5. RTS options for profiling
4.15.6. Tracing
4.15.7. RTS options for hackers, debuggers, and over-interested souls
4.15.8. “Hooks” to change RTS behaviour
4.15.9. Getting information about the RTS
4.16. Generating and compiling External Core Files
4.17. Debugging the compiler
4.17.1. Dumping out compiler intermediate structures
4.17.2. Checking for consistency
4.17.3. How to read Core syntax (from some -ddump flags)
4.17.4. Unregisterised compilation
4.18. Flag reference
4.18.1. Help and verbosity options
4.18.2. Which phases to run
4.18.3. Alternative modes of operation
4.18.4. Redirecting output
4.18.5. Keeping intermediate files
4.18.6. Temporary files
4.18.7. Finding imports
4.18.8. Interface file options
4.18.9. Recompilation checking
4.18.10. Interactive-mode options
4.18.11. Packages
4.18.12. Language options
4.18.13. Warnings
4.18.14. Optimisation levels
4.18.15. Individual optimisations
4.18.16. Profiling options
4.18.17. Program coverage options
4.18.18. Haskell pre-processor options
4.18.19. C pre-processor options
4.18.20. Code generation options
4.18.21. Linking options
4.18.22. Replacing phases
4.18.23. Forcing options to particular phases
4.18.24. Platform-specific options
4.18.25. External core file options
4.18.26. Compiler debugging options
4.18.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
5.4.2.1. Hints for using retainer profiling
5.4.3. Biographical Profiling
5.4.4. Actual memory residency
5.5. hp2ps––heap profile to PostScript
5.5.1. Manipulating the hp file
5.5.2. Zooming in on regions of your profile
5.5.3. Viewing the heap profile of a running program
5.5.4. Viewing a heap profile in real time
5.6. Observing Code Coverage
5.6.1. A small example: Reciprocation
5.6.2. Options for instrumenting code for coverage
5.6.3. The hpc toolkit
5.6.3.1. hpc report
5.6.3.2. hpc markup
5.6.3.3. hpc sum
5.6.3.4. hpc combine
5.6.3.5. hpc map
5.6.3.6. hpc overlay and hpc draft
5.6.4. Caveats and Shortcomings of Haskell Program Coverage
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. Unicode syntax
7.3.2. The magic hash
7.3.3. New qualified operator syntax
7.3.4. Hierarchical Modules
7.3.5. Pattern guards
7.3.6. View patterns
7.3.7. n+k patterns
7.3.8. The recursive do-notation
7.3.8.1. Details of recursive do-notation
7.3.8.2. Mdo-notation (deprecated)
7.3.9. Parallel List Comprehensions
7.3.10. Generalised (SQL-Like) List Comprehensions
7.3.11. Rebindable syntax and the implicit Prelude import
7.3.12. Postfix operators
7.3.13. Tuple sections
7.3.14. Record field disambiguation
7.3.15. Record puns
7.3.16. Record wildcards
7.3.17. Local Fixity Declarations
7.3.18. Package-qualified imports
7.3.19. Summary of stolen syntax
7.4. Extensions to data types and type synonyms
7.4.1. Data types with no constructors
7.4.2. Infix type constructors, classes, and type variables
7.4.3. Liberalised type synonyms
7.4.4. Existentially quantified data constructors
7.4.4.1. Why existential?
7.4.4.2. Existentials and type classes
7.4.4.3. Record Constructors
7.4.4.4. Restrictions
7.4.5. Declaring data types with explicit constructor signatures
7.4.6. Generalised Algebraic Data Types (GADTs)
7.5. Extensions to the "deriving" mechanism
7.5.1. Inferred context for deriving clauses
7.5.2. Stand-alone deriving declarations
7.5.3. Deriving clause for extra classes (Typeable, Data, etc)
7.5.4. Generalised derived instances for newtypes
7.5.4.1. Generalising the deriving clause
7.5.4.2. A more precise specification
7.6. Class and instances declarations
7.6.1. Class declarations
7.6.1.1. Multi-parameter type classes
7.6.1.2. The superclasses of a class declaration
7.6.1.3. Class method types
7.6.2. Functional dependencies
7.6.2.1. Rules for functional dependencies
7.6.2.2. Background on functional dependencies
7.6.3. Instance declarations
7.6.3.1. Relaxed rules for the instance head
7.6.3.2. Relaxed rules for instance contexts
7.6.3.3. Undecidable instances
7.6.3.4. Overlapping instances
7.6.4. Overloaded string literals
7.7. Type families
7.7.1. Data families
7.7.1.1. Data family declarations
7.7.1.2. Data instance declarations
7.7.1.3. Import and export
7.7.2. Synonym families
7.7.2.1. Type family declarations
7.7.2.2. Type instance declarations
7.7.2.3. Equality constraints
7.7.2.4. Type families and instance declarations
7.8. Other type system extensions
7.8.1. Explicit universal quantification (forall)
7.8.2. The context of a type signature
7.8.3. Implicit parameters
7.8.3.1. Implicit-parameter type constraints
7.8.3.2. Implicit-parameter bindings
7.8.3.3. Implicit parameters and polymorphic recursion
7.8.3.4. Implicit parameters and monomorphism
7.8.4. Explicitly-kinded quantification
7.8.5. Arbitrary-rank polymorphism
7.8.5.1. Examples
7.8.5.2. Type inference
7.8.5.3. Implicit quantification
7.8.6. Impredicative polymorphism
7.8.7. Lexically scoped type variables
7.8.7.1. Overview
7.8.7.2. Declaration type signatures
7.8.7.3. Expression type signatures
7.8.7.4. Pattern type signatures
7.8.7.5. Class and instance declarations
7.8.8. Generalised typing of mutually recursive bindings
7.8.9. Monomorphic local bindings
7.9. Template Haskell
7.9.1. Syntax
7.9.2. Using Template Haskell
7.9.3. A Template Haskell Worked Example
7.9.4. Using Template Haskell with Profiling
7.9.5. Template Haskell Quasi-quotation
7.10. Arrow notation
7.10.1. do-notation for commands
7.10.2. Conditional commands
7.10.3. Defining your own control structures
7.10.4. Primitive constructs
7.10.5. Differences with the paper
7.10.6. Portability
7.11. Bang patterns
7.11.1. Informal description of bang patterns
7.11.2. Syntax and semantics
7.12. Assertions
7.13. Pragmas
7.13.1. LANGUAGE pragma
7.13.2. OPTIONS_GHC pragma
7.13.3. INCLUDE pragma
7.13.4. WARNING and DEPRECATED pragmas
7.13.5. INLINE and NOINLINE pragmas
7.13.5.1. INLINE pragma
7.13.5.2. NOINLINE pragma
7.13.5.3. Phase control
7.13.6. ANN pragmas
7.13.6.1. Annotating values
7.13.6.2. Annotating types
7.13.6.3. Annotating modules
7.13.7. LINE pragma
7.13.8. RULES pragma
7.13.9. SPECIALIZE pragma
7.13.10. SPECIALIZE instance pragma
7.13.11. UNPACK pragma
7.13.12. SOURCE pragma
7.14. Rewrite rules
7.14.1. Syntax
7.14.2. Semantics
7.14.3. List fusion
7.14.4. Specialisation
7.14.5. Controlling what's going on
7.14.6. CORE pragma
7.15. Special built-in functions
7.16. Generic classes
7.16.1. Using generics
7.16.2. Changes wrt the paper
7.16.3. Terminology and restrictions
7.16.4. Another example
7.17. Control over monomorphism
7.17.1. Switching off the dreaded Monomorphism Restriction
7.17.2. Monomorphic pattern bindings
7.18. Concurrent and Parallel Haskell
7.18.1. Concurrent Haskell
7.18.2. Software Transactional Memory
7.18.3. Parallel Haskell
7.18.4. Annotating pure code for parallelism
7.18.5. Data Parallel Haskell
8. Foreign function interface (FFI)
8.1. GHC extensions to the FFI Addendum
8.1.1. Unboxed types
8.1.2. Newtype wrapping of the IO monad
8.1.3. Primitive imports
8.2. Using the FFI with GHC
8.2.1. Using foreign export and foreign import ccall "wrapper" with GHC
8.2.1.1. Using your own main()
8.2.1.2. Making a Haskell library that can be called from foreign code
8.2.2. Using header files
8.2.3. Memory Allocation
8.2.4. Multi-threading and the FFI
8.2.4.1. Foreign imports and multi-threading
8.2.4.2. The relationship between Haskell threads and OS threads
8.2.4.3. Foreign exports and multi-threading
8.2.4.4. On the use of hs_exit()
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 Windows platforms
11.2. Running GHCi on Windows
11.3. Interacting with the terminal
11.4. Differences in library behaviour
11.5. Using GHC (and other GHC-compiled executables) with cygwin
11.5.1. Background
11.5.2. The problem
11.5.3. Things to do
11.6. Building and using Win32 DLLs
11.6.1. Creating a DLL
11.6.2. Making DLLs to be called from other languages
11.6.3. Beware of DllMain()!
12. Known bugs and infelicities
12.1. Haskell 98 vs. Glasgow Haskell: language non-compliance
12.1.1. Divergence from Haskell 98
12.1.1.1. Lexical syntax
12.1.1.2. Context-free syntax
12.1.1.3. Expressions and patterns
12.1.1.4. Declarations and bindings
12.1.1.5. Module system and interface files
12.1.1.6. Numbers, basic types, and built-in classes
12.1.1.7. In Prelude support
12.1.2. GHC's interpretation of undefined behaviour in Haskell 98
12.1.3. Divergence from the FFI specification
12.2. Known bugs or infelicities
12.2.1. Bugs in GHC
12.2.2. Bugs in GHCi (the interactive GHC)
Index