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 ==