Changes between Version 25 and Version 26 of Building/Hacking


Ignore:
Timestamp:
Mar 31, 2009 9:01:17 AM (5 years ago)
Author:
simonmar
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • Building/Hacking

    v25 v26  
    22[[PageOutline]] 
    33 
    4 [http://video.google.com/videoplay?docid=7166458546326012899  Video: Getting and Building], layout of the source tree, how to set up build.mk (23'43") 
     4= Getting started with the build system = 
    55 
    6 = Controlling your build = 
     6There is more complete documentation for the build system later on in this guide (see [wiki:Building/Using]), but this page gives a quick overview of how to get around the GHC build system. 
    77 
    8 This section is for those who want to do more than just build & install GHC.  It 
    9 is for those who want to actually modify parts of GHC, and perhaps distribute those 
    10 modifications to others.  This section contains a few nuggets of information 
    11 that will help get you started right away.  For more detailed documentation 
    12 on the build system, read on to the later sections. 
     8== Building after making changes == 
    139 
    14  
    15 == Using `mk/build.mk` == 
    16  
    17 {{{mk/build.mk}}} is a GNU makefile that contains all your build settings. 
    18 By default, this file doesn't exist, and all the parameters are set to 
    19 their defaults in {{{mk/config.mk}}} ({{{mk/config.mk}}} is the place to look for 
    20 ''all'' the things you might want to tune).  
    21  
    22 There's an example in  
    23 [[GhcFile(mk/build.mk.sample)]], which you can copy to `mk/build.mk` and edit as required. 
    24 Alternatively if you want to understand a bit more about what's going on (recommended), read on. 
    25  
    26 == How to make GHC build quickly == 
    27  
    28 The GHC build tree is set up so that, by default, it builds a compiler 
    29 ready for installing and using.  That means full optimisation, and the 
    30 build can take a ''long'' time.  If you unpack your source tree and 
    31 right away say {{{./configure; make}}}, expect to have to wait a while. 
    32 For hacking, you want the build to be quick - quick to build in the 
    33 first place, and quick to rebuild after making changes.  Tuning your 
    34 build setup can make the difference between several hours to build 
    35 GHC, and less than an hour.   
    36  
    37 Here are the `build.mk` settings that 
    38 we use to build fast: 
     10To bring the whole tree up to date after making a change, just  
    3911 
    4012{{{ 
    41 # My build settings for hacking on stage 1  
    42 SRC_HC_OPTS     = -H32m -O -fasm -Rghc-timing 
    43 GhcStage1HcOpts = -O0 -DDEBUG -Wall 
    44 GhcLibHcOpts    = -O -fgenerics 
    45 GhcLibWays      = 
    46 SplitObjs       = NO 
    47 GhcBootLibs     = YES 
     13$ make 
    4814}}} 
    4915 
    50 What do these options do? 
    51  
    52  {{{SRC_HC_OPTS = -H32m -O -fasm -Rghc-timing}}}:: 
    53   These options are added to the command line for all Haskell 
    54   compilations.  We turn on `-fasm`, because that halves compilation 
    55   time at the expense of a few percent performance. `-Rghc-timing` 
    56   prints out a line of timing info about each compilation.  It's handy 
    57   to keep an eye on.  `-Wall` turns on all the warnings; GHC is 
    58   meant to be warning-clean with `-Wall`. 
    59  
    60  {{{GhcStage1HcOpts = -O0 -DDEBUG}}}:: 
    61   The options for building the stage1 compiler (these come after 
    62   SRC_HC_OPTS, so you can override settings from there).  We turn off 
    63   optimisation here, assuming you'll be modifying and testing stage1. 
    64   With optimisation off, rebuilding GHC after modifying it will be 
    65   ''much'' quicker, not only because the individual compilations will be 
    66   quicker, but also there will be fewer dependencies between modules, 
    67   so much less stuff is recompiled after each modification. 
    68   [[br]][[br]] 
    69   Also we turn on {{{-DDEBUG}}}, because that enables assertions and 
    70   debugging code in the compiler itself.  Turning on DEBUG makes 
    71   the compiler about 30% slower. 
    72  
    73  {{{GhcLibHcOpts = -O -fgenerics}}}:: 
    74   You almost certainly want optimisation ''on'' when building 
    75   libraries, otherwise the code you build with this compiler 
    76   goes really slowly.  {{{-fgenerics}}} add generics support to the 
    77   libraries - you can turn this off if you like (it'll make the 
    78   libraries a bit smaller), but you won't be able to use Generics in 
    79   the code you build against these libraries. 
    80  
    81  {{{GhcLibWays =}}}:: 
    82   Normally the profiled libs are built.  Setting {{{GhcLibWays}}} to 
    83   empty disables this, so you only build the normal libs. 
    84  
    85  {{{SplitObjs = NO}}}:: 
    86   Object splitting causes each module to be split into smaller 
    87   pieces in the final library, to reduce executable sizes when 
    88   linking against the library.  It can be quite time and 
    89   memory-consuming, so turn it off when you're hacking. 
    90  
    91  {{{GhcBootLibs = YES}}}:: 
    92   If you're just interested in working on GHC, then you probably don't want 
    93   to build the "extralibs" libraries that we normally ship with GHC.   
    94   So when [wiki:Building/GettingTheSources getting the sources],  
    95   run `darcs-all` without the `--extra` option.  Alternatively, even if you have 
    96   the libraries in your tree, you can stop them being built by setting 
    97   `GhcBootLibs` in your `build.mk`. 
    98  
    99 The other thing to remember is that for quick re-builds, you don't necessarily 
    100 want to go through the entire "make boot, make stage1, make libraries, make stage2" 
    101 sequence, which is the default if you type `make` in the root directory.  Instead, 
    102 we often say: 
    103  * {{{cd compiler; make stage=1}}}: re-makes the stage-1 compiler only 
    104  * {{{cd libraries; make}}}: re-make the libraries only 
    105  * {{{cd compiler; make stage=2}}}: re-make the stage-2 compiler only 
    106 If you do things this way, it's your responsibility to say `make boot` when necessary 
    107 to rebuild dependencies. 
    108  
    109  
    110 == Actually building the bits == 
    111  
    112 To just build everything, from the top level: 
     16it might take a while, depending on what you changed.  If you want to rebuild just part of the tree, for example the RTS, go into the appropriate subdirectory and say `make` there: 
    11317 
    11418{{{ 
    115   $ sh boot 
    116   $ ./configure 
    117   $ make 
     19$ cd rts 
     20$ make 
    11821}}} 
    11922 
    120 (See here for [wiki:Building/FAQ what can go wrong].) 
    121  
    122 If you just want to build stage 1, then instead you can say 
     23this should rebuild just the RTS.  If you want to just build the stage 2 compiler, then 
    12324 
    12425{{{ 
    125   $ make stage1 
     26$ cd ghc 
     27$ make stage2 
    12628}}} 
    12729 
    128 but note that the stage 1 compiler doesn't support GHCi or Template Haskell, those are compiled into stage 2 only (see  
    129 [wiki:Building/Using#BootstrappingGHC BootstrappingGHC]). 
    130  
    131 To install the compiler you built, you can say 
    132  
    133 {{{ 
    134   $ make install 
    135 }}} 
    136  
    137 However, you don't need to install GHC to use it.  Running `ghc/stage1-inplace/ghc` from the build tree 
    138 will invoke the stage1 compiler, and `ghc/stage2-inplace/ghc` will invoke the stage2 compiler. 
    139  
    140 == Building individual parts of the tree == 
    141  
    142 The first thing to understand is that in general each part of the source 
    143 tree may be built in two passes.  First `make boot` does any configuring 
    144 necessary, and then `make` will actually build everything. 
    145  
    146 If you say `make` from the very top-level, the build system will 
    147 arrange to do the appropriate `make boot` steps for you.  If you just 
    148 want to build in a subdirectory (eg. `compiler`), you have to do 
    149 `make boot` yourself. You don't need to `make boot` after every single 
    150 change, but you might need to do it after changing modules imports, 
    151 for example, so that the module dependency graph can be recalculated. 
    152  
    153 == Refining the setup == 
    154  
    155 If you will be hacking mostly on libraries, then you probably want to 
    156 build stage1 with optimisation, because you're only building it once 
    157 but using it many times. 
    158  
    159 {{{ 
    160   GhcStage1HcOpts = -O 
    161 }}} 
    162  
    163 If you are working on GHCi or Template Haskell, then you will be 
    164 building and modifying the stage 2 compiler.  Hence, you want to build 
    165 stage 1 with, and stage 2 without, optimisation. 
    166  
    167 {{{ 
    168   GhcStage1HcOpts = -O 
    169   GhcStage2HcOpts = -O0 -DDEBUG 
    170 }}} 
    171  
    172 Take a look through {{{mk/config.mk}}} for more settings you might want to 
    173 override in build.mk.  Remember: don't modify {{{config.mk}}} directly (it 
    174 gets overwritten when you run {{{./configure}}}). 
    175  
    176 == The fastest GHC build == 
    177  
    178 The settings that give you the fastest complete GHC build are these: 
    179  
    180 {{{ 
    181   SRC_HC_OPTS     = -H64m -O0 -fasm 
    182   GhcStage1HcOpts = -O -fasm 
    183   GhcStage2HcOpts = -O0 -fasm 
    184   GhcLibHcOpts    = -O0 -fasm 
    185   GhcLibWays      = 
    186   SplitObjs       = NO 
    187 }}} 
    188  
    189 However, note that the libraries are built without optimisation, so this build isn't very useful.  The stage 2 compiler will be very slow. 
    190  
    191 On a 4-core x86 machine using `make -j10`, this build was timed at less than 8 minutes. 
     30For more, see [wiki:Building/Using#DevelopinginaGHCbuildtree Developing in a GHC build tree]. 
    19231 
    19332== Parallel builds == 
     
    19534The GHC build system works with make's `-j` flag, which spawns multiple compile processes in parallel.  Even on a single processor machine it's usually worthwhile using at least `make -j2`, because the I/O will be overlapped with compute-intensive compilation.  On a multicore machine, higher `-j` values will speed up the build even more. 
    19635 
    197 == Full optimisation == 
     36== Controlling your build == 
    19837 
    199 To turn up everything to the max, for running performance tests for 
    200 example, try these: 
     38The build is controlled in two ways: 
     39 
     40 * Flags given to `./configure`.  See [wiki:Building/Using#Runtheconfigurescript Run the configure script]. 
     41 
     42 * The file `mk/build.mk`.  This is a file you create yourself, containing various build settings.  There's a sample file in `mk/build.mk.sample` that you can copy to `mk/build.mk` and use as a starting point.  For more information on what you can do with `build.mk`, see [wiki:Building/Using#Buildconfiguration Build configuration].  In particular, you might want to [wiki:Building/Using#HowtomakeGHCbuildquickly make GHC build quickly]. 
     43 
     44== Running GHC from the build tree == 
     45 
     46You don't need to install GHC to use it.  After the build has completed, you can run GHC like this: 
    20147 
    20248{{{ 
    203   SRC_HC_OPTS  = -H64m -O2  
    204   GhcLibHcOpts = 
    205   SplitObjs    = YES 
     49$ ./inplace/bin/ghc-stage2 
    20650}}} 
    20751 
    208 You can even add some more aggresive options, such as 
    209 {{{-fliberate-case-threshold50}}}, {{{-funfolding-use-threshold50}}}. 
     52and to start GHCi, just add the `--interactive` flag.  You can also see what packages have been built: 
    21053 
    211 Here is a [wiki:Commentary/SourceTree roadmap to the source tree]. 
     54{{{ 
     55$ ./inplace/bin/ghc-pkg list 
     56}}} 
     57 
     58== Old stuff == 
     59 
     60[http://video.google.com/videoplay?docid=7166458546326012899  Video: Getting and Building], layout of the source tree, how to set up build.mk (23'43")