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.

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

• 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

• The User Manual (formatting guidelines etc)

• The Evil Mangler

Contributed Documentation

Please feel free to add new pages here. In due course information will migrate from here to the main commentary above.

• The Compiler
  • TypeFunctions: Notes concerning the implementation of type functions and associated types, which was merged in the HEAD during ICFP'06.
  • IntermediateTypes: Notes about the type system of GHC's new intermediate language (in the HEAD since ICFP'06)
  • DataParallel: Notes about the implementation of Data Parallel Haskell
  • RewriteRules: Notes about the implementation of RULEs in GHC
  • BackEndNotes: Some ideas and notes about the back end.
  • Cmm: Implementing Exception Handling: Implementing exception handling for primitive operations in Cmm
  • GhciDebugger: Some notes about the implementation of the GHCi debugger. Probably uninteresting unless you want to work on the debugger.
  • NewGhciDebugger: The new GHCi debugger.
  • AddingNewPrimitiveOperations: How to add new primitive operations to GHC Haskell.
  • Replacing GMP: Notes from an effort to replace GMP with another Bignum library.
  • ExternalCore: Describes the process of bringing External Core up to speed. Once finished, this will simply describe what External Core is, and how it works.
  • HaddockComments: Some notes about how the Haddock comment support is implemented.
  • ExplicitCallStack: Notes about maintaining an explicit call stack, to support error attribution and profiling.
  • Position Independent Code and Dynamic Linking

• The Runtime System
  • GarbageCollectorNotes Notes about GHC's existing single threaded garbage collector and development of a parallel GC.
  • GMPMemoryManagement 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 usign CPU events (cache misses, branch mispredictions).

• Getting to grips with the code base
  • BeginnersNotes?: Some notes about getting started hacking GHC and the structure of the compiler (especially types and typecheck)
  • DebuggingGhcCrashes: how to use gdb to debug a crash in GHC-compiled code.

• 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.
• GhcPapers: papers and pointers to other documents that relate to the inner workings of GHC.

Convert type diagram to SVG? Upload graphviz source?