Quick Start to using the build system as a developer

This page gives a quick overview of how to get around the GHC build system as a developer. There is more complete documentation for the build system later on in this guide (see Comprehensive overview of using the build system). If you are not looking to hack on GHC at all, but just want to build and install GHC, head on over to Quick Start to just building and installing GHC.

Before starting your build

You need to configure your build: which things to build, how much optimisation to use, whether to build profiling libraries, and so on. If you don't do this, then you get everything, and it will be optimised to the hilt, which means the build will take a Very Long Time. This is fine if you wanted to build GHC for installation and use, but not if you're building GHC to do some development work on it.

To configure your build, create the file mk/ from the sample:

$ cp mk/ mk/

and then edit mk/ to select the build you want. If you're not sure what you want, just uncommenting this line

#BuildFlavour = devel2

is usually a good choice. For more information on what you can do with, see Build configuration. In particular, you might want to make GHC build quickly.

Starting the build

To build the whole thing (compiler, libraries, compiler again), do this:

$ ./boot
$ ./configure
# 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
$ make

There are more configuration settings that you can use when running the configure script, see Run the configure script.

assuming everything goes according to plan, this should leave you with a compiler that you can run: inplace/bin/ghc-stage2.

Building after making changes

To bring the whole tree up to date after making a change, just

$ make

it might take a while, depending on what you changed. If you want to rebuild just part of the tree, for example the RTS, go into the appropriate subdirectory and say make there:

$ cd rts
$ make

this should rebuild just the RTS. If you want to just build the stage 2 compiler, then

$ cd ghc
$ make 2

For more, see Developing in a GHC build tree.


To clean the whole tree:

$ make clean

there's also make distclean, which will clean files that are generated by configure, and make maintainer-clean, which cleans everything that is not in the source repository.

You can clean just a part of the tree, e.g. the RTS:

$ cd rts
$ make clean


The validation script does a build of GHC from scratch and runs the test suite. If it passes without any errors, then it is ok to submit the patches from your tree. You should of course either be adding onto the test suite or running manual tests to verify your changes.

Parallel builds

The GHC build system works with make's -j flag, which spawns multiple compile processes in parallel. Even on a single processor machine it's usually worthwhile using at least make -j2, because the I/O will be overlapped with compute-intensive compilation. On a multicore machine, higher -j values will speed up the build even more.

Running GHC from the build tree

You don't need to install GHC to use it. After the build has completed, you can run GHC like this:

$ ./inplace/bin/ghc-stage2

and to start GHCi, just add the --interactive flag. You can also see what packages have been built:

$ ./inplace/bin/ghc-pkg list
Last modified 4 weeks ago Last modified on Jul 31, 2015 4:07:01 PM