Changes between Version 7 and Version 8 of Building/Architecture


Ignore:
Timestamp:
Mar 31, 2009 7:50:26 AM (6 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.