From: Simon Marlow Date: Mon, 11 Sep 2006 13:50:37 +0000 (+0000) Subject: move the "meat" into the wiki, this file just contains pointers now X-Git-Tag: Before_FC_branch_merge~25 X-Git-Url: http://git.megacz.com/?p=ghc-hetmet.git;a=commitdiff_plain;h=b4d59b7caa9dd5816dcdd07a1be94ebd3e6b06d5 move the "meat" into the wiki, this file just contains pointers now --- diff --git a/HACKING b/HACKING index c7e6895..74aa742 100644 --- a/HACKING +++ b/HACKING @@ -2,205 +2,43 @@ 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. +rewarding experience. This file will point you in the direction of +information to help you get started right away. -Getting the sources -------------------- - -First get the GHC darcs repository: - - $ darcs get http://darcs.haskell.org/ghc/ - -Then run the darcs-all shell script in that repository -to get the other repositories: - - $ cd ghc - $ sh darcs-all - - -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, -utils/genprimopcode is built as part of 'make boot', because it is -required to preprocess 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 these: - - 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: - - compat compatibility library used by GHC and utils - compiler the compiler itself - distrib materials for building distributions - driver various scripts, and package databases - docs all documentation - includes header files shipped with GHC - libraries The hierarchical libraries - nofib A benchmark suite (optional) - rts the runtime system and storage manager - testsuite The regression test suite (optional) - utils tools that come with GHC, and tools used in the build - -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/ - +------------------------ + + The home for GHC Developers, with information on accessing the + latest sources, the bug tracker, and documentation on the + code: + + http://hackage.haskell.org/trac/ghc + + In particular, the wiki contains the following pages of interest to + new hackers: + + Quick Start for developers + + http://hackage.haskell.org/trac/ghc/wiki/Building/Hacking + + This section on the wiki will get you up & running with a + serviceable build tree in no time: + + This is part of the "Building GHC" section of the wiki, which + has more detailed information on GHC's build system should you + need it. + + + The GHC Commentary + + http://hackage.haskell.org/trac/wiki/Commentary + + Notes on the internals and architecture of GHC. + 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