Resources for newcomers to GHC

This page is intended to serve as the first stop for those people who say, "I want to contribute to GHC, but I don't know quite where to begin." Begin here. While the building guide, working conventions, commentary and debugging pages (always linked from the left sidebar) have great information that can come in handy while you're working on your first, or first several patches, this page is intended to have the details you will need to get rolling.

First steps

  • To orient yourself to the general architecture of GHC, this article, written by two of the chief architects of GHC, Simon Marlow and Simon Peyton-Jones, is excellent and current (2012).
  • While you're reading that article, download and build the sources. Prepare your machine, download the source, and build. For the short, short version, which may or may not work for your machine, you can try this:
# needed only once, URL rewrite rule is persisted in ${HOME}/.gitconfig
git config --global url."git://".insteadOf git:// 

# clone GHC's main Git repository (creates './ghc' folder in CWD)
git clone --recursive git://
cd ghc/
git clone git://  # Windows only

# configure build
cd mk
## edit to remove the comment marker # on the line "BuildFlavour = quick"
cd ..
perl boot

# build GHC
make -j8 # parallelize to at most 8 parallel jobs; adapt to actual number of cpu cores
## edit to remove the comment marker # on the line stage=2

replace git:// by http:// or https:// in the instructions above if you're behind a firewall blocking port 9418. For more details see also Building/GettingTheSources.

If your machine has all the prerequisites, this might just work. Expect it all to take roughly an hour.

  • After a successful build, you should have your brand new compiler in ghc/inplace/bin/ghc-stage2. (GHCi is launched with ghc/inplace/bin/ghc-stage2 --interactive). Try it out.
  • To speed up the development cycle, the final edit of makes sure that only the stage-2 compiler will be rebuild after this (see here about stages).
  • A good first sanity check is to twiddle some error message in the code, just to see that changed error message pop up when you compile a file. Write some Haskell code with an error in it, and look at the error message. Search through the code for that error message. Change the message, rebuild ghc (run make again), and recompile your file again with ghc/inplace/bin/ghc-stage2. If you see the changed message, you're good to go.
  • To further speed up the development cycle, after you make some changes, don't run make directly in the ghc root directory (where you ran make the first time). Instead run it in the directory where you are making your changes, usually compiler, ghc, rts or one of the libraries or utils subdirectories. This greatly speeds up a rebuild.

Fixing a bug or implementing a new feature

Below is a list of tickets that appear to be "low-hanging fruit" -- things that might be reasonable for a newcomer to GHC hacking. Of course, we can't ever be sure of how hard a task is before doing it, so apologies if one of these is too hard.


hsc2hs emits invalid OPTIONS_GHC pragmas
Pretty-printing of long types
GHC is inconsistent with the Haskell Report on which Unicode characters are allowed in string and character literals
ghc-pkg complains about missing haddock interface files
Performance tests behave differently depending on presence of .hi file (even with -fforce-recomp)
make sdist picks up test files

Feature requests:

RecursiveDo in Template Haskell
The -> in ViewPatterns binds more weakly than infix data constructors.
Allow local foreign imports
Wildcards in type functions
Make error message more user friendly when module is not found because package is unusable
Easy way to defer type errors
GHC mode for converting files to explicit layout

Once you fix the bug or implement the new feature, make sure to write a test-case proving that you've done what you said. Then take some time to get to know and submit a code review to Phabricator. If the patch looks good, one of the committers will put it into the GHC codebase. Then, tackle another bug!

Practical advice

  • This page describes in more detail workflow for fixing bugs.
  • I (Richard E) use emacs to edit the code, and I have a hotkey dedicated to searching the ghc codebase, and another one dedicated to compiling ghc. This makes work on ghc much more interactive. See the Emacs page for more info.

Less practical advice

  • Don't get scared. GHC is a big codebase, but it makes sense when you stare at it long enough!
  • Be forewarned that many pages on the GHC wiki are somewhat out-of-date. Always check the last modification date. Email if you're not sure.

Need help?

You can email the ghc-devs list, or Richard Eisenberg (eir at cis . upenn . edu), a newish GHC developer himself who would be happy to foster more participation and answer your emails.

Happy hacking!

Last modified 2 months ago Last modified on Mar 17, 2015 11:41:35 PM