The Glorious Glasgow Haskell Compilation System User's Guide, Version 7.8.4 (original) (raw)

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.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.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.6. Release notes for version 7.8.2

1.6.1. GHC

1.7. Release notes for version 7.8.3

1.7.1. GHC

1.8. Release notes for version 7.8.4

1.8.1. GHC

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.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. Promoting existential data constructors

7.9.6. Promoting type operators

7.10. Type-Level Literals

7.10.1. Runtime Values for Type-Level Literals

7.10.2. Computing With Type-Level Naturals

7.11. Equality constraints

7.11.1. The Coercible constraint

7.12. The Constraint kind

7.13. Other type system extensions

7.13.1. Explicit universal quantification (forall)

7.13.2. The context of a type signature

7.13.3. Ambiguous types and the ambiguity check

7.13.4. Implicit parameters

7.13.4.1. Implicit-parameter type constraints

7.13.4.2. Implicit-parameter bindings

7.13.4.3. Implicit parameters and polymorphic recursion

7.13.4.4. Implicit parameters and monomorphism

7.13.5. Explicitly-kinded quantification

7.13.6. Arbitrary-rank polymorphism

7.13.6.1. Examples

7.13.6.2. Type inference

7.13.6.3. Implicit quantification

7.13.7. Impredicative polymorphism

7.13.8. Lexically scoped type variables

7.13.8.1. Overview

7.13.8.2. Declaration type signatures

7.13.8.3. Expression type signatures

7.13.8.4. Pattern type signatures

7.13.8.5. Class and instance declarations

7.13.9. Bindings and generalisation

7.13.9.1. Switching off the dreaded Monomorphism Restriction

7.13.9.2. Generalised typing of mutually recursive bindings

7.13.9.3. Let-generalisation

7.14. Typed Holes

7.15. Deferring type errors to runtime

7.15.1. Enabling deferring of type errors

7.15.2. Deferred type errors in GHCi

7.16. Template Haskell

7.16.1. Syntax

7.16.2. Using Template Haskell

7.16.3. A Template Haskell Worked Example

7.16.4. Using Template Haskell with Profiling

7.16.5. Template Haskell Quasi-quotation

7.17. Arrow notation

7.17.1. do-notation for commands

7.17.2. Conditional commands

7.17.3. Defining your own control structures

7.17.4. Primitive constructs

7.17.5. Differences with the paper

7.17.6. Portability

7.18. Bang patterns

7.18.1. Informal description of bang patterns

7.18.2. Syntax and semantics

7.19. Assertions

7.20. Pragmas

7.20.1. LANGUAGE pragma

7.20.2. OPTIONS_GHC pragma

7.20.3. INCLUDE pragma

7.20.4. WARNING and DEPRECATED pragmas

7.20.5. MINIMAL pragma

7.20.6. INLINE and NOINLINE pragmas

7.20.6.1. INLINE pragma

7.20.6.2. INLINABLE pragma

7.20.6.3. NOINLINE pragma

7.20.6.4. CONLIKE modifier

7.20.6.5. Phase control

7.20.7. LINE pragma

7.20.8. RULES pragma

7.20.9. SPECIALIZE pragma

7.20.9.1. SPECIALIZE INLINE

7.20.9.2. SPECIALIZE for imported functions

7.20.9.3. Obsolete SPECIALIZE syntax

7.20.10. SPECIALIZE instance pragma

7.20.11. UNPACK pragma

7.20.12. NOUNPACK pragma

7.20.13. SOURCE pragma

7.21. Rewrite rules

7.21.1. Syntax

7.21.2. Semantics

7.21.3. How rules interact with INLINE/NOINLINE and CONLIKE pragmas

7.21.4. List fusion

7.21.5. Specialisation

7.21.6. Controlling what's going on in rewrite rules

7.21.7. CORE pragma

7.22. Special built-in functions

7.23. Generic classes

7.24. Generic programming

7.24.1. Deriving representations

7.24.2. Writing generic functions

7.24.3. Generic defaults

7.24.4. More information

7.25. Roles

7.25.1. Nominal, Representational, and Phantom

7.25.2. Role inference

7.25.3. Role annotations

7.26. Concurrent and Parallel Haskell

7.26.1. Concurrent Haskell

7.26.2. Software Transactional Memory

7.26.3. Parallel Haskell

7.26.4. Annotating pure code for parallelism

7.26.5. Data Parallel Haskell

7.27. Safe Haskell

7.27.1. Uses of Safe Haskell

7.27.1.1. Strict type-safety (good style)

7.27.1.2. Building secure systems (restricted IO Monads)

7.27.2. Safe Language

7.27.3. Safe Imports

7.27.4. Trust and Safe Haskell Modes

7.27.4.1. Trust check (-fpackage-trust disabled)

7.27.4.2. Trust check (-fpackage-trust enabled)

7.27.4.3. Example

7.27.4.4. Trustworthy Requirements

7.27.4.5. Package Trust

7.27.5. Safe Haskell Inference

7.27.6. Safe Haskell Flag Summary

7.27.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