Changes between Version 3 and Version 4 of Building/Architecture


Ignore:
Timestamp:
Mar 30, 2009 2:34:41 PM (5 years ago)
Author:
simonmar
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • Building/Architecture

    v3 v4  
    396396 
    397397The moral of the story is, avoid white space unless you're sure it'll be OK! 
     398 
     399 
     400 
     401== Modifying the build system == 
     402 
     403This section is a collection of information that you should find 
     404useful when modifying the build system. 
     405 
     406=== Overall structure and important files === 
     407  
     408 [http://darcs.haskell.org/ghc/ghc.mk ghc.mk]:: 
     409  This is where you should start reading: `ghc.mk` is the main file in 
     410  the build system which ties together all the other build-system 
     411  files.  It uses '''make''''s `include` directive to include all the 
     412  files in `mk/*.mk`, `rules/*.mk`, and all the other `ghc.mk` files 
     413  elsewhere in the tree. 
     414 
     415 [http://darcs.haskell.org/ghc/Makefile Makefile]:: 
     416  The top-level `Makefile`, recursively invokes `make` on `ghc.mk` 
     417  according to the [#Idiom:phaseordering phase ordering idiom]. 
     418 
     419 `rules/*.mk`:: 
     420  Each `.mk` file in the `rules` directory corresponds to a single 
     421  macro that can be called using '''make''''s `$(call ...)` 
     422  expression.  For example, the `build-package` macro is in 
     423  `rules/build-package.mk`. 
     424 
     425 [http://darcs.haskell.org/ghc/mk/config.mk.in config.mk.in]:: 
     426  The configuration information for the build system, processed by 
     427  `configure` to produce `mk/config.mk`.  Settings can be overriden by 
     428  creating a local file `mk/build.mk` (see 
     429  [wiki:Building/Using#Buildconfiguration Build configuration]). 
     430 
     431 [http://darcs.haskell.org/ghc/compiler/ghc.mk compiler/ghc.mk], [http://darcs.haskell.org/ghc/rts/ghc.mk rts/ghc.mk], etc.:: 
     432  Most subdirectories of the source tree have a `ghc.mk` file which 
     433  contains the instructions for building the components in that 
     434  directory.  Note: these `ghc.mk` files cannot be invoked 
     435  individually, they should only be included by the top-level 
     436  `ghc.mk`. 
     437 
     438=== Debugging === 
     439 
     440When the build system doesn't do what you want, the results can be 
     441pretty cryptic.  Often the problem is that something is being built in 
     442the wrong order, or some variable isn't being propagated to the places 
     443you thought it was.  How do you go about debugging the build system? 
     444Here are the techniques that we use: 
     445 
     446Note, for many of these diagnosis techniques you may want to invoke 
     447'''make''' on `ghc.mk` directly using `make -f ghc.mk`, to bypass the 
     448[#Idiom:phaseordering phase ordering] machinery of the top-level 
     449`Makefile`. 
     450 
     451 `make --debug=b --debug=m`:: 
     452   causes '''make''' to show the sequence of dependencies that it is 
     453   following, which will often tell you ''why'' something is being 
     454   built.  This can help to track down missing or incorrect 
     455   dependencies. 
     456 
     457 `make -p`:: 
     458  prints out all the generated rules and variables.  The output can be 
     459  huge; so pipe it to a file, and search through it for the bits of 
     460  interest. 
     461 
     462 `$(warning ... message ...)`:: 
     463  equivalent to "printf-debugging` in a C program: this causes 
     464  '''make''' to print a message when it reads the `$(warning ..)` 
     465  expression, and the message can include variable references.  Very 
     466  useful for finding out what '''make''' thinks the value of a 
     467  variable is at a particular point in the `Makefile`, or for finding 
     468  out the parameters for a particular macro call. 
     469 
     470 `make show VALUE=VAR`:: 
     471  prints the value of variable `VAR`.  Useful for quick diagnosis.