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


Ignore:
Timestamp:
Jan 13, 2009 2:10:24 PM (7 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