Changes between Version 1 and Version 2 of Building/Architecture


Ignore:
Timestamp:
Mar 30, 2009 1:52:34 PM (5 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.