The Glorious Glasgow Haskell Compilation System User's Guide, Version 7.4.1
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.2.1
- 1.5.1. Highlights
- 1.5.2. Language changes
- 1.5.3. Warnings
- 1.5.4. Dumps
- 1.5.5. Runtime system
- 1.5.6. Compiler
- 1.5.7. GHCi
- 1.5.8. ghc-pkg
- 1.5.9. hsc2hs
- 1.5.10. GHC API
- 1.5.11. Build System and Infrastructure
- 1.5.12. Libraries
- 1.5.12.1. array
- 1.5.12.2. base
- 1.5.12.3. bin-package-db
- 1.5.12.4. binary
- 1.5.12.5. bytestring
- 1.5.12.6. Cabal
- 1.5.12.7. containers
- 1.5.12.8. directory
- 1.5.12.9. extensible-exceptions
- 1.5.12.10. filepath
- 1.5.12.11. ghc-binary
- 1.5.12.12. ghc-prim
- 1.5.12.13. haskell98
- 1.5.12.14. haskell2010
- 1.5.12.15. hoopl
- 1.5.12.16. hpc
- 1.5.12.17. integer-gmp
- 1.5.12.18. old-locale
- 1.5.12.19. old-time
- 1.5.12.20. pretty
- 1.5.12.21. process
- 1.5.12.22. random
- 1.5.12.23. template-haskell
- 1.5.12.24. time
- 1.5.12.25. unix
- 1.5.12.26. Win32
- 1.6. Release notes for version 7.2.2
- 1.7. Release notes for version 7.4.1
- 1.7.1. Highlights
- 1.7.2. Full details
- 1.7.2.1. Language
- 1.7.2.2. Compiler
- 1.7.2.3. GHCi
- 1.7.2.4. Template Haskell
- 1.7.2.5. Profiling
- 1.7.2.6. Event logging
- 1.7.2.7. Runtime system
- 1.7.2.8. Build system
- 1.7.3. Libraries
- 1.7.3.1. array
- 1.7.3.2. base
- 1.7.3.3. bin-package-db
- 1.7.3.4. binary
- 1.7.3.5. bytestring
- 1.7.3.6. Cabal
- 1.7.3.7. containers
- 1.7.3.8. deepseq
- 1.7.3.9. directory
- 1.7.3.10. extensible-exceptions
- 1.7.3.11. filepath
- 1.7.3.12. ghc-prim
- 1.7.3.13. haskell98
- 1.7.3.14. haskell2010
- 1.7.3.15. hoopl
- 1.7.3.16. hpc
- 1.7.3.17. integer-gmp
- 1.7.3.18. old-locale
- 1.7.3.19. old-time
- 1.7.3.20. pretty
- 1.7.3.21. process
- 1.7.3.22. template-haskell
- 1.7.3.23. time
- 1.7.3.24. unix
- 1.7.3.25. 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. 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.
:module and
:load - 2.4.5.2. Qualified names
- 2.4.5.3. The
:main and :run commands
- 2.4.6. The
it variable - 2.4.7. 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. 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. Help and 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. Help and verbosity options
- 4.20.2. Which phases to run
- 4.20.3. Alternative modes of operation
- 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. Hierarchical Modules
- 7.3.4. Pattern guards
- 7.3.5. View patterns
- 7.3.6. n+k patterns
- 7.3.7. Traditional record syntax
- 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. Monad comprehensions
- 7.3.12. Rebindable syntax and the implicit Prelude import
- 7.3.13. Postfix operators
- 7.3.14. Tuple sections
- 7.3.15. Record field disambiguation
- 7.3.16. Record puns
- 7.3.17. Record wildcards
- 7.3.18. Local Fixity Declarations
- 7.3.19. Package-qualified imports
- 7.3.20. Safe imports
- 7.3.21. 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. Liberalised type synonyms
- 7.4.5. Existentially quantified data constructors
- 7.4.5.1. Why existential?
- 7.4.5.2. Existentials and type classes
- 7.4.5.3. Record Constructors
- 7.4.5.4. Restrictions
- 7.4.6. Declaring data types with explicit constructor signatures
- 7.4.7. 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.1.4. Default method signatures
- 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. 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. Overlap of type synonym instances
- 7.7.2.4. 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.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 and promotion
- 7.8.1. Kind polymorphism
- 7.8.2. Datatype promotion
- 7.8.2.1. Distinguishing between types and constructors
- 7.8.2.2. Promoted lists and tuples types
- 7.8.3. Shortcomings of the current implementation
- 7.9. Equality constraints
- 7.10. The
Constraint kind - 7.11. Other type system extensions
- 7.11.1. Explicit universal quantification (forall)
- 7.11.2. The context of a type signature
- 7.11.3. Implicit parameters
- 7.11.3.1. Implicit-parameter type constraints
- 7.11.3.2. Implicit-parameter bindings
- 7.11.3.3. Implicit parameters and polymorphic recursion
- 7.11.3.4. Implicit parameters and monomorphism
- 7.11.4. Explicitly-kinded quantification
- 7.11.5. Arbitrary-rank polymorphism
- 7.11.5.1. Examples
- 7.11.5.2. Type inference
- 7.11.5.3. Implicit quantification
- 7.11.6. Impredicative polymorphism
- 7.11.7. Lexically scoped type variables
- 7.11.7.1. Overview
- 7.11.7.2. Declaration type signatures
- 7.11.7.3. Expression type signatures
- 7.11.7.4. Pattern type signatures
- 7.11.7.5. Class and instance declarations
- 7.11.8. Generalised typing of mutually recursive bindings
- 7.11.9. Monomorphic local bindings
- 7.12. Template Haskell
- 7.12.1. Syntax
- 7.12.2. Using Template Haskell
- 7.12.3. A Template Haskell Worked Example
- 7.12.4. Using Template Haskell with Profiling
- 7.12.5. Template Haskell Quasi-quotation
- 7.13. Arrow notation
- 7.13.1. do-notation for commands
- 7.13.2. Conditional commands
- 7.13.3. Defining your own control structures
- 7.13.4. Primitive constructs
- 7.13.5. Differences with the paper
- 7.13.6. Portability
- 7.14. Bang patterns
- 7.14.1. Informal description of bang patterns
- 7.14.2. Syntax and semantics
- 7.15. Assertions
- 7.16. Pragmas
- 7.16.1. LANGUAGE pragma
- 7.16.2. OPTIONS_GHC pragma
- 7.16.3. INCLUDE pragma
- 7.16.4. WARNING and DEPRECATED pragmas
- 7.16.5. INLINE and NOINLINE pragmas
- 7.16.5.1. INLINE pragma
- 7.16.5.2. INLINABLE pragma
- 7.16.5.3. NOINLINE pragma
- 7.16.5.4. CONLIKE modifier
- 7.16.5.5. Phase control
- 7.16.6. LINE pragma
- 7.16.7. RULES pragma
- 7.16.8. SPECIALIZE pragma
- 7.16.8.1. SPECIALIZE INLINE
- 7.16.8.2. SPECIALIZE for imported functions
- 7.16.8.3. Obsolete SPECIALIZE syntax
- 7.16.9. SPECIALIZE instance pragma
- 7.16.10. UNPACK pragma
- 7.16.11. NOUNPACK pragma
- 7.16.12. SOURCE pragma
- 7.17. Rewrite rules
- 7.17.1. Syntax
- 7.17.2. Semantics
- 7.17.3. How rules interact with INLINE/NOINLINE and CONLIKE pragmas
- 7.17.4. List fusion
- 7.17.5. Specialisation
- 7.17.6. Controlling what's going on in rewrite rules
- 7.17.7. CORE pragma
- 7.18. Special built-in functions
- 7.19. Generic classes
- 7.20. Generic programming
- 7.20.1. Deriving representations
- 7.20.2. Writing generic functions
- 7.20.3. Generic defaults
- 7.20.4. More information
- 7.21. Control over monomorphism
- 7.21.1. Switching off the dreaded Monomorphism Restriction
- 7.21.2. Monomorphic pattern bindings
- 7.22. Concurrent and Parallel Haskell
- 7.22.1. Concurrent Haskell
- 7.22.2. Software Transactional Memory
- 7.22.3. Parallel Haskell
- 7.22.4. Annotating pure code for parallelism
- 7.22.5. Data Parallel Haskell
- 7.23. Safe Haskell
- 7.23.1. Uses of Safe Haskell
- 7.23.1.1. Strict type-safety (good style)
- 7.23.1.2. Building secure systems (restricted IO Monads)
- 7.23.2. Safe Language
- 7.23.3. Safe Imports
- 7.23.4. Trust and Safe Haskell Modes
- 7.23.4.1. Trust check (
-fpackage-trust disabled) - 7.23.4.2. Trust check (
-fpackage-trust enabled) - 7.23.4.3. Example
- 7.23.4.4. Trustworthy Requirements
- 7.23.4.5. Package Trust
- 7.23.5. Safe Haskell Inference
- 7.23.6. Safe Haskell Flag Summary
- 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.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. 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. “Yacc for Haskell”: happy
- 11.2. Writing Haskell interfaces to C code:
hsc2hs
- 11.2.1. command line syntax
- 11.2.2. Input syntax
- 11.2.3. Custom constructs
- 11.2.4. Cross-compilation
- 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.2.1. Using from VBA
- 12.6.2.2. Using from C++
- 13. Known bugs and infelicities
- 13.1. Haskell standards vs. Glasgow Haskell: language non-compliance
- 13.1.1. Divergence from Haskell 98 and Haskell 2010
- 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.1.8. The Foreign Function Interface
- 13.1.2. GHC's interpretation of undefined behaviour in
Haskell 98 and Haskell 2010
- 13.2. Known bugs or infelicities
- 13.2.1. Bugs in GHC
- 13.2.2. Bugs in GHCi (the interactive GHC)
- Index