From bd08f5336fd6a0982e058c2cc58ff9693db28de3 Mon Sep 17 00:00:00 2001 From: panne Date: Wed, 2 Jun 2004 08:53:54 +0000 Subject: [PATCH] [project @ 2004-06-02 08:53:54 by panne] Make the Building Guide almost valid DocBook XML V4.2 (to get the real thing, simply add an XML prolog and change "artheader" to "articleinfo"). Things that had to be changed: * XML tags are case-sensitive, so lowercase must be used for tags/attributes * Make "xref" an empty element. * "constant" is not allowed within "filename" * Move "indexterm" to a valid place. * Change some "&" to "&" * The "_" character in titles makes some trouble in the TeX backend => avoid it --- docs/building/building.sgml | 917 +++++++++++++++++++++++-------------------- 1 file changed, 492 insertions(+), 425 deletions(-) diff --git a/docs/building/building.sgml b/docs/building/building.sgml index 0e2b254..ecac376 100644 --- a/docs/building/building.sgml +++ b/docs/building/building.sgml @@ -1,13 +1,13 @@ -
+
- + -Building the Glasgow Functional Programming Tools Suite -The GHC Team -
glasgow-haskell-{users,bugs}@haskell.org
-November 2001 +Building the Glasgow Functional Programming Tools Suite +The GHC Team +
glasgow-haskell-{users,bugs}@haskell.org
+November 2001 The Glasgow fptools suite is a collection of Functional @@ -17,16 +17,16 @@ installation system. This guide is intended for people who want to build or - modify programs from the Glasgow fptools + modify programs from the Glasgow fptools suite (as distinct from those who merely want to - run them). Installation instructions are + run them). Installation instructions are now provided in the user guide. The bulk of this guide applies to building on Unix - systems; see for Windows notes. + systems; see for Windows notes. - + @@ -64,9 +64,7 @@ - The CVS repository. - CVS repository - + The CVS repository.CVS repository We make releases infrequently. If you want more up-to-the minute (but less tested) source code then you need @@ -84,7 +82,7 @@ scratch. More information about our CVS repository can be found - in . + in . @@ -113,8 +111,8 @@ Getting access to the CVS Repository You can access the repository in one of two ways: - read-only (), or read-write (). + read-only (), or read-write (). Remote Read-only CVS Access @@ -156,7 +154,7 @@ - Now go to . + Now go to . @@ -246,7 +244,7 @@ - Windows users: see the notes in about ssh wrinkles! + Windows users: see the notes in about ssh wrinkles! @@ -270,7 +268,7 @@ Set the following environment variables: - + $HOME: points to your home directory. This is where CVS @@ -318,7 +316,7 @@ - + @@ -328,12 +326,12 @@ Put the following in $HOME/.cvsrc: - + checkout -P release -d update -P diff -u - + These are the default options for the specified CVS commands, @@ -403,10 +401,10 @@ some other junk. [Windows users.] The following messages appear to be harmless: - + setsockopt IPTOS_LOWDELAY: Invalid argument setsockopt IPTOS_THROUGHPUT: Invalid argument - + @@ -437,7 +435,7 @@ setsockopt IPTOS_THROUGHPUT: Invalid argument you need at least the ghc, hslibs and libraries modules (for a full list of the projects available, see - ). + ). Remember that if you do not have happy and/or Alex @@ -726,9 +724,10 @@ $ cvs checkout nofib/spectral - alex - alex - project + + alex + alexproject + The Alex lexical @@ -737,9 +736,11 @@ $ cvs checkout nofib/spectral - ghc - ghc - project + + ghc + ghc + project + The Glasgow Haskell Compiler (minus libraries). Absolutely @@ -748,8 +749,10 @@ $ cvs checkout nofib/spectral - glafp-utils - glafp-utilsproject + + glafp-utils + glafp-utilsproject + Utility programs, some of which are used by the build/installation system. Required for pretty much @@ -758,8 +761,10 @@ $ cvs checkout nofib/spectral - greencard - greencardproject + + greencard + greencardproject + The GreenCard @@ -769,8 +774,10 @@ $ cvs checkout nofib/spectral - haggis - haggisproject + + haggis + haggisproject + The Haggis @@ -779,8 +786,10 @@ $ cvs checkout nofib/spectral - haddock - haddockproject + + haddock + haddockproject + The Haddock @@ -789,8 +798,10 @@ $ cvs checkout nofib/spectral - happy - happyproject + + happy + happyproject + The Happy Parser @@ -799,8 +810,10 @@ $ cvs checkout nofib/spectral - hdirect - hdirectproject + + hdirect + hdirectproject + The H/Direct @@ -809,8 +822,10 @@ $ cvs checkout nofib/spectral - hood - hoodproject + + hood + hoodproject + The Haskell Object Observation Debugger. @@ -818,8 +833,10 @@ $ cvs checkout nofib/spectral - hslibs - hslibsproject + + hslibs + hslibsproject + Supplemental libraries for GHC (required for building GHC). @@ -827,8 +844,10 @@ $ cvs checkout nofib/spectral - libraries - project + + libraries + project + Hierarchical Haskell library suite (required for building GHC). @@ -836,16 +855,20 @@ $ cvs checkout nofib/spectral - mhms - project + + mhms + project + The Modular Haskell Metric System. - nofib - nofibproject + + nofib + nofibproject + The NoFib suite: A collection of Haskell programs used primarily for benchmarking. @@ -853,8 +876,10 @@ $ cvs checkout nofib/spectral - testsuite - testsuiteproject + + testsuite + testsuiteproject + A testing framework, including GHC's regression test suite. @@ -876,9 +901,8 @@ $ cvs checkout nofib/spectral - - Disk space needed - Disk space needed: from about 100Mb for a basic GHC + Disk space neededDisk + space needed: from about 100Mb for a basic GHC build, up to probably 500Mb for a GHC build with everything included (libraries built several different ways, etc.). @@ -886,23 +910,23 @@ $ cvs checkout nofib/spectral Use an appropriate machine / operating system. lists the supported platforms; if + linkend="sec-port-info"/> lists the supported platforms; if yours isn't amongst these then you can try porting GHC (see - ). + ). Be sure that the “pre-supposed” utilities are - installed. + installed. elaborates. If you have any problem when building or installing the - Glasgow tools, please check the “known pitfalls” (). Also check the FAQ for the + Glasgow tools, please check the “known pitfalls” (). Also check the FAQ for the version you're building, which is part of the User's Guide and - available on the GHC web + available on the GHC web site. bugsknown @@ -978,13 +1002,13 @@ $ cvs checkout nofib/spectral - alpha-dec-{osf,linux,freebsd,openbsd,netbsd}: + alpha-dec-{osf,linux,freebsd,openbsd,netbsd}: alpha-dec-osf alpha-dec-linux alpha-dec-freebsd alpha-dec-openbsd alpha-dec-netbsd - + The OSF port is currently working (as of GHC version 5.02.1) and well supported. The native code generator is @@ -994,8 +1018,9 @@ $ cvs checkout nofib/spectral - sparc-sun-sunos4 - sparc-sun-sunos4 + sparc-sun-sunos4 + sparc-sun-sunos4 + Probably works with minor tweaks, hasn't been tested for a while. @@ -1003,8 +1028,9 @@ $ cvs checkout nofib/spectral - sparc-sun-solaris2 - sparc-sun-solaris2 + sparc-sun-solaris2 + sparc-sun-solaris2 + Fully supported (at least for Solaris 2.7 and 2.6), including native-code generator. @@ -1012,8 +1038,9 @@ $ cvs checkout nofib/spectral - sparc-unknown-openbsd - sparc-unknown-openbsd + sparc-unknown-openbsd + sparc-unknown-openbsd + Supported, including native-code generator. The same should also be true of NetBSD @@ -1021,8 +1048,9 @@ $ cvs checkout nofib/spectral - hppa1.1-hp-hpux (HP-PA boxes running HPUX 9.x) - hppa1.1-hp-hpux + hppa1.1-hp-hpux (HP-PA boxes running HPUX 9.x) + hppa1.1-hp-hpux + A registerised port is available for version 4.08, but GHC hasn't been built on that platform since (as far @@ -1031,11 +1059,12 @@ $ cvs checkout nofib/spectral - i386-unknown-linux (PCs running Linux, ELF binary format) - i386-*-linux + i386-unknown-linux (PCs running Linux, ELF binary format) + i386-*-linux + GHC works registerised and has a native code - generator. You must have GCC 2.7.x + generator. You must have GCC 2.7.x or later. NOTE about glibc versions: GHC binaries built on a system running glibc 2.0 won't work on a system running @@ -1047,9 +1076,9 @@ $ cvs checkout nofib/spectral - i386-unknown-freebsd (PCs running FreeBSD 2.2 or - higher) - i386-unknown-freebsd + i386-unknown-freebsd (PCs running FreeBSD 2.2 or higher) + i386-unknown-freebsd + GHC works registerised. Pre-built packages are available in the native package format, so if you just @@ -1060,8 +1089,9 @@ $ cvs checkout nofib/spectral - i386-unknown-openbsd (PCs running OpenBSD) - i386-unknown-openbsd + i386-unknown-openbsd (PCs running OpenBSD) + i386-unknown-openbsd + Supported, with native code generator. Packages are available through the ports system in the native package @@ -1070,8 +1100,9 @@ $ cvs checkout nofib/spectral - i386-unknown-netbsd (PCs running NetBSD) - i386-unknown-netbsd + i386-unknown-netbsd (PCs running NetBSD) + i386-unknown-netbsd + Will require some minor porting effort, but should work registerised. @@ -1079,8 +1110,9 @@ $ cvs checkout nofib/spectral - i386-unknown-mingw32 (PCs running Windows) - i386-unknown-mingw32 + i386-unknown-mingw32 (PCs running Windows) + i386-unknown-mingw32 + Fully supported under Win9x, WinNT, Win2k, and WinXP. Includes a native code generator. Building from @@ -1091,8 +1123,9 @@ $ cvs checkout nofib/spectral - ia64-unknown-linux - ia64-unknown-linux + ia64-unknown-linux + ia64-unknown-linux + Supported, except there is no native code generator. @@ -1100,8 +1133,9 @@ $ cvs checkout nofib/spectral - x86_64-unknown-linux - x86_64-unknown-linux + x86_64-unknown-linux + x86_64-unknown-linux + GHC currently works unregisterised. A registerised port is in progress. @@ -1109,8 +1143,9 @@ $ cvs checkout nofib/spectral - amd64-unknown-openbsd - amd64-unknown-linux + amd64-unknown-openbsd + amd64-unknown-linux + (This is the same as x86_64-unknown-openbsd). GHC currently works unregisterised. A registerised port is in @@ -1119,8 +1154,9 @@ $ cvs checkout nofib/spectral - mips-sgi-irix5 - mips-sgi-irix[5-6] + mips-sgi-irix5 + mips-sgi-irix[5-6] + Port has worked in the past, but hasn't been tested for some time (and will certainly have rotted in various @@ -1131,16 +1167,18 @@ $ cvs checkout nofib/spectral - mips64-sgi-irix6 - mips-sgi-irix6 + mips64-sgi-irix6 + mips-sgi-irix6 + GHC currently works unregisterised. - powerpc-ibm-aix - powerpc-ibm-aix + powerpc-ibm-aix + powerpc-ibm-aix + Port currently doesn't work, needs some minimal porting effort. As usual, we don't have access to @@ -1150,8 +1188,9 @@ $ cvs checkout nofib/spectral - powerpc-apple-darwin - powerpc-apple-darwin + powerpc-apple-darwin + powerpc-apple-darwin + Supported registerised. Native code generator is almost working. @@ -1159,8 +1198,9 @@ $ cvs checkout nofib/spectral - powerpc-apple-linux - powerpc-apple-linux + powerpc-apple-linux + powerpc-apple-linux + Not supported (yet). @@ -1199,14 +1239,15 @@ $ cvs checkout nofib/spectral - GHC - pre-supposed: GHC - GHC, pre-supposed + GHC + pre-supposed: GHC + 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 . + then see . Which version of GHC you need will depend on the packages you intend to build. GHC itself will normally @@ -1216,9 +1257,10 @@ $ cvs checkout nofib/spectral - Perl - pre-supposed: Perl - Perl, pre-supposed + Perl + pre-supposed: Perl + Perl, pre-supposed + You have to have Perl to proceed! Perl version 5 at least is required. GHC has been known to @@ -1240,10 +1282,10 @@ $ cvs checkout nofib/spectral - GNU C (gcc) - pre-supposed: GCC (GNU C - compiler) GCC (GNU C - compiler), pre-supposed + GNU C (gcc) + pre-supposed: GCC (GNU C compiler) + GCC (GNU C compiler), pre-supposed + We recommend using GCC version 2.95.2 on all platforms. Failing that, version 2.7.2 is stable on most @@ -1265,9 +1307,9 @@ $ cvs checkout nofib/spectral - GNU Make - makeGNU - + GNU Make + makeGNU + The fptools build system makes heavy use of features specific to GNU make, so you must have @@ -1277,8 +1319,9 @@ $ cvs checkout nofib/spectral - Happy - Happy + Happy + Happy + Happy is a parser generator tool for Haskell, and is used to generate GHC's parsers. Happy is written in @@ -1294,8 +1337,9 @@ $ cvs checkout nofib/spectral - Alex - Alex + Alex + Alex + Alex is a lexical-analyser generator for Haskell, which GHC uses to generate its lexer. Like Happy, Alex is @@ -1307,9 +1351,10 @@ $ cvs checkout nofib/spectral - autoconf - pre-supposed: autoconf - autoconf, pre-supposed + autoconf + pre-supposed: autoconf + autoconf, pre-supposed + GNU autoconf is needed if you intend to build from the CVS sources, it is not needed if you @@ -1329,9 +1374,10 @@ $ cvs checkout nofib/spectral - sed - pre-supposed: sed - sed, pre-supposed + sed + pre-supposed: sed + sed, pre-supposed + You need a working sed if you are going to build from sources. The build-configuration stuff @@ -1355,9 +1401,10 @@ $ cvs checkout nofib/spectral - PVM version 3: + PVM version 3: pre-supposed: PVM3 (Parallel Virtual Machine) - PVM3 (Parallel Virtual Machine), pre-supposed + PVM3 (Parallel Virtual Machine), pre-supposed + PVM is the Parallel Virtual Machine on which Parallel Haskell programs run. (You only need this if you @@ -1379,8 +1426,9 @@ $ cvs checkout nofib/spectral - bash: - bash, presupposed (Parallel Haskell only) + bash: + bash, presupposed (Parallel Haskell only) + Sadly, the gr2ps script, used to convert “parallelism profiles” to PostScript, @@ -1396,9 +1444,10 @@ $ cvs checkout nofib/spectral - Flex - pre-supposed: flex - flex, pre-supposed + 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 @@ -1411,7 +1460,7 @@ $ cvs checkout nofib/spectral More tools are required if you want to format the documentation that comes with GHC and other fptools projects. See . + linkend="building-docs"/>. @@ -1533,8 +1582,8 @@ $ 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 for a typical invocation. + fptools/glafp-utils/lndir). See for a typical invocation. The build tree does not need to be anywhere near the source tree in the file system. Indeed, one advantage of @@ -1542,8 +1591,8 @@ $ make install can be placed in a non-backed-up partition, saving your systems support people from backing up untold megabytes of easily-regenerated, and rapidly-changing, gubbins. The golden - rule is that (with a single exception—) absolutely everything in + rule is that (with a single exception—) absolutely everything in the build tree is either a symbolic link to the source tree, or else is mechanically generated. It should be perfectly OK for your build tree to vanish overnight; an hour or @@ -1578,7 +1627,7 @@ $ make install $(FPTOOLS_TOP) unless otherwise stated. For example, the file ghc/mk/target.mk is actually - $(FPTOOLS_TOP)/ghc/mk/target.mk. + $(FPTOOLS_TOP)/ghc/mk/target.mk. @@ -1617,15 +1666,15 @@ $ make install Change directory to $(FPTOOLS_TOP) and issue the command - + autoreconf - + autoreconf (with no arguments). This GNU program (recursively) converts - $(FPTOOLS_TOP)/configure.ac and - $(FPTOOLS_TOP)/aclocal.m4 + $(FPTOOLS_TOP)/configure.ac and + $(FPTOOLS_TOP)/aclocal.m4 to a shell script called - $(FPTOOLS_TOP)/configure. + $(FPTOOLS_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 @@ -1635,7 +1684,7 @@ autoreconf Some projects, including GHC, 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). + $(FPTOOLS_TOP). These steps are completely platform-independent; they just mean that the human-written files (configure.ac and @@ -1651,14 +1700,14 @@ autoreconf Runs the newly-created configure script, thus: - + ./configure args - + configure's mission is to scurry round your computer working out what architecture it has, what operating system, whether it has the - vfork system call, where + vfork system call, where tar is kept, whether gcc is available, where various obscure #include files are, whether it's a @@ -1703,9 +1752,9 @@ autoreconf - --with-ghc=path - --with-ghc - + --with-ghc=path + --with-ghc + Specifies the path to an installed GHC which you would like to use. This compiler will be used @@ -1720,9 +1769,9 @@ autoreconf - --with-hc=path - --with-hc - + --with-hc=path + --with-hc + Specifies the path to any installed Haskell compiler. This compiler will be used for compiling @@ -1732,9 +1781,9 @@ autoreconf - --with-gcc=path - --with-gcc - + --with-gcc=path + --with-gcc + Specifies the path to the installed GCC. This compiler will be used to compile all C files, @@ -1795,9 +1844,9 @@ autoreconf For example, config.mk.in contains the definition: - + GhcHcOpts=-O -Rghc-timing - + The accompanying comment explains that this is the list of flags passed to GHC when building GHC itself. For doing @@ -1807,9 +1856,9 @@ GhcHcOpts=-O -Rghc-timing or, if you prefer, - + GhcHcOpts += -DDEBUG - + GNU make allows existing definitions to have new text appended using the “+=” @@ -1820,9 +1869,9 @@ GhcHcOpts += -DDEBUG lot quicker), you can just override GhcLibHcOpts altogether: - + GhcHcOpts=-DDEBUG -Rghc-timing - + When reading config.mk.in, remember that anything between “@...@” signs is going to be substituted @@ -1831,9 +1880,9 @@ GhcHcOpts=-DDEBUG -Rghc-timing you want, but you need to be a bit surer what you are doing. For example, there's a line that says: - + TAR = @TarCmd@ - + This defines the Make variables TAR to the pathname for a tar that @@ -1841,9 +1890,9 @@ TAR = @TarCmd@ own pet tar you want to use instead, that's fine. Just add this line to mk/build.mk: - + TAR = mytar - + You do not have to have a mk/build.mk file at all; if you don't, @@ -1874,8 +1923,8 @@ TAR = mytar 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 ). + have the essential files (see ). @@ -2207,8 +2256,8 @@ $ emacs mk/build.mk is only available in the root directory $(FPTOOLS_TOP); it has - been discussed in . + been discussed in . @@ -2224,9 +2273,9 @@ $ emacs mk/build.mk generated .depend file will contain the dependency: - + Foo.o : Baz.hi - + which says that the object file Foo.o depends on the interface file @@ -2293,9 +2342,9 @@ Foo.o : Baz.hi make is going to rebuild everything anyway, the following hack may be useful: - + gmake 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 @@ -2364,7 +2413,7 @@ gmake FAST=YES Makefile, minimal - + # Makefile for fptools project "small" TOP = .. @@ -2374,7 +2423,7 @@ SRCS = $(wildcard *.lhs) $(wildcard *.c) HS_PROG = small include $(TOP)/target.mk - + this Makefile has three sections: @@ -2393,11 +2442,11 @@ directive. a file of “boilerplate” code from the level above (which in this case will be - FPTOOLS_TOP/mk/boilerplate.mkboilerplate.mk). + FPTOOLS_TOP/mk/boilerplate.mkboilerplate.mk). As its name suggests, boilerplate.mk consists of a large quantity of standard Makefile code. We discuss this - boilerplate in more detail in . + boilerplate in more detail in . include, directive in Makefiles Makefile inclusion @@ -2409,9 +2458,9 @@ directive. 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 @@ -2424,7 +2473,7 @@ include ../mk/boilerplate.mk # NO NO NO included sits.) In general, every file foo.mk assumes that - $(TOP)/mk/foo.mk + $(TOP)/mk/foo.mk refers to itself. It is up to the Makefile doing the include to ensure this is the case. @@ -2449,8 +2498,8 @@ include ../mk/boilerplate.mk # NO NO NO 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 . + and how they affect what happens, in . The definition for SRCS uses the useful GNU make construct @@ -2469,12 +2518,12 @@ include ../mk/boilerplate.mk # NO NO NO code, called target.mktarget.mk. It contains the rules that tell gmake how - to make the standard targets (). Why, you ask, can't this + to make the standard targets (). Why, you ask, can't this standard code be part of boilerplate.mk? Good question. We - discuss the reason later, in . + discuss the reason later, in . You do not have to include the @@ -2483,8 +2532,8 @@ include ../mk/boilerplate.mk # NO NO NO though, you will find quite a big payoff from using the canned rules in target.mk; the price tag is that you have to understand what canned rules get - enabled, and what they do (). + enabled, and what they do (). @@ -2540,7 +2589,7 @@ include ../mk/boilerplate.mk # NO NO NO rare.) To give you the idea, here's part of the directory structure for the (rather large) GHC project: - + $(FPTOOLS_TOP)/ghc/ Makefile mk/ @@ -2557,14 +2606,14 @@ $(FPTOOLS_TOP)/ghc/ 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. + $(FPTOOLS_TOP)/ghc. It does most of its work by recursively invoking gmake on the Makefiles in the sub-directories. We say that @@ -2666,9 +2715,9 @@ $(FPTOOLS_TOP)/ghc/ augment them. For example, a Makefile might say: - + SRC_HC_OPTS += -O - + thereby adding “” to the end of @@ -2678,7 +2727,7 @@ SRC_HC_OPTS += -O target.mk contains make rules for the standard targets - described in . These + described in . These rules are selectively included, depending on the setting of certain make variables. These variables are usually set in the middle section of the @@ -2695,13 +2744,13 @@ SRC_HC_OPTS += -O gmake commits target and dependency lists earlier than it should. For example, - target.mk has a rule that looks + target.mk has a rule that looks like this: - + $(HS_PROG) : $(OBJS) $(HC) $(LD_OPTS) $< -o $@ - + If this rule was in boilerplate.mk then @@ -2742,23 +2791,25 @@ $(HS_PROG) : $(OBJS) boilerplate.mk If you look at - $(FPTOOLS_TOP)/mk/boilerplate.mk + $(FPTOOLS_TOP)/mk/boilerplate.mk you will find that it consists of the following sections, each held in a separate file: - config.mk - config.mk + config.mk + config.mk + is the build configuration file we discussed at - length in . + length in . - paths.mk - paths.mk + paths.mk + paths.mk + defines make variables for pathnames and file lists. This file contains code for @@ -2774,9 +2825,9 @@ $(HS_PROG) : $(OBJS) - ALL_DIRS - ALL_DIRS - + ALL_DIRS + ALL_DIRS + Set to a list of directories to search in addition to the current directory for source @@ -2785,9 +2836,9 @@ $(HS_PROG) : $(OBJS) - EXCLUDE_SRCS - EXCLUDE_SRCS - + EXCLUDE_SRCS + EXCLUDE_SRCS + Set to a list of source files (relative to the current directory) to omit from the automatic @@ -2803,9 +2854,9 @@ $(HS_PROG) : $(OBJS) - EXTRA_SRCS - EXCLUDE_SRCS - + EXTRA_SRCS + EXCLUDE_SRCS + Set to a list of extra source files (perhaps in directories not listed in @@ -2820,8 +2871,9 @@ $(HS_PROG) : $(OBJS) - SRCS - SRCS + SRCS + SRCS + All source files found, sorted and without duplicates, including those which might not exist @@ -2833,8 +2885,9 @@ $(HS_PROG) : $(OBJS) - HS_SRCS - HS_SRCS + HS_SRCS + HS_SRCS + all Haskell source files in the current directory, including those derived from other source @@ -2844,8 +2897,9 @@ $(HS_PROG) : $(OBJS) - HS_OBJS - HS_OBJS + HS_OBJS + HS_OBJS + Object files derived from HS_SRCS. @@ -2853,8 +2907,9 @@ $(HS_PROG) : $(OBJS) - HS_IFACES - HS_IFACES + HS_IFACES + HS_IFACES + Interface files (.hi files) derived from HS_SRCS. @@ -2862,16 +2917,18 @@ $(HS_PROG) : $(OBJS) - C_SRCS + C_SRCS C_SRCS + All C source files found. - C_OBJS + C_OBJS C_OBJS + Object files derived from C_SRCS. @@ -2879,8 +2936,9 @@ $(HS_PROG) : $(OBJS) - SCRIPT_SRCS + SCRIPT_SRCS SCRIPT_SRCS + All script source files found (.lprl files). @@ -2888,8 +2946,9 @@ $(HS_PROG) : $(OBJS) - SCRIPT_OBJS + SCRIPT_OBJS SCRIPT_OBJS + object files derived from SCRIPT_SRCS @@ -2898,8 +2957,9 @@ $(HS_PROG) : $(OBJS) - HSC_SRCS + HSC_SRCS HSC_SRCS + All hsc2hs source files (.hsc files). @@ -2907,8 +2967,9 @@ $(HS_PROG) : $(OBJS) - HAPPY_SRCS + HAPPY_SRCS HAPPY_SRCS + All happy source files (.y or .hy files). @@ -2916,8 +2977,9 @@ $(HS_PROG) : $(OBJS) - OBJS + OBJS OBJS + the concatenation of $(HS_OBJS), @@ -2943,23 +3005,25 @@ $(HS_PROG) : $(OBJS) - opts.mk - opts.mk + opts.mk + opts.mk + defines make variables for option strings to pass to each program. For example, it defines HC_OPTSHC_OPTS, the option strings to pass to the Haskell compiler. See - . + . - suffix.mk - suffix.mk + suffix.mk + suffix.mk + - defines standard pattern rules—see . + defines standard pattern rules—see . @@ -2988,11 +3052,11 @@ $(HS_PROG) : $(OBJS) Almost all the rules look something like this: - + %.o : %.c $(RM) $@ $(CC) $(CC_OPTS) -c $< -o $@ - + Here's how to understand the rule. It says that something.o (say @@ -3020,9 +3084,10 @@ $(HS_PROG) : $(OBJS) defined in mk/opts.mk. Almost all of them are defined like this: - -CC_OPTS = $(SRC_CC_OPTS) $(WAY$(_way)_CC_OPTS) $($*_CC_OPTS) $(EXTRA_CC_OPTS) - + +CC_OPTS = \ + $(SRC_CC_OPTS) $(WAY$(_way)_CC_OPTS) $($*_CC_OPTS) $(EXTRA_CC_OPTS) + The four variables from which CC_OPTS is built have the following @@ -3046,7 +3111,7 @@ CC_OPTS = $(SRC_CC_OPTS) $(WAY$(_way)_CC_OPTS) $($*_CC_OPTS) $(EXTRA_CC_OPTS) mp. The variable WAY_CC_OPTS holds options to pass to the C compiler when compiling the - standard way. ( dicusses + standard way. ( dicusses multi-way compilation.) @@ -3068,9 +3133,9 @@ CC_OPTS = $(SRC_CC_OPTS) $(WAY$(_way)_CC_OPTS) $($*_CC_OPTS) $(EXTRA_CC_OPTS) extra options to pass to all C compilations. This is intended for command line use, thus: - + gmake libHS.a EXTRA_CC_OPTS="-v" - + @@ -3081,8 +3146,8 @@ gmake libHS.a EXTRA_CC_OPTS="-v" target.mk target.mk contains canned rules for - all the standard targets described in . It is complicated by the fact + all the standard targets described in . It is complicated by the fact that you don't want all of these rules to be active in every Makefile. Rather than have a plethora of tiny files which you can include selectively, there is a single @@ -3176,10 +3241,10 @@ gmake libHS.a EXTRA_CC_OPTS="-v" All of these rules are “double-colon” rules, thus - + install :: $(HS_PROG) ...how to install it... - + GNU make treats double-colon rules as separate entities. If there are several double-colon rules for @@ -3210,7 +3275,7 @@ install :: $(HS_PROG) When SUBDIRS is defined, target.mk includes a rather neat rule for - the standard targets ( that + the standard targets ( that simply invokes make recursively in each of the sub-directories. @@ -3299,8 +3364,8 @@ install :: $(HS_PROG) Makefile to the list of way tags you want these targets built for. The mechanism here is very much like the recursive invocation of - make in sub-directories (). It is up to you to set + make in sub-directories (). It is up to you to set WAYS in your Makefile; this is how you control what ways will get built. @@ -3320,10 +3385,10 @@ install :: $(HS_PROG) file will match. The key pattern rules (in suffix.mk) look like this: - + %.$(way_)o : %.lhs $(HC) $(HC_OPTS) $< -o $@ - + Neat, eh? @@ -3371,9 +3436,10 @@ $ make way=p - DocBook - pre-supposed: DocBook - DocBook, pre-supposed + DocBook + pre-supposed: DocBook + DocBook, pre-supposed + Much of our documentation is written in SGML, using the DocBook DTD. Instructions on installing and @@ -3382,9 +3448,10 @@ $ make way=p - TeX - pre-supposed: TeX - TeX, pre-supposed + TeX + pre-supposed: TeX + TeX, pre-supposed + A decent TeX distribution is required if you want to produce printable documentation. We recomment teTeX, @@ -3393,9 +3460,9 @@ $ make way=p - Haddock - Haddock - + Haddock + Haddock + Haddock is a Haskell documentation tool that we use for automatically generating documentation from the @@ -3422,21 +3489,21 @@ $ make way=p If you don't have DocBook tools installed, and you are using a system that can handle RedHat RPM packages, you can - probably use the Cygnus - DocBook tools, which is the most shrink-wrapped SGML + probably use the Cygnus + DocBook tools, which is the most shrink-wrapped SGML suite that we could find. You need all the RPMs except for - psgml (i.e. docbook, - jade, jadetex, - sgmlcommon and - stylesheets). Note that most of these + psgml (i.e. docbook, + jade, jadetex, + sgmlcommon and + stylesheets). Note that most of these RPMs are architecture neutral, so are likely to be found in a - noarch directory. The SuSE RPMs also - work; the RedHat ones don't in RedHat 6.2 + noarch directory. The SuSE RPMs also + work; the RedHat ones don't in RedHat 6.2 (7.0 and later should be OK), but they are easy to fix: just make a symlink from - /usr/lib/sgml/stylesheets/nwalsh-modular/lib/dblib.dsl - to /usr/lib/sgml/lib/dblib.dsl. + /usr/lib/sgml/stylesheets/nwalsh-modular/lib/dblib.dsl + to /usr/lib/sgml/lib/dblib.dsl. @@ -3460,17 +3527,17 @@ $ make way=p Installing from binaries on Windows - It's a good idea to use Norman Walsh's installation - notes as a guide. You should get version 3.1 of - DocBook, and note that his file test.sgm + It's a good idea to use Norman Walsh's installation + notes as a guide. You should get version 3.1 of + DocBook, and note that his file test.sgm won't work, as it needs version 3.0. You should unpack Jade - into \Jade, along with the entities, - DocBook into \docbook, and the DocBook - stylesheets into \docbook\stylesheets (so + into \Jade, along with the entities, + DocBook into \docbook, and the DocBook + stylesheets into \docbook\stylesheets (so they actually end up in - \docbook\stylesheets\docbook). - + \docbook\stylesheets\docbook). + @@ -3479,58 +3546,58 @@ $ make way=p Jade - Install OpenJade + Install OpenJade (Windows binaries are available as well as sources). If you want DVI, PS, or PDF then install JadeTeX from the - dsssl subdirectory. (If you get the + dsssl subdirectory. (If you get the error: ! LaTeX Error: Unknown option implicit=false' for package hyperref'. - your version of hyperref is out of date; + your version of hyperref is out of date; download it from CTAN - (macros/latex/contrib/supported/hyperref), + (macros/latex/contrib/supported/hyperref), and make it, ensuring that you have first removed or renamed your old copy. If you start getting file not found errors - when making the test for hyperref, you + when making the test for hyperref, you can abort at that point and proceed straight to - make install, or enter them as - ../filename.) + make install, or enter them as + ../filename.) - Make links from virtex to - jadetex and - pdfvirtex to - pdfjadetex (otherwise DVI, PostScript + Make links from virtex to + jadetex and + pdfvirtex to + pdfjadetex (otherwise DVI, PostScript and PDF output will not work). Copy - dsssl/*.{dtd,dsl} and - catalog to - /usr/[local/]lib/sgml. + dsssl/*.{dtd,dsl} and + catalog to + /usr/[local/]lib/sgml. DocBook and the DocBook stylesheets - Get a Zip of DocBook + Get a Zip of DocBook and install the contents in - /usr/[local/]/lib/sgml. + /usr/[local/]/lib/sgml. - Get the DocBook - stylesheets and install in - /usr/[local/]lib/sgml/stylesheets + Get the DocBook + stylesheets and install in + /usr/[local/]lib/sgml/stylesheets (thereby creating a subdirectory docbook). For indexing, - copy or link collateindex.pl from the - DocBook stylesheets archive in bin into - a directory on your PATH. - - Download the ISO - entities into - /usr/[local/]lib/sgml. + copy or link collateindex.pl from the + DocBook stylesheets archive in bin into + a directory on your PATH. + + Download the ISO + entities into + /usr/[local/]lib/sgml. @@ -3538,7 +3605,7 @@ $ make way=p Configuring the DocBook tools - Once the DocBook tools are installed, the configure script + Once the DocBook tools are installed, the configure script will detect them and set up the build system accordingly. If you have a system that isn't supported, let us know, and we'll try to help. @@ -3550,12 +3617,12 @@ $ make way=p If you install from source, you'll get a pile of warnings of the form -DTDDECL catalog entries are not supported +DTDDECL catalog entries are not supported every time you build anything. These can safely be ignored, but if you find them tedious you can get rid of them by removing all - the DTDDECL entries from - docbook.cat. + the DTDDECL entries from + docbook.cat. @@ -3633,14 +3700,14 @@ $ make install-docs 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 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 . + linkend="unregisterised-porting"/>. @@ -3666,7 +3733,7 @@ $ make install-docs supplied on the GHC download page, otherwise you'll have to compile some up yourself, or start from unregisterised HC files - see . + linkend="unregisterised-porting"/>. The following steps should result in a working GHC build with full libraries: @@ -3693,9 +3760,9 @@ $ make install-docs command will execute the whole build process (it won't install yet): - + foo% distrib/hc-build --prefix=dir - + --hc-build By default, the installation directory is @@ -3708,9 +3775,9 @@ foo% distrib/hc-build --prefix=dir build process, you can install the resulting system, as normal, with - + foo% make install - + @@ -3891,8 +3958,8 @@ $ touch H/ghc/includes/config.h Now build the compiler: -$ cd H/glafp-utils && make boot && make -$ cd H/ghc && make boot && make +$ cd H/glafp-utils && make boot && make +$ cd H/ghc && make boot && make Don't worry if the build falls over in the RTS, we don't need the RTS yet. @@ -3901,14 +3968,14 @@ $ cd H/ghc && make boot && make $ cd H/libraries -$& make boot && make +$ make boot && make $ cd H/ghc -$ make boot stage=2 && make stage=2 +$ make boot stage=2 && make stage=2 @@ -3943,7 +4010,7 @@ $ make hc-file-bundle Project=Ghc from the intermediate C files we generated above. The process of bootstrapping from C files is automated by the script in distrib/hc-build, and is - described in . + described in . $ ./distrib/hc-build --enable-hc-boot-unregisterised @@ -3993,9 +4060,9 @@ Hello World! - ghc/includes/MachRegs.h - MachRegs.h - + ghc/includes/MachRegs.h + MachRegs.h + Defines the STG-register to machine-register mapping. You need to know your platform's C calling @@ -4005,19 +4072,19 @@ Hello World! - ghc/includes/TailCalls.h - TailCalls.h - + ghc/includes/TailCalls.h + TailCalls.h + Macros that cooperate with the mangler (see ) to make proper tail-calls + linkend="sec-mangler"/>) to make proper tail-calls work. - ghc/rts/Adjustor.c - Adjustor.c - + ghc/rts/Adjustor.c + Adjustor.c + Support for foreign import "wrapper" @@ -4028,9 +4095,9 @@ Hello World! - ghc/rts/StgCRun.c - StgCRun.c - + ghc/rts/StgCRun.c + StgCRun.c + The little assembly layer between the C world and the Haskell world. See the comments and code for the @@ -4038,12 +4105,12 @@ Hello World! - ghc/rts/MBlock.h - ghc/rts/MBlock.c - MBlock.h - - MBlock.c - + ghc/rts/MBlock.h + MBlock.h + + ghc/rts/MBlock.c + MBlock.c + These files are really OS-specific rather than architecture-specific. In MBlock.h @@ -4137,7 +4204,7 @@ WARNINGS about pitfalls and known “problems”: - + @@ -4153,9 +4220,9 @@ of choice). 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 @@ -4187,11 +4254,11 @@ incompatible pointer type” out of GCC. Harmless. Similarly, archiving warning messages like the following are not a problem: - + ar: filename GlaIOMonad__1_2s.o truncated to GlaIOMonad_ ar: filename GlaIOMonad__2_2s.o truncated to GlaIOMonad_ ... - + @@ -4231,15 +4298,15 @@ above. -and try again: gmake. (see for information about +and try again: gmake. (see for information about <module>_HC_OPTS.) Alternatively, just cut to the chase: - + % cd ghc/compiler % make EXTRA_HC_OPTS=-optCrts-M128M - + @@ -4263,13 +4330,13 @@ this bug also suggests that you have an old GCC. You may need to re-ranlibranlib your libraries (on Sun4s). - + % cd $(libdir)/ghc-x.xx/sparc-sun-sunos4 % foreach i ( `find . -name '*.a' -print` ) # or other-shell equiv... ? ranlib $i ? # or, on some machines: ar s $i ? end - + We'd be interested to know if this is still necessary. @@ -4285,18 +4352,18 @@ a bit from one Unix to another. One particular gotcha is macro calls like this: - + SLIT("Hello, world") - + Some cpps treat the comma inside the string as separating two macro arguments, so you get - + :731: macro `SLIT' used with too many (2) args - + Alas, cpp doesn't tell you the offending file! @@ -4305,20 +4372,20 @@ Workaround: don't put weird things in string args to cpp macr - + -Platforms, scripts, and file names +Platforms, scripts, and file names GHC is designed both to be built, and to run, on both Unix and Windows. This flexibility gives rise to a good deal of brain-bending detail, which we have tried to collect in this chapter. -Windows platforms: Cygwin, MSYS, and MinGW +Windows platforms: Cygwin, MSYS, and MinGW The build system is built around Unix-y makefiles. Because it's not native, the Windows situation for building GHC is particularly confusing. This section @@ -4410,14 +4477,14 @@ that Haskell programs compiled by GHC-cygwin can import the (Haskell) Posix libr how GHC is built. We use both MSYS and Cygwin as build environments for GHC; both work fine, though MSYS is rather lighter weight. -In your build tree, you build a compiler called ghc-inplace. It -uses the gcc that you specify using the +In your build tree, you build a compiler called ghc-inplace. It +uses the gcc that you specify using the flag when you run -configure (see below). -The makefiles are careful to use ghc-inplace (not gcc) -to compile any C files, so that it will in turn invoke the correct gcc rather that -whatever one happens to be in your path. However, the makefiles do use whatever ld -and ar happen to be in your path. This is a bit naughty, but (a) they are only +configure (see below). +The makefiles are careful to use ghc-inplace (not gcc) +to compile any C files, so that it will in turn invoke the correct gcc rather that +whatever one happens to be in your path. However, the makefiles do use whatever ld +and ar happen to be in your path. This is a bit naughty, but (a) they are only used to glom together .o files into a bigger .o file, or a .a file, so they don't ever get libraries (which would be bogus; they might be the wrong libraries), and (b) Cygwin and MinGW use the same .o file format. So its ok. @@ -4452,7 +4519,7 @@ Cygwin programs have a more complicated mount table, and map the lettered drives -HOST_OS vs TARGET_OS +Host System vs Target System In the source code you'll find various ifdefs looking like: @@ -4470,12 +4537,12 @@ and These macros are set by the configure script (via the file config.h). Which is which? The criterion is this. In the ifdefs in GHC's source code: - - The "host" system is the one on which GHC itself will be run. - - - The "target" system is the one for which the program compiled by GHC will be run. - + + The "host" system is the one on which GHC itself will be run. + + + The "target" system is the one for which the program compiled by GHC will be run. + For a stage-2 compiler, in which GHCi is available, the "host" and "target" systems must be the same. So then it doesn't really matter whether you use the HOST_OS or TARGET_OS cpp macros. @@ -4523,7 +4590,7 @@ shortcomings of the native Windows cmd shell. -Instructions for building under Windows +Instructions for building under Windows This section gives detailed instructions for how to build @@ -4532,13 +4599,13 @@ installing and running GHC may be found in the user guide. In general, Win95/Win98 behave the same, and WinNT/Win2k behave the same. -Make sure you read the preceding section on platforms () +Make sure you read the preceding section on platforms () before reading section. You don't need Cygwin or MSYS to use GHC, but you do need one or the other to build GHC. -Installing and configuring MSYS +Installing and configuring MSYS MSYS is a lightweight alternative to Cygwin. @@ -4621,10 +4688,10 @@ bzip'd dump. -Installing and configuring Cygwin +Installing and configuring Cygwin Install Cygwin from http://www.cygwin.com/. -The installation process is straightforward; we install it in c:/cygwin. +The installation process is straightforward; we install it in c:/cygwin. During the installation dialogue, make sure that you select all of the following: cvs, openssh, @@ -4646,17 +4713,17 @@ stage of Cygwin's installation dialogue, until the view says "Full". The defaul -Set MAKE_MODE to UNIX. If you +Set MAKE_MODE to UNIX. If you don't do this you get very weird messages when you type -make, such as: - +make, such as: + /c: /c: No such file or directory - + Set SHELL to -c:/cygwin/bin/bash. When you invoke a shell in Emacs, this +c:/cygwin/bin/bash. When you invoke a shell in Emacs, this SHELL is what you get. @@ -4689,21 +4756,21 @@ you can't rename a running program! -Some script files used in the make system start with "#!/bin/perl", -(and similarly for sh). Notice the hardwired path! -So you need to ensure that your /bin directory has the following +Some script files used in the make system start with "#!/bin/perl", +(and similarly for sh). Notice the hardwired path! +So you need to ensure that your /bin directory has the following binaries in it: - sh - perl - cat + sh + perl + cat -All these come in Cygwin's bin directory, which you probably have -installed as c:/cygwin/bin. By default Cygwin mounts "/" as -c:/cygwin, so if you just take the defaults it'll all work ok. +All these come in Cygwin's bin directory, which you probably have +installed as c:/cygwin/bin. By default Cygwin mounts "/" as +c:/cygwin, so if you just take the defaults it'll all work ok. (You can discover where your Cygwin -root directory / is by typing mount.) -Provided /bin points to the Cygwin bin +root directory / is by typing mount.) +Provided /bin points to the Cygwin bin directory, there's no need to copy anything. If not, copy these binaries from the cygwin/bin directory (after fixing the sh.exe stuff mentioned in the previous bullet). @@ -4727,16 +4794,16 @@ they don't recognise symlinks. -See the notes in about find and bzip, +See the notes in about find and bzip, which apply to Cygwin too. - + -Configuring SSH +Configuring SSH ssh comes with Cygwin, provided you remember to ask for it when you install Cygwin. (If not, the installer lets you update easily.) Look for openssh @@ -4750,10 +4817,10 @@ you install Cygwin. (If not, the installer lets you update easily.) Look for < seem to lock up bash entirely if they try to get user input (e.g. if they ask for a password). To solve this, start up cmd.exe and run it as follows: - + c:\tmp> set CYGWIN32=tty c:\tmp> c:/user/local/bin/ssh-keygen1 - + (Cygwin-only problem, I think.) @@ -4803,7 +4870,7 @@ you do that, ssh uses the $HOME environment variable instead. -Other things you need to install +Other things you need to install You have to install the following other things to build GHC, listed below. @@ -4850,14 +4917,14 @@ Make sure the installation directory is in your GHC uses the mingw C compiler to -generate code, so you have to install that (see ). +generate code, so you have to install that (see ). Just pick up a mingw bundle at http://www.mingw.org/. We install it in c:/mingw. Do not add any of the mingw binaries to your path. They are only going to get used by explicit access (via the --with-gcc flag you -give to configure later). If you do add them to your path +give to configure later). If you do add them to your path you are likely to get into a mess because their names overlap with Cygwin binaries. @@ -4877,25 +4944,25 @@ so you will need to add emacs/bin to your PATH Finally, check out a copy of GHC sources from -the CVS repository, following the instructions above (). +the CVS repository, following the instructions above (). -Building GHC +Building GHC OK! -Now go read the documentation above on building from source (); +Now go read the documentation above on building from source (); the bullets below only tell you about Windows-specific wrinkles. - + -If you used autoconf instead of autoreconf, +If you used autoconf instead of autoreconf, you'll get an error when you run ./configure: - + ...lots of stuff... creating mk/config.h mk/config.h is unchanged @@ -4903,7 +4970,7 @@ configuring in ghc running /bin/sh ./configure --cache-file=.././config.cache --srcdir=. ./configure: ./configure: No such file or directory configure: error: ./configure failed for ghc - + @@ -4921,11 +4988,11 @@ Solution: delete configure first. After autoreconf run ./configure in fptools/ 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 -(see ). +(see ). Both these options are important! It's possible to get into trouble using the wrong C compiler! @@ -4942,7 +5009,7 @@ typically leaving you with this: make[4]: Leaving directory `/cygdrive/e/fptools-stage1/ghc/rts/gmp' ../../ghc/compiler/ghc-inplace -optc-mno-cygwin -optc-O - -optc-Wall -optc-W -optc-Wstrict-prototypes -optc-Wmissing-prototypes + -optc-Wall -optc-W -optc-Wstrict-prototypes -optc-Wmissing-prototypes -optc-Wmissing-declarations -optc-Winline -optc-Waggregate-return -optc-Wbad-function-cast -optc-Wcast-align -optc-I../includes -optc-I. -optc-Iparallel -optc-DCOMPILING_RTS @@ -4957,11 +5024,11 @@ Be warned! -If you want to build GHC-cygwin () +If you want to build GHC-cygwin () you'll have to do something more like: - + ./configure --with-gcc=...the Cygwin gcc... - + @@ -4976,7 +5043,7 @@ can be really confusing. SplitObjs = NO -in your build.mk configuration file (see ). +in your build.mk configuration file (see ). This tells the build system not to split each library into a myriad of little object files, one for each function. Doing so reduces binary sizes for statically-linked binaries, but on Windows it dramatically increases the time taken to build the libraries in the first place. @@ -4986,10 +5053,10 @@ it dramatically increases the time taken to build the libraries in the first pla Do not attempt to build the documentation. It needs all kinds of wierd Jade stuff that we haven't worked out for Win32. - - + + -
+
-- 1.7.10.4