From: simonmar Date: Tue, 25 Oct 2005 09:35:57 +0000 (+0000) Subject: [project @ 2005-10-25 09:35:57 by simonmar] X-Git-Tag: Initial_conversion_from_CVS_complete~141 X-Git-Url: http://git.megacz.com/?p=ghc-hetmet.git;a=commitdiff_plain;h=a832fad6755b121081a70c9a5eeb450853740d5b [project @ 2005-10-25 09:35:57 by simonmar] Add a "getting started" guide to hacking on GHC. --- diff --git a/ghc/HACKING b/ghc/HACKING new file mode 100644 index 0000000..6d6f62b --- /dev/null +++ b/ghc/HACKING @@ -0,0 +1,172 @@ +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. + + +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. + + GhcState1HcOpts = -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. + + GhcState1HcOpts = -O + GhcState2HcOpts = -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 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