Changes between Version 1 and Version 2 of Building/Architecture


Ignore:
Timestamp:
Mar 30, 2009 1:52:34 PM (6 years ago)
Author:
simonmar
Comment:

move idioms into a sub-section

Legend:

Unmodified
Added
Removed
Modified
  • Building/Architecture

    v1 v2  
    99decidedly non-trivial: do not attempt to modify it without having a
    1010grasp of the concepts that follow!
    11 
    12 Each of the following subsections describes one of the ``idioms`` that
    13 we use in the build system.  There are a handful of such idioms, and
    14 when you've understood them all you'll be able to understand most of
    15 the code you'll find in the build system.  We'll describe the idioms
    16 first, and then get on to the specifics of how we build GHC.
    1711
    1812'''Historical note''': this is the third major revision of the GHC build
     
    2620described in the next section.
    2721
    28 == Idiom: non-recursive make ==
     22== Idioms ==
     23
     24Each of the following subsections describes one of the ``idioms`` that
     25we use in the build system.  There are a handful of such idioms, and
     26when you've understood them all you'll be able to understand most of
     27the code you'll find in the build system.  We'll describe the idioms
     28first, and then get on to the specifics of how we build GHC.
     29
     30=== Idiom: non-recursive make ===
    2931
    3032Build systems for large projects often use the technique commonly
     
    6971   ordering" idiom below).
    7072
    71 == Idiom: stub makefiles ==
     73=== Idiom: stub makefiles ===
    7274
    7375It's all very well having a single giant `Makefile` that knows how to
     
    9395where `mk/sub-makefile.mk` knows how to recursively invoke the giant top-level '''make'''.
    9496
    95 == Idiom: standard targets (all, clean, etc.) ==
     97=== Idiom: standard targets (all, clean, etc.) ===
    9698
    9799We want an `all` target that builds everything, but we also want a way to build individual components (say, everything in `rts/`).  This is achieved by having a separate "all" target for each directory, named `all_`''directory''.  For example in `rts/ghc.mk` we might have this:
     
    109111Other standard targets such as `clean`, `install`, and so on use the same technique.  There are pre-canned macros to define your "all" and "clean" targets, take a look in `rules/all-target.mk` and `rules/clean-target.mk`.
    110112
    111 == Idiom: stages ==
     113=== Idiom: stages ===
    112114
    113115What do we use to compile GHC?  GHC itself, of course.  In a complete build we actually build GHC twice: once using the GHC version that is installed, and then again using the GHC we just built.  To be clear about which GHC we are talking about, we number them:
     
    120122Stage 1 does not support interactive execution (GHCi) and Template Haskell.  The reason being that when running byte code we must dynamically link the packages, and only in stage 2 and later can we guarantee that the packages we dynamically link are compatible with those that GHC was built against (because they are the very same packages).
    121123
    122 == Idiom: distdir ==
     124=== Idiom: distdir ===
    123125
    124126Often we want to build a component multiple times in different ways.  For example:
     
    136138There is a related concept called ''ways'', which includes profiling and dynamic-linking.  Multiple ways are currently part of the same "build" and use the same distdir, but in the future we might unify these concepts and give each way its own distdir.
    137139
    138 == Idiom: interaction with Cabal ==
     140=== Idiom: interaction with Cabal ===
    139141
    140142Many of the components of the GHC build system are also Cabal
     
    155157`.mk` files.
    156158
    157 == Idiom: variable names ==
     159=== Idiom: variable names ===
    158160
    159161Now that our build system is one giant `Makefile`, all our variables
     
    226228`$2`, and so on.
    227229
    228 == Idiom: phase ordering ==
     230=== Idiom: phase ordering ===
    229231
    230232NB. you need to understand this section if either (a) you are modifying parts of the build system that include automatically-generated `Makefile` code, or (b) you need to understand why we have a top-level `Makefile` that recursively invokes '''make'''.
     
    353355
    354356
    355 == Idiom: no double-colon rules ==
     357=== Idiom: no double-colon rules ===
    356358
    357359'''Make''' has a special type of rule of the form `target :: prerequisites`,
     
    361363really necessary - see the "all" idiom above - and this means there's one fewer makeism you need to know about.
    362364
    363 == Idiom: the vanilla way ==
     365=== Idiom: the vanilla way ===
    364366
    365367Libraries can be built in several different "ways", for example
     
    375377course).
    376378
    377 == Idiom: whitespace ==
     379=== Idiom: whitespace ===
    378380
    379381make has a rather ad-hoc approach to whitespace. Most of the time it ignores it, e.g.