Changes between Version 14 and Version 15 of Attic/Building/BuildSystem/New


Ignore:
Timestamp:
Jan 13, 2009 2:10:24 PM (5 years ago)
Author:
simonmar
Comment:

add idiom for distdirs

Legend:

Unmodified
Added
Removed
Modified
  • Attic/Building/BuildSystem/New

    v14 v15  
    9292below). 
    9393 
     94== Idiom: stages == 
     95 
     96GHC is built by itself.  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: 
     97 
     98 * stage 0 is the GHC you have installed 
     99 * stage 1 is the first GHC we build, using stage 0 
     100 * stage 2 is the second GHC we build, using stage 1.  This is the one we normally install when you say `make install`. 
     101 * stage 3 is optional, but is sometimes built to test stage 2. 
     102 
     103Only stages 2 and 3 support interactive execution (GHCi) and Template Haskell.  The reason being that when running interactive code we must dynamically link the packages, and only in stage 2 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). 
     104 
     105== Idiom: multiple builds per directory == 
     106 
     107Often we want to build a component multiple times in different ways.  For example: 
     108 
     109 * certain libraries (e.g. Cabal) are required by GHC, so we build them once with the 
     110   bootstrapping compiler, and again with stage 1 once that is built. 
     111 
     112 * GHC itself is built multiple times (stage 1, stage 2, maybe stage 3) 
     113 
     114 * some tools (e.g. ghc-pkg) are also built once with the bootstrapping compiler, 
     115   and then again using stage 1 later. 
     116 
     117In order to support multiple builds in a directory, we place all generated files in a subdirectory, called the "distdir".  The distdir can be anything at all; for example in `compiler/` we name our distdirs after the stage (`stage1`, `stage2` etc.).  When there is only a single build in a directory, by convention we usually call the distdir simply "dist". 
     118 
     119There 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. 
     120 
    94121== Idiom: interaction with Cabal == 
    95122 
     
    116143share the same namespace.  Where previously we might have had a 
    117144variable that contained a list of the Haskell source files called 
    118 `HS_SRCS`, now we have one of these for each directory in the source tree, 
     145`HS_SRCS`, now we have one of these for each directory (and indeed each build, or distdir) in the source tree, 
    119146so we have to give them all different names. 
    120147 
    121148The idiom that we use for distinguishing variable names is to prepend 
    122 the directory name to the variable.  So for example the list of 
     149the directory name and the distdir to the variable.  So for example the list of 
    123150Haskell sources in the directory `utils/hsc2hs` would be in the 
    124 variable `utils/hsc2hs_HS_SRCS` ('''make''' doesn't mind slashes in variable 
    125 names). 
    126  
    127 In many parts of the build, we can build the same component in 
    128 multiple different ways.  For example, the compiler itself is built in 
    129 the `stage1` and `stage2` ways, so we additionally need to distinguish 
    130 variable names based on which way we're building.  Typically we place 
    131 each build in a separate subdirectory, so for example the `stage1` 
    132 build of the compiler places its files in `compiler/stage1`.  Variable 
    133 names related to this build would be named something like 
    134 `compiler_stage1_HS_SRCS`.  The pattern is therefore: 
    135 ''directory''_''build''_''variable''. 
     151variable `utils/hsc2hs_dist_HS_SRCS` ('''make''' doesn't mind slashes in variable 
     152names).  The pattern is: ''directory''_''distdir''_''variable''. 
    136153 
    137154== Idiom: macros == 
     
    141158{{{ 
    142159define build-package 
    143 # args: $1 = directory, $2 = build 
     160# args: $1 = directory, $2 = distdir 
    144161... makefile code to build a package ... 
    145162endef 
     
    149166 
    150167{{{ 
    151 $(eval $(call build-library,libraries/base,dist)) 
     168$(eval $(call build-package,libraries/base,dist)) 
    152169}}} 
    153170 
     
    164181variables which are guaranteed to not clash with other variables by 
    165182preceding their names with a string that is unique to this macro call. 
    166 A convenient unique string to use is ''directory''_''build''_; this is unique as long as we only call each macro with a given directory/build pair once.  Most macros in 
     183A convenient unique string to use is ''directory''_''distdir''_; this is unique as long as we only call each macro with a given directory/build pair once.  Most macros in 
    167184the GHC build system take the directory and build as the first two 
    168185arguments for exactly this reason.  For example, here's an excerpt