[update the build system documentation Simon Marlow **20060505105843] { hunk ./docs/building/building.xml 878 - 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 hunk ./docs/building/building.xml 963 + + + 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. + + hunk ./docs/building/building.xml 1017 - 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. hunk ./docs/building/building.xml 1068 - install. + install (WARNING: probably doesn't work). hunk ./docs/building/building.xml 1124 - - hunk ./docs/building/building.xml 1125 - - check - - run the test suite. + After a maintainer-clean, a + configure will be necessary before + building again. hunk ./docs/building/building.xml 1136 - - configure - - is only available in the root directory - $(FPTOOLS_TOP); it has - been discussed in . - - - hunk ./docs/building/building.xml 1157 - - - 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. - - hunk ./docs/building/building.xml 1159 - Most Makefiles have targets other + Some Makefiles have targets other hunk ./docs/building/building.xml 1165 - Using a project from the build tree + Using GHC from the build tree hunk ./docs/building/building.xml 1167 - 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. hunk ./docs/building/building.xml 1175 - compiler/ghc, or - compiler/ghc-6.xx, as these are the + compiler/stage1/ghc, or + compiler/stage1/ghc-6.xx, as these are the hunk ./docs/building/building.xml 1180 - - Happy can similarly be run from the build tree, using - happy/src/happy-inplace, and similarly for - Alex and Haddock. hunk ./docs/building/building.xml 1249 - A small project + A small example hunk ./docs/building/building.xml 1252 - 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 hunk ./docs/building/building.xml 1262 -# Makefile for fptools project "small" - +# Makefile for program "small" hunk ./docs/building/building.xml 1266 -SRCS = $(wildcard *.lhs) $(wildcard *.c) hunk ./docs/building/building.xml 1285 - 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). hunk ./docs/building/building.xml 1298 - to be the directory containing the mk + to be the top-level directory of the source tree, containing + the mk hunk ./docs/building/building.xml 1305 - hunk ./docs/building/building.xml 1319 - - 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. hunk ./docs/building/building.xml 1322 - 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 hunk ./docs/building/building.xml 1329 - - 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.) hunk ./docs/building/building.xml 1362 - 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 ). hunk ./docs/building/building.xml 1377 - Foo.lhs to Foo.o + Foo.hs to Foo.o hunk ./docs/building/building.xml 1405 - - 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. - - hunk ./docs/building/building.xml 1523 - The main <filename>mk/boilerplate.mk</filename> file + The <filename>mk/boilerplate.mk</filename> file hunk ./docs/building/building.xml 1917 -$ make libHS.a EXTRA_CC_OPTS="-v" +$ make libHS.a EXTRA_HC_OPTS="-v" hunk ./docs/building/building.xml 1993 - - - 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. - - hunk ./docs/building/building.xml 1995 - All of these rules are “double-colon” rules, + Some rules are “double-colon” rules, }