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