= 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 ==

 * [wiki:Commentary/Organisation The overall organisation of GHC]
 * [wiki:Commentary/SourceTree Source Tree Roadmap]
 * [wiki:Commentary/Pipeline The compilation pipeline]

 * [wiki:Commentary/Compiler The Compiler]
   * [wiki:ModuleDependencies Compiler Module Dependencies]
   * [wiki:Commentary/CodingStyle Coding guidelines]
     [[BR]][[BR]]
   * [wiki:Commentary/Compiler/HscMain Compiling one module: HscMain]
   * Key data types:
     * [wiki:Commentary/Compiler/HsSynType The source language: HsSyn] 
     * [wiki:Commentary/Compiler/RdrNameType RdrNames, Modules, and OccNames]
     * [wiki:Commentary/Compiler/NameType Names]
     * [wiki:Commentary/Compiler/EntityTypes Entities]: variables, type constructors, data constructors, and classes.
     * Types: [wiki:Commentary/Compiler/TypeType Type and Kind], [wiki:Commentary/Compiler/FC equality types and coercions]
     * [wiki:Commentary/Compiler/CoreSynType The core language]
     * [wiki:Commentary/Compiler/StgSynType The STG language]
     * [wiki:Commentary/Compiler/CmmType The Cmm language]
   * Passes:
     * [wiki:Commentary/Compiler/Renamer Renamer]
     * Typechecker
     * Desugarer
     * Core->core
       [[BR]][[BR]]
   * SPJ ModIface, ModDetails, ModGuts
   * SPJ Core->CorePrep->Stg->Cmm
   * [wiki:Commentary/Compiler/API The GHC API]
   * [wiki:Commentary/Compiler/SymbolNames Symbol names and the Z-encoding]
   * [wiki:Commentary/Compiler/WiredIn Wired-in and known-key things]
   * [wiki:Commentary/Packages Packages]
   * [wiki:Commentary/Compiler/Finder The Finder]
  
 * [wiki:Commentary/Rts The Runtime System]
   * [wiki:Commentary/Rts/Config RTS Configurations]
   * [wiki:Commentary/Rts/Word The Word]
   * [wiki:Commentary/Rts/Cmm What the hell is a {{{.cmm}}} file?]
   * [wiki:Commentary/Rts/HeapObjects Layout of heap objects]
   * [wiki:Commentary/Rts/Stack Layout of the stack]
   * [wiki:Commentary/Rts/HaskellExecution Haskell Execution]
   * [wiki:Commentary/Rts/Scheduler The Scheduler]
   * [wiki:Commentary/Rts/Storage The Storage Manager]
   * [wiki:Commentary/Rts/FFI So how does {{{foreign import "wrapper"}}} work?]
   * [wiki:Commentary/Rts/Interpreter GHCi support: the byte-code interpreter and dynamic linker]
   * [wiki:Commentary/Rts/AsyncExceptions Asynchronous exceptions]
   * [wiki:Commentary/Rts/STM Software Transactional Memory (STM)]
   * [wiki:Commentary/Rts/CAFs Garbage Collecting CAFs]
   * [wiki:Commentary/Rts/Weak Weak Pointers and Finalizers]
   * [wiki:Commentary/Rts/Conventions Coding conventions in the RTS]

 * Cross-cutting concerns: topics which span both the compiler and the RTS
    * [wiki:Commentary/Profiling Profiling]
    * [wiki:Commentary/PrimOps Primitive Operations (PrimOps)]

== 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)
   * [wiki:TypeFunctions]: Notes concerning the implementation of type functions and associated types in the [http://darcs.haskell.org/ghc-fc2/ FC branch] of GHC.
   * [wiki:IntermediateTypes]: Notes about the type system of GHC's new intermediate language, in the [http://darcs.haskell.org/ghc-fc2/ FC branch]
   * [wiki:RewriteRules]: Notes about the implementation of RULEs in GHC
   * [wiki:BackEndNotes]: Some ideas and notes about the back end.
   * [wiki: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.
   * [wiki:ReplacingGMPNotes Replacing GMP]: Notes from an effort to replace GMP with another Bignum library.
 * The Runtime System
   * [wiki: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:
 * [http://www.cse.unsw.edu.au/~chak/haskell/ghc/comm/ 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.