|
# The GHC Commentary
|
|
# 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.
|
|
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 beginners there is [a short getting started guide](contributing#newcomers-to-ghc).
|
|
For the beginners there is [a short getting started guide](contributing#newcomers-to-ghc).
|
|
|
|
|
|
|
|
For the dedicated, there are videos of the 2023 [GHC contributors' workshop](https://youtube.com/playlist?list=PLQpeDZt0_xQfTQPvjsT1ub-qVPXJ6fVy0&si=aay-zvuOexPSQkCE), where the GHC team gives detailed talks about the internals of the compiler. There are also other [videos of Simon and Simon](about-videos), at the 2006 [GHC Hackathon](hackathon).
|
|
For the dedicated, there are [videos of Simon and Simon giving an overview of GHC](about-videos), at the 2006 [GHC Hackathon](hackathon).
|
|
|
|
|
|
|
|
|
|
|
|
Also check out the [GHC Reading List](reading-list), which gives lots of background reading that will help you understand the actual implementation. Here's [another reading list](http://www.stephendiehl.com/posts/essential_compilers.html) from Stephen Diehl.
|
|
Also check out the [GHC Reading List](reading-list), which gives lots of background reading that will help you understand the actual implementation. Here's [another reading list](http://www.stephendiehl.com/posts/essential_compilers.html) from Stephen Diehl.
|
|
|
|
|
|
|
|
|
|
Stephen also has a helpful series of blog posts about GHC internals
|
|
Stephen also has a helpful series of blog posts about GHC internals
|
|
|
|
|
|
- [Dive into GHC: pipeline](http://www.stephendiehl.com/posts/ghc_01.html)
|
|
- [Dive into GHC: pipeline](http://www.stephendiehl.com/posts/ghc_01.html)
|
... | @@ -21,59 +16,38 @@ Stephen also has a helpful series of blog posts about GHC internals |
... | @@ -21,59 +16,38 @@ Stephen also has a helpful series of blog posts about GHC internals |
|
|
|
|
|
## Editing the Commentary
|
|
## Editing the Commentary
|
|
|
|
|
|
|
|
|
|
Please feel free to add material to the rest of the wiki: don't worry too much about accuracy (in due course someone will edit your contribution). When unsure though please indicate this; it's best to ask on the GHC mailing list so you can correct the commentary. Please give some thought to where in the commentary your contribution belongs. GHC has an older commentary (non wiki based) that read like a single coherent narrative, made sure to define terms before using them, and introduced concepts in the order which made them easiest to understand. Please do try to preserve those properties in this wiki commentary. If you're unsure or in a hurry, consider creating a wiki page outside the commentary and linking to it from the commentary (or the "contributed documentation" section below).
|
|
Please feel free to add material to the rest of the wiki: don't worry too much about accuracy (in due course someone will edit your contribution). When unsure though please indicate this; it's best to ask on the GHC mailing list so you can correct the commentary. Please give some thought to where in the commentary your contribution belongs. GHC has an older commentary (non wiki based) that read like a single coherent narrative, made sure to define terms before using them, and introduced concepts in the order which made them easiest to understand. Please do try to preserve those properties in this wiki commentary. If you're unsure or in a hurry, consider creating a wiki page outside the commentary and linking to it from the commentary (or the "contributed documentation" section below).
|
|
|
|
|
|
|
|
|
|
Also try to add appropriate links to other parts of the commentary.
|
|
Also try to add appropriate links to other parts of the commentary.
|
|
|
|
|
|
## Contents
|
|
## Contents
|
|
|
|
|
|
- [Getting Started](commentary/getting-started)
|
|
- [Getting Started](commentary/getting-started)
|
|
|
|
|
|
- [Source Tree Roadmap](commentary/source-tree)
|
|
- [Source Tree Roadmap](commentary/source-tree)
|
|
- [Module Structure](commentary/module-structure)
|
|
- [Module Structure](commentary/module-structure)
|
|
- [Documentation Style](commentary/Documentation-Style-Guide)
|
|
- [Documentation Style](commentary/Documentation-Style-Guide)
|
|
- [Coding Style](commentary/coding-style)
|
|
- [Coding Style](commentary/coding-style)
|
|
- [Abbreviations in GHC](commentary/abbreviations)
|
|
- [Abbreviations in GHC](commentary/abbreviations)
|
|
- [Platforms and their Naming Convention](commentary/platform-naming)
|
|
- [Platforms and their Naming Convention](commentary/platform-naming)
|
|
|
|
|
|
- [The Compiler](commentary/compiler)
|
|
- [The Compiler](commentary/compiler)
|
|
|
|
|
|
- [The Libraries on which GHC depends](commentary/libraries)
|
|
- [The Libraries on which GHC depends](commentary/libraries)
|
|
|
|
|
|
- [The Integer libraries (\`integer-gmp\` and \`integer-simple\`)](commentary/libraries/integer)
|
|
- [The Integer libraries (\`integer-gmp\` and \`integer-simple\`)](commentary/libraries/integer)
|
|
|
|
|
|
- [The Runtime System (RTS)](commentary/rts)
|
|
- [The Runtime System (RTS)](commentary/rts)
|
|
|
|
|
|
- [RTS Coding Conventions](commentary/rts/conventions)
|
|
- [RTS Coding Conventions](commentary/rts/conventions)
|
|
- [The Haskell Execution Model](commentary/rts/haskell-execution)
|
|
- [The Haskell Execution Model](commentary/rts/haskell-execution)
|
|
- [The memory layout of heap and stack objects](commentary/rts/storage)
|
|
- [The memory layout of heap and stack objects](commentary/rts/storage)
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
- Cross-cutting concerns: topics which span both the compiler and the runtime system
|
|
- Cross-cutting concerns: topics which span both the compiler and the runtime system
|
|
|
|
|
|
- [Profiling](commentary/profiling)
|
|
- [Profiling](commentary/profiling)
|
|
- [Wired-in and known-key things](commentary/compiler/wired-in)
|
|
- [Wired-in and known-key things](commentary/compiler/wired-in)
|
|
- [Primitive Operations (PrimOps)](commentary/prim-ops)
|
|
- [Primitive Operations (PrimOps)](commentary/prim-ops)
|
|
- [The Package System](commentary/packages)
|
|
- [The Package System](commentary/packages)
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
- [The User Manual](commentary/user-manual) (formatting guidelines etc)
|
|
- [The User Manual](commentary/user-manual) (formatting guidelines etc)
|
|
|
|
|
|
## Contributed Documentation
|
|
## Contributed Documentation
|
|
|
|
|
|
|
|
|
|
The above commentary covers the source code of GHC. For material that doesn't concern this topic (such as proposals, work-in-progress and status reports) or that don't fit into the existing structure, you will find them below. Feel free to add new material here but please categorise it correctly.
|
|
The above commentary covers the source code of GHC. For material that doesn't concern this topic (such as proposals, work-in-progress and status reports) or that don't fit into the existing structure, you will find them below. Feel free to add new material here but please categorise it correctly.
|
|
|
|
|
|
- General Notes on the GHC compiler
|
|
- General Notes on the GHC compiler
|
|
|
|
|
|
- Ningning Xie's [literature review](https://github.com/xnning/GHC-Core-Literature-Review/blob/master/doc/doc.pdf) of various contributions to GHC's type system
|
|
- Ningning Xie's [literature review](https://github.com/xnning/GHC-Core-Literature-Review/blob/master/doc/doc.pdf) of various contributions to GHC's type system
|
|
- Edward Yang's blog post about [the entire compilation pipeline for \`factorial\`](http://blog.ezyang.com/2011/04/tracing-the-compilation-of-hello-factorial/)
|
|
- Edward Yang's blog post about [the entire compilation pipeline for \`factorial\`](http://blog.ezyang.com/2011/04/tracing-the-compilation-of-hello-factorial/)
|
|
- [New Prim Ops](adding-new-primitive-operations): How to add new primitive operations to GHC Haskell.
|
|
- [New Prim Ops](adding-new-primitive-operations): How to add new primitive operations to GHC Haskell.
|
... | @@ -83,7 +57,6 @@ The above commentary covers the source code of GHC. For material that doesn't co |
... | @@ -83,7 +57,6 @@ The above commentary covers the source code of GHC. For material that doesn't co |
|
- [Optimisation Ordering](commentary/compiler/opt-ordering) Describe the ordering and interaction of optimisation passes (Old).
|
|
- [Optimisation Ordering](commentary/compiler/opt-ordering) Describe the ordering and interaction of optimisation passes (Old).
|
|
- [GHC Illustrated](https://github.com/takenobu-hs/haskell-ghc-illustrated) (follow the PDF link), a very insightful tutorial on GHC's internals.
|
|
- [GHC Illustrated](https://github.com/takenobu-hs/haskell-ghc-illustrated) (follow the PDF link), a very insightful tutorial on GHC's internals.
|
|
- [Ollie Charles's 24 days of GHC Extensions](https://ocharles.org.uk/blog/pages/2014-12-01-24-days-of-ghc-extensions.html), and [Lennart Augstsson's commentary](http://augustss.blogspot.com/2014/12/a-commentary-on-24-days-of-ghc.html)
|
|
- [Ollie Charles's 24 days of GHC Extensions](https://ocharles.org.uk/blog/pages/2014-12-01-24-days-of-ghc-extensions.html), and [Lennart Augstsson's commentary](http://augustss.blogspot.com/2014/12/a-commentary-on-24-days-of-ghc.html)
|
|
|
|
|
|
- [Welcome](https://ocharles.org.uk/blog/posts/2014-12-01-24-days-of-ghc-extensions.html)
|
|
- [Welcome](https://ocharles.org.uk/blog/posts/2014-12-01-24-days-of-ghc-extensions.html)
|
|
- [Static Pointers](https://ocharles.org.uk/blog/guest-posts/2014-12-23-static-pointers.html)
|
|
- [Static Pointers](https://ocharles.org.uk/blog/guest-posts/2014-12-23-static-pointers.html)
|
|
- [Template Haskell](https://ocharles.org.uk/blog/guest-posts/2014-12-22-template-haskell.html)
|
|
- [Template Haskell](https://ocharles.org.uk/blog/guest-posts/2014-12-22-template-haskell.html)
|
... | @@ -108,11 +81,9 @@ The above commentary covers the source code of GHC. For material that doesn't co |
... | @@ -108,11 +81,9 @@ The above commentary covers the source code of GHC. For material that doesn't co |
|
- [Pattern Synonyms](https://ocharles.org.uk/blog/posts/2014-12-03-pattern-synonyms.html)
|
|
- [Pattern Synonyms](https://ocharles.org.uk/blog/posts/2014-12-03-pattern-synonyms.html)
|
|
- [View Patterns](https://ocharles.org.uk/blog/posts/2014-12-02-view-patterns.html)
|
|
- [View Patterns](https://ocharles.org.uk/blog/posts/2014-12-02-view-patterns.html)
|
|
- [Thanks](https://ocharles.org.uk/blog/posts/2014-12-24-conclusion.html)
|
|
- [Thanks](https://ocharles.org.uk/blog/posts/2014-12-24-conclusion.html)
|
|
- [Commentary/Rts/CompilerWays](commentary/rts/compiler-ways): Compiler *ways* in GHC, what, how, and where
|
|
- [Commentary/Rts/CompilerWays](commentary/rts/compiler-ways): Compiler _ways_ in GHC, what, how, and where
|
|
- [How to Change the Settings Shown in `ghc --info`]
|
|
- \[How to Change the Settings Shown in `ghc --info`\]
|
|
|
|
|
|
- Notes on implemented GHC features:
|
|
- Notes on implemented GHC features:
|
|
|
|
|
|
- [Evaluation order and state tokens](https://wiki.haskell.org/Evaluation_order_and_state_tokens): notes written by Michael Snoyberg in response to #9390.
|
|
- [Evaluation order and state tokens](https://wiki.haskell.org/Evaluation_order_and_state_tokens): notes written by Michael Snoyberg in response to #9390.
|
|
- [Notes on fusion](foldr-build-notes) (eg foldr/build)
|
|
- [Notes on fusion](foldr-build-notes) (eg foldr/build)
|
|
- [Overloaded list syntax](overloaded-lists) allows you to use list notation for things other than lists.
|
|
- [Overloaded list syntax](overloaded-lists) allows you to use list notation for things other than lists.
|
... | @@ -141,9 +112,7 @@ The above commentary covers the source code of GHC. For material that doesn't co |
... | @@ -141,9 +112,7 @@ The above commentary covers the source code of GHC. For material that doesn't co |
|
- [OneShot](one-shot) The magic `oneShot` function.
|
|
- [OneShot](one-shot) The magic `oneShot` function.
|
|
- [Deriving Functor, Foldable, and Traversable](commentary/compiler/derive-functor)
|
|
- [Deriving Functor, Foldable, and Traversable](commentary/compiler/derive-functor)
|
|
- [GHC Settings File](commentary/ghc-settings-file) Change linker/compiler flags and other internal compiler settings.
|
|
- [GHC Settings File](commentary/ghc-settings-file) Change linker/compiler flags and other internal compiler settings.
|
|
|
|
|
|
- Notes on proposed or in progress (but out of tree) GHC compiler features:
|
|
- Notes on proposed or in progress (but out of tree) GHC compiler features:
|
|
|
|
|
|
- [Making Haskell strict](language-strict)
|
|
- [Making Haskell strict](language-strict)
|
|
- [Improving pattern-match overlap and exhaustiveness checks](pattern-match-check)
|
|
- [Improving pattern-match overlap and exhaustiveness checks](pattern-match-check)
|
|
- [Source-locations on HsSyn](ghc-ast-annotations)
|
|
- [Source-locations on HsSyn](ghc-ast-annotations)
|
... | @@ -178,37 +147,23 @@ The above commentary covers the source code of GHC. For material that doesn't co |
... | @@ -178,37 +147,23 @@ The above commentary covers the source code of GHC. For material that doesn't co |
|
- [Lambda-Case](lambdas-vs-pattern-matching): Syntax for full (with branching) pattern matching on arguments of lambda abstractions
|
|
- [Lambda-Case](lambdas-vs-pattern-matching): Syntax for full (with branching) pattern matching on arguments of lambda abstractions
|
|
- [Typeable](typeable): Making Typeable more expressive
|
|
- [Typeable](typeable): Making Typeable more expressive
|
|
- [SafeRoles](safe-roles): Roles & Safe Haskell
|
|
- [SafeRoles](safe-roles): Roles & Safe Haskell
|
|
|
|
|
|
- Library issues
|
|
- Library issues
|
|
|
|
|
|
- [Splitting up the base package](split-base)
|
|
- [Splitting up the base package](split-base)
|
|
|
|
|
|
- GHCi Debugger
|
|
- GHCi Debugger
|
|
|
|
|
|
- [Commentary/GHCi](commentary/GHCi): Notes on the implementation details for the support of breakpoints in GHCi.
|
|
- [Commentary/GHCi](commentary/GHCi): Notes on the implementation details for the support of breakpoints in GHCi.
|
|
- [GHCi Debugger](ghci-debugger): Notes on the implementation details of the GHCi debugger's feature for inspecting values.
|
|
- [GHCi Debugger](ghci-debugger): Notes on the implementation details of the GHCi debugger's feature for inspecting values.
|
|
|
|
|
|
- The Runtime System
|
|
- The Runtime System
|
|
|
|
|
|
- [A new lightweight concurrency substrate for GHC](lightweight-concurrency)
|
|
- [A new lightweight concurrency substrate for GHC](lightweight-concurrency)
|
|
- [Garbage Collector](garbage-collector-notes): Notes about GHC's existing single threaded garbage collector and development of a parallel GC.
|
|
- [Garbage Collector](garbage-collector-notes): Notes about GHC's existing single threaded garbage collector and development of a parallel GC.
|
|
- [GMP Memory Managment](gmp-memory-management): Describes how the garbage collector cooperates with GMP for Integer.
|
|
- [GMP Memory Managment](gmp-memory-management): Describes how the garbage collector cooperates with GMP for Integer.
|
|
- [SemiTagging](semi-tagging): Describes how the semi-tagging optimisation will be implemented.
|
|
- [SemiTagging](semi-tagging): Describes how the semi-tagging optimisation will be implemented.
|
|
- [PAPI](papi): Measurement of program performance using CPU events (cache misses, branch mis-predictions).
|
|
- [PAPI](papi): Measurement of program performance using CPU events (cache misses, branch mis-predictions).
|
|
|
|
|
|
- Cross-cutting concerns: topics which span both the compiler and the runtime system
|
|
- Cross-cutting concerns: topics which span both the compiler and the runtime system
|
|
|
|
|
|
- [Haskell Program Coverage](commentary/hpc): How HPC works
|
|
- [Haskell Program Coverage](commentary/hpc): How HPC works
|
|
|
|
|
|
- [Parallel Haskell Variants](gph-eden): All aspects of the GpH and Eden parallel variants of GHC.
|
|
- [Parallel Haskell Variants](gph-eden): All aspects of the GpH and Eden parallel variants of GHC.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
## Old Documentation
|
|
## Old Documentation
|
|
|
|
|
|
|
|
|
|
Here are some useful, but somewhat-out-of-date resources:
|
|
Here are some useful, but somewhat-out-of-date resources:
|
|
|
|
|
|
- [The old GHC Commentary](http://darcs.haskell.org/ghc/docs/comm/): 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. There is a [page](commentary/migrating-old-commentary) which tracks the progress of migrating information from the old commentary to this wiki.
|
|
- [The old GHC Commentary](http://darcs.haskell.org/ghc/docs/comm/): 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. There is a [page](commentary/migrating-old-commentary) which tracks the progress of migrating information from the old commentary to this wiki.
|
... | | ... | |