Changes between Version 3 and Version 4 of Building/Architecture

Mar 30, 2009 2:34:41 PM (7 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.