--- /dev/null
+<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
+<html>
+ <head>
+ <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=ISO-8859-1">
+ <title>The GHC Commentary - Outline of the Genesis</title>
+ </head>
+
+ <body BGCOLOR="FFFFFF">
+ <h1>The GHC Commentary - Outline of the Genesis</h1>
+ <p>
+ Building GHC happens in two stages: First you have to prepare the tree
+ with <code>make boot</code>; and second, you build the compiler and
+ associated libraries with <code>make all</code>. The <code>boot</code>
+ stage builds some tools used during the main build process, generates
+ parsers and other pre-computed source, and finally computes dependency
+ information. There is considerable detail on the build process in GHC's
+ <a
+ href="http://haskell.cs.yale.edu/ghc/docs/latest/building/building-guide.html">Building Guide.</a>
+
+ <h4>Debugging the Beast</h4>
+ <p>
+ If you are hacking the compiler or like to play with unstable
+ development versions, chances are that the compiler someday just crashes
+ on you. Then, it is a good idea to load the <code>core</code> into
+ <code>gdb</code> as usual, but unfortunately there is usually not too
+ much useful information.
+ <p>
+ The next step, then, is somewhat tedious. You should build a compiler
+ producing programs with a runtime system that has debugging turned on
+ and use that to build the crashing compiler. There are many sanity
+ checks in the RTS, which may detect inconsistency before they lead to a
+ crash and you may include more debugging information, which helps
+ <code>gdb.</code> For a RTS with debugging turned on, add the following
+ to <code>build.mk</code> (see also the comment in
+ <a
+ href="http://cvs.haskell.org/cgi-bin/cvsweb.cgi/fptools/mk/config.mk.in"><code>config.mk.in</code></a> that you find when searching for
+ <code>GhcRtsHcOpts</code>):
+<blockquote><pre>
+GhcRtsHcOpts+=-optc-DDEBUG
+GhcRtsCcOpts+=-g
+EXTRA_LD_OPTS=-lbfd -liberty</pre></blockquote>
+ <p>
+ Then go into <code>fptools/ghc/rts</code> and <code>make clean boot &&
+ make all</code>. With the resulting runtime system, you have to re-link
+ the compiler. Go into <code>fptools/ghc/compiler</code>, delete the
+ file <code>hsc</code> (up to version 4.08) or
+ <code>ghc-<version></code>, and execute <code>make all</code>.
+ <p>
+ The <code>EXTRA_LD_OPTS</code> are necessary as some of the debugging
+ code uses the BFD library, which in turn requires <code>liberty</code>.
+ I would also recommend (in 4.11 and from 5.0 upwards) adding these linker
+ options to the files <code>package.conf</code> and
+ <code>package.conf.inplace</code> in the directory
+ <code>fptools/ghc/driver/</code> to the <code>extra_ld_opts</code> entry
+ of the package <code>RTS</code>. Otherwise, you have to supply them
+ whenever you compile and link a program with a compiler that uses the
+ debugging RTS for the programs it produces.
+ <p>
+ To run GHC up to version 4.08 in <code>gdb</code>, first invoke the
+ compiler as usual, but pass it the option <code>-v</code>. This will
+ show you the exact invocation of the compiler proper <code>hsc</code>.
+ Run <code>hsc</code> with these options in <code>gdb</code>. The
+ development version 4.11 and stable releases from 5.0 on do no longer
+ use the Perl driver; so, you can run them directly with gdb.
+ <p>
+ <strong>Debugging a compiler during building from HC files.</strong>
+ If you are boot strapping the compiler on new platform from HC files and
+ it crashes somewhere during the build (e.g., when compiling the
+ libraries), do as explained above, but you may have to re-configure the
+ build system with <code>--enable-hc-boot</code> before re-making the
+ code in <code>fptools/ghc/driver/</code>.
+ If you do this with a compiler up to version 4.08, run the build process
+ with <code>make EXTRA_HC_OPTS=-v</code> to get the exact arguments with
+ which you have to invoke <code>hsc</code> in <code>gdb</code>.
+
+ <p><small>
+<!-- hhmts start -->
+Last modified: Sun Apr 24 22:16:30 CEST 2005
+<!-- hhmts end -->
+ </small>
+ </body>
+</html>