Changes between Version 25 and Version 26 of Building/Hacking

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