Changes between Version 25 and Version 26 of Building/Hacking

Mar 31, 2009 9:01:17 AM (6 years ago)



  • Building/Hacking

    v25 v26  
    4 [  Video: Getting and Building], layout of the source tree, how to set up (23'43") 
     4= Getting started with the build system = 
    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. 
    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 == 
    15 == Using `mk/` == 
    17 {{{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/}}} ({{{mk/}}} is the place to look for 
    20 ''all'' the things you might want to tune).  
    22 There's an example in  
    23 [[GhcFile(mk/]], which you can copy to `mk/` and edit as required. 
    24 Alternatively if you want to understand a bit more about what's going on (recommended), read on. 
    26 == How to make GHC build quickly == 
    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.   
    37 Here are the `` settings that 
    38 we use to build fast: 
     10To bring the whole tree up to date after making a change, just  
    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 
    50 What do these options do? 
    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`. 
    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. 
    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. 
    81  {{{GhcLibWays =}}}:: 
    82   Normally the profiled libs are built.  Setting {{{GhcLibWays}}} to 
    83   empty disables this, so you only build the normal libs. 
    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. 
    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 ``. 
    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. 
    110 == Actually building the bits == 
    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: 
    115   $ sh boot 
    116   $ ./configure 
    117   $ make 
     19$ cd rts 
     20$ make 
    120 (See here for [wiki:Building/FAQ what can go wrong].) 
    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 
    125   $ make stage1 
     26$ cd ghc 
     27$ make stage2 
    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]). 
    131 To install the compiler you built, you can say 
    133 {{{ 
    134   $ make install 
    135 }}} 
    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. 
    140 == Building individual parts of the tree == 
    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. 
    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. 
    153 == Refining the setup == 
    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. 
    159 {{{ 
    160   GhcStage1HcOpts = -O 
    161 }}} 
    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. 
    167 {{{ 
    168   GhcStage1HcOpts = -O 
    169   GhcStage2HcOpts = -O0 -DDEBUG 
    170 }}} 
    172 Take a look through {{{mk/}}} for more settings you might want to 
    173 override in  Remember: don't modify {{{}}} directly (it 
    174 gets overwritten when you run {{{./configure}}}). 
    176 == The fastest GHC build == 
    178 The settings that give you the fastest complete GHC build are these: 
    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 }}} 
    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. 
    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]. 
    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. 
    197 == Full optimisation == 
     36== Controlling your build == 
    199 To turn up everything to the max, for running performance tests for 
    200 example, try these: 
     38The build is controlled in two ways: 
     40 * Flags given to `./configure`.  See [wiki:Building/Using#Runtheconfigurescript Run the configure script]. 
     42 * The file `mk/`.  This is a file you create yourself, containing various build settings.  There's a sample file in `mk/` that you can copy to `mk/` and use as a starting point.  For more information on what you can do with ``, see [wiki:Building/Using#Buildconfiguration Build configuration].  In particular, you might want to [wiki:Building/Using#HowtomakeGHCbuildquickly make GHC build quickly]. 
     44== Running GHC from the build tree == 
     46You don't need to install GHC to use it.  After the build has completed, you can run GHC like this: 
    203   SRC_HC_OPTS  = -H64m -O2  
    204   GhcLibHcOpts = 
    205   SplitObjs    = YES 
     49$ ./inplace/bin/ghc-stage2 
    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: 
    211 Here is a [wiki:Commentary/SourceTree roadmap to the source tree]. 
     55$ ./inplace/bin/ghc-pkg list 
     58== Old stuff == 
     60[  Video: Getting and Building], layout of the source tree, how to set up (23'43")