The GHC Commentary

This tree of wiki pages is a "commentary" on the GHC source code. It contains all the explanatory material that doesn't belong in comments in the source code itself, because the material is wide-ranging, usually covers multiple source files, and is more architectural in nature. The commentary can also be considered a design document for GHC.

For the dedicated, there are videos of Simon and Simon giving an overview of GHC, at the 2006 GHC Hackathon.

Please feel free to add material to this commentary: don't worry too much about accuracy, in due course someone will edit your contribution. Try to link to source files as much as possible by using this macro: [[GhcFile(compiler/Makefile)]] (the usual Trac source: macro doesn't work here because the GHC darcs repository isn't integrated into this Trac). Also try to add appropriate links to other parts of the commentary.

Contents

• Source Tree Roadmap
• Coding style guidelines
• The compilation pipeline

• The Compiler

• The Runtime System In addition to the usual runtime support contains information on:
  • The Haskell Execution Model
  • The memory layout of heap and stack objects

• Cross-cutting concerns: topics which span both the compiler and the runtime system
  • Profiling
  • Primitive Operations (PrimOps); see also Wired-in and known-key things
  • Support for shared libraries
  • The Package System

• The Libraries

• The User Manual (formatting guidelines etc)

• The Evil Mangler

Contributed Documentation

Please edit and improve the Commentary above, or the Building Guide.

However sometimes you may want to add new material that doesn't quite fit into the existing structure. Or perhaps your pages are about work-in-progress, status reports and suchlike, which don't belong in the Commentary per se. Regardless, you can add your new material here.

• The Compiler
  • Edward Yang's blog post about  the entire complilation pipeline for `factorial`
  • Compiler plug-ins
  • Type level naturals
  • Proposal to add a kind for facts, e.g. class constraints
  • Proposal to allow classes to give default implementations for their superclasses
  • The new deriving mechanism
  • Notes about Template Haskell?
  • Notes about the new code generator
  • Type families/type functions: Notes concerning the implementation of type families, associated types, and equality constraints as well as the extension of the type checker with a contraint solver for equality constraints.
  • Intermediate Types: Notes about the type system of GHC's new intermediate language (in the HEAD since ICFP'06)
  • DPH: Notes about the implementation of Data Parallel Haskell
  • Rewrite Rules: Notes about the implementation of RULEs in GHC
  • Backend Ideas: Some ideas and notes about the back end.
  • Cmm: Implementing Exception Handling: Implementing exception handling for primitive operations in Cmm
  • Cmm: Using Kinds to implement calling conventions: Pointers to explanations of what a CmmKind is and why you might find one useful.
  • GHCi Debugger: Some notes about the implementation of the GHCi debugger. Probably uninteresting unless you want to work on the debugger.
  • New GHCi Debugger: The new GHCi debugger.
  • New Prim Ops: How to add new primitive operations to GHC Haskell.
  • Replacing GMP: Notes from an effort to replace GMP with another Bignum library.
  • External Core: Describes the process of bringing External Core up to speed. Once finished, this will simply describe what External Core is, and how it works.
  • Haddock: Some notes about how the Haddock comment support is implemented.
  • Explicit Call Stack: Notes about maintaining an explicit call stack, to support error attribution and profiling.
  • SQL-Like Comprehensions: Notes on the ongoing implementation of SPJs "Comprehensive Comprehensions".
  • SIMD: Notes on adding SIMD instructions and primOps to GHC
  •  Scrap your boilerplate page written by Ralf Lammel.
  • GHC Source Abbreviations: Abbreviations used in the GHC code
  • Safe Haskell: The design of an extension to Haskell around 'Safe' code.

• The Runtime System
  • Garbage Collector: Notes about GHC's existing single threaded garbage collector and development of a parallel GC.
  • GMP Memory Managment: Describes how the garbage collector cooperates with GMP for Integer.
  • SemiTagging: Describes how the semi-tagging optimisation will be implemented.
  • PAPI: Measurement of program performance using CPU events (cache misses, branch mis-predictions).

• Other Cross-cutting concerns: topics which span both the compiler and the runtime system
  • Haskell Program Coverage: How HPC works
  • Benchmarking: The nofib benchmark suite

• Parallel Haskell Variants: All aspects of the GpH and Eden parallel variants of GHC. (work in progress)

• Hackathon presentations (video)

Old but useful

Finally, here are some generally-useful, but now somewhat-out-of-date resources:

•  The old GHC Commentary: Information on the internals of GHC, in various states of up-to-dateness. We are keen to move this stuff out of its current location and onto this Wiki. If anyone is willing to help do that, even for just a part in which you are interested, we would be delighted.
• GHC Papers: Papers and pointers to other documents that relate to the inner workings of GHC.