--- /dev/null
+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
projects / ghc-hetmet.git / commitdiff