Requirements:

• GHC (== 8.6.x): for ghc-paths
• GCC: for CPP
• Sphinx: for docs building

git clone https://github.com/myuon/ghc-compiler-notes.git
cd ghc-compiler-notes
git clone --depth 1 https://gitlab.haskell.org/ghc/ghc.git output/ghc
make generate
make docs

Run make serve-docs and enjoy reading the notes from http://localhost:8000.

Using stack.

$ stack run
$ stack test --flag ghc-compiler-notes:dev

Using cabal.

$ cabal new-run
$ cabal new-test --enable-tests -fdev

• Read Cabal config

  • For MIN_VERSION_Cabal / etc. macros.
  • e.g. Failed to parse utils/haddock/haddock-test/src/Test/Haddock/Config.hs.

• Sources using nested pragmas: https://ghc.haskell.org/trac/ghc/ticket/314

  • GHC 8.6.x has an issue for raw stream token with nested comments.
  • Fixed this issue in GHC 8.8.x.
  • e.g. Failed to parse libraries/ghc-prim/GHC/Classes.hs.

• Notes not followed standard style

  • e.g. "A note about the stupid context" at compiler/basicTypes/DataCon.hs.
  • e.g. "Note [About the NameSorts]" at compiler/basicTypes/Name.hs.
  • e.g. "Note [Continuation BlockId]" at compiler/cmm/CmmNode.hs.
  • e.g. "Soundness checks" at compiler/ghci/RtClosureInspect.hs.

• Collect note references

  • Collect See Note [...] and relate them to notes