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

Temporary note: don't edit in the main section yet; instead send us comments. We are editing heavily, from sources held in emacs, and might overwrite your changes'''

Contents

• The overall organisation of GHC
• Source Tree Roadmap
• The compilation pipeline

• The Compiler
  • Compiler Module Dependencies
  • Coding guidelines
    
    
  • Compiling one module: HscMain
  • Key data types:
    • The source language: HsSyn
    • RdrNames, Modules, and OccNames
    • Names
    • Entities: variables, type constructors, data constructors, and classes.
    • Types: Type and Kind, equality types and coercions
    • The core language
    • The STG language
    • The Cmm language
  • Passes:
    • Renamer
    • Typechecker
    • Desugarer
    • Core->core

• SPJ ModIface?, ModDetails?, ModGuts?
• SPJ Core->CorePrep?->Stg->Cmm
• The GHC API
• SM HscMain? upwards: ModSummary?, Finder, upsweep, downsweep

• Cross-cutting concerns
  • Primitive Operations (PrimOps)
  • Wired-in and known-key things
  • Packages
  • Symbol names and the Z-encoding

• The Runtime System
  • RTS Configurations
  • The Word
  • What the hell is a {{{.cmm}}} file?
  • Layout of heap objects
  • Layout of the stack
  • Haskell Execution
  • The Scheduler
  • The Storage Manager
  • So how does {{{foreign import "wrapper"}}} work?
  • GHCi support: the byte-code interpreter and dynamic linker
  • Asynchronous exceptions
  • Software Transactional Memory (STM)
  • Garbage Collecting CAFs
  • Weak Pointers and Finalizers
  • Coding conventions in the RTS

• Profiling

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
  • BeginnersNotes?: Some notes about getting started hacking GHC and the structure of the compiler (especially types and typecheck)
  • TypeFunctions: Notes concerning the implementation of type functions and associated types in the  FC branch of GHC.
  • IntermediateTypes: Notes about the type system of GHC's new intermediate language, in the  FC branch
  • RewriteRules: Notes about the implementation of RULEs in GHC
  • BackEndNotes: Some ideas and notes about the back end.
  • GhciDebugger: Some notes about the implementation of the GHCi debugger. Probably uninteresting unless you want to work on the debugger.
  • DebuggingGhcCrashes: how to use gdb to debug a crash in GHC-compiled code.
  • AddingNewPrimitiveOperations: How to add new primitive operations to GHC Haskell.
  • Replacing GMP: Notes from an effort to replace GMP with another Bignum library.
• The Runtime System
  • GarbageCollectorNotes Notes about GHC's existing single threaded garbage collector and development of a parallel GC.

Old but useful

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

•  The 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.