Changes between Version 25 and Version 26 of Building/Hacking


Ignore:
Timestamp:
Mar 31, 2009 9:01:17 AM (6 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")