Welcome to the GHC Users 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 7.12.1
  • 3.1. Highlights
  • 3.2. Full details
    • 3.2.1. Language
    • 3.2.2. Compiler
    • 3.2.3. GHCi
    • 3.2.4. Template Haskell
    • 3.2.5. Runtime system
    • 3.2.6. Build system
    • 3.2.7. Package system
  • 3.3. Libraries
    • 3.3.1. array
    • 3.3.2. base
    • 3.3.3. binary
    • 3.3.4. bytestring
    • 3.3.5. Cabal
    • 3.3.6. containers
    • 3.3.7. deepseq
    • 3.3.8. directory
    • 3.3.9. filepath
    • 3.3.10. ghc
    • 3.3.11. ghc-boot
    • 3.3.12. ghc-prim
    • 3.3.13. haskell98
    • 3.3.14. haskell2010
    • 3.3.15. hoopl
    • 3.3.16. hpc
    • 3.3.17. integer-gmp
    • 3.3.18. old-locale
    • 3.3.19. old-time
    • 3.3.20. process
    • 3.3.21. template-haskell
    • 3.3.22. time
    • 3.3.23. unix
    • 3.3.24. Win32
  • 3.4. Known bugs
• 4. Using GHCi
  • 4.1. Introduction to GHCi
  • 4.2. Loading source files
    • 4.2.1. Modules vs. filenames
    • 4.2.2. Making changes and recompilation
  • 4.3. Loading compiled code
  • 4.4. Interactive evaluation at the prompt
    • 4.4.1. I/O actions at the prompt
    • 4.4.2. Using do-notation at the prompt
    • 4.4.3. Multiline input
    • 4.4.4. Type, class and other declarations
    • 4.4.5. What’s really in scope at the prompt?
    • 4.4.6. The :main and :run commands
    • 4.4.7. The it variable
    • 4.4.8. Type defaulting in GHCi
    • 4.4.9. Using a custom interactive printing function
  • 4.5. The GHCi Debugger
    • 4.5.1. Breakpoints and inspecting variables
    • 4.5.2. Single-stepping
    • 4.5.3. Nested breakpoints
    • 4.5.4. The _result variable
    • 4.5.5. Tracing and history
    • 4.5.6. Debugging exceptions
    • 4.5.7. Example: inspecting functions
    • 4.5.8. Limitations
  • 4.6. Invoking GHCi
    • 4.6.1. Packages
    • 4.6.2. Extra libraries
  • 4.7. GHCi commands
  • 4.8. The :set and :seti commands
    • 4.8.1. GHCi options
    • 4.8.2. Setting GHC command-line options in GHCi
    • 4.8.3. Setting options for interactive evaluation only
  • 4.9. The .ghci and .haskeline files
    • 4.9.1. The .ghci files
    • 4.9.2. The .haskeline file
  • 4.10. Compiling to object code inside GHCi
  • 4.11. FAQ and Things To Watch Out For
• 5. Using runghc
  • 5.1. Flags
• 6. Using GHC
  • 6.1. Using GHC
    • 6.1.1. Getting started: compiling programs
    • 6.1.2. Options overview
    • 6.1.3. Static, Dynamic, and Mode options
    • 6.1.4. Meaningful file suffixes
    • 6.1.5. Modes of operation
    • 6.1.6. Verbosity options
    • 6.1.7. Platform-specific Flags
  • 6.2. Warnings and sanity-checking
  • 6.3. Optimisation (code improvement)
    • 6.3.1. -O*: convenient “packages” of optimisation flags.
    • 6.3.2. -f*: platform-independent flags
  • 6.4. Using Concurrent Haskell
  • 6.5. Using SMP parallelism
    • 6.5.1. Compile-time options for SMP parallelism
    • 6.5.2. RTS options for SMP parallelism
    • 6.5.3. Hints for using SMP parallelism
  • 6.6. Flag reference
    • 6.6.1. Verbosity options
    • 6.6.2. Alternative modes of operation
    • 6.6.3. Which phases to run
    • 6.6.4. Redirecting output
    • 6.6.5. Keeping intermediate files
    • 6.6.6. Temporary files
    • 6.6.7. Finding imports
    • 6.6.8. Interface file options
    • 6.6.9. Recompilation checking
    • 6.6.10. Interactive-mode options
    • 6.6.11. Packages
    • 6.6.12. Language options
    • 6.6.13. Warnings
    • 6.6.14. Optimisation levels
    • 6.6.15. Individual optimisations
    • 6.6.16. Profiling options
    • 6.6.17. Program coverage options
    • 6.6.18. C pre-processor options
    • 6.6.19. Code generation options
    • 6.6.20. Linking options
    • 6.6.21. Plugin options
    • 6.6.22. Replacing phases
    • 6.6.23. Forcing options to particular phases
    • 6.6.24. Platform-specific options
    • 6.6.25. Compiler debugging options
    • 6.6.26. Miscellaneous compiler options
  • 6.7. Running a compiled program
    • 6.7.1. Setting RTS options
    • 6.7.2. Miscellaneous RTS options
    • 6.7.3. RTS options to control the garbage collector
    • 6.7.4. RTS options to produce runtime statistics
    • 6.7.5. RTS options for concurrency and parallelism
    • 6.7.6. RTS options for profiling
    • 6.7.7. Tracing
    • 6.7.8. RTS options for hackers, debuggers, and over-interested souls
    • 6.7.9. Getting information about the RTS
  • 6.8. Filenames and separate compilation
    • 6.8.1. Haskell source files
    • 6.8.2. Output files
    • 6.8.3. The search path
    • 6.8.4. Redirecting the compilation output(s)
    • 6.8.5. Keeping Intermediate Files
    • 6.8.6. Redirecting temporary files
    • 6.8.7. Other options related to interface files
    • 6.8.8. The recompilation checker
    • 6.8.9. How to compile mutually recursive modules
    • 6.8.10. Module signatures
    • 6.8.11. Using make
    • 6.8.12. Dependency generation
    • 6.8.13. Orphan modules and instance declarations
  • 6.9. Packages
    • 6.9.1. Using Packages
    • 6.9.2. The main package
    • 6.9.3. Consequences of packages for the Haskell language
    • 6.9.4. Thinning and renaming modules
    • 6.9.5. Package Databases
    • 6.9.6. Installed package IDs, dependencies, and broken packages
    • 6.9.7. Package management (the ghc-pkg command)
    • 6.9.8. Building a package from Haskell source
    • 6.9.9. InstalledPackageInfo: a package specification
    • 6.9.10. Package environments
  • 6.10. GHC Backends
    • 6.10.1. Native code Generator (-fasm)
    • 6.10.2. LLVM Code Generator (-fllvm)
    • 6.10.3. C Code Generator (-fvia-C)
    • 6.10.4. Unregisterised compilation
  • 6.11. Options related to a particular phase
    • 6.11.1. Replacing the program for one or more phases
    • 6.11.2. Forcing options to a particular phase
    • 6.11.3. Options affecting the C pre-processor
    • 6.11.4. Options affecting a Haskell pre-processor
    • 6.11.5. Options affecting code generation
    • 6.11.6. Options affecting linking
  • 6.12. Using shared libraries
    • 6.12.1. Building programs that use shared libraries
    • 6.12.2. Shared libraries for Haskell packages
    • 6.12.3. Shared libraries that export a C API
    • 6.12.4. Finding shared libraries at runtime
  • 6.13. Debugging the compiler
    • 6.13.1. Dumping out compiler intermediate structures
    • 6.13.2. Formatting dumps
    • 6.13.3. Suppressing unwanted information
    • 6.13.4. Checking for consistency
    • 6.13.5. Checking for determinism
• 7. Profiling
  • 7.1. Cost centres and cost-centre stacks
    • 7.1.1. Inserting cost centres by hand
    • 7.1.2. Rules for attributing costs
  • 7.2. Compiler options for profiling
  • 7.3. Time and allocation profiling
  • 7.4. Profiling memory usage
    • 7.4.1. RTS options for heap profiling
    • 7.4.2. Retainer Profiling
    • 7.4.3. Biographical Profiling
    • 7.4.4. Actual memory residency
  • 7.5. hp2ps – Rendering heap profiles to PostScript
    • 7.5.1. Manipulating the hp file
    • 7.5.2. Zooming in on regions of your profile
    • 7.5.3. Viewing the heap profile of a running program
    • 7.5.4. Viewing a heap profile in real time
  • 7.6. Profiling Parallel and Concurrent Programs
  • 7.7. Observing Code Coverage
    • 7.7.1. A small example: Reciprocation
    • 7.7.2. Options for instrumenting code for coverage
    • 7.7.3. The hpc toolkit
    • 7.7.4. Caveats and Shortcomings of Haskell Program Coverage
  • 7.8. Using “ticky-ticky” profiling (for implementors)
• 8. Advice on: sooner, faster, smaller, thriftier
  • 8.1. Sooner: producing a program more quickly
  • 8.2. Faster: producing a program that runs quicker
  • 8.3. Smaller: producing a program that is smaller
  • 8.4. Thriftier: producing a program that gobbles less heap space
• 9. GHC Language Features
  • 9.1. Language options
  • 9.2. Unboxed types and primitive operations
    • 9.2.1. Unboxed types
    • 9.2.2. Unboxed tuples
  • 9.3. Syntactic extensions
    • 9.3.1. Unicode syntax
    • 9.3.2. The magic hash
    • 9.3.3. Negative literals
    • 9.3.4. Fractional looking integer literals
    • 9.3.5. Binary integer literals
    • 9.3.6. Hierarchical Modules
    • 9.3.7. Pattern guards
    • 9.3.8. View patterns
    • 9.3.9. Pattern synonyms
    • 9.3.10. n+k patterns
    • 9.3.11. The recursive do-notation
    • 9.3.12. Applicative do-notation
    • 9.3.13. Parallel List Comprehensions
    • 9.3.14. Generalised (SQL-Like) List Comprehensions
    • 9.3.15. Monad comprehensions
    • 9.3.16. New monadic failure desugaring mechanism
    • 9.3.17. Rebindable syntax and the implicit Prelude import
    • 9.3.18. Postfix operators
    • 9.3.19. Tuple sections
    • 9.3.20. Lambda-case
    • 9.3.21. Empty case alternatives
    • 9.3.22. Multi-way if-expressions
    • 9.3.23. Local Fixity Declarations
    • 9.3.24. Import and export extensions
    • 9.3.25. Summary of stolen syntax
  • 9.4. Extensions to data types and type synonyms
    • 9.4.1. Data types with no constructors
    • 9.4.2. Data type contexts
    • 9.4.3. Infix type constructors, classes, and type variables
    • 9.4.4. Type operators
    • 9.4.5. Liberalised type synonyms
    • 9.4.6. Existentially quantified data constructors
    • 9.4.7. Declaring data types with explicit constructor signatures
    • 9.4.8. Generalised Algebraic Data Types (GADTs)
  • 9.5. Extensions to the record system
    • 9.5.1. Traditional record syntax
    • 9.5.2. Record field disambiguation
    • 9.5.3. Duplicate record fields
    • 9.5.4. Record puns
    • 9.5.5. Record wildcards
  • 9.6. Extensions to the “deriving” mechanism
    • 9.6.1. Inferred context for deriving clauses
    • 9.6.2. Stand-alone deriving declarations
    • 9.6.3. Deriving instances of extra classes (Data, etc.)
    • 9.6.4. Deriving Functor instances
    • 9.6.5. Deriving Foldable instances
    • 9.6.6. Deriving Traversable instances
    • 9.6.7. Deriving Typeable instances
    • 9.6.8. Deriving Lift instances
    • 9.6.9. Generalised derived instances for newtypes
    • 9.6.10. Deriving any other class
  • 9.7. Class and instances declarations
    • 9.7.1. Class declarations
    • 9.7.2. Functional dependencies
    • 9.7.3. Instance declarations
    • 9.7.4. Overloaded string literals
    • 9.7.5. Overloaded lists
  • 9.8. Type families
    • 9.8.1. Data families
    • 9.8.2. Synonym families
    • 9.8.3. Associated data and type families
    • 9.8.4. Import and export
    • 9.8.5. Type families and instance declarations
    • 9.8.6. Injective type families
  • 9.9. Kind polymorphism
    • 9.9.1. Overview of kind polymorphism
    • 9.9.2. Principles of kind inference
    • 9.9.3. Polymorphic kind recursion and complete kind signatures
    • 9.9.4. Kind inference in closed type families
    • 9.9.5. Kind inference in class instance declarations
  • 9.10. Datatype promotion
    • 9.10.1. Motivation
    • 9.10.2. Overview
    • 9.10.3. Distinguishing between types and constructors
    • 9.10.4. Promoted list and tuple types
    • 9.10.5. Promoting existential data constructors
    • 9.10.6. Promoting type operators
  • 9.11. Type-Level Literals
    • 9.11.1. Runtime Values for Type-Level Literals
    • 9.11.2. Computing With Type-Level Naturals
  • 9.12. Equality constraints
    • 9.12.1. The Coercible constraint
  • 9.13. The Constraint kind
  • 9.14. Other type system extensions
    • 9.14.1. Explicit universal quantification (forall)
    • 9.14.2. The context of a type signature
    • 9.14.3. Ambiguous types and the ambiguity check
    • 9.14.4. Implicit parameters
    • 9.14.5. Explicitly-kinded quantification
    • 9.14.6. Arbitrary-rank polymorphism
    • 9.14.7. Impredicative polymorphism
    • 9.14.8. Lexically scoped type variables
    • 9.14.9. Bindings and generalisation
  • 9.15. Typed Holes
  • 9.16. Partial Type Signatures
    • 9.16.1. Syntax
    • 9.16.2. Where can they occur?
  • 9.17. Deferring type errors to runtime
    • 9.17.1. Enabling deferring of type errors
    • 9.17.2. Deferred type errors in GHCi
  • 9.18. Template Haskell
    • 9.18.1. Syntax
    • 9.18.2. Using Template Haskell
    • 9.18.3. Viewing Template Haskell generated code
    • 9.18.4. A Template Haskell Worked Example
    • 9.18.5. Using Template Haskell with Profiling
    • 9.18.6. Template Haskell Quasi-quotation
  • 9.19. Arrow notation
    • 9.19.1. do-notation for commands
    • 9.19.2. Conditional commands
    • 9.19.3. Defining your own control structures
    • 9.19.4. Primitive constructs
    • 9.19.5. Differences with the paper
    • 9.19.6. Portability
  • 9.20. Bang patterns
    • 9.20.1. Informal description of bang patterns
    • 9.20.2. Syntax and semantics
  • 9.21. Assertions
  • 9.22. Static pointers
    • 9.22.1. Using static pointers
    • 9.22.2. Static semantics of static pointers
  • 9.23. Pragmas
    • 9.23.1. LANGUAGE pragma
    • 9.23.2. OPTIONS_GHC pragma
    • 9.23.3. INCLUDE pragma
    • 9.23.4. WARNING and DEPRECATED pragmas
    • 9.23.5. MINIMAL pragma
    • 9.23.6. INLINE and NOINLINE pragmas
    • 9.23.7. LINE pragma
    • 9.23.8. RULES pragma
    • 9.23.9. SPECIALIZE pragma
    • 9.23.10. SPECIALIZE instance pragma
    • 9.23.11. UNPACK pragma
    • 9.23.12. NOUNPACK pragma
    • 9.23.13. SOURCE pragma
    • 9.23.14. OVERLAPPING, OVERLAPPABLE, OVERLAPS, and INCOHERENT pragmas
  • 9.24. Rewrite rules
    • 9.24.1. Syntax
    • 9.24.2. Semantics
    • 9.24.3. How rules interact with INLINE/NOINLINE pragmas
    • 9.24.4. How rules interact with CONLIKE pragmas
    • 9.24.5. How rules interact with class methods
    • 9.24.6. List fusion
    • 9.24.7. Specialisation
    • 9.24.8. Controlling what’s going on in rewrite rules
  • 9.25. Special built-in functions
  • 9.26. Generic classes
  • 9.27. Generic programming
    • 9.27.1. Deriving representations
    • 9.27.2. Writing generic functions
    • 9.27.3. Unlifted representation types
    • 9.27.4. Generic defaults
    • 9.27.5. More information
  • 9.28. Roles
    • 9.28.1. Nominal, Representational, and Phantom
    • 9.28.2. Role inference
    • 9.28.3. Role annotations -XRoleAnnotations
  • 9.29. Strict Haskell
    • 9.29.1. Strict-by-default data types
    • 9.29.2. Strict-by-default pattern bindings
    • 9.29.3. Modularity
    • 9.29.4. Recursive and polymorphic let bindings
  • 9.30. Concurrent and Parallel Haskell
    • 9.30.1. Concurrent Haskell
    • 9.30.2. Software Transactional Memory
    • 9.30.3. Parallel Haskell
    • 9.30.4. Annotating pure code for parallelism
    • 9.30.5. Data Parallel Haskell
  • 9.31. Safe Haskell
    • 9.31.1. Uses of Safe Haskell
    • 9.31.2. Safe Language
    • 9.31.3. Safe Imports
    • 9.31.4. Trust and Safe Haskell Modes
    • 9.31.5. Safe Haskell Inference
    • 9.31.6. Safe Haskell Flag Summary
    • 9.31.7. Safe Compilation
• 10. Foreign function interface (FFI)
  • 10.1. GHC extensions to the FFI Addendum
    • 10.1.1. Unboxed types
    • 10.1.2. Newtype wrapping of the IO monad
    • 10.1.3. Primitive imports
    • 10.1.4. Interruptible foreign calls
    • 10.1.5. The CAPI calling convention
    • 10.1.6. hs_thread_done()
  • 10.2. Using the FFI with GHC
    • 10.2.1. Using foreign export and foreign import ccall "wrapper" with GHC
    • 10.2.2. Using header files
    • 10.2.3. Memory Allocation
    • 10.2.4. Multi-threading and the FFI
    • 10.2.5. Floating point and the FFI
• 11. Extending and using GHC as a Library
  • 11.1. Source annotations
    • 11.1.1. Annotating values
    • 11.1.2. Annotating types
    • 11.1.3. Annotating modules
  • 11.2. Using GHC as a Library
  • 11.3. Compiler Plugins
    • 11.3.1. Using compiler plugins
    • 11.3.2. Writing compiler plugins
    • 11.3.3. Core plugins in more detail
    • 11.3.4. Typechecker plugins
    • 11.3.5. Frontend plugins
• 12. What to do when something goes wrong
  • 12.1. When the compiler “does the wrong thing”
  • 12.2. When your program “does the wrong thing”
• 13. Other Haskell utility programs
  • 13.1. “Yacc for Haskell”: happy
  • 13.2. Writing Haskell interfaces to C code: hsc2hs
    • 13.2.1. command line syntax
    • 13.2.2. Input syntax
    • 13.2.3. Custom constructs
    • 13.2.4. Cross-compilation
• 14. Running GHC on Win32 systems
  • 14.1. Starting GHC on Windows platforms
  • 14.2. Running GHCi on Windows
  • 14.3. Interacting with the terminal
  • 14.4. Differences in library behaviour
  • 14.5. Using GHC (and other GHC-compiled executables) with Cygwin
    • 14.5.1. Background
    • 14.5.2. The problem
    • 14.5.3. Things to do
  • 14.6. Building and using Win32 DLLs
    • 14.6.1. Creating a DLL
    • 14.6.2. Making DLLs to be called from other languages
• 15. Known bugs and infelicities
  • 15.1. Haskell standards vs. Glasgow Haskell: language non-compliance
    • 15.1.1. Divergence from Haskell 98 and Haskell 2010
    • 15.1.2. GHC’s interpretation of undefined behaviour in Haskell 98 and Haskell 2010
  • 15.2. Known bugs or infelicities
    • 15.2.1. Bugs in GHC
    • 15.2.2. Bugs in GHCi (the interactive GHC)
• 16. Care and feeding of your GHC Users Guide
  • 16.1. Basics
    • 16.1.1. Headings
    • 16.1.2. Formatting code
    • 16.1.3. Links
    • 16.1.4. Index entries
  • 16.2. Citations
  • 16.3. Admonitions
  • 16.4. Style Conventions
  • 16.5. GHC command-line options reference
  • 16.6. ReST reference materials

Indices and tables

• Index
• Search Page