# The GHC Commentary - Outline of the Genesis

Building GHC happens in two stages: First you have to prepare the tree with `make boot`; and second, you build the compiler and associated libraries with `make all`. The `boot` 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 Building Guide.

#### Debugging the Beast

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 `core` into `gdb` as usual, but unfortunately there is usually not too much useful information.

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 `gdb.` For a RTS with debugging turned on, add the following to `build.mk` (see also the comment in `config.mk.in` that you find when searching for `GhcRtsHcOpts`):

>     GhcRtsHcOpts+=-optc-DDEBUG
>     GhcRtsCcOpts+=-g
>     EXTRA_LD_OPTS=-lbfd -liberty

Then go into `fptools/ghc/rts` and `make clean boot && make all`. With the resulting runtime system, you have to re-link the compiler. Go into `fptools/ghc/compiler`, delete the file `hsc` (up to version 4.08) or `ghc-<version>`, and execute `make all`.

The `EXTRA_LD_OPTS` are necessary as some of the debugging code uses the BFD library, which in turn requires `liberty`. I would also recommend (in 4.11 and from 5.0 upwards) adding these linker options to the files `package.conf` and `package.conf.inplace` in the directory `fptools/ghc/driver/` to the `extra_ld_opts` entry of the package `RTS`. 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.

To run GHC up to version 4.08 in `gdb`, first invoke the compiler as usual, but pass it the option `-v`. This will show you the exact invocation of the compiler proper `hsc`. Run `hsc` with these options in `gdb`. 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.

Debugging a compiler during building from HC files. 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 `--enable-hc-boot` before re-making the code in `fptools/ghc/driver/`. If you do this with a compiler up to version 4.08, run the build process with `make EXTRA_HC_OPTS=-v` to get the exact arguments with which you have to invoke `hsc` in `gdb`.

Last modified: Sun Apr 24 22:16:30 CEST 2005