Changes between Version 3 and Version 4 of Building/Architecture

Mar 30, 2009 2:34:41 PM (5 years ago)



  • Building/Architecture

    v3 v4  
    397397The moral of the story is, avoid white space unless you're sure it'll be OK! 
     401== Modifying the build system == 
     403This section is a collection of information that you should find 
     404useful when modifying the build system. 
     406=== Overall structure and important files === 
     408 []:: 
     409  This is where you should start reading: `` 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 `` files 
     413  elsewhere in the tree. 
     415 [ Makefile]:: 
     416  The top-level `Makefile`, recursively invokes `make` on `` 
     417  according to the [#Idiom:phaseordering phase ordering idiom]. 
     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/`. 
     425 []:: 
     426  The configuration information for the build system, processed by 
     427  `configure` to produce `mk/`.  Settings can be overriden by 
     428  creating a local file `mk/` (see 
     429  [wiki:Building/Using#Buildconfiguration Build configuration]). 
     431 [ compiler/], [ rts/], etc.:: 
     432  Most subdirectories of the source tree have a `` file which 
     433  contains the instructions for building the components in that 
     434  directory.  Note: these `` files cannot be invoked 
     435  individually, they should only be included by the top-level 
     436  ``. 
     438=== Debugging === 
     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: 
     446Note, for many of these diagnosis techniques you may want to invoke 
     447'''make''' on `` directly using `make -f`, to bypass the 
     448[#Idiom:phaseordering phase ordering] machinery of the top-level 
     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. 
     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. 
     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. 
     470 `make show VALUE=VAR`:: 
     471  prints the value of variable `VAR`.  Useful for quick diagnosis.