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


Ignore:
Timestamp:
Jan 13, 2009 12:27:25 PM (6 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