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.

If you have any questions along the way don't hesitate to reach out to the community. There are people on the mailing lists and IRC who will gladly help you (although you may need to be patient). Don't forget that all GHC developers are still learning; your question is never too silly to ask.

First steps

Prepare your machine, clone the git repo, and Building/QuickStart GHC. For the short, short version, which may or may not work for your machine, you can try this (note that building older versions of GHC may require having an older version of GHC on your path):

# needed only once, URL rewrite rule is persisted in ${HOME}/.gitconfig
git config --global url."git://".insteadOf git://
# (if you already cloned using ssh, you'll need this rule instead to make submodules work:)
# git config --global url."".insteadOf

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

# configure build
cp mk/ mk/

## edit mk/ to remove the comment marker # on the line "BuildFlavour = devel2"

# NOTE: On Windows you need to download some binary distributables before being able to build
# This only has to be done once and can be done by adding a flag to the call to configure:
./configure --enable-tarballs-autodownload

# build GHC
make -j8 # parallelize to at most 8 parallel jobs; adapt to actual number of cpu cores

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

  • While you are waiting for your build to finish, orient yourself to the general architecture of GHC. This article is written by two of the chief architects of GHC, Simon Marlow and Simon Peyton-Jones, is excellent and current (2012).
  • After a successful build, you should have your brand new compiler in ./inplace/bin/ghc-stage2. (GHCi is launched with ./inplace/bin/ghc-stage2 --interactive). Try it out.

Fast rebuilding

There are 4 things to remember:

  1. Select BuildFlavour = devel2 in your mk/ file (copy mk/ to mk/ first), to make GHC build more quickly.
  1. Don't run make directly in the ghc root directory (unless you just pulled in changes from others). Instead, first change to the directory (compiler, utils, ghc or libraries) where you're making your changes. See Building a single sub-component.

  1. Set stage=2 in your mk/ file, to freeze the stage 1 compiler. This makes sure that only the stage-2 compiler will be rebuilt after this.
  1. While in the sub-component directory, use make fast skip dependency building (except after pulling in changes from others).

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 fast in the ghc directory), and recompile your file again with ./inplace/bin/ghc-stage2. If you see the changed message, you're good to go.

Finding a ticket

Now that you can build GHC, let's get hacking. But first, you'll need to identify a goal. GHC's Trac tickets are a great place to find starting points. You are encouraged to ask for a starting point on IRC or the ghc-devs mailing list. There someone familiar with the process can help you find a ticket that matches your expertise and help you when you get stuck.

If you want to get a taste for possible starting tasks, 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.

You can add tickets to this list by giving them the newcomer Trac keyword.


Cross-module SpecConstr
Make Generic/Generic1 methods inlinable
Large Address space is not supported on Windows
ProfHeap's printf modifiers are incorrect
Speed up the RTS hash table
Integer (gmp) performance regression?
Lock .tix file
loadObj() does not respect alignment
:kind! is not expanding type synonyms anymore
RTS linker maps code as writable
Significant compilation time regression between 8.4 and HEAD due to coverage checking
Add PrelRules for par#
syn_arg_wraps and syn_res_wrap are only populated after typechecking
The settings and behaviour of idle GC are very confusing
GHCi does not follow the XDG Base Directory Specification
ref6 example from StaticPointers documentation doesn't type check
source file modify race leads to inconsistent error message
:doc shouldn't report <has no documentation> for a data constructor when it can show docs for the type constructor of the same name and type
Document the proposals process in the GHC manual
ghc-in-ghci script fails when there is a Main.hs in the top-level directory
DerivingStrategies defaulting warning has no associated enable/suppress flag
Tuple sections can't be quoted
Error message: "Perhaps you need a let in a do block", when there is no do block.
DeriveFunctor and GeneralizedNewtypeDeriving instances never reporting as covered
TYPE is not generated by genprimops
Test suite should report timeouts as timeouts
Int used to represent target integer literals

Feature requests:

Type family patterns should support as-patterns.
Allow inline pragmas on pattern synonyms
Missed constant folding oportunities
Machine accessible interface to GHCi
ghc -M requires -dep-suffix for no good reason
Flag to warn when deriving strategy is not explicitly specified
Exponentiation needs PrelRules


Better inlining test in CoreUnfold
Make the runtime reflection API for names, modules, locations more systematic
Allow users guide to be built independently from GHC
Add a flag to control constraint solving trace
Cleanup GHC verbosity flags
Add a more complete example for the special SPEC argument to the user guide
Add some benchmarks to nofib from Andras Kovac's Eff benchmarks
Add a suppression flag to stop Typeable bindings being emitted with -ddump-simpl
Split up glasgow_exts.rst
Document fundeps
Check if some auto apply code is dead and remove if appropriate.
Implement more constant folding for Naturals
Explore whether adding XRay attributes to LLVM IR is worthwhile
Core optimizations for memset on a small range

Practical advice

  • See also code reviews in Phabricator. You can refer to how they have been fixed.

Less practical advice

  • Don't get scared. GHC is a big codebase, but it makes sense when you stare at it long enough!
  • Don't hesitate to ask questions. We have all been beginners at some point and understand that diving in to GHC can be a challenge. Asking questions will help you make better use of your hacking time.
  • Be forewarned that many pages on the GHC Wiki are somewhat out-of-date. Always check the last modification date. Email ghc-devs if you're not sure.
  • There is a blog post series by Stephen Diehl that provides an overview of many important data structures and contains links to other sources of information: Dive into GHC

Need help?

You can email the ghc-devs list, or ask on IRC in #ghc.

Happy hacking!

Last modified 4 months ago Last modified on Aug 27, 2018 10:19:14 PM