From 22501a5d518c093b1233af3e5c52503d5aa43281 Mon Sep 17 00:00:00 2001 From: Simon Marlow Date: Fri, 5 May 2006 03:02:18 +0000 Subject: [PATCH] partial update for new source tree layout --- docs/building/building.xml | 327 +++++++++++++++++++------------------------- 1 file changed, 140 insertions(+), 187 deletions(-) diff --git a/docs/building/building.xml b/docs/building/building.xml index 8a4ef35..18d3ff4 100644 --- a/docs/building/building.xml +++ b/docs/building/building.xml @@ -158,10 +158,12 @@ GHC, pre-supposed - 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 . Which version of GHC you need will depend on the packages you intend to build. GHC itself will normally @@ -222,10 +224,9 @@ makeGNU - The fptools build system makes heavy use of features + The GHC build system makes heavy use of features specific to GNU make, so you must have - this installed in order to build any of the fptools - suite. + this installed in order to build GHC. NB. it has been reported that version 3.79 no longer works to build GHC, and 3.80 is required. @@ -246,16 +247,10 @@ modify the compiler and/or you're using a darcs checkout, then you need Happy. - 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. @@ -317,13 +312,6 @@ - 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. - Tools for building parallel GHC (GPH) @@ -365,29 +353,9 @@ - - - - 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 . @@ -428,7 +396,7 @@ $ make install Quick start for GHC developers This section is a copy of the file - ghc/HACKING from the GHC source tree. It describes + HACKING from the GHC source tree. It describes how to get started with setting up your build tree for developing GHC or its libraries, and how to start building. @@ -447,53 +415,28 @@ $ make install software, and lay hands on them gently when they don't work. - - Your source tree - - The source code is held in your source - tree. The root directory of your source tree - must contain the following directories and - files: - - - - Makefile: the root - Makefile. - - - - 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. + + History + + 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. + + 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. + + You might find old comments that refer to "projects" or + "fptools" in the documentation and/or source; please let us know + if you do. @@ -522,7 +465,7 @@ $ make install are two (If you don't have either, the source distribution includes sources for the X11 lndir—check out - fptools/glafp-utils/lndir). See utils/lndir). See for a typical invocation. The build tree does not need to be anywhere near the @@ -559,24 +502,23 @@ $ make install source file.) Like the source tree, the top level of your build tree - must be (a linked copy of) the root directory of the - 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 $(FPTOOLS_TOP)FPTOOLS_TOP. In the rest of this document path names are relative to $(FPTOOLS_TOP) unless otherwise stated. For example, the file - ghc/mk/target.mk is actually - $(FPTOOLS_TOP)/ghc/mk/target.mk. + mk/target.mk is actually + $(FPTOOLS_TOP)/mk/target.mk. Getting the build you want - 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 platform)platform. The difficulty is that there are minor differences between different platforms; minor, but enough that the code needs to be @@ -585,12 +527,11 @@ $ make install different native-code generator. There are also knobs you can turn to control how the - 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. All of this stuff is called the configuration of your build. You set the @@ -619,7 +560,8 @@ $ make install a message like "No rule to make target 'mk/config.h.in'". - Some projects, including GHC, have their own configure script. + Some parts of the source tree, particularly + libraries, have their own configure script. autoreconf takes care of that, too, so all you have to do is calling autoreconf in the top-level directory $(FPTOOLS_TOP). @@ -712,7 +654,10 @@ $ make install Specifies the path to any installed Haskell compiler. This compiler will be used for compiling generic Haskell code. The default is to use - 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.) @@ -737,7 +682,7 @@ $ make install Step 3: build configuration. Next, you say how this build of - fptools is to differ from the standard + GHC is to differ from the standard defaults by creating a new file mk/build.mkbuild.mk in the build tree. This file is the @@ -774,13 +719,14 @@ $ make install includes build.mk after config.mk.) - 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. For example, config.mk.in contains the definition: -GhcHcOpts=-O -Rghc-timing +GhcHcOpts=-Rghc-timing The accompanying comment explains that this is the list of flags passed to GHC when building GHC itself. For doing @@ -788,20 +734,30 @@ $ make install enable debugging code. So you would add the following to build.mk: - or, if you prefer, - GhcHcOpts += -DDEBUG GNU make allows existing definitions to have new text appended using the “+=” - operator, which is quite a convenient feature.) + operator, which is quite a convenient feature. + + Haskell compilations by default have -O + turned on, by virtue of this setting from + config.mk: - 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: +SRC_HC_OPTS += -H16m -O + + 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: -GhcHcOpts=-DDEBUG -Rghc-timing +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. When reading config.mk.in, remember that anything between “@...@” signs is going to be substituted @@ -834,7 +790,6 @@ $ make install correct directory is hard to find automatically. If you find that configure has got it wrong, just put the correct definition in build.mk. - @@ -847,19 +802,16 @@ $ make install Get your source tree from somewhere (darcs repository or source distribution). Say you call the root directory - 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). - (Optional) Use lndir or mkshadowdir to create a build tree. -$ cd myfptools -$ mkshadowdir . /scratch/joe-bloggs/myfptools-sun4 +$ cd myghc +$ mkshadowdir . /scratch/joe-bloggs/myghc-x86 (N.B. mkshadowdir's first argument is taken relative to its second.) You probably want to give @@ -872,7 +824,7 @@ $ mkshadowdir . /scratch/joe-bloggs/myfptools-sun4 Change directory to the build tree. Everything is going to happen there now. -$ cd /scratch/joe-bloggs/myfptools-sun4 +$ cd /scratch/joe-bloggs/myghc-x86 @@ -902,8 +854,6 @@ $ mkshadowdir . /scratch/joe-bloggs/myfptools-sun4 Create the file mk/build.mk, adding definitions for your desired configuration options. - -$ emacs mk/build.mk @@ -911,10 +861,9 @@ $ mkshadowdir . /scratch/joe-bloggs/myfptools-sun4 mk/build.mk as often as you like. You do not have to run any further configuration programs to make these changes take effect. In theory you should, however, say - 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. @@ -925,18 +874,23 @@ $ mkshadowdir . /scratch/joe-bloggs/myfptools-sun4 things. The first thing you need to know is that you - 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 Makefiles use GNU make's facilities extensively. To just build the whole thing, cd to - 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. @@ -953,13 +907,12 @@ $ mkshadowdir . /scratch/joe-bloggs/myfptools-sun4 Note that when doing a bootstrap, the stage 1 compiler must be built, followed by the runtime system and libraries, and then the stage 2 compiler. The correct ordering is implemented - 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: @@ -1015,14 +968,14 @@ $ mkshadowdir . /scratch/joe-bloggs/myfptools-sun4 The stage1, stage2 and stage3 targets also work in the - ghc/compiler directory, but don't forget that + compiler directory, but don't forget that each stage requires its own make boot step: for example, you must do $ make boot stage=2 before make stage2 in - ghc/compiler. + compiler. @@ -1037,7 +990,7 @@ $ mkshadowdir . /scratch/joe-bloggs/myfptools-sun4 boot does the one-off preparation required to get ready - for the real work. Notably, it does gmake + for the real work. Notably, it does make depend in all directories that contain programs. It also builds the necessary tools for compilation to proceed. @@ -1045,14 +998,14 @@ $ mkshadowdir . /scratch/joe-bloggs/myfptools-sun4 Invoking the boot target explicitly is not normally necessary. From the top-level fptools directory, invoking - gmake causes gmake boot + make causes make boot all to be invoked in each of the project subdirectories, in the order specified by $(AllTargets) in config.mk. If you're working in a subdirectory somewhere and - need to update the dependencies, gmake + need to update the dependencies, make boot is a good way to do it. @@ -1064,8 +1017,8 @@ $ mkshadowdir . /scratch/joe-bloggs/myfptools-sun4 Depending on which directory you are in a “final target” may be an executable program, a library archive, a shell script, or a Postscript file. Typing - gmake alone is generally the same as - typing gmake all. + make alone is generally the same as + typing make all. @@ -1106,7 +1059,7 @@ $ mkshadowdir . /scratch/joe-bloggs/myfptools-sun4 Delete all files from the current directory that are normally created by building the program. Don't delete the files that record the configuration, or files - generated by gmake boot. Also preserve + generated by make boot. Also preserve files that could be made by building, but normally aren't because the distribution comes with them. @@ -1229,11 +1182,11 @@ $ mkshadowdir . /scratch/joe-bloggs/myfptools-sun4 If you want to build GHC (say) and just use it direct from the build tree without doing make install first, you can run the in-place driver script: - ghc/compiler/ghc-inplace. + compiler/ghc-inplace. Do NOT use - ghc/compiler/ghc, or - ghc/compiler/ghc-6.xx, as these are the + compiler/ghc, or + compiler/ghc-6.xx, as these are the scripts intended for installation, and contain hard-wired paths to the installed libraries, rather than the libraries in the build tree. @@ -1256,7 +1209,7 @@ $ mkshadowdir . /scratch/joe-bloggs/myfptools-sun4 make is going to rebuild everything anyway, the following hack may be useful: -$ gmake FAST=YES +$ make FAST=YES This tells the make system to ignore dependencies and just build what you tell it to. In other words, it's equivalent to @@ -1278,7 +1231,7 @@ $ mkshadowdir . /scratch/joe-bloggs/myfptools-sun4 makefile architecture make is great if everything - works—you type gmake install and lo! the + works—you type make install and lo! the right things get compiled and installed in the right places. Our goal is to make this happen often, but somehow it often doesn't; instead some weird error message eventually emerges from the @@ -1376,7 +1329,7 @@ directive. include other files. (Unfortunately, when an included file does an include, the filename is treated relative - to the directory in which gmake is being + to the directory in which make is being run, not the directory in which the included sits.) In general, every file foo.mk assumes @@ -1425,7 +1378,7 @@ directive. The last section includes a second file of standard code, called target.mktarget.mk. - It contains the rules that tell gmake how + It contains the rules that tell make how to make the standard targets (). Why, you ask, can't this standard code be part of @@ -1447,12 +1400,12 @@ directive. In our example Makefile, most of the work is done by the two included files. When - you say gmake all, the following things + you say make all, the following things happen: - gmake figures out that the object + make figures out that the object files are Foo.o and Baz.o. @@ -1476,7 +1429,7 @@ directive. compiler to do the link step. (Why not use ld? Because the Haskell compiler knows what standard libraries to link in. How did - gmake know to use the Haskell compiler to + make know to use the Haskell compiler to do the link, rather than the C compiler? Because we set the variable HS_PROG rather than C_PROG.) @@ -1521,7 +1474,7 @@ directive. Makefile in $(FPTOOLS_TOP)/ghc. It does most of its work by recursively invoking - gmake on the Makefiles + make on the Makefiles in the sub-directories. We say that ghc/Makefile is a non-leaf Makefile, because it does little @@ -1603,7 +1556,7 @@ directive. Standard pattern rules that - tell gmake how to construct one file + tell make how to construct one file from another. @@ -1613,7 +1566,7 @@ directive. of each Makefile, so that the user can replace the boilerplate definitions or pattern rules by simply giving a new definition or pattern rule in the - Makefile. gmake + Makefile. make simply takes the last definition as the definitive one. Instead of replacing boilerplate @@ -1646,7 +1599,7 @@ directive. - gmake commits target and + make commits target and dependency lists earlier than it should. For example, target.mk has a rule that looks like this: @@ -1660,8 +1613,8 @@ directive. and $(OBJS)OBJS would not have their final values at the moment - gmake encountered the rule. Alas, - gmake takes a snapshot of their + make encountered the rule. Alas, + make takes a snapshot of their current values, and wires that snapshot into the rule. (In contrast, the commands executed when the rule “fires” are only substituted at the moment @@ -2083,7 +2036,7 @@ directive. extra options to pass to all C compilations. This is intended for command line use, thus: -$ gmake libHS.a EXTRA_CC_OPTS="-v" +$ make libHS.a EXTRA_CC_OPTS="-v" @@ -2198,7 +2151,7 @@ directive. dependencies say to do so. This means that you can, for example, define both HS_PROG and LIBRARY, which will generate two rules for - install. When you type gmake + install. When you type make install both rules will be fired, and both the program and the library will be installed, just as you wanted. @@ -2228,7 +2181,7 @@ directive. These recursive invocations are guaranteed to occur in the order in which the list of directories is specified in SUBDIRS. This guarantee can - be important. For example, when you say gmake + be important. For example, when you say make boot it can be important that the recursive invocation of make boot is done in one sub-directory (the include files, say) before another (the source files). @@ -2274,11 +2227,11 @@ directive. A make variable called way holds the current way tag. way is only ever set on the - 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 system). It is never set inside a Makefile. So it is a global constant for - any one invocation of gmake. Two other + any one invocation of make. Two other make variables, way_ and _way are immediately derived from @@ -2323,9 +2276,9 @@ directive. Foo.mp_o) there is a rule which recursively invokes make to make the specified target, setting the way - variable. So if you say gmake + variable. So if you say make Foo.mp_o you should see a recursive - invocation gmake Foo.mp_o way=mp, + invocation make Foo.mp_o way=mp, and in this recursive invocation the pattern rule for compiling a Haskell file into a .o file will match. The key pattern rules (in @@ -3168,7 +3121,7 @@ above. -and try again: gmake. (see for information about +and try again: make. (see for information about <module>_HC_OPTS.) Alternatively, just cut to the chase: -- 1.7.10.4