Glasgow Haskell Compiler User's Guide

Welcome to the GHC User’s Guide¶

Contents:

1. The Glasgow Haskell Compiler License
2. Introduction to GHC
- 2.1. Obtaining GHC
- 2.2. Meta-information: Web sites, mailing lists, etc.
- 2.3. Reporting bugs in GHC
- 2.4. GHC version numbering policy
3. Release notes for version 8.8.1
- 3.1. Highlights
- 3.2. Full details
- 3.3. Included libraries
4. Release notes for version 8.8.2
- 4.1. Highlights
- 4.2. Known issues
- 4.3. Included libraries
5. Release notes for version 8.8.3
- 5.1. Highlights
- 5.2. Known issues
- 5.3. Included libraries
6. Release notes for version 8.8.4
- 6.1. Highlights
- 6.2. Known issues
- 6.3. Included libraries
7. Using GHCi
- 7.1. Introduction to GHCi
- 7.2. Loading source files
  - 7.2.1. Modules vs. filenames
  - 7.2.2. Making changes and recompilation
- 7.3. Loading compiled code
- 7.4. Interactive evaluation at the prompt
- 7.5. The GHCi Debugger
- 7.6. Invoking GHCi
  - 7.6.1. Packages
  - 7.6.2. Extra libraries
- 7.7. GHCi commands
- 7.8. The :set and :seti commands
- 7.9. The .ghci and .haskeline files
  - 7.9.1. The .ghci files
  - 7.9.2. The .haskeline file
- 7.10. Compiling to object code inside GHCi
- 7.11. Running the interpreter in a separate process
- 7.12. FAQ and Things To Watch Out For
8. Using runghc
- 8.1. Usage
- 8.2. runghc flags
- 8.3. GHC Flags
9. Using GHC
- 9.1. Using GHC
- 9.2. Warnings and sanity-checking
- 9.3. Optimisation (code improvement)
  - 9.3.1. -O*: convenient “packages” of optimisation flags.
  - 9.3.2. -f*: platform-independent flags
- 9.4. Using Concurrent Haskell
- 9.5. Using SMP parallelism
- 9.6. Flag reference
- 9.7. Running a compiled program
- 9.8. Filenames and separate compilation
- 9.9. Packages
- 9.10. GHC Backends
- 9.11. Options related to a particular phase
- 9.12. Using shared libraries
- 9.13. Debugging the compiler
10. Profiling
- 10.1. Cost centres and cost-centre stacks
  - 10.1.1. Inserting cost centres by hand
  - 10.1.2. Rules for attributing costs
- 10.2. Compiler options for profiling
- 10.3. Time and allocation profiling
  - 10.3.1. JSON profile format
- 10.4. Profiling memory usage
- 10.5. hp2ps – Rendering heap profiles to PostScript
- 10.6. Profiling Parallel and Concurrent Programs
- 10.7. Observing Code Coverage
- 10.8. Using “ticky-ticky” profiling (for implementors)
11. Advice on: sooner, faster, smaller, thriftier
- 11.1. Sooner: producing a program more quickly
- 11.2. Faster: producing a program that runs quicker
- 11.3. Smaller: producing a program that is smaller
- 11.4. Thriftier: producing a program that gobbles less heap space
12. GHC Language Features
- 12.1. Language options
- 12.2. Unboxed types and primitive operations
  - 12.2.1. Unboxed types
  - 12.2.2. Unboxed type kinds
  - 12.2.3. Unboxed tuples
  - 12.2.4. Unboxed sums
- 12.3. Syntactic extensions
  - 12.3.1. Unicode syntax
  - 12.3.2. The magic hash
  - 12.3.3. Negative literals
  - 12.3.4. Fractional looking integer literals
  - 12.3.5. Binary integer literals
  - 12.3.6. Hexadecimal floating point literals
  - 12.3.7. Numeric underscores
  - 12.3.8. Pattern guards
  - 12.3.9. View patterns
  - 12.3.10. n+k patterns
  - 12.3.11. The recursive do-notation
    - 12.3.11.1. Recursive binding groups
    - 12.3.11.2. The mdo notation
  - 12.3.12. Applicative do-notation
    - 12.3.12.1. Strict patterns
    - 12.3.12.2. Things to watch out for
  - 12.3.13. Parallel List Comprehensions
  - 12.3.14. Generalised (SQL-like) List Comprehensions
  - 12.3.15. Monad comprehensions
  - 12.3.16. New monadic failure desugaring mechanism
  - 12.3.17. Rebindable syntax and the implicit Prelude import
    - 12.3.17.1. Things unaffected by RebindableSyntax
  - 12.3.18. Postfix operators
  - 12.3.19. Tuple sections
  - 12.3.20. Lambda-case
  - 12.3.21. Empty case alternatives
  - 12.3.22. Multi-way if-expressions
  - 12.3.23. Local Fixity Declarations
  - 12.3.24. Import and export extensions
    - 12.3.24.1. Hiding things the imported module doesn’t export
    - 12.3.24.2. Package-qualified imports
    - 12.3.24.3. Safe imports
    - 12.3.24.4. Explicit namespaces in import/export
  - 12.3.25. More liberal syntax for function arguments
    - 12.3.25.1. Changes to the grammar
  - 12.3.26. Summary of stolen syntax
- 12.4. Extensions to data types and type synonyms
  - 12.4.1. Data types with no constructors
  - 12.4.2. Data type contexts
  - 12.4.3. Infix type constructors, classes, and type variables
  - 12.4.4. Type operators
  - 12.4.5. Liberalised type synonyms
  - 12.4.6. Existentially quantified data constructors
  - 12.4.7. Declaring data types with explicit constructor signatures
  - 12.4.8. Generalised Algebraic Data Types (GADTs)
- 12.5. Extensions to the record system
  - 12.5.1. Traditional record syntax
  - 12.5.2. Record field disambiguation
  - 12.5.3. Duplicate record fields
  - 12.5.4. Record puns
  - 12.5.5. Record wildcards
  - 12.5.6. Record field selector polymorphism
    - 12.5.6.1. Solving HasField constraints
    - 12.5.6.2. Virtual record fields
- 12.6. Extensions to the “deriving” mechanism
  - 12.6.1. Deriving instances for empty data types
  - 12.6.2. Inferred context for deriving clauses
  - 12.6.3. Stand-alone deriving declarations
  - 12.6.4. Deriving instances of extra classes (Data, etc.)
  - 12.6.5. Generalised derived instances for newtypes
  - 12.6.6. Deriving any other class
  - 12.6.7. Deriving strategies
    - 12.6.7.1. Default deriving strategy
  - 12.6.8. Deriving via
- 12.7. Pattern synonyms
  - 12.7.1. Record Pattern Synonyms
  - 12.7.2. Syntax and scoping of pattern synonyms
  - 12.7.3. Import and export of pattern synonyms
  - 12.7.4. Typing of pattern synonyms
  - 12.7.5. Matching of pattern synonyms
- 12.8. Class and instances declarations
  - 12.8.1. Class declarations
  - 12.8.2. Functional dependencies
    - 12.8.2.1. Rules for functional dependencies
    - 12.8.2.2. Background on functional dependencies
  - 12.8.3. Instance declarations
  - 12.8.4. Overloaded string literals
  - 12.8.5. Overloaded labels
  - 12.8.6. Overloaded lists
  - 12.8.7. Undecidable (or recursive) superclasses
- 12.9. Type families
  - 12.9.1. Data families
  - 12.9.2. Synonym families
  - 12.9.3. Wildcards on the LHS of data and type family instances
  - 12.9.4. Associated data and type families
  - 12.9.5. Import and export
    - 12.9.5.1. Examples
    - 12.9.5.2. Instances
  - 12.9.6. Type families and instance declarations
  - 12.9.7. Injective type families
    - 12.9.7.1. Syntax of injectivity annotation
    - 12.9.7.2. Verifying injectivity annotation against type family equations
- 12.10. Datatype promotion
  - 12.10.1. Motivation
  - 12.10.2. Overview
  - 12.10.3. Distinguishing between types and constructors
  - 12.10.4. Promoted list and tuple types
  - 12.10.5. Promoting existential data constructors
- 12.11. Kind polymorphism
  - 12.11.1. Overview of kind polymorphism
  - 12.11.2. Overview of Type-in-Type
  - 12.11.3. Principles of kind inference
  - 12.11.4. Inferring the order of variables in a type/class declaration
  - 12.11.5. Complete user-supplied kind signatures and polymorphic recursion
  - 12.11.6. Kind inference in closed type families
  - 12.11.7. Kind inference in class instance declarations
  - 12.11.8. Kind inference in type signatures
  - 12.11.9. Explicit kind quantification
  - 12.11.10. Kind-indexed GADTs
  - 12.11.11. Higher-rank kinds
  - 12.11.12. The kind Type
  - 12.11.13. Inferring dependency in datatype declarations
  - 12.11.14. Inferring dependency in user-written foralls
  - 12.11.15. Kind defaulting without PolyKinds
  - 12.11.16. Pretty-printing in the presence of kind polymorphism
- 12.12. Levity polymorphism
  - 12.12.1. No levity-polymorphic variables or arguments
  - 12.12.2. Levity-polymorphic bottoms
  - 12.12.3. Printing levity-polymorphic types
- 12.13. Type-Level Literals
  - 12.13.1. Runtime Values for Type-Level Literals
  - 12.13.2. Computing With Type-Level Naturals
- 12.14. Equality constraints, Coercible, and the kind Constraint
  - 12.14.1. Equality constraints
  - 12.14.2. Heterogeneous equality
  - 12.14.3. Unlifted heterogeneous equality
  - 12.14.4. The Coercible constraint
  - 12.14.5. The Constraint kind
- 12.15. Quantified constraints
  - 12.15.1. Motivation
  - 12.15.2. Syntax changes
  - 12.15.3. Typing changes
  - 12.15.4. Superclasses
  - 12.15.5. Overlap
  - 12.15.6. Instance lookup
  - 12.15.7. Termination
  - 12.15.8. Coherence
- 12.16. Extensions to type signatures
  - 12.16.1. Explicit universal quantification (forall)
  - 12.16.2. The context of a type signature
  - 12.16.3. Ambiguous types and the ambiguity check
  - 12.16.4. Explicitly-kinded quantification
- 12.17. Lexically scoped type variables
  - 12.17.1. Overview
  - 12.17.2. Declaration type signatures
  - 12.17.3. Expression type signatures
  - 12.17.4. Pattern type signatures
  - 12.17.5. Class and instance declarations
- 12.18. Bindings and generalisation
  - 12.18.1. Switching off the dreaded Monomorphism Restriction
  - 12.18.2. Let-generalisation
- 12.19. Visible type application
  - 12.19.1. Inferred vs. specified type variables
  - 12.19.2. Ordering of specified variables
- 12.20. Implicit parameters
  - 12.20.1. Implicit-parameter type constraints
  - 12.20.2. Implicit-parameter bindings
  - 12.20.3. Implicit parameters and polymorphic recursion
  - 12.20.4. Implicit parameters and monomorphism
- 12.21. Arbitrary-rank polymorphism
  - 12.21.1. Examples
  - 12.21.2. Type inference
  - 12.21.3. Implicit quantification
- 12.22. Impredicative polymorphism
- 12.23. Typed Holes
  - 12.23.1. Valid Hole Fits
    - 12.23.1.1. Refinement Hole Fits
    - 12.23.1.2. Sorting Valid Hole Fits
- 12.24. Partial Type Signatures
  - 12.24.1. Syntax
  - 12.24.2. Where can they occur?
- 12.25. Custom compile-time errors
- 12.26. Deferring type errors to runtime
  - 12.26.1. Enabling deferring of type errors
  - 12.26.2. Deferred type errors in GHCi
  - 12.26.3. Limitations of deferred type errors
- 12.27. Template Haskell
  - 12.27.1. Syntax
  - 12.27.2. Using Template Haskell
  - 12.27.3. Viewing Template Haskell generated code
  - 12.27.4. A Template Haskell Worked Example
  - 12.27.5. Using Template Haskell with Profiling
  - 12.27.6. Template Haskell Quasi-quotation
- 12.28. Arrow notation
  - 12.28.1. do-notation for commands
  - 12.28.2. Conditional commands
  - 12.28.3. Defining your own control structures
  - 12.28.4. Primitive constructs
  - 12.28.5. Differences with the paper
  - 12.28.6. Portability
- 12.29. Bang patterns and Strict Haskell
  - 12.29.1. Bang patterns
  - 12.29.2. Strict-by-default data types
  - 12.29.3. Strict-by-default pattern bindings
  - 12.29.4. Modularity
  - 12.29.5. Dynamic semantics of bang patterns
- 12.30. Assertions
- 12.31. Static pointers
  - 12.31.1. Using static pointers
  - 12.31.2. Static semantics of static pointers
- 12.32. Pragmas
  - 12.32.1. LANGUAGE pragma
  - 12.32.2. OPTIONS_GHC pragma
  - 12.32.3. INCLUDE pragma
  - 12.32.4. WARNING and DEPRECATED pragmas
  - 12.32.5. MINIMAL pragma
  - 12.32.6. INLINE and NOINLINE pragmas
  - 12.32.7. LINE pragma
  - 12.32.8. COLUMN pragma
  - 12.32.9. RULES pragma
  - 12.32.10. SPECIALIZE pragma
    - 12.32.10.1. SPECIALIZE INLINE
    - 12.32.10.2. SPECIALIZE for imported functions
  - 12.32.11. SPECIALIZE instance pragma
  - 12.32.12. UNPACK pragma
  - 12.32.13. NOUNPACK pragma
  - 12.32.14. SOURCE pragma
  - 12.32.15. COMPLETE pragmas
  - 12.32.16. Disambiguating between multiple COMPLETE pragmas
  - 12.32.17. OVERLAPPING, OVERLAPPABLE, OVERLAPS, and INCOHERENT pragmas
- 12.33. Rewrite rules
  - 12.33.1. Syntax
  - 12.33.2. Semantics
  - 12.33.3. How rules interact with INLINE/NOINLINE pragmas
  - 12.33.4. How rules interact with CONLIKE pragmas
  - 12.33.5. How rules interact with class methods
  - 12.33.6. List fusion
  - 12.33.7. Specialisation
  - 12.33.8. Controlling what’s going on in rewrite rules
- 12.34. Special built-in functions
- 12.35. Generic classes
- 12.36. Generic programming
  - 12.36.1. Deriving representations
  - 12.36.2. Writing generic functions
  - 12.36.3. Unlifted representation types
  - 12.36.4. Generic defaults
  - 12.36.5. More information
- 12.37. Roles
  - 12.37.1. Nominal, Representational, and Phantom
  - 12.37.2. Role inference
  - 12.37.3. Role annotations
- 12.38. HasCallStack
  - 12.38.1. Compared with other sources of stack traces
- 12.39. Concurrent and Parallel Haskell
  - 12.39.1. Concurrent Haskell
  - 12.39.2. Software Transactional Memory
  - 12.39.3. Parallel Haskell
  - 12.39.4. Annotating pure code for parallelism
- 12.40. Safe Haskell
  - 12.40.1. Uses of Safe Haskell
    - 12.40.1.1. Strict type-safety (good style)
    - 12.40.1.2. Building secure systems (restricted IO Monads)
  - 12.40.2. Safe Language
    - 12.40.2.1. Safe Overlapping Instances
  - 12.40.3. Safe Imports
  - 12.40.4. Trust and Safe Haskell Modes
  - 12.40.5. Safe Haskell Inference
  - 12.40.6. Safe Haskell Flag Summary
  - 12.40.7. Safe Compilation
13. Foreign function interface (FFI)
- 13.1. GHC differences to the FFI Chapter
  - 13.1.1. Guaranteed call safety
- 13.2. GHC extensions to the FFI Chapter
- 13.3. Using the FFI with GHC
14. Extending and using GHC as a Library
- 14.1. Source annotations
- 14.2. Using GHC as a Library
- 14.3. Compiler Plugins
15. What to do when something goes wrong
- 15.1. When the compiler “does the wrong thing”
- 15.2. When your program “does the wrong thing”
16. Debugging compiled programs
- 16.1. Tutorial
- 16.2. Requesting a stack trace from Haskell code
- 16.3. Requesting a stack trace with SIGQUIT
- 16.4. Implementor’s notes: DWARF annotations
  - 16.4.1. Debugging information entities
    - 16.4.1.1. DW_TAG_ghc_src_note
- 16.5. Further Reading
17. Other Haskell utility programs
- 17.1. “Yacc for Haskell”: happy
- 17.2. Writing Haskell interfaces to C code: hsc2hs
18. Running GHC on Win32 systems
- 18.1. Starting GHC on Windows platforms
- 18.2. Running GHCi on Windows
- 18.3. Interacting with the terminal
- 18.4. Differences in library behaviour
- 18.5. File paths under Windows
- 18.6. Using GHC (and other GHC-compiled executables) with Cygwin
- 18.7. Building and using Win32 DLLs
  - 18.7.1. Creating a DLL
  - 18.7.2. Making DLLs to be called from other languages
    - 18.7.2.1. Using from VBA
    - 18.7.2.2. Using from C++
19. Known bugs and infelicities
- 19.1. Haskell standards vs. Glasgow Haskell: language non-compliance
  - 19.1.1. Divergence from Haskell 98 and Haskell 2010
  - 19.1.2. GHC’s interpretation of undefined behaviour in Haskell 98 and Haskell 2010
- 19.2. Known bugs or infelicities
  - 19.2.1. Bugs in GHC
  - 19.2.2. Bugs in GHCi (the interactive GHC)
20. Eventlog encodings
- 20.1. Heap profiler event log output
  - 20.1.1. Metadata event types
    - 20.1.1.1. Beginning of sample stream
    - 20.1.1.2. Cost centre definitions
  - 20.1.2. Sample event types
    - 20.1.2.1. Cost-centre break-down
    - 20.1.2.2. String break-down
21. Care and feeding of your GHC User’s Guide
- 21.1. Basics
- 21.2. Citations
- 21.3. Admonitions
- 21.4. Documenting command-line options and GHCi commands
  - 21.4.1. Command-line options
  - 21.4.2. GHCi commands
- 21.5. Style Conventions
- 21.6. ReST reference materials

Indices and tables¶