X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;f=docs%2Fbuilding%2Fbuilding.xml;h=d0db332513abc11c8891073227db712d401f666c;hb=c838103b0636d8209d9d910db0a0328ee1682a39;hp=ca88a206687f15587d76e2e8dfa7c08ca1b65ef6;hpb=b52f24c24d808466ad440fd5132ac1c7203aaf2b;p=ghc-hetmet.git diff --git a/docs/building/building.xml b/docs/building/building.xml index ca88a20..d0db332 100644 --- a/docs/building/building.xml +++ b/docs/building/building.xml @@ -158,15 +158,22 @@ 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 . - - Which version of GHC you need will depend on the - packages you intend to build. GHC itself will normally - build using one of several older versions of itself - check - the announcement or release notes for details. + 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 . + + GHC can be built using either an earlier released + version of GHC (currently 5.04 and later are supported), or + bootstrapped using a GHC built from exactly the same + sources. Note that this means you cannot in general build + GHC using an arbitrary development snapshot, or a build from + say last week. It might work, it might not - we don't + guarantee anything. To be on the safe side, start your + build using the most recently released stable version of + GHC. @@ -222,10 +229,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 +252,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 +317,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 +358,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 +401,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 +420,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 +470,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 +507,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 - $(FPTOOLS_TOP)FPTOOLS_TOP. + must be (a linked copy of) the root directory of the GHC source + tree.. Inside Makefiles, the root of your build tree is called + $(GHC_TOP)GHC_TOP. In the rest of this document path names are relative to - $(FPTOOLS_TOP) unless + $(GHC_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 + $(GHC_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 +532,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 @@ -604,25 +550,26 @@ $ make install rather than darcs sources, you can skip this step. Change directory to - $(FPTOOLS_TOP) and + $(GHC_TOP) and issue the command $ autoreconf autoreconf (with no arguments). This GNU program (recursively) converts - $(FPTOOLS_TOP)/configure.ac and - $(FPTOOLS_TOP)/aclocal.m4 + $(GHC_TOP)/configure.ac and + $(GHC_TOP)/aclocal.m4 to a shell script called - $(FPTOOLS_TOP)/configure. + $(GHC_TOP)/configure. If autoreconf bleats that it can't write the file configure, then delete the latter and try again. Note that you must use autoreconf, and not the old autoconf! If you erroneously use the latter, you'll get 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). + $(GHC_TOP). These steps are completely platform-independent; they just mean that the human-written files (configure.ac and @@ -712,7 +659,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 +687,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 +724,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 +739,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: + +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: - 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 -O0 -GhcHcOpts=-DDEBUG -Rghc-timing + 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 @@ -828,13 +789,12 @@ $ make install You can also use build.mk to override anything that configure got wrong. One place where this happens often is with the definition of - FPTOOLS_TOP_ABS: this + GHC_TOP_ABS: this variable is supposed to be the canonical path to the top of your source tree, but if your system uses an automounter then the 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 +807,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 +829,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 +859,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 +866,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 +879,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 (eg. FreeBSD) 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 +912,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: @@ -1007,6 +965,23 @@ $ mkshadowdir . /scratch/joe-bloggs/myfptools-sun4 n is the stage to install. + + + binary-dist + + make a binary distribution. This is the target we + use to build the binary distributions of GHC. + + + + + dist + + make a source distribution. Note that this target + does “make distclean” as part of its work; + don't use it if you want to keep what you've built. + + The top-level Makefile also arranges @@ -1015,14 +990,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,22 +1012,21 @@ $ 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. Invoking the boot target explicitly is not normally necessary. From the top-level - fptools directory, invoking - gmake causes gmake boot - all to be invoked in each of the project - subdirectories, in the order specified by - $(AllTargets) in - config.mk. + directory, invoking make causes + make boot to be invoked in various + subdirectories first, in the right order. Unless you + really know what you are doing, it is best to always say + make from the top level first. 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 +1038,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. @@ -1096,7 +1070,7 @@ $ mkshadowdir . /scratch/joe-bloggs/myfptools-sun4 uninstall reverses the effect of - install. + install (WARNING: probably doesn't work). @@ -1106,7 +1080,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. @@ -1152,13 +1126,10 @@ $ mkshadowdir . /scratch/joe-bloggs/myfptools-sun4 anything that needs to exist in order to run configure and then begin to build the program. - - - - check - - run the test suite. + After a maintainer-clean, a + configure will be necessary before + building again. @@ -1168,16 +1139,6 @@ $ mkshadowdir . /scratch/joe-bloggs/myfptools-sun4 - configure - - is only available in the root directory - $(FPTOOLS_TOP); it has - been discussed in . - - - - depend make a .depend file in each @@ -1198,49 +1159,29 @@ $ mkshadowdir . /scratch/joe-bloggs/myfptools-sun4 file is automatically included by every Makefile. - - - binary-dist - - make a binary distribution. This is the target we - use to build the binary distributions of GHC and - Happy. - - - - - dist - - make a source distribution. Note that this target - does “make distclean” as part of its work; - don't use it if you want to keep what you've built. - - - Most Makefiles have targets other + Some Makefiles have targets other than these. You can discover them by looking in the Makefile itself. - Using a project from the build tree + Using GHC from the build tree - 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. + If you want to build GHC and just use it direct from the + build tree without doing make install first, + you can run the in-place driver script. To run the stage 1 + compiler, use compiler/stage1/ghc-inplace, + stage 2 is compiler/stage2/ghc-inplace, and + so on. Do NOT use - ghc/compiler/ghc, or - ghc/compiler/ghc-6.xx, as these are the + compiler/stage1/ghc, or + compiler/stage1/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. - - Happy can similarly be run from the build tree, using - happy/src/happy-inplace, and similarly for - Alex and Haddock. @@ -1256,7 +1197,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 +1219,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 @@ -1310,27 +1251,23 @@ $ mkshadowdir . /scratch/joe-bloggs/myfptools-sun4 - A small project + A small example To get started, let us look at the - Makefile for an imaginary small - fptools project, small. - Each project in fptools has its own directory - in FPTOOLS_TOP, so the - small project will have its own directory - FPOOLS_TOP/small/. Inside the - small/ directory there will be a + Makefile for an imaginary small program, + small. Each program or library in the GHC + source tree typically has its own directory, in this case we'll + use $(GHC_TOP)/small. + Inside the small/ directory there will be a Makefile, looking something like this: Makefile, minimal -# Makefile for fptools project "small" - +# Makefile for program "small" TOP = .. include $(TOP)/mk/boilerplate.mk -SRCS = $(wildcard *.lhs) $(wildcard *.c) HS_PROG = small include $(TOP)/target.mk @@ -1350,9 +1287,8 @@ directive. - a file of “boilerplate” code from the level - above (which in this case will be - FPTOOLS_TOP/mk/boilerplate.mkboilerplate.mk). + a file of “boilerplate” code from the top level + boilerplate.mk). As its name suggests, boilerplate.mk consists of a large quantity of standard Makefile code. We discuss this @@ -1364,19 +1300,19 @@ directive. Before the include statement, you must define the make variable TOPTOP - to be the directory containing the mk + to be the top-level directory of the source tree, containing + the mk directory in which the boilerplate.mk file is. It is not OK to simply say include ../mk/boilerplate.mk # NO NO NO - Why? Because the boilerplate.mk file needs to know where it is, so that it can, in turn, 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 @@ -1385,47 +1321,23 @@ directive. refers to itself. It is up to the Makefile doing the include to ensure this is the case. - - Files intended for inclusion in other - Makefiles are written to have the - following property: after - foo.mk is included, - it leaves TOP containing the same value - as it had just before the include - statement. In our example, this invariant - guarantees that the include for - target.mk will look in the same - directory as that for boilerplate.mk. - The second section defines the following standard - make variables: - SRCSSRCS - (the source files from which is to be built), and + The second section defines the standard + make variable HS_PROGHS_PROG (the executable binary to be built). We will discuss in more detail what the “standard variables” are, and how they affect what happens, in . - - The definition for SRCS uses the - useful GNU make construct - $(wildcard $pat$)wildcard, - which expands to a list of all the files matching the - pattern pat in the current directory. In - this example, SRCS is set to the list - of all the .lhs and - .c files in the directory. (Let's - suppose there is one of each, Foo.lhs - and Baz.c.) 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,19 +1359,27 @@ 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 - files are Foo.o and - Baz.o. + make looks in the current directory + to see what source files it can find + (eg. Foo.hs, + Baz.c), and from that it figures out + what object files need to be built + (eg. Foo.o, + Baz.o). Because source files are found + and used automatically, omitting them from a program or + library has to be done manually (see + EXCLUDED_SRCS in ). It uses a boilerplate pattern rule to compile - Foo.lhs to Foo.o + Foo.hs to Foo.o using a Haskell compiler. (Which one? That is set in the build configuration.) @@ -1476,7 +1396,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.) @@ -1487,90 +1407,6 @@ directive. three-section format. - - A larger project - - Larger projects are usually structured into a number of - sub-directories, each of which has its own - Makefile. (In very large projects, this - sub-structure might be iterated recursively, though that is - rare.) To give you the idea, here's part of the directory - structure for the (rather large) GHC project: - -$(FPTOOLS_TOP)/ghc/ - Makefile - mk/ - boilerplate.mk - rules.mk - docs/ - Makefile - ...source files for documentation... - driver/ - Makefile - ...source files for driver... - compiler/ - Makefile - parser/...source files for parser... - renamer/...source files for renamer... - ...etc... - - The sub-directories docs, - driver, compiler, and - so on, each contains a sub-component of GHC, and each has its - own Makefile. There must also be a - Makefile in - $(FPTOOLS_TOP)/ghc. - It does most of its work by recursively invoking - gmake on the Makefiles - in the sub-directories. We say that - ghc/Makefile is a non-leaf - Makefile, because it does little - except organise its children, while the - Makefiles in the sub-directories are all - leaf Makefiles. (In - principle the sub-directories might themselves contain a - non-leaf Makefile and several - sub-sub-directories, but that does not happen in GHC.) - - The Makefile in - ghc/compiler is considered a leaf - Makefile even though the - ghc/compiler has sub-directories, because - these sub-directories do not themselves have - Makefiles in them. They are just used to - structure the collection of modules that make up GHC, but all - are managed by the single Makefile in - ghc/compiler. - - You will notice that ghc/ also - contains a directory ghc/mk/. It contains - GHC-specific Makefile boilerplate code. - More precisely: - - - - ghc/mk/boilerplate.mk is included - at the top of ghc/Makefile, and of all - the leaf Makefiles in the - sub-directories. It in turn includes the - main boilerplate file - mk/boilerplate.mk. - - - - ghc/mk/target.mk is - included at the bottom of - ghc/Makefile, and of all the leaf - Makefiles in the sub-directories. It - in turn includes the file - mk/target.mk. - - - - So these two files are the place to look for GHC-wide - customisation of the standard boilerplate. - - Boilerplate architecture boilerplate architecture @@ -1603,7 +1439,7 @@ directive. Standard pattern rules that - tell gmake how to construct one file + tell make how to construct one file from another. @@ -1613,7 +1449,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 +1482,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 +1496,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 @@ -1689,11 +1525,11 @@ directive. - The main <filename>mk/boilerplate.mk</filename> file + The <filename>mk/boilerplate.mk</filename> file boilerplate.mk If you look at - $(FPTOOLS_TOP)/mk/boilerplate.mk + $(GHC_TOP)/mk/boilerplate.mk you will find that it consists of the following sections, each held in a separate file: @@ -2083,7 +1919,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_HC_OPTS="-v" @@ -2159,34 +1995,9 @@ directive. $(libdir). - - - LIB_DATALIB_DATA - - … - - - - - LIB_EXECLIB_EXEC - - … - - - - - HS_SRCSHS_SRCS, C_SRCSC_SRCS. - - If HS_SRCS is defined - and non-empty, a rule for the target - depend is included, which generates - dependency information for Haskell programs. Similarly - for C_SRCS. - - - All of these rules are “double-colon” rules, + Some rules are “double-colon” rules, thus install :: $(HS_PROG) @@ -2198,7 +2009,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 +2039,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 +2085,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 +2134,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 @@ -2373,8 +2184,7 @@ directive. Tools for building the Documentation The following additional tools are required if you want to - format the documentation that comes with the - fptools projects: + format the documentation that comes with GHC: @@ -2407,11 +2217,9 @@ directive. Haddock is a Haskell documentation tool that we use for automatically generating documentation from the - library source code. It is an fptools - project in itself. To build documentation for the - libraries (fptools/libraries) you - should check out and build Haddock in - fptools/haddock. Haddock requires GHC + library source code. To build documentation for the + libraries ($(GHC_TOP)/libraries) you + should build and install Haddock. Haddock requires GHC to build. @@ -2548,24 +2356,25 @@ $ make install Porting GHC This section describes how to port GHC to a currenly - unsupported platform. There are two distinct - possibilities: + unsupported platform. To avoid confusion, when we say + “architecture” we are referring to the processor, and + we use the term “platform” to refer to the combination + of architecture and operating system. + + There are two distinct porting scenarios: - The hardware architecture for your system is already - supported by GHC, but you're running an OS that isn't - supported (or perhaps has been supported in the past, but - currently isn't). This is the easiest type of porting job, - but it still requires some careful bootstrapping. Proceed to - . + Your platform is already supported, but you want to + compile up GHC using just a C compiler. This is a + straightforward bootstrap from HC files, and is described in + . - Your system's hardware architecture isn't supported by - GHC. This will be a more difficult port (though by comparison - perhaps not as difficult as porting gcc). Proceed to . + Your platform isn't supported by GHC. You will need to + do an unregisterised bootstrap, proceed + to . @@ -2586,25 +2395,40 @@ $ make install later. HC files are platform-dependent, so you have to get a set - that were generated on the same platform. There - may be some supplied on the GHC download page, otherwise you'll have to - compile some up yourself, or start from - unregisterised HC files - see . + that were generated on the same platform. + There may be some supplied on the GHC download page, otherwise + you'll have to compile some up yourself. The following steps should result in a working GHC build with full libraries: - Unpack the HC files on top of a fresh source tree - (make sure the source tree version matches the version of - the HC files exactly!). This will - place matching .hc files next to the - corresponding Haskell source (.hs or - .lhs) in the compiler subdirectory - ghc/compiler and in the libraries - (subdirectories of + Make a set of HC files. On an identical system with + GHC already installed, get a GHC source tree and put the + following in mk/build.mk: + + +SRC_HC_OPTS = -H32m -O -fasm -Rghc-timing -keep-hc-files +GhcLibHcOpts = -O +GhcLibWays = +SplitObjs = NO + + + Build GHC as normal, and then make + hc-file-bundle Project=ghc to creates the tar file + containing the hc files. + + + + On the target system, unpack the HC files on top of a + fresh source tree (make sure the source tree version matches + the version of the HC files exactly!). + This will place matching .hc files next + to the corresponding Haskell source + (.hs or .lhs) in + the compiler subdirectory ghc/compiler + and in the libraries (subdirectories of libraries). @@ -2636,10 +2460,10 @@ $ make install - Porting GHC to a new architecture + Porting GHC to a new platform - The first step in porting to a new architecture is to get - an unregisterised build working. An + The first step in porting to a new platform is to get an + unregisterised build working. An unregisterised build is one that compiles via vanilla C only. By contrast, a registerised build uses the following architecture-specific hacks for speed: @@ -2670,6 +2494,13 @@ $ make install since unregisterised compilation is usually just a step on the way to a full registerised port, we don't mind too much. + You should go through this process even if your + architecture is already has registerised support in GHC, but + your OS currently isn't supported. In this case you probably + won't need to port any of the architecture-specific parts of the + code, and you can proceed straight from the unregisterised build + to build a registerised compiler. + Notes on GHC portability in general: we've tried to stick to writing portable code in most parts of the system, so it should compile on any POSIXish system with gcc, but in our @@ -2726,7 +2557,7 @@ $ ./configure --enable-hc-boot --enable-hc-boot-unregisterised You might need to update configure.in to recognise the new - architecture, and re-generate + platform, and re-generate configure with autoreconf. @@ -2777,7 +2608,8 @@ GhcBootLibs = YES change TARGETPLATFORM appropriately, and set the variables involving - TARGET to the correct values for + TARGET or + Target to the correct values for the target platform. This step is necessary because currently configure doesn't cope with specifying different values for the @@ -2839,12 +2671,11 @@ $ make boot stage=2 && make stage=2 -$ cd H/ghc/lib/compat +$ cd H/compat $ make clean $ rm .depend -$ make boot UseStage1=YES -$ make -k UseStage1=YES EXTRA_HC_OPTS='-O -fvia-C -keep-hc-files' -$ cd H/ghc/utils +$ make boot UseStage1=YES EXTRA_HC_OPTS='-O -fvia-C -keep-hc-files' +$ cd H/utils $ make clean $ make -k UseStage1=YES EXTRA_HC_OPTS='-O -fvia-C -keep-hc-files' @@ -3048,15 +2879,15 @@ Hello World! GHCi To support GHCi, you need to port the dynamic linker - (fptools/ghc/rts/Linker.c). The linker - currently supports the ELF and PEi386 object file formats - if - your platform uses one of these then things will be - significantly easier. The majority of Unix platforms use the - ELF format these days. Even so, there are some + ($(GHC_TOP)/rts/Linker.c). The + linker currently supports the ELF and PEi386 object file + formats - if your platform uses one of these then things will + be significantly easier. The majority of Unix platforms use + the ELF format these days. Even so, there are some machine-specific parts of the ELF linker: for example, the code for resolving particular relocation types is machine-specific, so some porting of this code to your - architecture will probaly be necessary. + architecture and/or OS will probaly be necessary. If your system uses a different object file format, then you have to write a linker — good luck! @@ -3096,9 +2927,8 @@ The best way around it is to say export TMPDIR=<dir> -in your build.mk file. -Then GHC and the other fptools programs will use the appropriate directory -in all cases. +in your build.mk file. Then GHC and the other +tools will use the appropriate directory in all cases. @@ -3168,7 +2998,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: @@ -3764,7 +3594,7 @@ you do that, ssh uses the $HOME environment variable instead. You have to install the following other things to build GHC, listed below. On Windows you often install executables in directories with spaces, such as -"Program Files". However, the make system for fptools doesn't +"Program Files". However, the make system doesn't deal with this situation (it'd have to do more quoting of binaries), so you are strongly advised to put binaries for all tools in places with no spaces in their path. On both MSYS and Cygwin, it's perfectly OK to install such programs in the standard Unixy places, @@ -3829,10 +3659,10 @@ but you must have them; hence needing the Cygwin binutils package. We use emacs a lot, so we install that too. -When you are in fptools/ghc/compiler, you can use +When you are in $(GHC_TOP)/compiler, you can use "make tags" to make a TAGS file for emacs. That uses the utility -fptools/ghc/utils/hasktags/hasktags, so you need to make that first. -The most convenient way to do this is by going make boot in fptools/ghc. +$(GHC_TOP)/ghc/utils/hasktags/hasktags, so you need to make that first. +The most convenient way to do this is by going make boot in $(GHC_TOP)/ghc. The make tags command also uses etags, which comes with emacs, so you will need to add emacs/bin to your PATH. @@ -3884,7 +3714,7 @@ Solution: delete configure first. After autoreconf run ./configure in - fptools/ thus: + $(GHC_TOP)/ thus: $ ./configure --host=i386-unknown-mingw32 --with-gcc=c:/mingw/bin/gcc This is the point at which you specify that you are building GHC-mingw @@ -3902,7 +3732,7 @@ say --with-gcc=/mingw/bin/gcc, it'll be interpreted as time it tries to invoke it. Worse, the failure comes with no error message whatsoever. GHC simply fails silently when first invoked, typically leaving you with this: -make[4]: Leaving directory `/cygdrive/e/fptools-stage1/ghc/rts/gmp' +make[4]: Leaving directory `/cygdrive/e/ghc-stage1/ghc/rts/gmp' ../../ghc/compiler/ghc-inplace -optc-mno-cygwin -optc-O -optc-Wall -optc-W -optc-Wstrict-prototypes -optc-Wmissing-prototypes -optc-Wmissing-declarations -optc-Winline -optc-Waggregate-return @@ -3912,7 +3742,7 @@ typically leaving you with this: -package-name rts -O -dcore-lint -c Adjustor.c -o Adjustor.o make[2]: *** [Adjustor.o] Error 1 make[1]: *** [all] Error 1 -make[1]: Leaving directory `/cygdrive/e/fptools-stage1/ghc' +make[1]: Leaving directory `/cygdrive/e/ghc-stage1/ghc' make: *** [all] Error 1 Be warned! @@ -3991,7 +3821,7 @@ choices, but it gives a single path that works. ; also, subscribe to cvs-all@haskell.org, or follow the mailing list ; archive, in case you checkout a version with problems ; http://www.haskell.org//pipermail/cvs-all/ - - mkdir c:/fptools; cd c:/fptools + - mkdir c:/ghc-build; cd c:/ghc-build ; (or whereever you want your darcs tree to be) - darcs get http://darcs.haskell.org/ghc - cd ghc @@ -4003,7 +3833,7 @@ choices, but it gives a single path that works. ; for haddock, alex, happy (*) - export PATH=/cygdrive/c/mingw/bin:$PATH ; without, we pick up some cygwin tools at best! - - cd c:/fptools/fptools + - cd c:/ghc-build ; (if you aren't there already) - autoreconf - ./configure --host=i386-unknown-mingw32 --with-gcc=C:/Mingw/bin/gcc.exe