Changes between Version 17 and Version 18 of Attic/Building/BuildSystem


Ignore:
Timestamp:
Aug 17, 2008 5:32:18 PM (7 years ago)
Author:
igloo
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • Attic/Building/BuildSystem

    v17 v18  
    4444{{{small}}}.  Each program or library in the GHC
    4545source tree typically has its own directory, in this case we'll
    46 use {{{$(GHC_TOP)/small}}}.
     46use {{{$(TOP)/small}}}.
    4747Inside the {{{small/}}} directory there will be a
    4848{{{Makefile}}}, looking something like
     
    5050
    5151{{{
    52 # Makefile for program "small"
    5352TOP = ..
     53
     54ENABLE_SHELL_WRAPPERS = YES
     55EXTRA_CLEAN = myFile
     56EXTRA_DISTCLEAN = myFile
     57
    5458include $(TOP)/mk/boilerplate.mk
    55 
    56 HS_PROG = small
    57 
    58 include $(TOP)/target.mk
     59include $(TOP)/mk/cabal.mk
    5960}}}
    6061
     
    6263sections:
    6364
    64      
    65  * The first section includes
    66    (One of the most important
     65 * We start by defining `$(TOP)` to point to the top of the tree.
     66
     67 * Next there are some variables that we can set to control how `small` is built.
     68   The most common one is `ENABLE_SHELL_WRAPPERS`, which we can set to `YES`
     69   if we want to use Cabal's binary wrappers feature. This means that, on
     70   unix-like OSes, we install `small.wrapper` as a shell script wrapper
     71   around the real `small` binary.
     72   [[br]][[br]]
     73   Less common are `EXTRA_CLEAN` and `EXTRA_DISTCLEAN`, which list extra files
     74   to be removed during `make clean` and `make distclean`.
     75
     76 * Finally we include (One of the most important
    6777   features of GNU {{{make}}} that we use is the ability for a {{{Makefile}}} to
    6878   include another named file, very like {{{cpp}}}'s {{{#include}}}
    6979   directive.)
    70    a file of "boilerplate" code from the top level.
    71    As its name suggests, {{{boilerplate.mk}}}
     80   the common build system components.
     81   First is `boilerplate.mk` which, as its name suggests,
    7282   consists of a large quantity of standard
    7383   {{{Makefile}}} code.  We discuss this
    7484   boilerplate in more detail in [[ref(the mk/boilerplate.mk file)]].
    7585   [[br]][[br]]
    76    Before the {{{include}}} statement, you
    77    must define the {{{make}}} variable
     86   Note that you '''must''' define the {{{make}}} variable
    7887   {{{TOP}}}
    7988   to be the top-level directory of the source tree, containing
     
    98107   {{{Makefile}}} doing the
    99108   {{{include}}} to ensure this is the case.
    100 
    101 
    102  * The second section defines the standard
    103    {{{make}}} variable
    104    {{{HS_PROG}}}
    105    (the executable binary to be built).  We will discuss in
    106    more detail what the "standard variables" are,
    107    and how they affect what happens, in
    108    [[ref(the main mk/target.mk file)]].
    109 
    110 
    111  * The last section includes a second file of standard
    112    code, called
    113    {{{target.mk}}}.
     109   [[br]][[br]]
     110   Second is `cabal.mk`, which is the rules for how to build a
     111   Cabal package in the build system.
    114112   It contains the rules that tell {{{make}}} how
    115    to make the [wiki:Building/Using#StandardTargets standard targets].  Why, you ask, can't this
    116    standard code be part of
    117    {{{boilerplate.mk}}}?  Good question.  We
    118    discuss the reason later, in [[ref(Boilerplate architecture)]].
    119    [[br]][[br]]
    120    You do not ''have'' to
    121    {{{include}}} the
    122    {{{target.mk}}} file.  Instead, you can write
    123    rules of your own for all the standard targets.  Usually,
    124    though, you will find quite a big payoff from using the
    125    canned rules in {{{target.mk}}}; the price
    126    tag is that you have to understand what canned rules get
    127    enabled, and what they do
    128    [[ref(the main mk/target.mk file)]].
    129 
    130      
    131 
    132 In our example {{{Makefile}}}, most of the
    133 work is done by the two {{{include}}}d files.  When
    134 you say {{{make all}}}, the following things
    135 happen:
    136 
    137      
    138  * {{{make}}} looks in the current directory
    139    to see what source files it can find
    140    (eg. {{{Foo.hs}}},
    141    {{{Baz.c}}}), and from that it figures out
    142    what object files need to be built
    143    (eg. {{{Foo.o}}},
    144    {{{Baz.o}}}).  Because source files are found
    145    and used automatically, omitting them from a program or
    146    library has to be done manually (see
    147    {{{EXCLUDED_SRCS}}} in [[ref(the mk/boilerplate.mk file)]]).
    148 
    149 
    150  * It uses a boilerplate pattern rule to compile
    151    {{{Foo.hs}}} to {{{Foo.o}}}
    152    using a Haskell compiler.  (Which one?  That is set in the
    153    build configuration.)
    154 
    155 
    156  * It uses another standard pattern rule to compile
    157    {{{Baz.c}}} to {{{Baz.o}}},
    158    using a C compiler.  (Ditto.)
    159 
    160 
    161  * It links the resulting {{{.o}}} files
    162    together to make {{{small}}}, using the Haskell
    163    compiler to do the link step.  (Why not use
    164    {{{ld}}}?  Because the Haskell compiler knows
    165    what standard libraries to link in.  How did
    166    {{{make}}} know to use the Haskell compiler to
    167    do the link, rather than the C compiler?  Because we set the
    168    variable {{{HS_PROG}}} rather than
    169    {{{C_PROG}}}.)
    170 
    171      
    172 
    173 All {{{Makefile}}}s should follow the above
    174 three-section format.
     113   to make the [wiki:Building/Using#StandardTargets standard targets].
     114   The reason that this standard code isn't part of
     115   {{{boilerplate.mk}}} is that some directories are built differently,
     116   either because they have not yet been migrated to build with Cabal,
     117   or because they have needs that don't fit well into a generic
     118   system.
     119
    175120
    176121== Boilerplate architecture ==