The Glorious Glasgow Haskell Compilation System User's Guide, Version 7.8.0.20140228
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 7.8.1
- 1.5.1. Highlights
- 1.5.2. Full details
- 1.5.2.1. Language
- 1.5.2.2. Compiler
- 1.5.2.3. GHCi
- 1.5.2.4. Template Haskell
- 1.5.2.5. Runtime system
- 1.5.2.6. Build system
- 1.5.3. Libraries
- 1.5.3.1. array
- 1.5.3.2. base
- 1.5.3.3. bin-package-db
- 1.5.3.4. binary
- 1.5.3.5. bytestring
- 1.5.3.6. Cabal
- 1.5.3.7. containers
- 1.5.3.8. deepseq
- 1.5.3.9. directory
- 1.5.3.10. filepath
- 1.5.3.11. ghc-prim
- 1.5.3.12. haskell98
- 1.5.3.13. haskell2010
- 1.5.3.14. hoopl
- 1.5.3.15. hpc
- 1.5.3.16. integer-gmp
- 1.5.3.17. old-locale
- 1.5.3.18. old-time
- 1.5.3.19. process
- 1.5.3.20. template-haskell
- 1.5.3.21. time
- 1.5.3.22. unix
- 1.5.3.23. Win32
- 1.5.4. Known bugs
- 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. Multiline input
- 2.4.4. Type, class and other declarations
- 2.4.5. What's really in scope at the prompt?
- 2.4.5.1. The effect of
:load on what is in scope - 2.4.5.2. Controlling what is in scope with
import - 2.4.5.3. Controlling what is in scope with the
:module command - 2.4.5.4. Qualified names
- 2.4.5.5.
:module and
:load
- 2.4.6. The
:main and :run commands - 2.4.7. The
it variable - 2.4.8. Type defaulting in GHCi
- 2.4.9. Using a custom interactive printing function
- 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 and :seti commands - 2.8.1. GHCi options
- 2.8.2. Setting GHC command-line options in GHCi
- 2.8.3. Setting options for interactive evaluation only
- 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. Getting started: compiling programs
- 4.2. Options overview
- 4.2.1. Command-line arguments
- 4.2.2. Command line options in source files
- 4.2.3. Setting options in GHCi
- 4.3. Static, Dynamic, and Mode options
- 4.4. Meaningful file suffixes
- 4.5. Modes of operation
- 4.5.1. Using ghc
--make - 4.5.2. Expression evaluation mode
- 4.5.3. Batch compiler mode
- 4.5.3.1. Overriding the default behaviour for a file
- 4.6. Verbosity options
- 4.7. Filenames and separate compilation
- 4.7.1. Haskell source files
- 4.7.2. Output files
- 4.7.3. The search path
- 4.7.4. Redirecting the compilation output(s)
- 4.7.5. Keeping Intermediate Files
- 4.7.6. Redirecting temporary files
- 4.7.7. Other options related to interface files
- 4.7.8. The recompilation checker
- 4.7.9. How to compile mutually recursive modules
- 4.7.10. Using make
- 4.7.11. Dependency generation
- 4.7.12. Orphan modules and instance declarations
- 4.8. Warnings and sanity-checking
- 4.9.
Packages
- 4.9.1. Using Packages
- 4.9.2. The main package
- 4.9.3. Consequences of packages for the Haskell language
- 4.9.4. Package Databases
- 4.9.4.1. The
GHC_PACKAGE_PATH environment variable
- 4.9.5. Package IDs, dependencies, and broken packages
- 4.9.6. Package management (the
ghc-pkg command) - 4.9.7. Building a package from Haskell source
- 4.9.8.
InstalledPackageInfo: a package specification
- 4.10. Optimisation (code improvement)
- 4.10.1.
-O*: convenient “packages” of optimisation flags. - 4.10.2.
-f*: platform-independent flags
- 4.11. GHC Backends
- 4.11.1. Native code Generator (
-fasm) - 4.11.2. LLVM Code Generator (
-fllvm) - 4.11.3. C Code Generator (
-fvia-C) - 4.11.4. Unregisterised compilation
- 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.3.1. CPP and string gaps
- 4.12.4. Options affecting a Haskell pre-processor
- 4.12.5. Options affecting code generation
- 4.12.6. Options affecting linking
- 4.13. Using shared libraries
- 4.13.1. Building programs that use shared libraries
- 4.13.2. Shared libraries for Haskell packages
- 4.13.3. Shared libraries that export a C API
- 4.13.4. Finding shared libraries at runtime
- 4.13.4.1. Unix
- 4.13.4.2. Mac OS X
- 4.14. Using Concurrent Haskell
- 4.15. Using SMP parallelism
- 4.15.1. Compile-time options for SMP parallelism
- 4.15.2. RTS options for SMP parallelism
- 4.15.3. Hints for using SMP parallelism
- 4.16. Platform-specific Flags
- 4.17. Running a compiled program
- 4.17.1. Setting RTS options
- 4.17.1.1. Setting RTS options on the command line
- 4.17.1.2. Setting RTS options at compile time
- 4.17.1.3. Setting RTS options with the
GHCRTS
environment variable - 4.17.1.4. “Hooks” to change RTS behaviour
- 4.17.2. Miscellaneous RTS options
- 4.17.3. RTS options to control the garbage collector
- 4.17.4. RTS options for concurrency and parallelism
- 4.17.5. RTS options for profiling
- 4.17.6. Tracing
- 4.17.7. RTS options for hackers, debuggers, and over-interested
souls
- 4.17.8. Getting information about the RTS
- 4.18. Generating and compiling External Core Files
- 4.19. Debugging the compiler
- 4.19.1. Dumping out compiler intermediate structures
- 4.19.2. Formatting dumps
- 4.19.3. Suppressing unwanted information
- 4.19.4. Checking for consistency
- 4.19.5. How to read Core syntax (from some
-ddump
flags)
- 4.20. Flag reference
- 4.20.1. Verbosity options
- 4.20.2. Alternative modes of operation
- 4.20.3. Which phases to run
- 4.20.4. Redirecting output
- 4.20.5. Keeping intermediate files
- 4.20.6. Temporary files
- 4.20.7. Finding imports
- 4.20.8. Interface file options
- 4.20.9. Recompilation checking
- 4.20.10. Interactive-mode options
- 4.20.11. Packages
- 4.20.12. Language options
- 4.20.13. Warnings
- 4.20.14. Optimisation levels
- 4.20.15. Individual optimisations
- 4.20.16. Profiling options
- 4.20.17. Program coverage options
- 4.20.18. Haskell pre-processor options
- 4.20.19. C pre-processor options
- 4.20.20. Code generation options
- 4.20.21. Linking options
- 4.20.22. Plugin options
- 4.20.23. Replacing phases
- 4.20.24. Forcing options to particular phases
- 4.20.25. Platform-specific options
- 4.20.26. External core file options
- 4.20.27. Compiler debugging options
- 4.20.28. 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. Profiling Parallel and Concurrent Programs
- 5.7. Observing Code Coverage
- 5.7.1. A small example: Reciprocation
- 5.7.2. Options for instrumenting code for coverage
- 5.7.3. The hpc toolkit
- 5.7.3.1. hpc report
- 5.7.3.2. hpc markup
- 5.7.3.3. hpc sum
- 5.7.3.4. hpc combine
- 5.7.3.5. hpc map
- 5.7.3.6. hpc overlay and hpc draft
- 5.7.4. Caveats and Shortcomings of Haskell Program Coverage
- 5.8. 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. Negative literals
- 7.3.4. Fractional looking integer literals
- 7.3.5. Hierarchical Modules
- 7.3.6. Pattern guards
- 7.3.7. View patterns
- 7.3.8. Pattern synonyms
- 7.3.9. n+k patterns
- 7.3.10. Traditional record syntax
- 7.3.11. The recursive do-notation
- 7.3.11.1. Recursive binding groups
- 7.3.11.2. The
mdo notation
- 7.3.12. Parallel List Comprehensions
- 7.3.13. Generalised (SQL-Like) List Comprehensions
- 7.3.14. Monad comprehensions
- 7.3.15. Rebindable syntax and the implicit Prelude import
- 7.3.16. Postfix operators
- 7.3.17. Tuple sections
- 7.3.18. Lambda-case
- 7.3.19. Empty case alternatives
- 7.3.20. Multi-way if-expressions
- 7.3.21. Record field disambiguation
- 7.3.22. Record puns
- 7.3.23. Record wildcards
- 7.3.24. Local Fixity Declarations
- 7.3.25. Package-qualified imports
- 7.3.26. Safe imports
- 7.3.27. Explicit namespaces in import/export
- 7.3.28. Summary of stolen syntax
- 7.4. Extensions to data types and type synonyms
- 7.4.1. Data types with no constructors
- 7.4.2. Data type contexts
- 7.4.3. Infix type constructors, classes, and type variables
- 7.4.4. Type operators
- 7.4.5. Liberalised type synonyms
- 7.4.6. Existentially quantified data constructors
- 7.4.6.1. Why existential?
- 7.4.6.2. Existentials and type classes
- 7.4.6.3. Record Constructors
- 7.4.6.4. Restrictions
- 7.4.7. Declaring data types with explicit constructor signatures
- 7.4.8. 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. Automatically deriving
Typeable instances - 7.5.5. Generalised derived instances for newtypes
- 7.5.5.1. Generalising the deriving clause
- 7.5.5.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.1.4. Default method signatures
- 7.6.1.5. Nullary type classes
- 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. Instance resolution
- 7.6.3.2. Relaxed rules for the instance head
- 7.6.3.3. Relaxed rules for instance contexts
- 7.6.3.4. Undecidable instances
- 7.6.3.5. Overlapping instances
- 7.6.3.6. Type signatures in instance declarations
- 7.6.4. Overloaded string literals
- 7.6.5. Overloaded lists
- 7.6.5.1. The
IsList class - 7.6.5.2. Rebindable syntax
- 7.6.5.3. Defaulting
- 7.6.5.4. Speculation about the future
- 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. Overlap of data instances
- 7.7.2. Synonym families
- 7.7.2.1. Type family declarations
- 7.7.2.2. Type instance declarations
- 7.7.2.3. Closed type families
- 7.7.2.4. Type family examples
- 7.7.2.5. Compatibility and apartness of type family equations
- 7.7.2.6. Decidability of type synonym instances
- 7.7.3. Associated data and type families
- 7.7.3.1. Associated instances
- 7.7.3.2. Associated type synonym defaults
- 7.7.3.3. Scoping of class parameters
- 7.7.3.4. Instance contexts and associated type and data instances
- 7.7.4. Import and export
- 7.7.4.1. Examples
- 7.7.4.2. Instances
- 7.7.5. Type families and instance declarations
- 7.8. Kind polymorphism
- 7.8.1. Overview of kind polymorphism
- 7.8.2. Overview
- 7.8.3. Polymorphic kind recursion and complete kind signatures
- 7.8.4. Kind inference in closed type families
- 7.8.5. Kind inference in class instance declarations
- 7.9. Datatype promotion
- 7.9.1. Motivation
- 7.9.2. Overview
- 7.9.3. Distinguishing between types and constructors
- 7.9.4. Promoted lists and tuples types
- 7.9.5. Promoted Literals
- 7.9.6. Promoting existential data constructors
- 7.9.7. Promoting type operators
- 7.10. Equality constraints
- 7.11. The
Constraint kind - 7.12. Other type system extensions
- 7.12.1. Explicit universal quantification (forall)
- 7.12.2. The context of a type signature
- 7.12.3. Ambiguous types and the ambiguity check
- 7.12.4. Implicit parameters
- 7.12.4.1. Implicit-parameter type constraints
- 7.12.4.2. Implicit-parameter bindings
- 7.12.4.3. Implicit parameters and polymorphic recursion
- 7.12.4.4. Implicit parameters and monomorphism
- 7.12.5. Explicitly-kinded quantification
- 7.12.6. Arbitrary-rank polymorphism
- 7.12.6.1. Examples
- 7.12.6.2. Type inference
- 7.12.6.3. Implicit quantification
- 7.12.7. Impredicative polymorphism
- 7.12.8. Lexically scoped type variables
- 7.12.8.1. Overview
- 7.12.8.2. Declaration type signatures
- 7.12.8.3. Expression type signatures
- 7.12.8.4. Pattern type signatures
- 7.12.8.5. Class and instance declarations
- 7.12.9. Bindings and generalisation
- 7.12.9.1. Switching off the dreaded Monomorphism Restriction
- 7.12.9.2. Generalised typing of mutually recursive bindings
- 7.12.9.3. Let-generalisation
- 7.13. Typed Holes
- 7.14. Deferring type errors to runtime
- 7.14.1. Enabling deferring of type errors
- 7.14.2. Deferred type errors in GHCi
- 7.15. Template Haskell
- 7.15.1. Syntax
- 7.15.2. Using Template Haskell
- 7.15.3. A Template Haskell Worked Example
- 7.15.4. Using Template Haskell with Profiling
- 7.15.5. Template Haskell Quasi-quotation
- 7.16. Arrow notation
- 7.16.1. do-notation for commands
- 7.16.2. Conditional commands
- 7.16.3. Defining your own control structures
- 7.16.4. Primitive constructs
- 7.16.5. Differences with the paper
- 7.16.6. Portability
- 7.17. Bang patterns
- 7.17.1. Informal description of bang patterns
- 7.17.2. Syntax and semantics
- 7.18. Assertions
- 7.19. Pragmas
- 7.19.1. LANGUAGE pragma
- 7.19.2. OPTIONS_GHC pragma
- 7.19.3. INCLUDE pragma
- 7.19.4. WARNING and DEPRECATED pragmas
- 7.19.5. MINIMAL pragma
- 7.19.6. INLINE and NOINLINE pragmas
- 7.19.6.1. INLINE pragma
- 7.19.6.2. INLINABLE pragma
- 7.19.6.3. NOINLINE pragma
- 7.19.6.4. CONLIKE modifier
- 7.19.6.5. Phase control
- 7.19.7. LINE pragma
- 7.19.8. RULES pragma
- 7.19.9. SPECIALIZE pragma
- 7.19.9.1. SPECIALIZE INLINE
- 7.19.9.2. SPECIALIZE for imported functions
- 7.19.9.3. Obsolete SPECIALIZE syntax
- 7.19.10. SPECIALIZE instance pragma
- 7.19.11. UNPACK pragma
- 7.19.12. NOUNPACK pragma
- 7.19.13. SOURCE pragma
- 7.20. Rewrite rules
- 7.20.1. Syntax
- 7.20.2. Semantics
- 7.20.3. How rules interact with INLINE/NOINLINE and CONLIKE pragmas
- 7.20.4. List fusion
- 7.20.5. Specialisation
- 7.20.6. Controlling what's going on in rewrite rules
- 7.20.7. CORE pragma
- 7.21. Special built-in functions
- 7.22. Generic classes
- 7.23. Generic programming
- 7.23.1. Deriving representations
- 7.23.2. Writing generic functions
- 7.23.3. Generic defaults
- 7.23.4. More information
- 7.24. Roles
- 7.24.1. Nominal, Representational, and Phantom
- 7.24.2. Role inference
- 7.24.3. Role annotations
- 7.25. Concurrent and Parallel Haskell
- 7.25.1. Concurrent Haskell
- 7.25.2. Software Transactional Memory
- 7.25.3. Parallel Haskell
- 7.25.4. Annotating pure code for parallelism
- 7.25.5. Data Parallel Haskell
- 7.26. Safe Haskell
- 7.26.1. Uses of Safe Haskell
- 7.26.1.1. Strict type-safety (good style)
- 7.26.1.2. Building secure systems (restricted IO Monads)
- 7.26.2. Safe Language
- 7.26.3. Safe Imports
- 7.26.4. Trust and Safe Haskell Modes
- 7.26.4.1. Trust check (
-fpackage-trust disabled) - 7.26.4.2. Trust check (
-fpackage-trust enabled) - 7.26.4.3. Example
- 7.26.4.4. Trustworthy Requirements
- 7.26.4.5. Package Trust
- 7.26.5. Safe Haskell Inference
- 7.26.6. Safe Haskell Flag Summary
- 7.26.7. Safe Compilation
- 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.1.4. Interruptible foreign calls
- 8.1.5. The CAPI calling convention
- 8.1.6.
hs_thread_done()
- 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()
- 8.2.5. Floating point and the FFI
- 9. Extending and using GHC as a Library
- 9.1. Source annotations
- 9.1.1. Annotating values
- 9.1.2. Annotating types
- 9.1.3. Annotating modules
- 9.2. Using GHC as a Library
- 9.3. Compiler Plugins
- 9.3.1. Using compiler plugins
- 9.3.2. Writing compiler plugins
- 9.3.2.1.
CoreToDo in more detail - 9.3.2.2. Manipulating bindings
- 9.3.2.3. Using Annotations
- 10. An External Representation for the GHC Core Language (For GHC 6.10)
- 10.1. Introduction
- 10.2. External Grammar of Core
- 10.3. Informal Semantics
- 10.3.1. Program Organization and Modules
- 10.3.2. Namespaces
- 10.3.3. Types and Kinds
- 10.3.3.1. Types
- 10.3.3.2. Coercions
- 10.3.3.3. Kinds
- 10.3.3.4. Lifted and Unlifted Types
- 10.3.3.5. Type Constructors; Base Kinds and Higher Kinds
- 10.3.3.6. Type Synonyms and Type Equivalence
- 10.3.4. Algebraic data types
- 10.3.5. Newtypes
- 10.3.6. Expression Forms
- 10.3.7. Expression Evaluation
- 10.4. Primitive Module
- 10.4.1. Non-concurrent Back End
- 10.4.2. Literals
- 11. What to do when something goes wrong
- 11.1. When the compiler “does the wrong thing”
- 11.2. When your program “does the wrong thing”
- 12. Other Haskell utility programs
- 12.1. “Yacc for Haskell”: happy
- 12.2. Writing Haskell interfaces to C code:
hsc2hs
- 12.2.1. command line syntax
- 12.2.2. Input syntax
- 12.2.3. Custom constructs
- 12.2.4. Cross-compilation
- 13. Running GHC on Win32 systems
- 13.1.
Starting GHC on Windows platforms
- 13.2. Running GHCi on Windows
- 13.3.
Interacting with the terminal
- 13.4.
Differences in library behaviour
- 13.5.
Using GHC (and other GHC-compiled executables) with cygwin
- 13.5.1. Background
- 13.5.2. The problem
- 13.5.3. Things to do
- 13.6. Building and using Win32 DLLs
- 13.6.1. Creating a DLL
- 13.6.2. Making DLLs to be called from other languages
- 13.6.2.1. Using from VBA
- 13.6.2.2. Using from C++
- 14. Known bugs and infelicities
- 14.1. Haskell standards vs. Glasgow Haskell: language non-compliance
- 14.1.1. Divergence from Haskell 98 and Haskell 2010
- 14.1.1.1. Lexical syntax
- 14.1.1.2. Context-free syntax
- 14.1.1.3. Expressions and patterns
- 14.1.1.4. Declarations and bindings
- 14.1.1.5. Module system and interface files
- 14.1.1.6. Numbers, basic types, and built-in classes
- 14.1.1.7. In
Prelude support - 14.1.1.8. The Foreign Function Interface
- 14.1.2. GHC's interpretation of undefined behaviour in
Haskell 98 and Haskell 2010
- 14.2. Known bugs or infelicities
- 14.2.1. Bugs in GHC
- 14.2.2. Bugs in GHCi (the interactive GHC)
- Index