The Glorious Glasgow Haskell Compilation System User's Guide, Version 6.10.1
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.3. GHC version numbering policy
- 1.4. Release notes for version 6.10.1
- 1.4.1. User-visible compiler changes
- 1.4.2. Deprecated flags
- 1.4.3. GHC API changes
- 1.4.4. GHCi changes
- 1.4.5. Runtime system changes
- 1.4.6. runghc
- 1.4.7. ghc-pkg
- 1.4.8. Haddock
- 1.4.9. DPH changes
- 1.4.10. Boot Libraries
- 1.4.10.1. array
- 1.4.10.2. base
- 1.4.10.3. bytestring
- 1.4.10.4. Cabal
- 1.4.10.5. containers
- 1.4.10.6. directory
- 1.4.10.7. editline
- 1.4.10.8. filepath
- 1.4.10.9. ghc-prim
- 1.4.10.10. haskell98
- 1.4.10.11. hpc
- 1.4.10.12. integer
- 1.4.10.13. old-locale
- 1.4.10.14. old-time
- 1.4.10.15. packedstring
- 1.4.10.16. pretty
- 1.4.10.17. process
- 1.4.10.18. random
- 1.4.10.19. readline
- 1.4.10.20. syb
- 1.4.10.21. template-haskell
- 1.4.10.22. unix
- 1.4.10.23. Win32
- 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.1.2.1. Installing
- 2.1.2.2. 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. I/O actions at the prompt
- 3.4.2. Using
do-notation at the prompt - 3.4.3. What's really in scope at the prompt?
- 3.4.3.1.
:module and
:load - 3.4.3.2. Qualified names
- 3.4.3.3. The
:main and :run commands
- 3.4.4. The
it variable - 3.4.5. Type defaulting in GHCi
- 3.5. The GHCi Debugger
- 3.5.1. Breakpoints and inspecting variables
- 3.5.1.1. Setting breakpoints
- 3.5.1.2. Listing and deleting breakpoints
- 3.5.2. Single-stepping
- 3.5.3. Nested breakpoints
- 3.5.4. The
_result variable - 3.5.5. Tracing and history
- 3.5.6. Debugging exceptions
- 3.5.7. Example: inspecting functions
- 3.5.8. Limitations
- 3.6. Invoking GHCi
- 3.6.1. Packages
- 3.6.2. Extra libraries
- 3.7. GHCi commands
- 3.8. The
:set command - 3.8.1. GHCi options
- 3.8.2. Setting GHC command-line options in GHCi
- 3.9. The
.ghci file - 3.10. Compiling to object code inside GHCi
- 3.11. FAQ and Things To Watch Out For
- 4. Using runghc
- 4.1. Flags
- 5. Using GHC
- 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
- 6. Profiling
- 6.1. Cost centres and cost-centre stacks
- 6.1.1. Inserting cost centres by hand
- 6.1.2. Rules for attributing costs
- 6.2. Compiler options for profiling
- 6.3. Time and allocation profiling
- 6.4. Profiling memory usage
- 6.4.1. RTS options for heap profiling
- 6.4.2. Retainer Profiling
- 6.4.2.1. Hints for using retainer profiling
- 6.4.3. Biographical Profiling
- 6.4.4. Actual memory residency
- 6.5. hp2ps––heap profile to PostScript
- 6.5.1. Manipulating the hp file
- 6.5.2. Zooming in on regions of your profile
- 6.5.3. Viewing the heap profile of a running program
- 6.5.4. Viewing a heap profile in real time
- 6.6. Observing Code Coverage
- 6.6.1. A small example: Reciprocation
- 6.6.2. Options for instrumenting code for coverage
- 6.6.3. The hpc toolkit
- 6.6.3.1. hpc report
- 6.6.3.2. hpc markup
- 6.6.3.3. hpc sum
- 6.6.3.4. hpc combine
- 6.6.3.5. hpc map
- 6.6.3.6. hpc overlay and hpc draft
- 6.6.4. Caveats and Shortcomings of Haskell Program Coverage
- 6.7. Using “ticky-ticky” profiling (for implementors)
- 7. Advice on: sooner, faster, smaller, thriftier
- 7.1. Sooner: producing a program more quickly
- 7.2. Faster: producing a program that runs quicker
- 7.3. Smaller: producing a program that is smaller
- 7.4. Thriftier: producing a program that gobbles less heap space
- 8. GHC Language Features
- 8.1. Language options
- 8.2. Unboxed types and primitive operations
- 8.2.1. Unboxed types
- 8.2.2. Unboxed Tuples
- 8.3. Syntactic extensions
- 8.3.1. The magic hash
- 8.3.2. New qualified operator syntax
- 8.3.3. Hierarchical Modules
- 8.3.4. Pattern guards
- 8.3.5. View patterns
- 8.3.6. The recursive do-notation
- 8.3.7. Parallel List Comprehensions
- 8.3.8. Generalised (SQL-Like) List Comprehensions
- 8.3.9. Rebindable syntax and the implicit Prelude import
- 8.3.10. Postfix operators
- 8.3.11. Record field disambiguation
- 8.3.12. Record puns
- 8.3.13. Record wildcards
- 8.3.14. Local Fixity Declarations
- 8.3.15. Package-qualified imports
- 8.3.16. Summary of stolen syntax
- 8.4. Extensions to data types and type synonyms
- 8.4.1. Data types with no constructors
- 8.4.2. Infix type constructors, classes, and type variables
- 8.4.3. Liberalised type synonyms
- 8.4.4. Existentially quantified data constructors
- 8.4.4.1. Why existential?
- 8.4.4.2. Existentials and type classes
- 8.4.4.3. Record Constructors
- 8.4.4.4. Restrictions
- 8.4.5. Declaring data types with explicit constructor signatures
- 8.4.6. Generalised Algebraic Data Types (GADTs)
- 8.5. Extensions to the "deriving" mechanism
- 8.5.1. Inferred context for deriving clauses
- 8.5.2. Stand-alone deriving declarations
- 8.5.3. Deriving clause for classes
Typeable and Data - 8.5.4. Generalised derived instances for newtypes
- 8.5.4.1. Generalising the deriving clause
- 8.5.4.2. A more precise specification
- 8.6. Class and instances declarations
- 8.6.1. Class declarations
- 8.6.1.1. Multi-parameter type classes
- 8.6.1.2. The superclasses of a class declaration
- 8.6.1.3. Class method types
- 8.6.2. Functional dependencies
- 8.6.2.1. Rules for functional dependencies
- 8.6.2.2. Background on functional dependencies
- 8.6.3. Instance declarations
- 8.6.3.1. Relaxed rules for instance declarations
- 8.6.3.2. Undecidable instances
- 8.6.3.3. Overlapping instances
- 8.6.3.4. Type synonyms in the instance head
- 8.6.4. Overloaded string literals
- 8.7. Type families
- 8.7.1. Data families
- 8.7.1.1. Data family declarations
- 8.7.1.2. Data instance declarations
- 8.7.1.3. Import and export
- 8.7.2. Synonym families
- 8.7.2.1. Type family declarations
- 8.7.2.2. Type instance declarations
- 8.7.2.3. Equality constraints
- 8.8. Other type system extensions
- 8.8.1. Type signatures
- 8.8.1.1. The context of a type signature
- 8.8.2. Implicit parameters
- 8.8.2.1. Implicit-parameter type constraints
- 8.8.2.2. Implicit-parameter bindings
- 8.8.2.3. Implicit parameters and polymorphic recursion
- 8.8.2.4. Implicit parameters and monomorphism
- 8.8.3. Explicitly-kinded quantification
- 8.8.4. Arbitrary-rank polymorphism
- 8.8.4.1. Examples
- 8.8.4.2. Type inference
- 8.8.4.3. Implicit quantification
- 8.8.5. Impredicative polymorphism
- 8.8.6. Lexically scoped type variables
- 8.8.6.1. Overview
- 8.8.6.2. Declaration type signatures
- 8.8.6.3. Expression type signatures
- 8.8.6.4. Pattern type signatures
- 8.8.6.5. Class and instance declarations
- 8.8.7. Generalised typing of mutually recursive bindings
- 8.9. Template Haskell
- 8.9.1. Syntax
- 8.9.2. Using Template Haskell
- 8.9.3. A Template Haskell Worked Example
- 8.9.4. Using Template Haskell with Profiling
- 8.9.5. Template Haskell Quasi-quotation
- 8.10. Arrow notation
- 8.10.1. do-notation for commands
- 8.10.2. Conditional commands
- 8.10.3. Defining your own control structures
- 8.10.4. Primitive constructs
- 8.10.5. Differences with the paper
- 8.10.6. Portability
- 8.11. Bang patterns
- 8.11.1. Informal description of bang patterns
- 8.11.2. Syntax and semantics
- 8.12. Assertions
- 8.13. Pragmas
- 8.13.1. LANGUAGE pragma
- 8.13.2. OPTIONS_GHC pragma
- 8.13.3. INCLUDE pragma
- 8.13.4. WARNING and DEPRECATED pragmas
- 8.13.5. INLINE and NOINLINE pragmas
- 8.13.5.1. INLINE pragma
- 8.13.5.2. NOINLINE pragma
- 8.13.5.3. Phase control
- 8.13.6. LINE pragma
- 8.13.7. RULES pragma
- 8.13.8. SPECIALIZE pragma
- 8.13.9. SPECIALIZE instance pragma
- 8.13.10. UNPACK pragma
- 8.13.11. SOURCE pragma
- 8.14. Rewrite rules
- 8.14.1. Syntax
- 8.14.2. Semantics
- 8.14.3. List fusion
- 8.14.4. Specialisation
- 8.14.5. Controlling what's going on
- 8.14.6. CORE pragma
- 8.15. Special built-in functions
- 8.16. Generic classes
- 8.16.1. Using generics
- 8.16.2. Changes wrt the paper
- 8.16.3. Terminology and restrictions
- 8.16.4. Another example
- 8.17. Control over monomorphism
- 8.17.1. Switching off the dreaded Monomorphism Restriction
- 8.17.2. Monomorphic pattern bindings
- 8.18. Concurrent and Parallel Haskell
- 8.18.1. Concurrent Haskell
- 8.18.2. Software Transactional Memory
- 8.18.3. Parallel Haskell
- 8.18.4. Annotating pure code for parallelism
- 8.18.5. Data Parallel Haskell
- 9.
Foreign function interface (FFI)
- 9.1. GHC extensions to the FFI Addendum
- 9.1.1. Unboxed types
- 9.1.2. Newtype wrapping of the IO monad
- 9.2. Using the FFI with GHC
- 9.2.1. Using
foreign export and foreign import ccall "wrapper" with GHC - 9.2.1.1. Using your own
main() - 9.2.1.2. Making a Haskell library that can be called from foreign
code
- 9.2.1.3. On the use of
hs_exit()
- 9.2.2. Using function headers
- 9.2.3. Memory Allocation
- 10. What to do when something goes wrong
- 10.1. When the compiler “does the wrong thing”
- 10.2. When your program “does the wrong thing”
- 11. Other Haskell utility programs
- 11.1. Ctags and Etags for Haskell: hasktags
- 11.1.1. Using tags with your editor
- 11.2. “Yacc for Haskell”: happy
- 11.3. Writing Haskell interfaces to C code:
hsc2hs
- 11.3.1. command line syntax
- 11.3.2. Input syntax
- 11.3.3. Custom constructs
- 12. Running GHC on Win32 systems
- 12.1.
Starting GHC on Windows platforms
- 12.2. Running GHCi on Windows
- 12.3.
Interacting with the terminal
- 12.4.
Differences in library behaviour
- 12.5.
Using GHC (and other GHC-compiled executables) with cygwin
- 12.5.1. Background
- 12.5.2. The problem
- 12.5.3. Things to do
- 12.6. Building and using Win32 DLLs
- 12.6.1. Creating a DLL
- 12.6.2. Making DLLs to be called from other languages
- 12.6.3. Beware of DllMain()!
- 13. Known bugs and infelicities
- 13.1. Haskell 98 vs. Glasgow Haskell: language non-compliance
- 13.1.1. Divergence from Haskell 98
- 13.1.1.1. Lexical syntax
- 13.1.1.2. Context-free syntax
- 13.1.1.3. Expressions and patterns
- 13.1.1.4. Declarations and bindings
- 13.1.1.5. Module system and interface files
- 13.1.1.6. Numbers, basic types, and built-in classes
- 13.1.1.7. In
Prelude support
- 13.1.2. GHC's interpretation of undefined behaviour in
Haskell 98
- 13.2. Known bugs or infelicities
- 13.2.1. Bugs in GHC
- 13.2.2. Bugs in GHCi (the interactive GHC)
- Index