Changes between Version 9 and Version 10 of Attic/Building/BuildSystem/New


Ignore:
Timestamp:
Jan 13, 2009 12:27:25 PM (7 years ago)
Author:
simonpj
Comment:

--

Legend:

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

    v9 v10  
    1818system.  The first incarnation was based on "jmake", a derivative of
    1919X11's "imake", which is based on using the C preprocessor to add macro
    20 capabilities and `#include` to plain make.  The second incarnation
    21 used GNU make's extensions for including makefiles (but lost the
    22 ability to use macros, since at the time GNU make didn't have support
     20capabilities and `#include` to plain '''make'''.  The second incarnation
     21used GNU '''make''''s extensions for including makefiles (but lost the
     22ability to use macros, since at the time GNU '''make''' didn't have support
    2323for general macros).  In this third revision, we use even more of GNU
    24 make's extensions, and we make a fundamental change to the design, as
     24'''make''''s extensions, and we make a fundamental change to the design, as
    2525described in the next section.
    2626
     
    3131each directory that is capable of building that part of the system.
    3232The `Makefile`s may share some common infrastructure and configuration
    33 by using GNU make's `include` directive; this is exactly what the
     33by using GNU '''make''''s `include` directive; this is exactly what the
    3434previous GHC build system did.  However, this design has a number of
    3535flaws, as described in Peter Miller's
    3636[http://miller.emu.id.au/pmiller/books/rmch/ Recursive Make Considered Harmful]. 
    3737
    38 The GHC build system adopts the non-recursive make idiom.  That is, we
    39 never invoke make from inside a `Makefile`, and the whole build system
     38The GHC build system adopts the non-recursive '''make''' idiom.  That is, we
     39never invoke '''make''' from inside a `Makefile`, and the whole build system
    4040is effectively a single giant `Makefile`.
    4141
     
    5454
    5555Doesn't this sacrifice modularity?  No - we can still split the build
    56 system into separate files, using GNU make's `include`.
     56system into separate files, using GNU '''make''''s `include`.
    5757
    5858Specific notes related to this idiom:
     
    7070build everything in the right order, but sometimes you want to build
    7171just part of the system.  When working on GHC itself, we might want to
    72 build just the compiler, for example.  In the recursive make system we
     72build just the compiler, for example.  In the recursive '''make''' system we
    7373would do `cd ghc` and then `make`.  In the non-recursive system we can
    7474still achieve this by specifying the target with something like `make
     
    8686}}}
    8787
    88 where `mk/sub-makefile.mk` knows how to recursively invoke make.  How
     88where `mk/sub-makefile.mk` knows how to recursively invoke '''make'''.  How
    8989does it know what to build?  By convention, for each directory there
    9090is a target `all_`''directory'' (e.g. `all_libraries/base`) which
     
    122122the directory name to the variable.  So for example the list of
    123123Haskell sources in the directory `utils/hsc2hs` would be in the
    124 variable `utils/hsc2hs_HS_SRCS` (make doesn't mind slashes in variable
     124variable `utils/hsc2hs_HS_SRCS` ('''make''' doesn't mind slashes in variable
    125125names).
    126126
     
    136136
    137137== Idiom: macros ==
    138 The build system makes extensive use of Gnu make '''macros'''.  A macro is defined in
    139 GNU make using `define`, e.g.
     138The build system makes extensive use of Gnu '''make''' '''macros'''.  A macro is defined in
     139GNU '''make''' using `define`, e.g.
    140140
    141141{{{
     
    155155
    156156Note that `eval` works like this: its argument is expended as normal,
    157 and then the result is interpreted by make as makefile code.  This
     157and then the result is interpreted by '''make''' as makefile code.  This
    158158means the body of the `define` gets expanded ''twice''.  Typically
    159159this means we need to use `$$` instead of `$` everywhere in the body of
     
    180180
    181181So if `build-prog` is called with `utils/hsc2hs` and `dist` for the
    182 first two arguments, after expansion make would see this:
     182first two arguments, after expansion '''make''' would see this:
    183183
    184184{{{
     
    193193== Idiom: phase ordering ==
    194194
    195 NB. 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.
    196 
    197 The main hitch with non-recursive make arises when parts of the build
     195NB. 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'''.
     196
     197The main hitch with non-recursive '''make''' arises when parts of the build
    198198system are automatically-generated.  The automatically-generated parts
    199199of our build system fall into two main categories:
     
    212212a `.depend` file needs to be re-generated if any of the source files have changed.
    213213
    214 GNU make has a clever strategy for handling this kind of scenario.  It
     214GNU '''make''' has a clever strategy for handling this kind of scenario.  It
    215215first reads all the included Makefiles, and then tries to build each
    216216one if it is out-of-date, using the rules in the Makefiles themselves.
     
    221221Makefiles.  For example in the GHC build, the `.depend` file for a
    222222package cannot be generated until `package-data.mk` has been generated
    223 and make has been restarted to read in its contents, because it is the
     223and '''make''' has been restarted to read in its contents, because it is the
    224224`package-data.mk` file that tells us which modules are in the package.
    225 But make always makes all the `Makefiles` before restarting - it
     225But '''make''' always makes all the `Makefiles` before restarting - it
    226226doesn't know how to restart itself earlier when there is a dependency
    227227between `Makefiles`.
     
    254254}}}
    255255
    256 make built both `inc1.mk` and `inc2.mk` without restarting itself
     256'''make''' built both `inc1.mk` and `inc2.mk` without restarting itself
    257257between the two (even though we added a dependency on `inc1.mk` from
    258258`inc2.mk`).
     
    290290}}}
    291291
    292 each time make is invoked, it first invokes `inc.mk` with `PHASE=0`.
     292each time '''make''' is invoked, it first invokes `inc.mk` with `PHASE=0`.
    293293This brings `inc1.mk` up-to-date (and ''only'' `inc1.mk`).  The second
    294 time we invoke make, we can be sure that `inc1.mk` is up-to-date and
     294time we invoke '''make''', we can be sure that `inc1.mk` is up-to-date and
    295295proceed to generate `inc2.mk`.  This is not at all pretty, and
    296 re-inovking make every time is slow, but we don't know of a better
     296re-invoking '''make''' every time is slow, but we don't know of a better
    297297workaround for this problem.
    298298
     
    302302== Idiom: no double-colon rules ==
    303303
    304 Make has a special type of rule of the form `target :: prerequisites`,
     304'''Make''' has a special type of rule of the form `target :: prerequisites`,
    305305with the behaviour that all double-colon rules for a given target are
    306306executed if the target needs to be rebuilt.  This style was popular