Welcome to the GHC User’s Guide — Glasgow Haskell Compiler 9.12.1 User's Guide (original) (raw)

Glasgow Haskell Compiler

Contents:

• 1. Introduction
  • 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. The Glasgow Haskell Compiler License
• 2. Release notes
  • 2.1. Version 9.12.1
    * 2.1.1. Language
    * 2.1.2. Compiler
    * 2.1.3. GHCi
    * 2.1.4. Runtime system
    * 2.1.5. Cmm
    * 2.1.6. base library
    * 2.1.7. ghc-prim library
    * 2.1.8. ghc library
    * 2.1.9. ghc-heap library
    * 2.1.10. template-haskell library
    * 2.1.11. Included libraries
• 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. Multiline input
    * 3.4.4. Type, class and other declarations
    * 3.4.5. What’s really in scope at the prompt?
    * 3.4.5.1. The effect of :load on what is in scope
    * 3.4.5.2. Controlling what is in scope with import
    * 3.4.5.3. Controlling what is in scope with the :module command
    * 3.4.5.4. Qualified names
    * 3.4.5.5. :module and :load
    * 3.4.5.6. Shadowing and the Ghci1 module name
    * 3.4.6. The it variable
    * 3.4.7. Type defaulting in GHCi
    * 3.4.7.1. Interactive classes
    * 3.4.7.2. Extended rules around default declarations
    * 3.4.8. Using a custom interactive printing function
    * 3.4.9. Stack Traces in GHCi
  • 3.5. The GHCi Debugger
    * 3.5.1. Breakpoints and inspecting variables
    * 3.5.1.1. Setting breakpoints
    * 3.5.1.2. Managing 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 and :seti commands
    * 3.8.1. GHCi options
    * 3.8.2. Setting GHC command-line options in GHCi
    * 3.8.3. Setting options for interactive evaluation only
  • 3.9. The .ghci and .haskeline files
    * 3.9.1. The .ghci files
    * 3.9.2. The .haskeline file
  • 3.10. Compiling to object code inside GHCi
  • 3.11. Running the interpreter in a separate process
    * 3.11.1. Building an external interpreter
    * 3.11.2. Running the interpreter on a different host
  • 3.12. Building GHCi libraries
  • 3.13. FAQ and Things To Watch Out For
• 4. Using runghc
  • 4.1. Usage
  • 4.2. runghc flags
  • 4.3. GHC Flags
• 5. Using GHC
  • 5.1. Using GHC
    * 5.1.1. Getting started: compiling programs
    * 5.1.2. Options overview
    * 5.1.2.1. Command-line arguments
    * 5.1.2.2. Command line options in source files
    * 5.1.2.3. Setting options in GHCi
    * 5.1.3. Dynamic and Mode options
    * 5.1.4. Meaningful file suffixes
    * 5.1.5. Modes of operation
    * 5.1.5.1. Using ghc --make
    * 5.1.5.2. GHC Jobserver Protocol
    * 5.1.5.3. Multiple Home Units
    * 5.1.5.4. Expression evaluation mode
    * 5.1.5.5. Batch compiler mode
    * 5.1.6. Verbosity options
    * 5.1.7. Platform-specific Flags
    * 5.1.8. Haddock
    * 5.1.9. Miscellaneous flags
    * 5.1.9.1. Other environment variables
  • 5.2. Warnings and sanity-checking
    * 5.2.1. Warning groups
    * 5.2.2. Treating warnings as fatal errors
    * 5.2.3. Individual warning options
  • 5.3. Optimisation (code improvement)
    * 5.3.1. -O*: convenient “packages” of optimisation flags.
    * 5.3.2. -f*: platform-independent flags
  • 5.4. Using Concurrent Haskell
  • 5.5. Using SMP parallelism
    * 5.5.1. Compile-time options for SMP parallelism
    * 5.5.2. RTS options for SMP parallelism
    * 5.5.3. Hints for using SMP parallelism
  • 5.6. Flag reference
    * 5.6.1. Verbosity options
    * 5.6.2. Alternative modes of operation
    * 5.6.3. Which phases to run
    * 5.6.4. Redirecting output
    * 5.6.5. Keeping intermediate files
    * 5.6.6. Temporary files
    * 5.6.7. Finding imports
    * 5.6.8. Interface file options
    * 5.6.9. Extended interface file options
    * 5.6.10. Recompilation checking
    * 5.6.11. Interactive-mode options
    * 5.6.12. Packages
    * 5.6.13. Language options
    * 5.6.14. Warnings
    * 5.6.15. Optimisation levels
    * 5.6.16. Individual optimisations
    * 5.6.17. Profiling options
    * 5.6.18. Program coverage options
    * 5.6.19. C pre-processor options
    * 5.6.20. Code generation options
    * 5.6.21. Linking options
    * 5.6.22. Plugin options
    * 5.6.23. Replacing phases
    * 5.6.24. Forcing options to particular phases
    * 5.6.25. Platform-specific options
    * 5.6.26. Compiler debugging options
    * 5.6.27. Miscellaneous compiler options
  • 5.7. Runtime system (RTS) options
    * 5.7.1. Setting RTS options
    * 5.7.1.1. Setting RTS options on the command line
    * 5.7.1.2. Setting RTS options at compile time
    * 5.7.1.3. Setting RTS options with the GHCRTS environment variable
    * 5.7.1.4. “Hooks” to change RTS behaviour
    * 5.7.2. Miscellaneous RTS options
    * 5.7.3. RTS options to control the garbage collector
    * 5.7.4. RTS options to produce runtime statistics
    * 5.7.5. RTS options for concurrency and parallelism
    * 5.7.6. RTS options for profiling
    * 5.7.7. Tracing
    * 5.7.8. RTS options for Haskell program coverage
    * 5.7.9. RTS options for hackers, debuggers, and over-interested souls
    * 5.7.10. Getting information about the RTS
  • 5.8. Filenames and separate compilation
    * 5.8.1. Haskell source files
    * 5.8.2. Output files
    * 5.8.3. The search path
    * 5.8.4. Redirecting the compilation output(s)
    * 5.8.5. Keeping Intermediate Files
    * 5.8.6. Redirecting temporary files
    * 5.8.7. Other options related to interface files
    * 5.8.8. Options related to extended interface files
    * 5.8.9. The recompilation checker
    * 5.8.9.1. Recompilation for Template Haskell and Plugins
    * 5.8.10. Mutually recursive modules and hs-boot files
    * 5.8.11. Module signatures
    * 5.8.12. Using make
    * 5.8.13. Dependency generation
    * 5.8.14. Orphan modules and instance declarations
  • 5.9. Packages
    * 5.9.1. Using Packages
    * 5.9.2. The main package
    * 5.9.3. Consequences of packages for the Haskell language
    * 5.9.4. Thinning and renaming modules
    * 5.9.5. Package Databases
    * 5.9.5.1. The GHC_PACKAGE_PATH environment variable
    * 5.9.5.2. Package environments
    * 5.9.6. Installed package IDs, dependencies, and broken packages
    * 5.9.7. Package management (the ghc-pkg command)
    * 5.9.8. Building a package from Haskell source
    * 5.9.9. InstalledPackageInfo: a package specification
    * 5.9.10. Linking against C++ libraries
  • 5.10. GHC Backends
    * 5.10.1. Native Code Generator (-fasm)
    * 5.10.2. LLVM Code Generator (-fllvm)
    * 5.10.3. C Code Generator (-fvia-C)
    * 5.10.4. JavaScript Code Generator
    * 5.10.5. Unregisterised compilation
  • 5.11. Options related to a particular phase
    * 5.11.1. Replacing the program for one or more phases
    * 5.11.2. Forcing options to a particular phase
    * 5.11.3. Options affecting the C pre-processor
    * 5.11.3.1. Standard CPP macros
    * 5.11.3.2. CPP and string gaps
    * 5.11.4. Options affecting a Haskell pre-processor
    * 5.11.5. Options affecting code generation
    * 5.11.6. Options affecting linking
  • 5.12. Using shared libraries
    * 5.12.1. Building programs that use shared libraries
    * 5.12.2. Shared libraries for Haskell packages
    * 5.12.3. Shared libraries that export a C API
    * 5.12.4. Finding shared libraries at runtime
    * 5.12.4.1. Unix
    * 5.12.4.2. Mac OS X
  • 5.13. Debugging the compiler
    * 5.13.1. Dumping out compiler intermediate structures
    * 5.13.1.1. Front-end
    * 5.13.1.2. Type-checking and renaming
    * 5.13.1.3. Core representation and simplification
    * 5.13.1.4. STG representation
    * 5.13.1.5. C-\- representation
    * 5.13.1.6. LLVM code generator
    * 5.13.1.7. C code generator
    * 5.13.1.8. Native code generator
    * 5.13.1.9. JavaScript code generator
    * 5.13.1.10. Miscellaneous backend dumps
    * 5.13.2. Formatting dumps
    * 5.13.3. Suppressing unwanted information
    * 5.13.4. Checking for consistency
    * 5.13.5. Checking for determinism
    * 5.13.6. Other
• 6. Language extensions
  • 6.1. Introduction
    * 6.1.1. Controlling editions and extensions
    * 6.1.2. Overview of all language extensions
    * 6.1.3. Summary of stolen syntax
  • 6.2. Syntax
    * 6.2.1. Unicode syntax
    * 6.2.2. The magic hash
    * 6.2.3. The recursive do-notation
    * 6.2.3.1. Recursive binding groups
    * 6.2.3.2. The mdo notation
    * 6.2.4. Applicative do-notation
    * 6.2.4.1. Strict patterns
    * 6.2.4.2. Things to watch out for
    * 6.2.5. Qualified do-notation
    * 6.2.5.1. Examples
    * 6.2.6. Parallel List Comprehensions
    * 6.2.7. Generalised (SQL-like) List Comprehensions
    * 6.2.8. Monad comprehensions
    * 6.2.9. Overloaded lists
    * 6.2.9.1. The IsList class
    * 6.2.9.2. Rebindable syntax
    * 6.2.9.3. Defaulting
    * 6.2.9.4. Speculation about the future
    * 6.2.10. Rebindable syntax and the implicit Prelude import
    * 6.2.10.1. Custom Prelude modules named Prelude
    * 6.2.10.2. Things unaffected by RebindableSyntax
    * 6.2.11. Postfix operators
    * 6.2.12. Tuple sections
    * 6.2.13. Lambda-case
    * 6.2.14. Empty case alternatives
    * 6.2.15. Multi-way if-expressions
    * 6.2.16. Local Fixity Declarations
    * 6.2.17. More liberal syntax for function arguments
    * 6.2.17.1. Changes to the grammar
    * 6.2.18. Typed Holes
    * 6.2.18.1. Valid Hole Fits
    * 6.2.19. Arrow notation
    * 6.2.19.1. do-notation for commands
    * 6.2.19.2. Conditional commands
    * 6.2.19.3. Defining your own control structures
    * 6.2.19.4. Primitive constructs
    * 6.2.19.5. Differences with the paper
    * 6.2.19.6. Portability
    * 6.2.20. Lexical negation
  • 6.3. Import and export
    * 6.3.1. Hiding things the imported module doesn’t export
    * 6.3.2. Package-qualified imports
    * 6.3.3. Safe imports
    * 6.3.4. Explicit namespaces in import/export
    * 6.3.5. Writing qualified in postpositive position
  • 6.4. Types
    * 6.4.1. Data types with no constructors
    * 6.4.2. Data type contexts
    * 6.4.3. Infix type constructors, classes, and type variables
    * 6.4.4. Type operators
    * 6.4.5. Liberalised type synonyms
    * 6.4.6. Existentially quantified data constructors
    * 6.4.6.1. Why existential?
    * 6.4.6.2. Existentials and type classes
    * 6.4.6.3. Record Constructors
    * 6.4.6.4. Restrictions
    * 6.4.7. Declaring data types with explicit constructor signatures
    * 6.4.7.1. Formal syntax for GADTs
    * 6.4.7.2. GADT syntax odds and ends
    * 6.4.8. Generalised Algebraic Data Types (GADTs)
    * 6.4.9. Type families
    * 6.4.9.1. Data families
    * 6.4.9.2. Synonym families
    * 6.4.9.3. Wildcards on the LHS of data and type family instances
    * 6.4.9.4. Associated data and type families
    * 6.4.9.5. Import and export
    * 6.4.9.6. Type families and instance declarations
    * 6.4.9.7. Injective type families
    * 6.4.10. Datatype promotion
    * 6.4.10.1. Motivation
    * 6.4.10.2. Overview
    * 6.4.10.3. Distinguishing between types and constructors
    * 6.4.10.4. Type-level literals
    * 6.4.10.5. Promoted list and tuple types
    * 6.4.10.6. Promoting existential data constructors
    * 6.4.10.7. DataKinds and type synonyms
    * 6.4.11. Unique syntax for type-level lists and tuples
    * 6.4.12. Type-level data declarations
    * 6.4.13. Kind polymorphism
    * 6.4.13.1. Overview of kind polymorphism
    * 6.4.13.2. Overview of Type-in-Type
    * 6.4.13.3. Principles of kind inference
    * 6.4.13.4. Kind inference in type signatures
    * 6.4.13.5. Explicit kind quantification
    * 6.4.13.6. Inferring the order of variables in a type/class declaration
    * 6.4.13.7. Complete user-supplied kind signatures and polymorphic recursion
    * 6.4.13.8. Standalone kind signatures and polymorphic recursion
    * 6.4.13.9. Standalone kind signatures and declaration headers
    * 6.4.13.10. Kind inference in data type declarations
    * 6.4.13.11. Kind inference for data/newtype instance declarations
    * 6.4.13.12. Kind inference in class instance declarations
    * 6.4.13.13. Kind inference in type synonyms and type family instances
    * 6.4.13.14. Kind inference in closed type families
    * 6.4.13.15. Higher-rank kinds
    * 6.4.13.16. The kind Type
    * 6.4.13.17. Inferring dependency in datatype declarations
    * 6.4.13.18. Inferring dependency in user-written foralls
    * 6.4.13.19. Kind defaulting without PolyKinds
    * 6.4.13.20. Pretty-printing in the presence of kind polymorphism
    * 6.4.13.21. Datatype return kinds
    * 6.4.14. Representation polymorphism
    * 6.4.14.1. Levity polymorphism
    * 6.4.14.2. No representation-polymorphic variables or arguments
    * 6.4.14.3. Representation-polymorphic bottoms
    * 6.4.14.4. Inference and defaulting
    * 6.4.14.5. Printing representation-polymorphic types
    * 6.4.15. Type-Level Literals
    * 6.4.15.1. Runtime Values for Type-Level Literals
    * 6.4.15.2. Computing With Type-Level Naturals
    * 6.4.16. Visible type application
    * 6.4.16.1. Inferred vs. specified type variables
    * 6.4.16.2. Ordering of specified variables
    * 6.4.16.3. Manually defining inferred variables
    * 6.4.17. Type abstractions
    * 6.4.17.1. Type Abstractions in Patterns
    * 6.4.17.2. Type Abstractions in Functions
    * 6.4.17.3. Invisible Binders in Type Declarations
    * 6.4.17.4. Wildcard Binders in Type Declarations
    * 6.4.18. Required type arguments
    * 6.4.18.1. Terminology: Dependent quantifier
    * 6.4.18.2. Terminology: Visible quantifier
    * 6.4.18.3. Relation to TypeApplications
    * 6.4.18.4. Relation to ExplicitNamespaces
    * 6.4.18.5. Types in terms
    * 6.4.18.6. Effect on implicit quantification
    * 6.4.18.7. Relation to Π-types
    * 6.4.19. Arbitrary-rank polymorphism
    * 6.4.19.1. Examples
    * 6.4.19.2. Subsumption
    * 6.4.19.3. Type inference
    * 6.4.19.4. Implicit quantification
    * 6.4.20. Impredicative polymorphism
    * 6.4.21. Linear types
    * 6.4.21.1. Expressions
    * 6.4.21.2. Data types
    * 6.4.21.3. Printing multiplicity-polymorphic types
    * 6.4.21.4. Limitations
    * 6.4.21.5. Design and further reading
    * 6.4.22. Custom compile-time errors
    * 6.4.23. Deferring type errors to runtime
    * 6.4.23.1. Enabling deferring of type errors
    * 6.4.23.2. Deferred type errors in GHCi
    * 6.4.23.3. Limitations of deferred type errors
    * 6.4.24. Roles
    * 6.4.24.1. Nominal, Representational, and Phantom
    * 6.4.24.2. Role inference
    * 6.4.24.3. Role annotations
  • 6.5. Records
    * 6.5.1. Record field name resolution
    * 6.5.2. Traditional record syntax
    * 6.5.3. Field selectors and TypeApplications
    * 6.5.3.1. Field selectors for Haskell98-style data constructors
    * 6.5.3.2. Field selectors for GADT constructors
    * 6.5.3.3. Field selectors for pattern synonyms
    * 6.5.4. Record field disambiguation
    * 6.5.5. Duplicate record fields
    * 6.5.5.1. Import and export of record fields
    * 6.5.6. Field selectors
    * 6.5.6.1. Import and export of selector functions
    * 6.5.7. Record puns
    * 6.5.8. Record wildcards
    * 6.5.9. Record field selector polymorphism
    * 6.5.9.1. Solving HasField constraints
    * 6.5.9.2. Virtual record fields
    * 6.5.10. Overloaded record dot
    * 6.5.11. Overloaded record update
  • 6.6. Deriving mechanism
    * 6.6.1. Deriving instances for empty data types
    * 6.6.2. Inferred context for deriving clauses
    * 6.6.3. Stand-alone deriving declarations
    * 6.6.4. Deriving instances of extra classes (Data, etc.)
    * 6.6.4.1. Deriving Functor instances
    * 6.6.4.2. Deriving Foldable instances
    * 6.6.4.3. Deriving Traversable instances
    * 6.6.4.4. Deriving Data instances
    * 6.6.4.5. Deriving Typeable instances
    * 6.6.4.6. Deriving Lift instances
    * 6.6.5. Generalised derived instances for newtypes
    * 6.6.5.1. Generalising the deriving clause
    * 6.6.5.2. A more precise specification
    * 6.6.5.3. Associated type families
    * 6.6.6. Deriving any other class
    * 6.6.7. Deriving strategies
    * 6.6.7.1. Default deriving strategy
    * 6.6.8. Deriving via
  • 6.7. Patterns
    * 6.7.1. Pattern guards
    * 6.7.2. View patterns
    * 6.7.3. n+k patterns
    * 6.7.4. Pattern synonyms
    * 6.7.4.1. Record Pattern Synonyms
    * 6.7.4.2. Syntax and scoping of pattern synonyms
    * 6.7.4.3. Import and export of pattern synonyms
    * 6.7.4.4. Typing of pattern synonyms
    * 6.7.4.5. Matching of pattern synonyms
    * 6.7.4.6. Pragmas for pattern synonyms
    * 6.7.5. Or-Patterns
    * 6.7.5.1. Specification
  • 6.8. Class and instances declarations
    * 6.8.1. Multi-parameter type classes
    * 6.8.2. Undecidable (or recursive) superclasses
    * 6.8.3. Constrained class method types
    * 6.8.4. Default method signatures
    * 6.8.5. Detailed requirements for default type signatures
    * 6.8.6. Nullary type classes
    * 6.8.7. Functional dependencies
    * 6.8.7.1. Rules for functional dependencies
    * 6.8.7.2. Background on functional dependencies
    * 6.8.8. Instance declarations and resolution
    * 6.8.8.1. Relaxed rules for the instance head
    * 6.8.8.2. Formal syntax for instance declaration types
    * 6.8.8.3. Instance termination rules
    * 6.8.8.4. Undecidable instances and loopy superclasses
    * 6.8.8.5. Overlapping instances
    * 6.8.8.6. Instance signatures: type signatures in instance declarations
  • 6.9. Literals
    * 6.9.1. Negative literals
    * 6.9.2. Binary integer literals
    * 6.9.3. Hexadecimal floating point literals
    * 6.9.4. Fractional looking integer literals
    * 6.9.5. Sized primitive literal syntax
    * 6.9.6. Numeric underscores
    * 6.9.7. Overloaded string literals
    * 6.9.8. Overloaded labels
    * 6.9.9. Multiline string literals
    * 6.9.9.1. Examples
  • 6.10. Constraints
    * 6.10.1. Loosening restrictions on class contexts
    * 6.10.2. Equality constraints and Coercible constraint
    * 6.10.2.1. Equality constraints
    * 6.10.2.2. Heterogeneous equality
    * 6.10.2.3. Unlifted heterogeneous equality
    * 6.10.2.4. The Coercible constraint
    * 6.10.3. The Constraint kind
    * 6.10.4. Quantified constraints
    * 6.10.4.1. Motivation
    * 6.10.4.2. Syntax changes
    * 6.10.4.3. Typing changes
    * 6.10.4.4. Superclasses
    * 6.10.4.5. Overlap
    * 6.10.4.6. Instance lookup
    * 6.10.4.7. Termination
    * 6.10.4.8. Coherence
  • 6.11. Type signatures
    * 6.11.1. Explicit universal quantification (forall)
    * 6.11.1.1. The forall-or-nothing rule
    * 6.11.2. Ambiguous types and the ambiguity check
    * 6.11.3. Named default declarations
    * 6.11.3.1. Specifying the class
    * 6.11.3.2. Exporting the defaults
    * 6.11.3.3. Definition of subsumption
    * 6.11.3.4. Rules for disambiguation of multiple declarations
    * 6.11.3.5. Rules for disambiguation at the use site
    * 6.11.4. Explicitly-kinded quantification
    * 6.11.5. Lexically scoped type variables
    * 6.11.5.1. Overview
    * 6.11.5.2. Declaration type signatures
    * 6.11.5.3. Expression type signatures
    * 6.11.5.4. Pattern type signatures
    * 6.11.5.5. Class and instance declarations
    * 6.11.6. Implicit parameters
    * 6.11.6.1. Implicit-parameter type constraints
    * 6.11.6.2. Implicit-parameter bindings
    * 6.11.6.3. Implicit parameters and polymorphic recursion
    * 6.11.6.4. Implicit parameters scoping guarantees
    * 6.11.6.5. Implicit parameters and monomorphism
    * 6.11.7. Partial Type Signatures
    * 6.11.7.1. Syntax
    * 6.11.7.2. Where can they occur?
  • 6.12. Bindings and generalisation
    * 6.12.1. Switching off the Monomorphism Restriction
    * 6.12.2. Let-generalisation
  • 6.13. Template Haskell
    * 6.13.1. Syntax
    * 6.13.2. Using Template Haskell
    * 6.13.3. Viewing Template Haskell generated code
    * 6.13.4. A Template Haskell Worked Example
    * 6.13.5. Template Haskell quotes and Rebindable Syntax
    * 6.13.6. Using Template Haskell with Profiling
    * 6.13.7. Template Haskell Quasi-quotation
  • 6.14. Bang patterns and Strict Haskell
    * 6.14.1. Bang patterns
    * 6.14.1.1. Strict bindings
    * 6.14.2. Strict-by-default data types
    * 6.14.3. Strict-by-default pattern bindings
    * 6.14.4. Modularity
    * 6.14.5. Dynamic semantics of bang patterns
  • 6.15. Parallel and Concurrent
    * 6.15.1. Concurrent and Parallel Haskell
    * 6.15.1.1. Concurrent Haskell
    * 6.15.1.2. Parallel Haskell
    * 6.15.1.3. Annotating pure code for parallelism
    * 6.15.2. Software Transactional Memory
    * 6.15.3. Static pointers
    * 6.15.3.1. Using static pointers
    * 6.15.3.2. Static semantics of static pointers
  • 6.16. Unboxed types and primitive operations
    * 6.16.1. Unboxed types
    * 6.16.2. Unboxed type kinds
    * 6.16.3. Unboxed tuples
    * 6.16.4. Unboxed sums
    * 6.16.5. Unlifted Newtypes
    * 6.16.6. Unlifted Datatypes
    * 6.16.7. Primitive string literals
    * 6.16.8. Desugaring of string literals
  • 6.17. Foreign function interface (FFI)
    * 6.17.1. GHC differences to the FFI Chapter
    * 6.17.1.1. Guaranteed call safety
    * 6.17.1.2. Interactions between safe calls and bound threads
    * 6.17.1.3. Varargs not supported by ccall calling convention
    * 6.17.2. GHC extensions to the FFI Chapter
    * 6.17.2.1. Unlifted FFI Types
    * 6.17.2.2. Newtype wrapping of the IO monad
    * 6.17.2.3. Explicit “forall”s in foreign types
    * 6.17.2.4. Primitive imports
    * 6.17.2.5. Interruptible foreign calls
    * 6.17.2.6. The CAPI calling convention
    * 6.17.2.7. hs_thread_done()
    * 6.17.2.8. Freeing many stable pointers efficiently
    * 6.17.3. Using the FFI with GHC
    * 6.17.3.1. Using foreign export and foreign import ccall "wrapper" with GHC
    * 6.17.3.2. Using header files
    * 6.17.3.3. Memory Allocation
    * 6.17.3.4. Multi-threading and the FFI
    * 6.17.3.5. Floating point and the FFI
    * 6.17.3.6. Pinned Byte Arrays
  • 6.18. Safe Haskell
    * 6.18.1. Uses of Safe Haskell
    * 6.18.1.1. Strict type-safety (good style)
    * 6.18.1.2. Building secure systems (restricted IO Monads)
    * 6.18.2. Safe Language
    * 6.18.2.1. Safe Overlapping Instances
    * 6.18.3. Safe Imports
    * 6.18.4. Trust and Safe Haskell Modes
    * 6.18.4.1. Trust check (-fpackage-trust disabled)
    * 6.18.4.2. Trust check (-fpackage-trust enabled)
    * 6.18.4.3. Example
    * 6.18.4.4. Trustworthy Requirements
    * 6.18.4.5. Package Trust
    * 6.18.5. Safe Haskell Inference
    * 6.18.6. Safe Haskell Flag Summary
    * 6.18.7. Safe Compilation
  • 6.19. Miscellaneous
    * 6.19.1. Rewrite rules
    * 6.19.1.1. Syntax
    * 6.19.1.2. Semantics
    * 6.19.1.3. How rules interact with INLINE/NOINLINE pragmas
    * 6.19.1.4. How rules interact with CONLIKE pragmas
    * 6.19.1.5. How rules interact with class methods
    * 6.19.1.6. List fusion
    * 6.19.1.7. Specialisation
    * 6.19.1.8. Controlling what’s going on in rewrite rules
    * 6.19.2. Special built-in functions
    * 6.19.3. Generic programming
    * 6.19.3.1. Deriving representations
    * 6.19.3.2. Writing generic functions
    * 6.19.3.3. Unlifted representation types
    * 6.19.3.4. Generic defaults
    * 6.19.3.5. More information
    * 6.19.4. Assertions
    * 6.19.5. The __GLASGOW_HASKELL_ASSERTS_IGNORED__ CPP macro
    * 6.19.6. HasCallStack
    * 6.19.6.1. Compared with other sources of stack traces
    * 6.19.7. Whitespace
  • 6.20. Pragmas
    * 6.20.1. LANGUAGE pragma
    * 6.20.2. OPTIONS_GHC pragma
    * 6.20.3. INCLUDE pragma
    * 6.20.4. WARNING and DEPRECATED pragmas
    * 6.20.5. MINIMAL pragma
    * 6.20.6. INLINE and NOINLINE pragmas
    * 6.20.6.1. INLINE pragma
    * 6.20.6.2. INLINABLE pragma
    * 6.20.6.3. NOINLINE pragma
    * 6.20.6.4. CONLIKE modifier
    * 6.20.6.5. Phase control
    * 6.20.7. OPAQUE pragma
    * 6.20.8. LINE pragma
    * 6.20.9. COLUMN pragma
    * 6.20.10. RULES pragma
    * 6.20.11. SPECIALIZE pragma
    * 6.20.11.1. SPECIALIZE INLINE
    * 6.20.11.2. SPECIALIZE for imported functions
    * 6.20.12. SPECIALIZE instance pragma
    * 6.20.13. UNPACK pragma
    * 6.20.14. NOUNPACK pragma
    * 6.20.15. SOURCE pragma
    * 6.20.16. COMPLETE pragmas
    * 6.20.17. OVERLAPPING, OVERLAPPABLE, OVERLAPS, and INCOHERENT pragmas
• 7. Extending and using GHC as a Library
  • 7.1. Source annotations
    * 7.1.1. Annotating values
    * 7.1.2. Annotating types
    * 7.1.3. Annotating modules
  • 7.2. Using GHC as a Library
  • 7.3. Compiler Plugins
    * 7.3.1. Using compiler plugins
    * 7.3.2. Writing compiler plugins
    * 7.3.3. Core plugins in more detail
    * 7.3.3.1. Manipulating bindings
    * 7.3.3.2. Late Plugins
    * 7.3.3.3. Using Annotations
    * 7.3.4. Typechecker plugins
    * 7.3.4.1. Constraint solving with plugins
    * 7.3.4.2. Type family rewriting with plugins
    * 7.3.5. Source plugins
    * 7.3.5.1. Parsed representation
    * 7.3.5.2. Type checked representation
    * 7.3.5.3. Evaluated code
    * 7.3.5.4. Interface files
    * 7.3.5.5. Source plugin example
    * 7.3.6. Hole fit plugins
    * 7.3.6.1. Stateful hole fit plugins
    * 7.3.6.2. Hole fit plugin example
    * 7.3.7. Defaulting plugins
    * 7.3.8. Controlling Recompilation
    * 7.3.9. Frontend plugins
    * 7.3.10. DynFlags plugins
  • 7.4. Referring to back ends
    * 7.4.1. Client code that only names back ends
    * 7.4.2. Client code that discriminates among back ends
    * 7.4.3. General migration strategy for client code
• 8. Profiling
  • 8.1. Cost centres and cost-centre stacks
    * 8.1.1. Inserting cost centres by hand
    * 8.1.2. Rules for attributing costs
  • 8.2. Profiling and foreign calls
  • 8.3. Compiler options for profiling
    * 8.3.1. Automatically placing cost-centres
  • 8.4. Time and allocation profiling
    * 8.4.1. JSON profile format
    * 8.4.2. Eventlog profile format
  • 8.5. Profiling memory usage
    * 8.5.1. RTS options for heap profiling
    * 8.5.2. Retainer Profiling
    * 8.5.2.1. Hints for using retainer profiling
    * 8.5.3. Precise Retainer Analysis
    * 8.5.4. Biographical Profiling
    * 8.5.5. Actual memory residency
  • 8.6. hp2ps – Rendering heap profiles to PostScript
  • 8.7. Profiling Parallel and Concurrent Programs
  • 8.8. Observing Code Coverage
    * 8.8.1. A small example: Reciprocation
    * 8.8.2. Options for instrumenting code for coverage
    * 8.8.3. The hpc toolkit
    * 8.8.3.1. hpc report
    * 8.8.3.2. hpc markup
    * 8.8.3.3. hpc sum
    * 8.8.3.4. hpc combine
    * 8.8.3.5. hpc map
    * 8.8.3.6. hpc overlay and hpc draft
    * 8.8.4. Caveats and Shortcomings of Haskell Program Coverage
  • 8.9. Using “ticky-ticky” profiling (for implementors)
    * 8.9.1. Additional Ticky Flags
    * 8.9.2. Understanding the Output of Ticky-Ticky profiles
    * 8.9.3. Information about name-specific counters
    * 8.9.4. Examples
    * 8.9.5. Notes about ticky profiling
• 9. Debugging compiled programs
  • 9.1. Tutorial
  • 9.2. Requesting a stack trace from Haskell code
  • 9.3. Requesting a stack trace with SIGQUIT
  • 9.4. Implementor’s notes: DWARF annotations
    * 9.4.1. Debugging information entities
    * 9.4.1.1. DW_TAG_ghc_src_note
  • 9.5. Further Reading
  • 9.6. Direct Mapping
  • 9.7. Querying the Info Table Map
• 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. Hints
  • 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
  • 11.5. Controlling inlining via optimisation flags.
    * 11.5.1. Unfolding creation
    * 11.5.2. Inlining decisions
    * 11.5.3. Inlining generics
  • 11.6. Controlling specialization
    * 11.6.1. Commonly used flag/pragma combinations
    * 11.6.2. Unfolding availabiliy
    * 11.6.3. When does GHC generate specializations
  • 11.7. Understanding how OS memory usage corresponds to live data
• 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. File paths under Windows
  • 13.6. Using GHC (and other GHC-compiled executables) with Cygwin
    * 13.6.1. Background
    * 13.6.2. The problem
    * 13.6.3. Things to do
  • 13.7. Building and using Win32 DLLs
    * 13.7.1. Creating a DLL
    * 13.7.2. Making DLLs to be called from other languages
    * 13.7.2.1. Using from VBA
    * 13.7.2.2. Using from C++
• 14. FFI and the JavaScript Backend
  • 14.1. JavaScript FFI Types
    * 14.1.1. JSVal
    * 14.1.2. JavaScript Callbacks
    * 14.1.3. Callbacks as Foreign Exports
  • 14.2. Writing Replacement Implementations for Libraries with C FFI Functions
    * 14.2.1. Direct Implementation of C FFI Imports in JavaScript as jsbits
    * 14.2.2. Writing JavaScript Functions to be NodeJS and Browser Aware
    * 14.2.3. Replacing C FFI Imports with Pure Haskell and JavaScript
  • 14.3. Linking with C sources
    * 14.3.1. EMCC pragmas
    * 14.3.2. Wrappers
    * 14.3.3. Callbacks
• 15. Using the GHC WebAssembly backend
  • 15.1. What does the WebAssembly “backend” mean
  • 15.2. Setting up the GHC wasm backend
  • 15.3. Using the GHC wasm backend to compile & link code
  • 15.4. Running the GHC wasm backend’s output
  • 15.5. JavaScript FFI in the wasm backend
    * 15.5.1. Marshalable types and JSVal
    * 15.5.2. Foreign imports
    * 15.5.3. Foreign exports
    * 15.5.4. Detect whether JSFFI is being used
    * 15.5.5. Interaction with async exception
    * 15.5.6. Interaction with C FFI
    * 15.5.7. The JavaScript API
• 16. Known bugs and infelicities
  • 16.1. Haskell standards vs. Glasgow Haskell: language non-compliance
    * 16.1.1. Divergence from Haskell 98 and Haskell 2010
    * 16.1.1.1. Lexical syntax
    * 16.1.1.2. Context-free syntax
    * 16.1.1.3. Expressions and patterns
    * 16.1.1.4. Failable patterns
    * 16.1.1.5. Typechecking of recursive binding groups
    * 16.1.1.6. Default Module headers with -main-is
    * 16.1.1.7. Module system and interface files
    * 16.1.1.8. Numbers, basic types, and built-in classes
    * 16.1.1.9. In Prelude support
    * 16.1.1.10. The Foreign Function Interface
    * 16.1.2. GHC’s interpretation of undefined behaviour in Haskell 98 and Haskell 2010
  • 16.2. Known bugs or infelicities
    * 16.2.1. Bugs in GHC
    * 16.2.2. Bugs in GHCi (the interactive GHC)
• 17. Eventlog encodings
  • 17.1. Event log format
  • 17.2. Runtime system diagnostics
    * 17.2.1. Capability sets
    * 17.2.2. Environment information
    * 17.2.3. Thread and scheduling events
    * 17.2.4. Garbage collector events
    * 17.2.5. Heap events and statistics
    * 17.2.6. Spark events
    * 17.2.7. Capability events
    * 17.2.8. Task events
    * 17.2.9. Tracing events
  • 17.3. Heap profiler event log output
    * 17.3.1. Metadata event types
    * 17.3.1.1. Beginning of sample stream
    * 17.3.1.2. Cost centre definitions
    * 17.3.1.3. Info Table Provenance definitions
    * 17.3.1.4. Sample event types
    * 17.3.1.5. Cost-centre break-down
    * 17.3.1.6. String break-down
  • 17.4. Time profiler event log output
    * 17.4.1. Profile begin event
    * 17.4.2. Profile sample event
  • 17.5. Biographical profile sample event
  • 17.6. Non-moving GC event output
    * 17.6.1. Non-moving heap census
    * 17.6.2. Ticky counters
• 18. Glossary
• 19. Care and feeding of your GHC User’s Guide
  • 19.1. Basics
    * 19.1.1. Headings
    * 19.1.2. Formatting code
    * 19.1.2.1. Haskell
    * 19.1.2.2. Other languages
    * 19.1.3. Links
    * 19.1.3.1. Within the User’s Guide
    * 19.1.3.2. To GHC resources
    * 19.1.3.3. To external resources
    * 19.1.3.4. To core library Haddock documentation
    * 19.1.3.5. Math
    * 19.1.4. Index entries
  • 19.2. Citations
  • 19.3. Admonitions
  • 19.4. Documenting command-line options and GHCi commands
    * 19.4.1. Command-line options
    * 19.4.2. GHCi commands
  • 19.5. Style Conventions
  • 19.6. reST reference materials

Indices and tables¶

• Index
• Search Page