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

Jan 13, 2009 2:10:24 PM (9 years ago)

add idiom for distdirs


  • Attic/Building/BuildSystem/New

    v14 v15  
     94== Idiom: stages ==
     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:
     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.
     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).
     105== Idiom: multiple builds per directory ==
     107Often we want to build a component multiple times in different ways.  For example:
     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.
     112 * GHC itself is built multiple times (stage 1, stage 2, maybe stage 3)
     114 * some tools (e.g. ghc-pkg) are also built once with the bootstrapping compiler,
     115   and then again using stage 1 later.
     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".
     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.
    94121== Idiom: interaction with Cabal ==
    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.
    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).
    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''.
    137154== Idiom: macros ==
    142159define build-package
    143 # args: $1 = directory, $2 = build
     160# args: $1 = directory, $2 = distdir
    144161... makefile code to build a package ...
    151 $(eval $(call build-library,libraries/base,dist))
     168$(eval $(call build-package,libraries/base,dist))
    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