| 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: |
| | 10 | To bring the whole tree up to date after making a change, just |
| 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: |
| | 16 | it 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: |
| 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. |
| | 30 | For more, see [wiki:Building/Using#DevelopinginaGHCbuildtree Developing in a GHC build tree]. |
