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
X11's own imake
, which is based on using the C preprocessor to add macro
capabilities and #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 Shake
is
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.
- ghc.mk
-
This is where you should start reading:
ghc.mk
is the main file in the build system which ties together all the other build-system files. It uses make'sinclude
directive to include all the files inmk/*.mk
,rules/*.mk
, and all the otherghc.mk
files elsewhere in the tree.
- Makefile
-
The top-level
Makefile
, recursively invokesmake
onghc.mk
according to the phase ordering idiom.
rules/*.mk
-
Each
.mk
file in therules
directory corresponds to a single macro that can be called using make's$(call ...)
expression. For example, thebuild-package
macro is inrules/build-package.mk
.
- mk/config.mk.in
-
The configuration information for the build system, processed by
configure
to producemk/config.mk
. Settings can be overriden by creating a local filemk/build.mk
(see Build configuration).
- compiler/ghc.mk, rts/ghc.mk, etc.
-
Most subdirectories of the source tree have a
ghc.mk
file which contains the instructions for building the components in that directory. Note: theseghc.mk
files cannot be invoked individually, they should only be included by the top-levelghc.mk
.
Idioms
Each of the following subsections describes one of the idioms
that
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.