Fix Commentary link in the HACKING file; trac #3706
[ghc.git] / HACKING
diff --git a/HACKING b/HACKING
index a57fd97..3c5db04 100644 (file)
--- a/HACKING
+++ b/HACKING
@@ -2,208 +2,54 @@ 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 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:
-
- 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 and 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.
+
+
+  Coding conventions
+
+     http://hackage.haskell.org/trac/ghc/wiki/WorkingConventions
+
+     This wiki page explains the ground rules for code that is intended
+     to go into the mainline compiler source.
+  
+  
+  The GHC Commentary
+  
+     http://hackage.haskell.org/trac/ghc/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
+   If you're working with the current darcs 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.