From 666e12912f5306132faecfef3f18e7ba3181a312 Mon Sep 17 00:00:00 2001 From: Simon Marlow Date: Fri, 5 May 2006 10:58:43 +0000 Subject: [PATCH] update the build system documentation --- docs/building/building.xml | 281 +++++++++++--------------------------------- 1 file changed, 67 insertions(+), 214 deletions(-) diff --git a/docs/building/building.xml b/docs/building/building.xml index 18d3ff4..97b5a69 100644 --- a/docs/building/building.xml +++ b/docs/building/building.xml @@ -875,9 +875,9 @@ $ mkshadowdir . /scratch/joe-bloggs/myghc-x86 The first thing you need to know is that you 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 + 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 @@ -960,6 +960,23 @@ $ mkshadowdir . /scratch/joe-bloggs/myghc-x86 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 @@ -997,12 +1014,11 @@ $ mkshadowdir . /scratch/joe-bloggs/myghc-x86 Invoking the boot target explicitly is not normally necessary. From the top-level - fptools directory, invoking - make causes make 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, make @@ -1049,7 +1065,7 @@ $ mkshadowdir . /scratch/joe-bloggs/myghc-x86 uninstall reverses the effect of - install. + install (WARNING: probably doesn't work). @@ -1105,13 +1121,10 @@ $ mkshadowdir . /scratch/joe-bloggs/myghc-x86 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. @@ -1121,16 +1134,6 @@ $ mkshadowdir . /scratch/joe-bloggs/myghc-x86 - configure - - is only available in the root directory - $(FPTOOLS_TOP); it has - been discussed in . - - - - depend make a .depend file in each @@ -1151,49 +1154,29 @@ $ mkshadowdir . /scratch/joe-bloggs/myghc-x86 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: - 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 - compiler/ghc, or - 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. @@ -1263,27 +1246,23 @@ $ mkshadowdir . /scratch/joe-bloggs/myghc-x86 - 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 $(FPTOOLS_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 @@ -1303,9 +1282,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 @@ -1317,13 +1295,13 @@ 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, @@ -1338,40 +1316,16 @@ 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.) @@ -1405,14 +1359,22 @@ directive. - make 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.) @@ -1440,90 +1402,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 - make 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 @@ -1642,7 +1520,7 @@ directive. - The main <filename>mk/boilerplate.mk</filename> file + The <filename>mk/boilerplate.mk</filename> file boilerplate.mk If you look at @@ -2036,7 +1914,7 @@ directive. extra options to pass to all C compilations. This is intended for command line use, thus: -$ make libHS.a EXTRA_CC_OPTS="-v" +$ make libHS.a EXTRA_HC_OPTS="-v" @@ -2112,34 +1990,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) -- 1.7.10.4