Changes between Version 7 and Version 8 of Building/Architecture


Ignore:
Timestamp:
Mar 31, 2009 7:50:26 AM (5 years ago)
Author:
simonmar
Comment:

remove the "modifying" parts, to put in a new page

Legend:

Unmodified
Added
Removed
Modified
  • Building/Architecture

    v7 v8  
    3030described in the next section. 
    3131 
     32== Overall structure and important files == 
     33  
     34 [http://darcs.haskell.org/ghc/ghc.mk ghc.mk]:: 
     35  This is where you should start reading: `ghc.mk` is the main file in 
     36  the build system which ties together all the other build-system 
     37  files.  It uses '''make''''s `include` directive to include all the 
     38  files in `mk/*.mk`, `rules/*.mk`, and all the other `ghc.mk` files 
     39  elsewhere in the tree. 
     40 
     41 [http://darcs.haskell.org/ghc/Makefile Makefile]:: 
     42  The top-level `Makefile`, recursively invokes `make` on `ghc.mk` 
     43  according to the [#Idiom:phaseordering phase ordering idiom]. 
     44 
     45 `rules/*.mk`:: 
     46  Each `.mk` file in the `rules` directory corresponds to a single 
     47  macro that can be called using '''make''''s `$(call ...)` 
     48  expression.  For example, the `build-package` macro is in 
     49  `rules/build-package.mk`. 
     50 
     51 [http://darcs.haskell.org/ghc/mk/config.mk.in config.mk.in]:: 
     52  The configuration information for the build system, processed by 
     53  `configure` to produce `mk/config.mk`.  Settings can be overriden by 
     54  creating a local file `mk/build.mk` (see 
     55  [wiki:Building/Using#Buildconfiguration Build configuration]). 
     56 
     57 [http://darcs.haskell.org/ghc/compiler/ghc.mk compiler/ghc.mk], [http://darcs.haskell.org/ghc/rts/ghc.mk rts/ghc.mk], etc.:: 
     58  Most subdirectories of the source tree have a `ghc.mk` file which 
     59  contains the instructions for building the components in that 
     60  directory.  Note: these `ghc.mk` files cannot be invoked 
     61  individually, they should only be included by the top-level 
     62  `ghc.mk`. 
     63 
    3264== Idioms == 
    3365 
     
    439471More details on when to use BUILD, HOST or TARGET can be found in 
    440472the comments in [http://darcs.haskell.org/mk/project.mk.in project.mk.in]. 
    441  
    442  
    443 == Modifying the build system == 
    444  
    445 This section is a collection of information that you should find 
    446 useful when modifying the build system. 
    447  
    448 === Overall structure and important files === 
    449   
    450  [http://darcs.haskell.org/ghc/ghc.mk ghc.mk]:: 
    451   This is where you should start reading: `ghc.mk` is the main file in 
    452   the build system which ties together all the other build-system 
    453   files.  It uses '''make''''s `include` directive to include all the 
    454   files in `mk/*.mk`, `rules/*.mk`, and all the other `ghc.mk` files 
    455   elsewhere in the tree. 
    456  
    457  [http://darcs.haskell.org/ghc/Makefile Makefile]:: 
    458   The top-level `Makefile`, recursively invokes `make` on `ghc.mk` 
    459   according to the [#Idiom:phaseordering phase ordering idiom]. 
    460  
    461  `rules/*.mk`:: 
    462   Each `.mk` file in the `rules` directory corresponds to a single 
    463   macro that can be called using '''make''''s `$(call ...)` 
    464   expression.  For example, the `build-package` macro is in 
    465   `rules/build-package.mk`. 
    466  
    467  [http://darcs.haskell.org/ghc/mk/config.mk.in config.mk.in]:: 
    468   The configuration information for the build system, processed by 
    469   `configure` to produce `mk/config.mk`.  Settings can be overriden by 
    470   creating a local file `mk/build.mk` (see 
    471   [wiki:Building/Using#Buildconfiguration Build configuration]). 
    472  
    473  [http://darcs.haskell.org/ghc/compiler/ghc.mk compiler/ghc.mk], [http://darcs.haskell.org/ghc/rts/ghc.mk rts/ghc.mk], etc.:: 
    474   Most subdirectories of the source tree have a `ghc.mk` file which 
    475   contains the instructions for building the components in that 
    476   directory.  Note: these `ghc.mk` files cannot be invoked 
    477   individually, they should only be included by the top-level 
    478   `ghc.mk`. 
    479  
    480 === Debugging === 
    481  
    482 When the build system doesn't do what you want, the results can be 
    483 pretty cryptic.  Often the problem is that something is being built in 
    484 the wrong order, or some variable isn't being propagated to the places 
    485 you thought it was.  How do you go about debugging the build system? 
    486 Here are the techniques that we use: 
    487  
    488 Note, for many of these diagnosis techniques you may want to invoke 
    489 '''make''' on `ghc.mk` directly using `make -f ghc.mk`, to bypass the 
    490 [#Idiom:phaseordering phase ordering] machinery of the top-level 
    491 `Makefile`. 
    492  
    493  `make --debug=b --debug=m`:: 
    494    causes '''make''' to show the sequence of dependencies that it is 
    495    following, which will often tell you ''why'' something is being 
    496    built.  This can help to track down missing or incorrect 
    497    dependencies. 
    498  
    499  `make -p`:: 
    500   prints out all the generated rules and variables.  The output can be 
    501   huge; so pipe it to a file, and search through it for the bits of 
    502   interest. 
    503  
    504  `$(warning ... message ...)`:: 
    505   equivalent to "printf-debugging` in a C program: this causes 
    506   '''make''' to print a message when it reads the `$(warning ..)` 
    507   expression, and the message can include variable references.  Very 
    508   useful for finding out what '''make''' thinks the value of a 
    509   variable is at a particular point in the `Makefile`, or for finding 
    510   out the parameters for a particular macro call. 
    511  
    512  `make show VALUE=VAR`:: 
    513   prints the value of variable `VAR`.  Useful for quick diagnosis.