The GHC Build System Architecture
This section contains information you need to know in order to understand and modify the GHC build system. The build system is non-standard in various ways (to be explained shortly), and is decidedly non-trivial: do not attempt to modify it without having a grasp of the concepts that follow!
It's difficult to document a system that is full of details and subject to constant change. The approach we've adopted here is to split the documentation in two:
- The high-level architectural design, the stuff that is less likely to change, is documented here. Occasionally we'll include direct links to source files to illustrate the details.
- The low-level technical details, such as the order of arguments to a macro, and the names of specific variables, are documented as comments in the build-system code. Hopefully this way the documentation is more likely to stay up to date.
Historical note: this is the third major revision of the GHC build
system. The first incarnation was based on
jmake, a derivative of
imake, which is based on using the C preprocessor to add macro
#include to plain make. The second incarnation
used GNU make's extensions for including makefiles (but lost the
ability to use macros, since at the time GNU make didn't have support
for general macros). In this third revision, we use even more of GNU
make's extensions, and we make a fundamental change to the design, as
described in the next section. Another (fourth) revision based on
currently being attempted; see Building/Shake for more details.
Overall structure and important files
The following are a few of the most important files in the build system. For a more complete overview of the source-tree layout, see Commentary/SourceTree.
This is where you should start reading:
ghc.mkis the main file in the build system which ties together all the other build-system files. It uses make's
includedirective to include all the files in
rules/*.mk, and all the other
ghc.mkfiles elsewhere in the tree.
Makefile, recursively invokes
ghc.mkaccording to the phase ordering idiom.
.mkfile in the
rulesdirectory corresponds to a single macro that can be called using make's
$(call ...)expression. For example, the
build-packagemacro is in
The configuration information for the build system, processed by
mk/config.mk. Settings can be overriden by creating a local file
mk/build.mk(see Build configuration).
- compiler/ghc.mk, rts/ghc.mk, etc.
Most subdirectories of the source tree have a
ghc.mkfile which contains the instructions for building the components in that directory. Note: these
ghc.mkfiles cannot be invoked individually, they should only be included by the top-level
Each of the following subsections describes one of the
we use in the build system. There are a handful of such idioms, and
when you've understood them all you'll be able to understand most of
the code you'll find in the build system. We'll describe the idioms
first, and then get on to the specifics of how we build GHC.