[partial update for new source tree layout Simon Marlow **20060505030218] { hunk ./docs/building/building.xml 161 - GHC is required to build many of the tools, including - GHC itself. If you need to port GHC to your platform - because there isn't a binary distribution of GHC available, - then see . + GHC is required to build GHC, because GHC itself is + written in Haskell, and uses GHC extensions. It is possible + to build GHC using just a C compiler, and indeed some + distributions of GHC do just that, but it isn't the best + supported method, and you may encounter difficulties. Full + instructions are in . hunk ./docs/building/building.xml 227 - The fptools build system makes heavy use of features + The GHC build system makes heavy use of features hunk ./docs/building/building.xml 229 - this installed in order to build any of the fptools - suite. + this installed in order to build GHC. hunk ./docs/building/building.xml 250 - Happy version 1.15 is currently required to build GHC. - - Happy is written in - Haskell, and is a project in the CVS repository - (fptools/happy). It can be built from - source, but bear in mind that you'll need GHC installed in - order to build it. To avoid the chicken/egg problem, - install a binary distribution of either Happy or GHC to get - started. Happy distributions are available from Happy's Web - Page. + Happy version 1.15 is currently required to build GHC. + Grab a copy from Happy's Web + Page. hunk ./docs/building/building.xml 315 - One fptools project is worth a quick note - at this point, because it is useful for all the others: - glafp-utils contains several utilities which - aren't particularly Glasgow-ish, but Occasionally Indispensable. - Like lndir for creating symbolic link - trees. - hunk ./docs/building/building.xml 356 - hunk ./docs/building/building.xml 357 - - Other useful tools - - - - Flex - pre-supposed: flex - flex, pre-supposed - - - This is a quite-a-bit-better-than-Lex lexer. Used - to build a couple of utilities in - glafp-utils. Depending on your - operating system, the supplied lex may - or may not work; you should get the GNU version. - - - - - More tools are required if you want to format the documentation - that comes with GHC and other fptools projects. See More tools are required if you want to format the + documentation that comes with GHC. See ghc/HACKING from the GHC source tree. It describes + HACKING from the GHC source tree. It describes hunk ./docs/building/building.xml 418 - - Your source tree + + History hunk ./docs/building/building.xml 421 - The source code is held in your source - tree. The root directory of your source tree - must contain the following directories and - files: + First, a historical note. The GHC build system used to be + called "fptools": a generic build system used to build multiple + projects (GHC, Happy, GreenCard, H/Direct, etc.). It had a + concept of the generic project-independent parts, and + project-specific parts that resided in a project + subdirectory. hunk ./docs/building/building.xml 428 - - - Makefile: the root - Makefile. - + Nowadays, most of these other projects are using Cabal, or have faded + away, and GHC is the only regular user of the fptools build + system. We decided therefore to simplify the situation for + developers, and specialise the build system for GHC. This + resulted in a simpler organisation of the source tree and the + build system, which hopefully makes the whole thing easier to + understand. hunk ./docs/building/building.xml 437 - - mk/: the directory that contains - the main Makefile code, shared by all the - fptools software. - - - - configure.ac, - config.sub, - config.guess: these files support the - configuration process. - - - - install-sh. - - - - All the other directories are individual - projects of the fptools - system—for example, the Glasgow Haskell Compiler - (ghc), the Happy parser generator - (happy), the nofib - benchmark suite, and so on. You can have zero or more of these. - Needless to say, some of them are needed to build others. - - The important thing to remember is that even if you want - only one project (happy, say), you must have - a source tree whose root directory contains - Makefile, mk/, - configure.ac, and the project(s) you want - (happy/ in this case). You cannot get by - with just the happy/ directory. + You might find old comments that refer to "projects" or + "fptools" in the documentation and/or source; please let us know + if you do. hunk ./docs/building/building.xml 468 - fptools/glafp-utils/lndir). See utils/lndir). See fptools suite. Inside Makefiles, the root of - your build tree is called + must be (a linked copy of) the root directory of the GHC source + tree.. Inside Makefiles, the root of your build tree is called hunk ./docs/building/building.xml 511 - ghc/mk/target.mk is actually - $(FPTOOLS_TOP)/ghc/mk/target.mk. + mk/target.mk is actually + $(FPTOOLS_TOP)/mk/target.mk. hunk ./docs/building/building.xml 518 - When you build fptools you will be - compiling code on a particular host - platform, to run on a particular target - platform (usually the same as the host + When you build GHC you will be compiling code on a + particular host platform, to run on a + particular target platform (usually the + same as the host hunk ./docs/building/building.xml 530 - fptools software is built. For example, you - might want to build GHC optimised (so that it runs fast) or - unoptimised (so that you can compile it fast after you've - modified it. Or, you might want to compile it with debugging on - (so that extra consistency-checking code gets included) or off. - And so on. + software is built. For example, you might want to build GHC + optimised (so that it runs fast) or unoptimised (so that you can + compile it fast after you've modified it. Or, you might want to + compile it with debugging on (so that extra consistency-checking + code gets included) or off. And so on. hunk ./docs/building/building.xml 563 - Some projects, including GHC, have their own configure script. + Some parts of the source tree, particularly + libraries, have their own configure script. hunk ./docs/building/building.xml 657 - ghc. + ghc. (NOTE: I'm not sure it + actually works to specify a compiler other than GHC + here; unless you really know what you're doing I + suggest not using this option at all.) hunk ./docs/building/building.xml 685 - fptools is to differ from the standard + GHC is to differ from the standard hunk ./docs/building/building.xml 722 - For your convenience, there's a file called build.mk.sample - that can serve as a starting point for your build.mk. + For your convenience, there's a file called + build.mk.sample that can serve as a starting + point for your build.mk. hunk ./docs/building/building.xml 729 -GhcHcOpts=-O -Rghc-timing +GhcHcOpts=-Rghc-timing hunk ./docs/building/building.xml 737 - or, if you prefer, - hunk ./docs/building/building.xml 741 - operator, which is quite a convenient feature.) + operator, which is quite a convenient feature. hunk ./docs/building/building.xml 743 - If you want to remove the -O as well (a - good idea when developing, because the turn-around cycle gets a - lot quicker), you can just override - GhcLibHcOpts altogether: + Haskell compilations by default have -O + turned on, by virtue of this setting from + config.mk: hunk ./docs/building/building.xml 747 -GhcHcOpts=-DDEBUG -Rghc-timing +SRC_HC_OPTS += -H16m -O hunk ./docs/building/building.xml 749 + SRC_HC_OPTS means "options for HC from + the source tree", where HC stands for Haskell Compiler. + SRC_HC_OPTS are added to every Haskell + compilation. To turn off optimisation, you could add this to + build.mk: + +SRC_HC_OPTS = -H16m -O0 + + Or you could just add -O0 to + GhcHcOpts to turn off optimisation for the + compiler. See for some more + suggestions. + hunk ./docs/building/building.xml 793 - hunk ./docs/building/building.xml 805 - myfptools (it does not have to be - called fptools). Make sure that you - have the essential files (see ). + myghc (it does not have to be + called ghc). hunk ./docs/building/building.xml 810 - hunk ./docs/building/building.xml 813 -$ cd myfptools -$ mkshadowdir . /scratch/joe-bloggs/myfptools-sun4 +$ cd myghc +$ mkshadowdir . /scratch/joe-bloggs/myghc-x86 hunk ./docs/building/building.xml 827 -$ cd /scratch/joe-bloggs/myfptools-sun4 +$ cd /scratch/joe-bloggs/myghc-x86 hunk ./docs/building/building.xml 857 - -$ emacs mk/build.mk hunk ./docs/building/building.xml 864 - gmake clean, gmake all, - because configuration option changes could affect - anything—but in practice you are likely to know what's - affected. + make clean; make, because configuration + option changes could affect anything—but in practice you + are likely to know what's affected. hunk ./docs/building/building.xml 877 - must use GNU make, usually called - gmake, not standard Unix - make. If you use standard Unix - make you will get all sorts of error messages - (but no damage) because the fptools + must use GNU make. On some + systems this is called gmake, whereas on + others it is the standard make command. In + this document we will always refer to it as + make; please substitute with + gmake if your system requires it. If you use + a the wrong make you will get all sorts of + error messages (but no damage) because the GHC hunk ./docs/building/building.xml 889 - the top of your fptools tree and type - gmake. This will prepare the tree and build - the various projects in the correct order. + the top of your build tree and type make. + This will prepare the tree and build the various parts in the + correct order, resulting in a complete build of GHC that can + even be used directly from the tree, without being installed + first. hunk ./docs/building/building.xml 910 - by the top-level fptools Makefile, so if - you want everything to work automatically it's best to start - make from the top of the tree. When building - GHC, the top-level fptools Makefile is set - up to do a 2-stage bootstrap by default (when you say - make). Some other targets it supports - are: + by the top-level Makefile, so if you want + everything to work automatically it's best to start + make from the top of the tree. The top-level + Makefile is set up to do a 2-stage + bootstrap by default (when you say make). + Some other targets it supports are: hunk ./docs/building/building.xml 971 - ghc/compiler directory, but don't forget that + compiler directory, but don't forget that hunk ./docs/building/building.xml 978 - ghc/compiler. + compiler. hunk ./docs/building/building.xml 993 - for the real work. Notably, it does gmake + for the real work. Notably, it does make hunk ./docs/building/building.xml 1001 - gmake causes gmake boot + make causes make boot hunk ./docs/building/building.xml 1008 - need to update the dependencies, gmake + need to update the dependencies, make hunk ./docs/building/building.xml 1020 - gmake alone is generally the same as - typing gmake all. + make alone is generally the same as + typing make all. hunk ./docs/building/building.xml 1062 - generated by gmake boot. Also preserve + generated by make boot. Also preserve hunk ./docs/building/building.xml 1185 - ghc/compiler/ghc-inplace. + compiler/ghc-inplace. hunk ./docs/building/building.xml 1188 - ghc/compiler/ghc, or - ghc/compiler/ghc-6.xx, as these are the + compiler/ghc, or + compiler/ghc-6.xx, as these are the hunk ./docs/building/building.xml 1212 -$ gmake FAST=YES +$ make FAST=YES hunk ./docs/building/building.xml 1234 - works—you type gmake install and lo! the + works—you type make install and lo! the hunk ./docs/building/building.xml 1332 - to the directory in which gmake is being + to the directory in which make is being hunk ./docs/building/building.xml 1381 - It contains the rules that tell gmake how + It contains the rules that tell make how hunk ./docs/building/building.xml 1403 - you say gmake all, the following things + you say make all, the following things hunk ./docs/building/building.xml 1408 - gmake figures out that the object + make figures out that the object hunk ./docs/building/building.xml 1432 - gmake know to use the Haskell compiler to + make know to use the Haskell compiler to hunk ./docs/building/building.xml 1477 - gmake on the Makefiles + make on the Makefiles hunk ./docs/building/building.xml 1559 - tell gmake how to construct one file + tell make how to construct one file hunk ./docs/building/building.xml 1569 - Makefile. gmake + Makefile. make hunk ./docs/building/building.xml 1602 - gmake commits target and + make commits target and hunk ./docs/building/building.xml 1616 - gmake encountered the rule. Alas, - gmake takes a snapshot of their + make encountered the rule. Alas, + make takes a snapshot of their hunk ./docs/building/building.xml 2039 -$ gmake libHS.a EXTRA_CC_OPTS="-v" +$ make libHS.a EXTRA_CC_OPTS="-v" hunk ./docs/building/building.xml 2154 - install. When you type gmake + install. When you type make hunk ./docs/building/building.xml 2184 - be important. For example, when you say gmake + be important. For example, when you say make hunk ./docs/building/building.xml 2230 - command line of gmake (usually in - a recursive invocation of gmake by the + command line of make (usually in + a recursive invocation of make by the hunk ./docs/building/building.xml 2234 - any one invocation of gmake. Two other + any one invocation of make. Two other hunk ./docs/building/building.xml 2279 - variable. So if you say gmake + variable. So if you say make hunk ./docs/building/building.xml 2281 - invocation gmake Foo.mp_o way=mp, + invocation make Foo.mp_o way=mp, hunk ./docs/building/building.xml 3124 -and try again: gmake. (see for information about +and try again: make. (see for information about }