diff options
Diffstat (limited to 'HACKING')
| -rw-r--r-- | HACKING | 208 |
1 files changed, 208 insertions, 0 deletions
diff --git a/HACKING b/HACKING new file mode 100644 index 0000000000..cbff47d6db --- /dev/null +++ b/HACKING @@ -0,0 +1,208 @@ +Getting started with hacking on GHC +----------------------------------- + +So you've decided to hack on GHC, congratulations! We hope you have a +rewarding experience. This file contains a few nuggets of information +that will help get you started right away, and point you in the +direction of more comprehensive documentation for later. + + +Setting up your build +--------------------- + +The GHC build tree is set up so that, by default, it builds a compiler +ready for installing and using. That means full optimisation, and the +build can take a *long* time. If you unpack your source tree and +right away say "./configure; make", expect to have to wait a while. + +For hacking, you want the build to be quick - quick to build in the +first place, and quick to rebuild after making changes. Tuning your +build setup can make the difference between several hours to build +GHC, and less than an hour. Here's how to do it. + +mk/build.mk is a GNU makefile that contains all your build settings. +By default, this file doesn't exist, and all the parameters are set to +their defaults in mk/config.mk (mk/config.mk is the place to look for +*all* the things you might want to tune). + +A good mk/build.mk to start hacking on GHC is: + +------ +SRC_HC_OPTS = -H32m -O -fasm -Rghc-timing +GhcStage1HcOpts = -O0 -DDEBUG +GhcLibHcOpts = -O -fgenerics +GhcLibWays = +SplitObjs = NO +------ + +What do these options do? + +SRC_HC_OPTS = -H32m -O -fasm -Rghc-timing + + These options are added to the command line for all Haskell + compilations. We turn on -fasm, because that halves compilation + time at the expense of a few percent performance. -Rghc-timing + prints out a line of timing info about each compilation. It's handy + to keep an eye on. + +GhcStage1HcOpts = -O0 -DDEBUG + + The options for building the stage1 compiler (these come after + SRC_HC_OPTS, so you can override settings from there). We turn off + optimisation here, assuming you'll be modifying and testing stage1. + With optimisation off, rebuilding GHC after modifying it will be + *much* quicker, not only because the individual compilations will be + quicker, but also there will be fewer dependencies between modules, + so less stuff needs to be rebuilt after each modification. + + Also we turn on -DDEBUG, because that enables assertions and + debugging code in the compiler itself. Turning on DEBUG makes + the compiler about 30% slower. + +GhcLibHcOpts = -O -fgenerics + + You almost certainly want optimisation *on* when building + libraries, otherwise the code you build with this compiler + goes really slowly. -fgenerics add generics support to the + libraries - you can turn this off if you like (it'll make the + libraries a bit smaller), but you won't be able to use Generics in + the code you build against these libraries. + +GhcLibWays = + + Normally the profiled libs are built. Setting GhcLibWays to + empty disables this, so you only build the normal libs. + +SplitObjs = NO + + Object splitting causes each module to be split into smaller + pieces in the final library, to reduce executable sizes when + linking against the library. It can be quite time and + memory-consuming, so turn it off when you're hacking. + + +Actually building the bits +-------------------------- + +To just build everything, from the top level: + + $ autoreconf + $ ./configure + $ make + $ make install + + +Building individual parts of the tree +------------------------------------- + +The first thing to understand is that the source tree is built in two +passes. First 'make boot' builds dependencies and any other tools +required as part of the build itself. For example, +ghc/utils/genprimopcode is built as part of 'make boot', because it is +required to preprocess ghc/compiler/prelude/primops.txt.pp. + +After 'make boot', 'make' will build everything. + +If you say 'make' from the very top-level, the build system will +arrange to do the appropriate 'make boot' steps for you. If you just +want to build in a subdirectory (eg. ghc), you have to do 'make boot' +yourself. You don't need to 'make boot' after every single change, +but you might want to do it to update dependencies, for example. + + +Refining the setup +------------------ + +If you will be hacking mostly on libraries, then you probably want to +build stage1 with optimisation, because you're only building it once +but using it many times. + + GhcStage1HcOpts = -O + +If you are working on GHCi or Template Haskell, then you will be +building and modifying the stage 2 compiler. Hence, you want to build +stage 1 with, and stage 2 without, optimisation. + + GhcStage1HcOpts = -O + GhcStage2HcOpts = -O0 -DDEBUG + +Take a look through mk/config.mk for more settings you might want to +override in build.mk. Remember: don't modify config.mk directly (it +gets overwritten when you run ./configure). + + +Full optimisation +----------------- + +To turn up everything to the max, for running performance tests for +example, try theses: + + SRC_HC_OPTS = -H64m -O2 + GhcLibHcOpts = -O2 + SplitObjs = YES + +You can even add some more aggresive options, such as +-fliberate-case-threshold50, -funfolding-use-threshold50. + + +Roadmap +------- + +A rough roadmap to the source tree: + + distrib materials for building distributions + + docs build system documentation + + ghc The GHC Compiler + rts the runtime system and storage manager + lib libraries used in GHC and its tools + utils tools that come with GHC, and tools used in the build + compiler the compiler itself + driver various scripts, and package databases + docs compiler documentation + includes header files shipped with GHC + + glafp-utils tools for the build system + + libraries The hierarchical libraries + + nofib A benchmark suite + + testsuite The regression test suite + + +Resources +--------- + +The GHC Developer's Wiki + + The home for GHC Developers, with information on accessing the latest sources, + the bug tracker, and further documentation on the code. + http://hackage.haskell.org/trac/ghc + + +The Building Guide + + Full documentation on the build system. + http://www.haskell.org/ghc/docs/latest/html/building/index.html + + +The GHC Commentary + + Notes on the internals and architecture of GHC. Much of this isn't + up to date, but there is still lots of useful stuff in there. Read + in conjunction with the source code. + http://www.cse.unsw.edu.au/~chak/haskell/ghc/comm/ + + +Mailing lists + + Ask on glasgow-haskell-users@haskell.org if you have difficulties. + If you're working with the current CVS sources of GHC, then + cvs-ghc@haskell.org might be a more appropriate (developers hang + out here). See http://www.haskell.org/mailman/listinfo for + subscription. + + +Happy Hacking! --The GHC Team |