Changes between Version 10 and Version 11 of Commentary/SourceTree

Jan 13, 2009 1:44:51 PM (5 years ago)

re-instate links to sub pages


  • Commentary/SourceTree

    v10 v11  
    3 This page has moved to [wiki:Building/Files]. 
     4= Layout of important files and directories = 
     6Everything starts with the main GHC repository (see [wiki:Building/GettingTheSources]).   The buld system calls that directory `$(TOP)`.  All the paths below are relative to `$(TOP)`. 
     8== Files in `$(TOP)` == 
     10 '''`darcs-all`''':: 
     11  This script allows you to get or pull all the additional repositories that you need to build GHC.  The command-line interface is documented in the file itself. 
     13 '''`Makefile`''':: Top-level {{{Makefile}}}; {{{make}}} by itself does a full 2-stage 
     14  bootstrap of GHC, there are also targets for building source and 
     15  binary distributions.  GHC requires 
     16  [ GNU make]. 
     18 '''`packages`''':: 
     19  Lists the packages that `darcs-all` should get or pull.  `packages` is looked at only by `darcs-all`. 
     21 '''`validate`''':: Run `validate` (a shell script) before committing (see [wiki:TestingPatches]).  The script is documented in the file itself. 
     23 '''Documentation files''':: `README`, `ANNOUNCE`, `HACKING`, `LICENSE` 
     25 '''GNU autoconf machinery''':: `aclocal.m4`, `config.guess`, `config.sub`, ``, `install-sh` 
     27 '''``''':: the RPM spec file 
     29== `libraries/` == 
     31The `libraries/` directory contains all the packages that GHC needs to build.  It has one sub-directory for each package repository (e.g. `base`, `haskell98`, `random`). Usually each such repository builds just one package but sometimes more than one (e.g DPH). 
     33 * '''`libraries/cabal-bin.hs`''' is a little program we use for building the libraries. It's similar to cabal-install, but without the dependencies on `http` etc. 
     34 * '''`libraries/ifBuildable/`''' is a utility that we use in the build system. It allows the build to continue if an extralib is not buildable (e.g., if we are missing a C library that an extralib depends on then we can still build the compiler). We expect this to disappear soon, when extralibs are removed. 
     35 * '''`libraries/bootstrapping/`''': In order to build `cabal-bin` we need to compile `cabal-bin.hs`, as well as a few libraries that we can't rely on the bootstrapping compiler having. We put the `.hi` and `.o` files that result from this in `bootstrapping/`. 
     37== `compiler/`, `docs/`, `ghc/` ==  
     39These directories contain the main GHC compiler and documentation. 
     40The `compiler/` directory contains the ghc package, which is linked 
     41into an executable in the `ghc/` directory. 
     43 * '''`compiler/ghc.cabal`''': the Cabal file for GHC.  If you add a module to GHC's source code, you must add it in the `ghc.cabal` file too, else you'll get link errors. 
     45== `rts/` == 
     47Sources for the runtime system; see [wiki:Commentary/SourceTree/Rts]. 
     49== `includes/` == 
     51Header files for the runtime system; see [wiki:Commentary/SourceTree/Includes]. 
     53== `utils/`, `libffi/` == 
     55The `utils` directory contains support utilities that GHC uses.  Some of these are themselves separate repositories that `darcs-all` pulls; others are part of the main GHC repository.  
     57These utils may be built with the bootstrapping compiler, for use during the build, or with the stage2 compiler, for installing. Some of them are built with both; we can't install the utils built with the bootstrapping compiler as they may use different versions of C libraries. The reason we use stage2 rather than stage1 is that some utils, e.g. haddock, need the GHC API package.  The file `utils/Makefile` controls all this. 
     59''Why isn't libffi in utils/?'' 
     61== `testsuite/`, `nofib/` ==  
     63The `testsuite/` and `nofib/` directories contain apparatus for testing GHC.  Each is a separate repository, which can be gotten with `darcs-all`. 
     65== `mk/` == 
     67The `mk/` directory contains all the build system Makefile boilerplate.  Some particular files are interesting: 
     68  * '''`mk/`''': contains Makefile settings that control your build. Details [wiki:Building/Hacking here].  The file `mk/` contains a starting point that you can copy to `mk/` if you want. 
     69  * '''`mk/`''': this file records the fact that you are doing [wiki:TestingPatches validation], by containing the single line `Validating=YES`.  That in turn means the the build system gets its settings from `mk/` instead of from `mk/`.  Remove the file to stop validating. 
     71== `distrib/` ==  
     73Micellaneous files for building distributions. 
     75== Stuff that appears only in a build tree == 
     77    * '''`ghc/stage1-inplace/`, `ghc/stage2-inplace/`''' 
     78      The in-place installations of GHC, so you can use the compiler in a build tree. 
     80    * '''`compiler/stage1/`, `ghc/stage2plus/`''' 
     81      These directories contain `ghc_boot_platform.h`, which contains various `#define`s needed when building GHC. These are different depending on whether we are building stage1 or a later stage. 
     83    * '''`.../dist*/`''' 
     84      In many directories, `dist*` subdirectories appear. These are where Cabal puts all of the files generated while building.