--- /dev/null
+<!DOCTYPE Article PUBLIC "-//OASIS//DTD DocBook V3.1//EN">
+
+<Article>
+
+<ArtHeader>
+
+<Title>Building and Installing the Glasgow Functional Programming Tools Suite
+Version 4.04</Title>
+<Author><OtherName>The GHC Team</OtherName></Author>
+<Address><Email>glasgow-haskell-{users,bugs}@dcs.gla.ac.uk</Email></Address>
+<PubDate>January 2000</PubDate>
+
+<Abstract>
+
+<Para>
+This guide is intended for people who want to build or modify
+programs from the Glasgow <Literal>fptools</Literal> suite (as distinct from those
+who merely want to <Emphasis>run</Emphasis> them). Installation instructions are now provided in the user guide.
+</Para>
+
+<Para>
+The bulk of this guide applies to building on Unix systems; see <XRef LinkEnd="winbuild"> for Windows notes.
+</Para>
+
+</Abstract>
+
+</ArtHeader>
+
+
+<Sect1 id="sec-getting">
+<Title>Getting the Glasgow <Literal>fptools</Literal> suite
+</Title>
+
+<Para>
+Building the Glasgow tools <Emphasis>can</Emphasis> be complicated, mostly because
+there are so many permutations of what/why/how, e.g., ``Build Happy
+with HBC, everything else with GHC, leave out profiling, and test it
+all on the `real' NoFib programs.'' Yeeps!
+</Para>
+
+<Para>
+Happily, such complications don't apply to most people. A few common
+``strategies'' serve most purposes. Pick one and proceed
+as suggested:
+</Para>
+
+<Para>
+<VariableList>
+
+<VarListEntry>
+<Term><IndexTerm><Primary>Binary distribution</Primary></IndexTerm>.</Term>
+<ListItem>
+<Para>
+If your only purpose is to install some of the <Literal>fptools</Literal> suite then the easiest thing to do is to get a binary distribution. In the
+binary distribution everything is pre-compiled for your particular
+machine architecture and operating system, so all you should have to
+do is install the binaries and libraries in suitable places. The user guide
+describes how to do this.
+</Para>
+
+<Para>
+A binary distribution may not work for you for two reasons. First, we
+may not have built the suite for the particular architecture/OS
+platform you want. That may be due to lack of time and energy (in
+which case you can get a source distribution and build from it; see
+below). Alternatively, it may be because we haven't yet ported the
+suite to your architecture, in which case you are considerably worse
+off.
+</Para>
+
+<Para>
+The second reason a binary distribution may not be what you want is
+if you want to read or modify the souce code.
+</Para>
+</ListItem></VarListEntry>
+<VarListEntry>
+<Term><IndexTerm><Primary>Source distribution</Primary></IndexTerm>.</Term>
+<ListItem>
+<Para>
+You have a supported
+platform, but (a) you like the warm fuzzy feeling of compiling things
+yourself; (b) you want to build something ``extra''—e.g., a set of
+libraries with strictness-analysis turned off; or (c) you want to hack
+on GHC yourself.
+</Para>
+
+<Para>
+A source distribution contains complete sources for one or more
+projects in the <Literal>fptools</Literal> suite. Not only that, but the more awkward
+machine-independent steps are done for you. For example, if you don't
+have <Command>flex</Command><IndexTerm><Primary>flex</Primary></IndexTerm> you'll find it convenient that the source
+distribution contains the result of running <Command>flex</Command> on the lexical
+analyser specification. If you don't want to alter the lexical
+analyser then this saves you having to find and install <Command>flex</Command>. You
+will still need a working version of GHC on your machine in order to
+compile (most of) the sources, however.
+</Para>
+
+<Para>
+We make source distributions more frequently than binary
+distributions; a release that comes with pre-compiled binaries
+is considered a major release, i.e., a release that we have some
+confidence will work well by having tested it (more) thoroughly.
+</Para>
+
+<Para>
+Source-only distributions are either bugfix releases or snapshots of
+current state of development. The release has undergone some testing.
+Source releases of 4.xx can be compiled up using 2.10 or later.
+</Para>
+</ListItem></VarListEntry>
+<VarListEntry>
+<Term>Build GHC from intermediate C <Filename>.hc</Filename> files<IndexTerm><Primary>hc files</Primary></IndexTerm>:</Term>
+<ListItem>
+<Para>
+You
+need a working GHC to use a source distribution. What if you don't
+have a working GHC? Then you have no choice but to ``bootstrap'' up
+from the intermediate C (<Filename>.hc</Filename>) files that we provide. Building GHC
+on an unsupported platform falls into this category. Please see
+<Xref LinkEnd="sec-booting-from-C">.
+</Para>
+
+<Para>
+Once you have built GHC, you can build the other Glasgow tools with
+it.
+</Para>
+
+<Para>
+In theory, you can (could?) build GHC with another Haskell compiler
+(e.g., HBC). We haven't tried to do this for ages and it almost
+certainly doesn't work any more (for tedious reasons).
+</Para>
+</ListItem></VarListEntry>
+<VarListEntry>
+<Term>The CVS repository.</Term>
+<ListItem>
+<Para>
+We make source distributions slightly more often than binary
+distributions; but still infrequently. If you want more up-to-the
+minute (but less tested) source code then you need to get access to
+our CVS repository.
+</Para>
+
+<Para>
+All the <Literal>fptools</Literal> source code is held in a CVS repository. CVS is a
+pretty good source-code control system, and best of all it works over
+the network.
+</Para>
+
+<Para>
+The repository holds source code only. It holds no mechanically
+generated files at all. So if you check out a source tree from CVS
+you will need to install every utility so that you can build all the
+derived files from scratch.
+</Para>
+
+<Para>
+More information about our CVS repository is available at <ULink
+URL="http://www.dcs.gla.ac.uk/fp/software/ghc/cvs-cheat-sheet.html"
+>The Fptools CVS Cheat Sheet</ULink
+>.
+</Para>
+</ListItem></VarListEntry>
+</VariableList>
+</Para>
+
+<Para>
+If you are going to do any building from sources (either from a source
+distribution or the CVS repository) then you need to read all of this
+manual in detail.
+</Para>
+
+</Sect1>
+
+<Sect1>
+<Title>Things to check before you start typing</Title>
+
+<Para>
+Here's a list of things to check before you get started.
+
+<OrderedList>
+<ListItem>
+
+<Para>
+<IndexTerm><Primary>Disk space needed</Primary></IndexTerm>: About 30MB (five hamburgers' worth) of disk space
+for the most basic binary distribution of GHC; more for some
+platforms, e.g., Alphas. An extra ``bundle'' (e.g., concurrent
+Haskell libraries) might take you to 8–10 hamburgers.
+
+You'll need over 100MB (say, 20 hamburgers' worth) if you need to
+build the basic stuff from scratch.
+
+
+All of the above are <Emphasis>estimates</Emphasis> of disk-space needs. (I don't yet
+know the disk requirements for the non-GHC tools).
+
+</Para>
+</ListItem>
+<ListItem>
+
+<Para>
+Use an appropriate machine, compilers, and things.
+
+SPARC boxes, DEC Alphas running OSF/1, and PCs running Linux, FreeBSD,
+or Solaris are all fully supported. MIPS, AIX, Win32 and HP boxes are
+in pretty good shape. <Xref LinkEnd="sec-port-info">
+gives the full run-down on ports or lack thereof.
+
+NOTE: as of version 4.00, we lost a few ports. All of the x86 ports
+are working, as is the Sparc/Solaris port, but the rest will need a
+little work. Please contact us if you can provide hardware cycles
+and/or porting expertise.
+
+</Para>
+</ListItem>
+<ListItem>
+
+<Para>
+ Be sure that the ``pre-supposed'' utilities are installed.
+<Xref LinkEnd="sec-pre-supposed"> elaborates.
+
+</Para>
+</ListItem>
+<ListItem>
+
+<Para>
+ If you have any problem when building or installing the Glasgow
+tools, please check the ``known pitfalls'' (<Xref LinkEnd="sec-build-pitfalls">). Also check the <ULink
+URL="http://www.dcs.gla.ac.uk/fp/software/ghc/ghc-bugs.html"
+>known bugs page</ULink>.
+<IndexTerm><Primary>known bugs</Primary></IndexTerm>
+<IndexTerm><Primary>bugs, known</Primary></IndexTerm>
+
+If you feel there is still some shortcoming in our procedure or
+instructions, please report it.
+
+For GHC, please see the bug-reporting section of the User's guide
+(separate document), to maximise the usefulness of your report.
+<IndexTerm><Primary>bugs, reporting</Primary></IndexTerm>
+
+If in doubt, please send a message to <Email>glasgow-haskell-bugs@dcs.gla.ac.uk</Email>.
+<IndexTerm><Primary>bugs, mailing list</Primary></IndexTerm>
+</Para>
+</ListItem>
+
+</OrderedList>
+
+</Para>
+
+</Sect1>
+
+<Sect1 id="sec-port-info">
+<Title>What machines the Glasgow tools run on
+</Title>
+
+<Para>
+<IndexTerm><Primary>ports, GHC</Primary></IndexTerm>
+<IndexTerm><Primary>GHC ports</Primary></IndexTerm>
+<IndexTerm><Primary>supported platforms</Primary></IndexTerm>
+<IndexTerm><Primary>platforms, supported</Primary></IndexTerm>
+</Para>
+
+<Para>
+The main question is whether or not the Haskell compiler (GHC) runs on
+your platform.
+</Para>
+
+<Para>
+A ``platform'' is a architecture/manufacturer/operating-system
+combination, such as <Literal>sparc-sun-solaris2</Literal>. Other common ones are
+<Literal>alpha-dec-osf2</Literal>, <Literal>hppa1.1-hp-hpux9</Literal>, <Literal>i386-unknown-linux</Literal>,
+<Literal>i386-unknown-solaris2</Literal>, <Literal>i386-unknown-freebsd</Literal>,
+<Literal>i386-unknown-cygwin32</Literal>, <Literal>m68k-sun-sunos4</Literal>, <Literal>mips-sgi-irix5</Literal>,
+<Literal>sparc-sun-sunos4</Literal>, <Literal>sparc-sun-solaris2</Literal>, <Literal>powerpc-ibm-aix</Literal>.
+</Para>
+
+<Para>
+Bear in mind that certain ``bundles'', e.g. parallel Haskell, may not
+work on all machines for which basic Haskell compiling is supported.
+</Para>
+
+<Para>
+Some libraries may only work on a limited number of platforms; for
+example, a sockets library is of no use unless the operating system
+supports the underlying BSDisms.
+</Para>
+
+<Sect2>
+<Title>What platforms the Haskell compiler (GHC) runs on</Title>
+
+<Para>
+<IndexTerm><Primary>fully-supported platforms</Primary></IndexTerm>
+<IndexTerm><Primary>native-code generator</Primary></IndexTerm>
+<IndexTerm><Primary>registerised ports</Primary></IndexTerm>
+<IndexTerm><Primary>unregisterised ports</Primary></IndexTerm>
+</Para>
+
+<Para>
+The GHC hierarchy of Porting Goodness: (a) Best is a native-code
+generator; (b) next best is a ``registerised''
+port; (c) the bare minimum is an ``unregisterised'' port.
+(``Unregisterised'' is so terrible that we won't say more about it).
+</Para>
+
+<Para>
+We use Sparcs running Solaris 2.5, x86 boxes running FreeBSD and
+Linux, and DEC Alphas running OSF/1 V2.0, so those are the
+``fully-supported'' platforms, unsurprisingly. All have native-code
+generators, for quicker compilations. The native-code generator for
+iX86 platforms (e.g., Linux ELF) is <Emphasis>nearly</Emphasis> working; but is not
+turned on by default.
+</Para>
+
+<Para>
+Here's everything that's known about GHC ports. We identify platforms
+by their ``canonical'' CPU/Manufacturer/OS triple.
+</Para>
+
+<Para>
+Note that some ports are fussy about which GCC version you use; or
+require GAS; or…
+</Para>
+
+<Para>
+<VariableList>
+
+<VarListEntry>
+<Term>alpha-dec-osf1:</Term>
+<ListItem>
+<Para>
+<IndexTerm><Primary>alpha-dec-osf1: fully supported</Primary></IndexTerm>
+</Para>
+
+<Para>
+(We have OSF/1 V3.0.) Fully supported, including native-code
+generator. We recommend GCC 2.6.x or later.
+</Para>
+</ListItem></VarListEntry>
+<VarListEntry>
+<Term>sparc-sun-sunos4:</Term>
+<ListItem>
+<Para>
+<IndexTerm><Primary>sparc-sun-sunos4: fully supported</Primary></IndexTerm>
+</Para>
+
+<Para>
+Fully supported, including native-code generator.
+</Para>
+</ListItem></VarListEntry>
+<VarListEntry>
+<Term>sparc-sun-solaris2:</Term>
+<ListItem>
+<Para>
+<IndexTerm><Primary>sparc-sun-solaris2: fully supported</Primary></IndexTerm>
+</Para>
+
+<Para>
+Fully supported, including native-code generator. A couple of quirks,
+though: (a) the profiling libraries are bizarrely huge when compiled
+with object splitting; (b) the default <Command>xargs</Command><IndexTerm><Primary>xargs</Primary></IndexTerm> program is
+atrociously bad for building GHC libraries (see <Xref LinkEnd="sec-pre-supposed"> for
+details).
+</Para>
+</ListItem></VarListEntry>
+<VarListEntry>
+<Term>HP-PA box running HP</Term>
+<ListItem>
+<Para>
+UX 9.x:/
+<IndexTerm><Primary>hppa1.1-hp-hpux: registerised port</Primary></IndexTerm>
+</Para>
+
+<Para>
+Works registerised. No native-code generator. For GCC, you're best
+off with one of the Utah releases of GCC 2.6.3 (`u3' or later), from
+<Literal>jaguar.cs.utah.edu</Literal>. We think a straight GCC 2.7.x works,
+too.
+</Para>
+
+<Para>
+Concurrent/Parallel Haskell probably don't work (yet).
+<IndexTerm><Primary>hppa1.1-hp-hpux: concurrent—no</Primary></IndexTerm>
+<IndexTerm><Primary>hppa1.1-hp-hpux: parallel—no</Primary></IndexTerm>
+</Para>
+</ListItem></VarListEntry>
+<VarListEntry>
+<Term>i386-*-linux (PCs running Linux—ELF format):</Term>
+<ListItem>
+<Para>
+<IndexTerm><Primary>i386-*-linux: registerised port</Primary></IndexTerm>
+</Para>
+
+<Para>
+GHC works registerised. You <Emphasis>must</Emphasis> have GCC 2.7.x or later. The
+iX86 native-code generator is <Emphasis>nearly</Emphasis> there, but it isn't turned
+on by default.
+</Para>
+
+<Para>
+Profiling works, and Concurrent Haskell works.
+<IndexTerm><Primary>i386-*-linux: profiling—yes</Primary></IndexTerm>
+<IndexTerm><Primary>i386-*-linux: concurrent—yes</Primary></IndexTerm>
+Parallel Haskell probably works.
+<IndexTerm><Primary>i386-*-linux: parallel—maybe</Primary></IndexTerm>
+</Para>
+
+<Para>
+On old Linux a.out systems: should be the same.
+<IndexTerm><Primary>i386-*-linuxaout: registerised port</Primary></IndexTerm>
+</Para>
+</ListItem></VarListEntry>
+<VarListEntry>
+<Term>i386-*-freebsd (PCs running FreeBSD 2.2 or higher, and
+NetBSD/OpenBSD using FreeBSD emulation):</Term>
+<ListItem>
+<Para>
+<IndexTerm><Primary>i386-*-freebsd:registerised port</Primary></IndexTerm>
+</Para>
+
+<Para>
+GHC works registerised. Supports same set of bundles as the above.
+</Para>
+
+<Para>
+<IndexTerm><Primary>i386-*-freebsd: profiling—yes</Primary></IndexTerm>
+<IndexTerm><Primary>i386-*-freebsd: concurrent—yes</Primary></IndexTerm>
+<IndexTerm><Primary>i386-*-freebsd: parallel—maybe</Primary></IndexTerm>
+</Para>
+</ListItem></VarListEntry>
+<VarListEntry>
+<Term>i386-unknown-cygwin32:</Term>
+<ListItem>
+<Para>
+<IndexTerm><Primary>i386-unknown-cygwin32: fully supported</Primary></IndexTerm>
+</Para>
+
+<Para>
+Fully supported under Win95/NT, including a native code
+generator. Requires the <Literal>cygwin32</Literal> compatibility library and a
+healthy collection of GNU tools (i.e., gcc, GNU ld, bash etc.)
+Profiling works, so does Concurrent Haskell.
+</Para>
+
+<Para>
+<IndexTerm><Primary>i386-*-cygwin32: profiling—yes</Primary></IndexTerm>
+<IndexTerm><Primary>i386-*-cygwin32: concurrent—yes</Primary></IndexTerm>
+</Para>
+</ListItem></VarListEntry>
+<VarListEntry>
+<Term>mips-sgi-irix5:</Term>
+<ListItem>
+<Para>
+<IndexTerm><Primary>mips-sgi-irix5: registerised port</Primary></IndexTerm>
+</Para>
+
+<Para>
+GHC works registerised (no native-code generator). I suspect any
+GCC 2.6.x (or later) is OK. The GCC that I used was built with
+<Option>--with-gnu-as</Option>; turns out that is important!
+</Para>
+
+<Para>
+Concurrent/Parallel Haskell probably don't work (yet).
+Profiling might work, but it is untested.
+<IndexTerm><Primary>mips-sgi-irix5: concurrent—no</Primary></IndexTerm>
+<IndexTerm><Primary>mips-sgi-irix5: parallel—no</Primary></IndexTerm>
+<IndexTerm><Primary>mips-sgi-irix5: profiling—maybe</Primary></IndexTerm>
+</Para>
+</ListItem></VarListEntry>
+<VarListEntry>
+<Term>mips-sgi-irix6:</Term>
+<ListItem>
+<Para>
+<IndexTerm><Primary>mips-sgi-irix6: registerised port</Primary></IndexTerm>
+</Para>
+
+<Para>
+Thanks to the fine efforts of Tomasz Cholewo <ULink
+URL="mailto:tjchol01@mecca.spd.louisville.edu"
+>tjchol01@mecca.spd.louisville.edu</ULink
+>, GHC works registerised (no
+native code generator) under IRIX 6.2 and 6.3. Depends on having a
+<ULink
+URL="http://mecca.spd.louisville.edu/~tjchol01/software/"
+>specially tweaked version of gcc-2.7.2 around</ULink>.
+</Para>
+
+<Para>
+Profiling works, Concurrent/Parallel Haskell might work (AFAIK, untested).
+<IndexTerm><Primary>mips-sgi-irix6: concurrent—maybe</Primary></IndexTerm>
+<IndexTerm><Primary>mips-sgi-irix6: parallel—maybe</Primary></IndexTerm>
+<IndexTerm><Primary>mips-sgi-irix6: profiling—yes</Primary></IndexTerm>
+</Para>
+</ListItem></VarListEntry>
+<VarListEntry>
+<Term>powerpc-ibm-aix:</Term>
+<ListItem>
+<Para>
+<IndexTerm><Primary>powerpc-ibm-aix: registerised port</Primary></IndexTerm>
+GHC works registerised (no native-code generator…yet).
+I suspect 2.7.x is what you need together with this.
+</Para>
+
+<Para>
+Concurrent/Parallel Haskell probably don't work (yet).
+Profiling might work, but it is untested.
+<IndexTerm><Primary>mips-sgi-irix5: concurrent—no</Primary></IndexTerm>
+<IndexTerm><Primary>mips-sgi-irix5: parallel—no</Primary></IndexTerm>
+<IndexTerm><Primary>mips-sgi-irix5: profiling—maybe</Primary></IndexTerm>
+</Para>
+</ListItem></VarListEntry>
+<VarListEntry>
+<Term>m68k-apple-macos7 (Mac, using MPW):</Term>
+<ListItem>
+<Para>
+<IndexTerm><Primary>m68k-apple-macos7: historically ported</Primary></IndexTerm>
+Once upon a time, David Wright in Tasmania has actually
+gotten GHC to run on a Macintosh. Ditto James Thomson here at Glasgow.
+You may be able to get Thomson's from here. (Not sure that it will
+excite you to death, but…)
+</Para>
+
+<Para>
+No particularly recent GHC is known to work on a Mac.
+</Para>
+</ListItem></VarListEntry>
+<VarListEntry>
+<Term>m68k-next-nextstep3:</Term>
+<ListItem>
+<Para>
+<IndexTerm><Primary>m68k-next-nextstep3: historically ported</Primary></IndexTerm>
+Carsten Schultz succeeded with a ``registerised'' port of GHC 0.29.
+There's probably a little bit-rot since then, but otherwise it should
+still be fine.
+</Para>
+
+<Para>
+Concurrent/Parallel Haskell probably won't work (yet).
+<IndexTerm><Primary>m68k-next-nextstep3: concurrent—no</Primary></IndexTerm>
+<IndexTerm><Primary>m68k-next-nextstep3: parallel—no</Primary></IndexTerm>
+</Para>
+</ListItem></VarListEntry>
+<VarListEntry>
+<Term>m68k-sun-sunos4 (Sun3):</Term>
+<ListItem>
+<Para>
+<IndexTerm><Primary>m68k-sun-sunos4: registerised
+port</Primary></IndexTerm> GHC 2.0x and 3.0x haven't been tried on a Sun3. GHC 0.26
+worked registerised. No native-code generator.
+</Para>
+
+<Para>
+Concurrent/Parallel Haskell probably don't work (yet).
+<IndexTerm><Primary>m68k-sun-sunos4: concurrent—no</Primary></IndexTerm>
+<IndexTerm><Primary>m68k-sun-sunos4: parallel—no</Primary></IndexTerm>
+</Para>
+</ListItem></VarListEntry>
+</VariableList>
+</Para>
+
+</Sect2>
+
+<Sect2>
+<Title>What machines the other tools run on</Title>
+
+<Para>
+Unless you hear otherwise, the other tools work if GHC works.
+</Para>
+
+<Para>
+Haggis requires Concurrent Haskell to work.
+<IndexTerm><Primary>Haggis, Concurrent Haskell</Primary></IndexTerm>
+</Para>
+
+</Sect2>
+
+</Sect1>
+
+
+<Sect1 id="sec-pre-supposed">
+<Title>Installing pre-supposed utilities
+
+<IndexTerm><Primary>pre-supposed utilities</Primary></IndexTerm>
+<IndexTerm><Primary>utilities, pre-supposed</Primary></IndexTerm></Title>
+
+<Para>
+Here are the gory details about some utility programs you may need;
+<Command>perl</Command> and <Command>gcc</Command> are the only important ones. (PVM<IndexTerm><Primary>PVM</Primary></IndexTerm> is important
+if you're going for Parallel Haskell.) The <Command>configure</Command><IndexTerm><Primary>configure</Primary></IndexTerm>
+script will tell you if you are missing something.
+</Para>
+
+<Para>
+<VariableList>
+
+<VarListEntry>
+<Term>Perl:</Term>
+<ListItem>
+<Para>
+<IndexTerm><Primary>pre-supposed: Perl</Primary></IndexTerm>
+<IndexTerm><Primary>Perl, pre-supposed</Primary></IndexTerm>
+<Emphasis>You have to have Perl to proceed!</Emphasis> Perl is a language quite good
+for doing shell-scripty tasks that involve lots of text processing.
+It is pretty easy to install.
+</Para>
+
+<Para>
+Perl 5 is required. For Win32 platforms, we strongly suggest you pick
+up a port of Perl 5 for <Literal>cygwin32</Literal>, as the common Hip/ActiveWare port
+of Perl is Not Cool Enough for our purposes.
+</Para>
+
+<Para>
+Perl should be put somewhere so that it can be invoked by the <Literal>#!</Literal>
+script-invoking mechanism. (I believe <Filename>/usr/bin/perl</Filename> is preferred;
+we use <Filename>/usr/local/bin/perl</Filename> at Glasgow.) The full pathname should
+may need to be less than 32 characters long on some systems.
+</Para>
+</ListItem></VarListEntry>
+<VarListEntry>
+<Term>GNU C (<Command>gcc</Command>):</Term>
+<ListItem>
+<Para>
+<IndexTerm><Primary>pre-supposed: GCC (GNU C compiler)</Primary></IndexTerm>
+<IndexTerm><Primary>GCC (GNU C compiler), pre-supposed</Primary></IndexTerm>
+</Para>
+
+<Para>
+Versions 2.7.2.x, 2.8.1 and egcs 1.1.2 are known to work. Use other
+versions at your own risk!
+</Para>
+
+<Para>
+If your GCC dies with ``internal error'' on some GHC source file,
+please let us know, so we can report it and get things improved.
+(Exception: on iX86 boxes—you may need to fiddle with GHC's
+<Option>-monly-N-regs</Option> option; see the User's Guide)
+</Para>
+</ListItem></VarListEntry>
+<VarListEntry>
+<Term><Command>xargs</Command> on Solaris2:</Term>
+<ListItem>
+<Para>
+<IndexTerm><Primary>xargs, presupposed (Solaris only)</Primary></IndexTerm>
+<IndexTerm><Primary>Solaris: alternative xargs</Primary></IndexTerm>
+The GHC libraries are put together with something like:
+
+<ProgramListing>
+find bunch-of-dirs -name '*.o' -print | xargs ar q ...
+</ProgramListing>
+
+Unfortunately the Solaris <Command>xargs</Command> (the shell-script equivalent
+of <Function>map</Function>) only ``bites off'' the <Filename>.o</Filename> files a few at a
+time—with near-infinite rebuilding of the symbol table in
+the <Filename>.a</Filename> file.
+</Para>
+
+<Para>
+The best solution is to install a sane <Command>xargs</Command> from the GNU
+findutils distribution. You can unpack, build, and install the GNU
+version in the time the Solaris <Command>xargs</Command> mangles just one GHC
+library.
+</Para>
+</ListItem></VarListEntry>
+<VarListEntry>
+<Term>Autoconf:</Term>
+<ListItem>
+<Para>
+<IndexTerm><Primary>pre-supposed: Autoconf</Primary></IndexTerm>
+<IndexTerm><Primary>Autoconf, pre-supposed</Primary></IndexTerm>
+</Para>
+
+<Para>
+GNU Autoconf is needed if you intend to build from the CVS sources, it
+is <Emphasis>not</Emphasis> needed if you just intend to build a standard source
+distribution.
+</Para>
+
+<Para>
+Autoconf builds the <Command>configure</Command> script from <Filename>configure.in</Filename> and
+<Filename>aclocal.m4</Filename>. If you modify either of these files, you'll need
+Autoconf to rebuild <Filename>configure</Filename>.
+</Para>
+</ListItem></VarListEntry>
+<VarListEntry>
+<Term><Command>sed</Command></Term>
+<ListItem>
+<Para>
+<IndexTerm><Primary>pre-supposed: sed</Primary></IndexTerm>
+<IndexTerm><Primary>sed, pre-supposed</Primary></IndexTerm>
+You need a working <Command>sed</Command> if you are going to build from sources. The
+build-configuration stuff needs it. GNU sed version 2.0.4 is no good!
+It has a bug in it that is tickled by the build-configuration. 2.0.5
+is OK. Others are probably OK too (assuming we don't create too
+elaborate configure scripts.)
+</Para>
+</ListItem></VarListEntry>
+</VariableList>
+</Para>
+
+<Para>
+One <Literal>fptools</Literal> project is worth a quick note at this point, because it
+is useful for all the others: <Literal>glafp-utils</Literal> contains several utilities
+which aren't particularly Glasgow-ish, but Occasionally Indispensable.
+Like <Command>lndir</Command> for creating symbolic link trees.
+</Para>
+
+<Sect2 id="pre-supposed-gph-tools">
+<Title>Tools for building parallel GHC (GPH)
+</Title>
+
+<Para>
+<VariableList>
+
+<VarListEntry>
+<Term>PVM version 3:</Term>
+<ListItem>
+<Para>
+<IndexTerm><Primary>pre-supposed: PVM3 (Parallel Virtual Machine)</Primary></IndexTerm>
+<IndexTerm><Primary>PVM3 (Parallel Virtual Machine), pre-supposed</Primary></IndexTerm>
+</Para>
+
+<Para>
+PVM is the Parallel Virtual Machine on which Parallel Haskell programs
+run. (You only need this if you plan to run Parallel Haskell.
+Concurent Haskell, which runs concurrent threads on a uniprocessor
+doesn't need it.) Underneath PVM, you can have (for example) a
+network of workstations (slow) or a multiprocessor box (faster).
+</Para>
+
+<Para>
+The current version of PVM is 3.3.11; we use 3.3.7. It is readily
+available on the net; I think I got it from <Literal>research.att.com</Literal>, in
+<Filename>netlib</Filename>.
+</Para>
+
+<Para>
+A PVM installation is slightly quirky, but easy to do. Just follow
+the <Filename>Readme</Filename> instructions.
+</Para>
+</ListItem></VarListEntry>
+<VarListEntry>
+<Term><Command>bash</Command>:</Term>
+<ListItem>
+<Para>
+<IndexTerm><Primary>bash, presupposed (Parallel Haskell only)</Primary></IndexTerm>
+Sadly, the <Command>gr2ps</Command> script, used to convert ``parallelism profiles''
+to PostScript, is written in Bash (GNU's Bourne Again shell).
+This bug will be fixed (someday).
+</Para>
+</ListItem></VarListEntry>
+</VariableList>
+</Para>
+
+</Sect2>
+
+<Sect2 id="pre-supposed-doc-tools">
+<Title>Tools for building the Documentation
+</Title>
+
+<Para>
+The following additional tools are required if you want to format the
+documentation that comes with the <Literal>fptools</Literal> projects:
+</Para>
+
+<Para>
+<VariableList>
+
+<VarListEntry>
+<Term>DocBook:</Term>
+<ListItem>
+<Para>
+<IndexTerm><Primary>pre-supposed: DocBook</Primary></IndexTerm>
+<IndexTerm><Primary>DocBook, pre-supposed</Primary></IndexTerm>
+All our documentation is written in SGML, using the DocBook DTD and processed using the <ULink URL="http://sourceware.cygnus.com/docbook-tools/">Cygnus DocBook tools</ULink>, which is the most shrink-wrapped SGML suite
+that we could find. Unfortunately, it's only packaged as RPMs. You can use it to generate HTML (and
+hence DVI, PDF and Postscript) and RTF from any
+LinuxDoc source file (including this manual).
+</Para>
+</ListItem></VarListEntry>
+<VarListEntry>
+<Term>TeX:</Term>
+<ListItem>
+<Para>
+<IndexTerm><Primary>pre-supposed: TeX</Primary></IndexTerm>
+<IndexTerm><Primary>TeX, pre-supposed</Primary></IndexTerm>
+A decent TeX distribution is required if you want to produce printable
+documentation. We recomment teTeX, which includes just about
+everything you need.
+</Para>
+</ListItem></VarListEntry>
+</VariableList>
+</Para>
+
+</Sect2>
+
+<Sect2 id="pre-supposed-other-tools">
+<Title>Other useful tools
+</Title>
+
+<Para>
+<VariableList>
+
+<VarListEntry>
+<Term>Flex:</Term>
+<ListItem>
+<Para>
+<IndexTerm><Primary>pre-supposed: flex</Primary></IndexTerm>
+<IndexTerm><Primary>flex, pre-supposed</Primary></IndexTerm>
+</Para>
+
+<Para>
+This is a quite-a-bit-better-than-Lex lexer. Used to build a couple
+of utilities in <Literal>glafp-utils</Literal>. Depending on your operating system,
+the supplied <Command>lex</Command> may or may not work; you should get the GNU
+version.
+</Para>
+</ListItem></VarListEntry>
+</VariableList>
+</Para>
+
+</Sect2>
+
+</Sect1>
+
+<Sect1 id="sec-building-from-source">
+<Title>Building from source
+
+<IndexTerm><Primary>Building from source</Primary></IndexTerm>
+<IndexTerm><Primary>Source, building from</Primary></IndexTerm></Title>
+
+<Para>
+You've been rash enough to want to build some of
+the Glasgow Functional Programming tools (GHC, Happy,
+nofib, etc.) from source. You've slurped the source,
+from the CVS repository or from a source distribution, and
+now you're sitting looking at a huge mound of bits, wondering
+what to do next.
+</Para>
+
+<Para>
+Gingerly, you type <Command>make</Command>. Wrong already!
+</Para>
+
+<Para>
+This rest of this guide is intended for duffers like me, who aren't
+really interested in Makefiles and systems configurations, but who
+need a mental model of the interlocking pieces so that they can make
+them work, extend them consistently when adding new software, and lay
+hands on them gently when they don't work.
+</Para>
+
+<Sect2 id="sec-source-tree">
+<Title>Your source tree
+</Title>
+
+<Para>
+The source code is held in your <Emphasis>source tree</Emphasis>.
+The root directory of your source tree <Emphasis>must</Emphasis>
+contain the following directories and files:
+</Para>
+
+<Para>
+
+<ItemizedList>
+<ListItem>
+
+<Para>
+<Filename>Makefile</Filename>: the root Makefile.
+</Para>
+</ListItem>
+<ListItem>
+
+<Para>
+<Filename>mk/</Filename>: the directory that contains the
+main Makefile code, shared by all the
+<Literal>fptools</Literal> software.
+</Para>
+</ListItem>
+<ListItem>
+
+<Para>
+ <Filename>configure.in</Filename>, <Filename>config.sub</Filename>, <Filename>config.guess</Filename>:
+these files support the configuration process.
+</Para>
+</ListItem>
+<ListItem>
+
+<Para>
+ <Filename>install-sh</Filename>.
+</Para>
+</ListItem>
+
+</ItemizedList>
+
+</Para>
+
+<Para>
+All the other directories are individual <Emphasis>projects</Emphasis> of the
+<Literal>fptools</Literal> system—for example, the Glasgow Haskell Compiler
+(<Literal>ghc</Literal>), the Happy parser generator (<Literal>happy</Literal>), the <Literal>nofib</Literal> benchmark
+suite, and so on. You can have zero or more of these. Needless to
+say, some of them are needed to build others.
+</Para>
+
+<Para>
+The important thing to remember is that even if you want only one
+project (<Literal>happy</Literal>, say), you must have a source tree whose root
+directory contains <Filename>Makefile</Filename>, <Filename>mk/</Filename>, <Filename>configure.in</Filename>, and the
+project(s) you want (<Filename>happy/</Filename> in this case). You cannot get by with
+just the <Filename>happy/</Filename> directory.
+</Para>
+
+</Sect2>
+
+<Sect2>
+<Title>Build trees
+<IndexTerm><Primary>build trees</Primary></IndexTerm>
+<IndexTerm><Primary>link trees, for building</Primary></IndexTerm></Title>
+
+<Para>
+While you can build a system in the source tree, we don't recommend it.
+We often want to build multiple versions of our software
+for different architectures, or with different options (e.g. profiling).
+It's very desirable to share a single copy of the source code among
+all these builds.
+</Para>
+
+<Para>
+So for every source tree we have zero or more <Emphasis>build trees</Emphasis>. Each
+build tree is initially an exact copy of the source tree, except that
+each file is a symbolic link to the source file, rather than being a
+copy of the source file. There are ``standard'' Unix utilities that
+make such copies, so standard that they go by different names:
+<Command>lndir</Command><IndexTerm><Primary>lndir</Primary></IndexTerm>, <Command>mkshadowdir</Command><IndexTerm><Primary>mkshadowdir</Primary></IndexTerm> are two (If you
+don't have either, the source distribution includes sources for the
+X11 <Command>lndir</Command>—check out <Filename>fptools/glafp-utils/lndir</Filename>). See <Xref LinkEnd="sec-storysofar"> for a typical invocation.
+</Para>
+
+<Para>
+The build tree does not need to be anywhere near the source tree in
+the file system. Indeed, one advantage of separating the build tree
+from the source is that the build tree 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—<XRef LinkEnd="sec-build-config"> <Emphasis>absolutely everything in the build tree is either
+a symbolic link to the source tree, or else is mechanically
+generated</Emphasis>. It should be perfectly OK for your build tree to vanish
+overnight; an hour or two compiling and you're on the road again.
+</Para>
+
+<Para>
+You need to be a bit careful, though, that any new files you create
+(if you do any development work) are in the source tree, not a build tree!
+</Para>
+
+<Para>
+Remember, that the source files in the build tree are <Emphasis>symbolic
+links</Emphasis> to the files in the source tree. (The build tree soon
+accumulates lots of built files like <Filename>Foo.o</Filename>, as well.) You
+can <Emphasis>delete</Emphasis> a source file from the build tree without affecting
+the source tree (though it's an odd thing to do). On the other hand,
+if you <Emphasis>edit</Emphasis> a source file from the build tree, you'll edit the
+source-tree file directly. (You can set up Emacs so that if you edit
+a source file from the build tree, Emacs will silently create an
+edited copy of the source file in the build tree, leaving the source
+file unchanged; but the danger is that you think you've edited the
+source file whereas actually all you've done is edit the build-tree
+copy. More commonly you do want to edit the source file.)
+</Para>
+
+<Para>
+Like the source tree, the top level of your build tree must be (a
+linked copy of) the root directory of the <Literal>fptools</Literal> suite. Inside
+Makefiles, the root of your build tree is called
+<Constant>$(FPTOOLS_TOP)</Constant><IndexTerm><Primary>FPTOOLS_TOP</Primary></IndexTerm>. In the rest of this document path
+names are relative to <Constant>$(FPTOOLS_TOP)</Constant> unless otherwise stated. For
+example, the file <Filename>ghc/mk/target.mk</Filename> is actually
+<Filename><Constant>$(FPTOOLS_TOP)</Constant>/ghc/mk/target.mk</Filename>.
+</Para>
+
+</Sect2>
+
+<Sect2 id="sec-build-config">
+<Title>Getting the build you want
+</Title>
+
+<Para>
+When you build <Literal>fptools</Literal> you will be compiling code on a particular
+<Emphasis>host platform</Emphasis>, to run on a particular <Emphasis>target platform</Emphasis>
+(usually the same as the host platform)<IndexTerm><Primary>platform</Primary></IndexTerm>. The
+difficulty is that there are minor differences between different
+platforms; minor, but enough that the code needs to be a bit different
+for each. There are some big differences too: for a different
+architecture we need to build GHC with a different native-code
+generator.
+</Para>
+
+<Para>
+There are also knobs you can turn to control how the <Literal>fptools</Literal>
+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.
+</Para>
+
+<Para>
+All of this stuff is called the <Emphasis>configuration</Emphasis> of your build.
+You set the configuration using a three-step process.
+<VariableList>
+
+<VarListEntry>
+<Term>Step 1: get ready for configuration.</Term>
+<ListItem>
+<Para>
+Change directory to
+<Constant>$(FPTOOLS_TOP)</Constant> and issue the command <Command>autoconf</Command><IndexTerm><Primary>autoconf</Primary></IndexTerm> (with
+no arguments). This GNU program converts <Filename><Constant>$(FPTOOLS_TOP)</Constant>/configure.in</Filename>
+to a shell script called <Filename><Constant>$(FPTOOLS_TOP)</Constant>/configure</Filename>.
+</Para>
+
+<Para>
+Both these steps are completely platform-independent; they just mean
+that the human-written file (<Filename>configure.in</Filename>) can be short, although
+the resulting shell script, <Command>configure</Command>, and <Filename>mk/config.h.in</Filename>, are
+long.
+</Para>
+
+<Para>
+In case you don't have <Command>autoconf</Command> we distribute the results,
+<Command>configure</Command>, and <Filename>mk/config.h.in</Filename>, with the source distribution. They
+aren't kept in the repository, though.
+</Para>
+</ListItem></VarListEntry>
+<VarListEntry>
+<Term>Step 2: system configuration.</Term>
+<ListItem>
+<Para>
+Runs the newly-created <Command>configure</Command> script, thus:
+
+<ProgramListing>
+./configure
+</ProgramListing>
+
+<Command>configure</Command>'s mission is to scurry round your computer working out
+what architecture it has, what operating system, whether it has the
+<Function>vfork</Function> system call, where <Command>yacc</Command> is kept, whether <Command>gcc</Command> is available,
+where various obscure <Literal>#include</Literal> files are, whether it's a leap year,
+and what the systems manager had for lunch. It communicates these
+snippets of information in two ways:
+</Para>
+
+<Para>
+
+<ItemizedList>
+<ListItem>
+
+<Para>
+ It translates <Filename>mk/config.mk.in</Filename><IndexTerm><Primary>config.mk.in</Primary></IndexTerm> to
+<Filename>mk/config.mk</Filename><IndexTerm><Primary>config.mk</Primary></IndexTerm>, substituting for things between
+``<Literal>@</Literal>'' brackets. So, ``<Literal>@HaveGcc@</Literal>'' will be replaced by
+``<Literal>YES</Literal>'' or ``<Literal>NO</Literal>'' depending on what <Command>configure</Command> finds.
+<Filename>mk/config.mk</Filename> is included by every Makefile (directly or indirectly),
+so the configuration information is thereby communicated to all
+Makefiles.
+
+</Para>
+</ListItem>
+<ListItem>
+
+<Para>
+ It translates <Filename>mk/config.h.in</Filename><IndexTerm><Primary>config.h.in</Primary></IndexTerm> to
+<Filename>mk/config.h</Filename><IndexTerm><Primary>config.h</Primary></IndexTerm>. The latter is <Literal>#include</Literal>d by various C
+programs, which can thereby make use of configuration information.
+
+</Para>
+</ListItem>
+
+</ItemizedList>
+
+</Para>
+
+<Para>
+<Command>configure</Command> caches the results of its run in <Filename>config.cache</Filename>. Quite
+often you don't want that; you're running <Command>configure</Command> a second time
+because something has changed. In that case, simply delete
+<Filename>config.cache</Filename>.
+</Para>
+</ListItem></VarListEntry>
+<VarListEntry>
+<Term>Step 3: build configuration.</Term>
+<ListItem>
+<Para>
+Next, you say how this build of <Literal>fptools</Literal> is to differ from the
+standard defaults by creating a new file <Filename>mk/build.mk</Filename><IndexTerm><Primary>build.mk</Primary></IndexTerm>
+<Emphasis>in the build tree</Emphasis>. This file is the one and only file you edit
+in the build tree, precisely because it says how this build differs
+from the source. (Just in case your build tree does die, you might
+want to keep a private directory of <Filename>build.mk</Filename> files, and use a
+symbolic link in each build tree to point to the appropriate one.) So
+<Filename>mk/build.mk</Filename> never exists in the source tree—you create one in
+each build tree from the template. We'll discuss what to put in it
+shortly.
+</Para>
+</ListItem></VarListEntry>
+</VariableList>
+</Para>
+
+<Para>
+And that's it for configuration. Simple, eh?
+</Para>
+
+<Para>
+What do you put in your build-specific configuration file
+<Filename>mk/build.mk</Filename>? <Emphasis>For almost all purposes all you will do is put
+make variable definitions that override those in</Emphasis> <Filename>mk/config.mk.in</Filename>.
+The whole point of <Filename>mk/config.mk.in</Filename>—and its derived counterpart
+<Filename>mk/config.mk</Filename>—is to define the build configuration. It is heavily
+commented, as you will see if you look at it. So generally, what you
+do is look at <Filename>mk/config.mk.in</Filename>, and add definitions in <Filename>mk/build.mk</Filename>
+that override any of the <Filename>config.mk</Filename> definitions that you want to
+change. (The override occurs because the main boilerplate file,
+<Filename>mk/boilerplate.mk</Filename><IndexTerm><Primary>boilerplate.mk</Primary></IndexTerm>, includes <Filename>build.mk</Filename> after
+<Filename>config.mk</Filename>.)
+</Para>
+
+<Para>
+For example, <Filename>config.mk.in</Filename> contains the definition:
+</Para>
+
+<Para>
+
+<ProgramListing>
+ProjectsToBuild = glafp-utils ghc hslibs
+</ProgramListing>
+
+</Para>
+
+<Para>
+The accompanying comment explains that this is the list of enabled
+projects; that is, if (after configuring) you type <Command>gmake all</Command> in
+<Constant>FPTOOLS_TOP</Constant> three specified projects will be made. If you want to
+add <Command>green-card</Command>, you can add this line to <Filename>build.mk</Filename>:
+</Para>
+
+<Para>
+
+<ProgramListing>
+ProjectsToBuild += green-card
+</ProgramListing>
+
+</Para>
+
+<Para>
+or, if you prefer,
+</Para>
+
+<Para>
+
+<ProgramListing>
+ProjectsToBuild = glafp-utils ghc green-card
+</ProgramListing>
+
+</Para>
+
+<Para>
+(GNU <Command>make</Command> allows existing definitions to have new text appended
+using the ``<Literal>+=</Literal>'' operator, which is quite a convenient feature.)
+</Para>
+
+<Para>
+When reading <Filename>config.mk.in</Filename>, remember that anything between
+``@...@'' signs is going to be substituted by <Command>configure</Command>
+later. You <Emphasis>can</Emphasis> override the resulting definition if you want,
+but you need to be a bit surer what you are doing. For example,
+there's a line that says:
+</Para>
+
+<Para>
+
+<ProgramListing>
+YACC = @YaccCmd@
+</ProgramListing>
+
+</Para>
+
+<Para>
+This defines the Make variables <Constant>YACC</Constant> to the pathname for a <Command>yacc</Command> that
+<Command>configure</Command> finds somewhere. If you have your own pet <Command>yacc</Command> you want
+to use instead, that's fine. Just add this line to <Filename>mk/build.mk</Filename>:
+</Para>
+
+<Para>
+
+<ProgramListing>
+YACC = myyacc
+</ProgramListing>
+
+</Para>
+
+<Para>
+You do not <Emphasis>have</Emphasis> to have a <Filename>mk/build.mk</Filename> file at all; if you
+don't, you'll get all the default settings from <Filename>mk/config.mk.in</Filename>.
+</Para>
+
+<Para>
+You can also use <Filename>build.mk</Filename> to override anything that <Command>configure</Command> got
+wrong. One place where this happens often is with the definition of
+<Constant>FPTOOLS_TOP_ABS</Constant>: 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 <Command>configure</Command> has got it wrong, just put the correct definition in
+<Filename>build.mk</Filename>.
+</Para>
+
+</Sect2>
+
+<Sect2 id="sec-storysofar">
+<Title>The story so far</Title>
+
+<Para>
+Let's summarise the steps you need to carry to get yourself
+a fully-configured build tree from scratch.
+</Para>
+
+<Para>
+
+<OrderedList>
+<ListItem>
+
+<Para>
+ Get your source tree from somewhere (CVS repository or source
+distribution). Say you call the root directory <Filename>myfptools</Filename> (it
+does not have to be called <Filename>fptools</Filename>). Make sure that you have
+the essential files (see <XRef LinkEnd="sec-source-tree">).
+
+</Para>
+</ListItem>
+<ListItem>
+
+<Para>
+ Use <Command>lndir</Command> or <Command>mkshadowdir</Command> to create a build tree.
+
+<ProgramListing>
+cd myfptools
+mkshadowdir . /scratch/joe-bloggs/myfptools-sun4
+</ProgramListing>
+
+(N.B. <Command>mkshadowdir</Command>'s first argument is taken relative to its second.) You probably want to give the build tree a name that
+suggests its main defining characteristic (in your mind at least),
+in case you later add others.
+
+</Para>
+</ListItem>
+<ListItem>
+
+<Para>
+ Change directory to the build tree. Everything is going
+to happen there now.
+
+<ProgramListing>
+cd /scratch/joe-bloggs/myfptools-sun4
+</ProgramListing>
+
+</Para>
+</ListItem>
+<ListItem>
+
+<Para>
+ Prepare for system configuration:
+
+<ProgramListing>
+autoconf
+</ProgramListing>
+
+(You can skip this step if you are starting from a source distribution,
+and you already have <Filename>configure</Filename> and <Filename>mk/config.h.in</Filename>.)
+
+</Para>
+</ListItem>
+<ListItem>
+
+<Para>
+ Do system configuration:
+
+<ProgramListing>
+./configure
+</ProgramListing>
+
+
+</Para>
+</ListItem>
+<ListItem>
+
+<Para>
+ Create the file <Filename>mk/build.mk</Filename>,
+adding definitions for your desired configuration options.
+
+<ProgramListing>
+emacs mk/build.mk
+</ProgramListing>
+
+</Para>
+</ListItem>
+
+</OrderedList>
+
+You can make subsequent changes to <Filename>mk/build.mk</Filename> 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 <Command>gmake clean</Command>, <Command>gmake all</Command>,
+because configuration option changes could affect anything—but in practice you are likely to know what's affected.
+</Para>
+
+</Sect2>
+
+<Sect2>
+<Title>Making things</Title>
+
+<Para>
+At this point you have made yourself a fully-configured build tree,
+so you are ready to start building real things.
+</Para>
+
+<Para>
+The first thing you need to know is that
+<Emphasis>you must use GNU <Command>make</Command>, usually called <Command>gmake</Command>, not standard Unix <Command>make</Command></Emphasis>.
+If you use standard Unix <Command>make</Command> you will get all sorts of error messages
+(but no damage) because the <Literal>fptools</Literal> <Command>Makefiles</Command> use GNU <Command>make</Command>'s facilities
+extensively.
+</Para>
+
+</Sect2>
+
+<Sect2 id="sec-standard-targets">
+<Title>Standard Targets
+
+<IndexTerm><Primary>targets, standard makefile</Primary></IndexTerm>
+<IndexTerm><Primary>makefile targets</Primary></IndexTerm></Title>
+
+<Para>
+In any directory you should be able to make the following:
+<VariableList>
+
+<VarListEntry>
+<Term><Literal>boot</Literal>:</Term>
+<ListItem>
+<Para>
+does the one-off preparation required to get ready for the real work.
+Notably, it does <Command>gmake depend</Command> in all directories that contain
+programs. It also builds the necessary tools for compilation to proceed.
+</Para>
+
+<Para>
+You should say <Command>gmake boot</Command> right after configuring your build tree,
+but note that this is a one-off, i.e., there's no need to re-do
+<Command>gmake boot</Command> if you should re-configure your build tree at a later
+stage (no harm caused if you do though).
+</Para>
+</ListItem></VarListEntry>
+<VarListEntry>
+<Term><Literal>all</Literal>:</Term>
+<ListItem>
+<Para>
+makes all the final target(s) for this Makefile.
+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 <Command>gmake</Command> alone is generally the same as typing <Command>gmake all</Command>.
+</Para>
+</ListItem></VarListEntry>
+<VarListEntry>
+<Term><Literal>install</Literal>:</Term>
+<ListItem>
+<Para>
+installs the things built by <Literal>all</Literal>. Where does it
+install them? That is specified by <Filename>mk/config.mk.in</Filename>; you can
+override it in <Filename>mk/build.mk</Filename>.
+</Para>
+</ListItem></VarListEntry>
+<VarListEntry>
+<Term><Literal>uninstall</Literal>:</Term>
+<ListItem>
+<Para>
+reverses the effect of <Literal>install</Literal>.
+</Para>
+</ListItem></VarListEntry>
+<VarListEntry>
+<Term><Literal>clean</Literal>:</Term>
+<ListItem>
+<Para>
+remove all easily-rebuilt files.
+</Para>
+</ListItem></VarListEntry>
+<VarListEntry>
+<Term><Literal>veryclean</Literal>:</Term>
+<ListItem>
+<Para>
+remove all files that can be rebuilt at all.
+There's a danger here that you may remove a file that needs a more
+obscure utility to rebuild it (especially if you started from a source
+distribution).
+</Para>
+</ListItem></VarListEntry>
+<VarListEntry>
+<Term><Literal>check</Literal>:</Term>
+<ListItem>
+<Para>
+run the test suite.
+</Para>
+</ListItem></VarListEntry>
+</VariableList>
+</Para>
+
+<Para>
+All of these standard targets automatically recurse into
+sub-directories. Certain other standard targets do not:
+</Para>
+
+<Para>
+<VariableList>
+
+<VarListEntry>
+<Term><Literal>configure</Literal>:</Term>
+<ListItem>
+<Para>
+is only available in the root directory
+<Constant>$(FPTOOLS_TOP)</Constant>; it has been discussed in <XRef LinkEnd="sec-build-config">.
+</Para>
+</ListItem></VarListEntry>
+<VarListEntry>
+<Term><Literal>depend</Literal>:</Term>
+<ListItem>
+<Para>
+make a <Filename>.depend</Filename> file in each directory that needs
+it. This <Filename>.depend</Filename> file contains mechanically-generated dependency
+information; for example, suppose a directory contains a Haskell
+source module <Filename>Foo.lhs</Filename> which imports another module <Literal>Baz</Literal>.
+Then the generated <Filename>.depend</Filename> file will contain the dependency:
+</Para>
+
+<Para>
+
+<ProgramListing>
+Foo.o : Baz.hi
+</ProgramListing>
+
+</Para>
+
+<Para>
+which says that the object file <Filename>Foo.o</Filename> depends on the interface file
+<Filename>Baz.hi</Filename> generated by compiling module <Literal>Baz</Literal>. The <Filename>.depend</Filename> file is
+automatically included by every Makefile.
+</Para>
+</ListItem></VarListEntry>
+<VarListEntry>
+<Term><Literal>binary-dist</Literal>:</Term>
+<ListItem>
+<Para>
+make a binary distribution. This is the
+target we use to build the binary distributions of GHC and Happy.
+</Para>
+</ListItem></VarListEntry>
+<VarListEntry>
+<Term><Literal>dist</Literal>:</Term>
+<ListItem>
+<Para>
+make a source distribution. You must be in a
+linked build tree to make this target.
+</Para>
+</ListItem></VarListEntry>
+</VariableList>
+</Para>
+
+<Para>
+Most <Filename>Makefile</Filename>s have targets other than these. You can discover them by looking in the <Filename>Makefile</Filename> itself.
+</Para>
+
+</Sect2>
+
+<Sect2>
+<Title>Fast Making
+<IndexTerm><Primary>fastmake</Primary></IndexTerm>
+<IndexTerm><Primary>dependencies, omitting</Primary></IndexTerm>
+<IndexTerm><Primary>FAST, makefile variable</Primary></IndexTerm></Title>
+
+<Para>
+Sometimes the dependencies get in the way: if you've made a small
+change to one file, and you're absolutely sure that it won't affect
+anything else, but you know that <Command>make</Command> is going to rebuild everything
+anyway, the following hack may be useful:
+</Para>
+
+<Para>
+
+<ProgramListing>
+gmake FAST=YES
+</ProgramListing>
+
+</Para>
+
+<Para>
+This tells the make system to ignore dependencies and just build what
+you tell it to. In other words, it's equivalent to temporarily
+removing the <Filename>.depend</Filename> file in the current directory (where
+<Command>mkdependHS</Command> and friends store their dependency information).
+</Para>
+
+<Para>
+A bit of history: GHC used to come with a <Command>fastmake</Command> script that did
+the above job, but GNU make provides the features we need to do it
+without resorting to a script. Also, we've found that fastmaking is
+less useful since the advent of GHC's recompilation checker (see the
+User's Guide section on "Separate Compilation").
+</Para>
+
+</Sect2>
+
+</Sect1>
+
+<Sect1>
+<Title>The <Filename>Makefile</Filename> architecture
+<IndexTerm><Primary>makefile architecture</Primary></IndexTerm></Title>
+
+<Para>
+<Command>make</Command> is great if everything works—you type <Command>gmake install</Command> 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 bowels of
+a directory you didn't know existed.
+</Para>
+
+<Para>
+The purpose of this section is to give you a road-map to help you figure
+out what is going right and what is going wrong.
+</Para>
+
+<Sect2>
+<Title>A small project</Title>
+
+<Para>
+To get started, let us look at the <Filename>Makefile</Filename> for an imaginary small
+<Literal>fptools</Literal> project, <Literal>small</Literal>. Each project in <Literal>fptools</Literal> has its own
+directory in <Constant>FPTOOLS_TOP</Constant>, so the <Literal>small</Literal> project will have its own
+directory <Constant>FPOOLS_TOP/small/</Constant>. Inside the <Filename>small/</Filename> directory there
+will be a <Filename>Makefile</Filename>, looking something like this:
+</Para>
+
+<Para>
+<IndexTerm><Primary>Makefile, minimal</Primary></IndexTerm>
+
+<ProgramListing>
+# Makefile for fptools project "small"
+
+TOP = ..
+include $(TOP)/mk/boilerplate.mk
+
+SRCS = $(wildcard *.lhs) $(wildcard *.c)
+HS_PROG = small
+
+include $(TOP)/target.mk
+</ProgramListing>
+
+</Para>
+
+<Para>
+This <Filename>Makefile</Filename> has three sections:
+</Para>
+
+<Para>
+
+<OrderedList>
+<ListItem>
+
+<Para>
+ The first section includes
+<FOOTNOTE>
+
+<Para>
+One of the most important
+features of GNU <Command>make</Command> that we use is the ability for a <Filename>Makefile</Filename> to
+include another named file, very like <Command>cpp</Command>'s <Literal>#include</Literal>
+directive.
+</Para>
+
+</FOOTNOTE>
+ a file of ``boilerplate'' code from the level
+above (which in this case will be
+<Filename><Constant>FPTOOLS_TOP</Constant>/mk/boilerplate.mk</Filename><IndexTerm><Primary>boilerplate.mk</Primary></IndexTerm>). As its name
+suggests, <Filename>boilerplate.mk</Filename> consists of a large quantity of standard
+<Filename>Makefile</Filename> code. We discuss this boilerplate in more detail in
+<XRef LinkEnd="sec-boiler">.
+<IndexTerm><Primary>include, directive in Makefiles</Primary></IndexTerm>
+<IndexTerm><Primary>Makefile inclusion</Primary></IndexTerm>
+
+Before the <Literal>include</Literal> statement, you must define the <Command>make</Command> variable
+<Constant>TOP</Constant><IndexTerm><Primary>TOP</Primary></IndexTerm> to be the directory containing the <Filename>mk</Filename> directory in
+which the <Filename>boilerplate.mk</Filename> file is. It is <Emphasis>not</Emphasis> OK to simply say
+
+
+<ProgramListing>
+include ../mk/boilerplate.mk # NO NO NO
+</ProgramListing>
+
+
+Why? Because the <Filename>boilerplate.mk</Filename> file needs to know where it is, so
+that it can, in turn, <Literal>include</Literal> other files. (Unfortunately, when an
+<Literal>include</Literal>d file does an <Literal>include</Literal>, the filename is treated relative to
+the directory in which <Command>gmake</Command> is being run, not the directory in
+which the <Literal>include</Literal>d sits.) In general, <Emphasis>every file <Filename>foo.mk</Filename>
+assumes that <Filename><Constant>$(TOP)</Constant>/mk/foo.mk</Filename> refers to itself.</Emphasis> It is up to the
+<Filename>Makefile</Filename> doing the <Literal>include</Literal> to ensure this is the case.
+
+Files intended for inclusion in other <Filename>Makefile</Filename>s are written to have
+the following property: <Emphasis>after <Filename>foo.mk</Filename> is <Literal>include</Literal>d, it leaves
+<Constant>TOP</Constant> containing the same value as it had just before the <Literal>include</Literal>
+statement</Emphasis>. In our example, this invariant guarantees that the
+<Literal>include</Literal> for <Filename>target.mk</Filename> will look in the same directory as that for
+<Filename>boilerplate.mk</Filename>.
+
+</Para>
+</ListItem>
+<ListItem>
+
+<Para>
+ The second section defines the following standard <Command>make</Command>
+variables: <Constant>SRCS</Constant><IndexTerm><Primary>SRCS</Primary></IndexTerm> (the source files from which is to be
+built), and <Constant>HS_PROG</Constant><IndexTerm><Primary>HS_PROG</Primary></IndexTerm> (the executable binary to be
+built). We will discuss in more detail what the ``standard
+variables'' are, and how they affect what happens, in <XRef LinkEnd="sec-targets">.
+
+The definition for <Constant>SRCS</Constant> uses the useful GNU <Command>make</Command> construct
+<Literal>$(wildcard $pat$)</Literal><IndexTerm><Primary>wildcard</Primary></IndexTerm>, which expands to a list of all
+the files matching the pattern <Literal>pat</Literal> in the current directory. In
+this example, <Constant>SRCS</Constant> is set to the list of all the <Filename>.lhs</Filename> and <Filename>.c</Filename>
+files in the directory. (Let's suppose there is one of each,
+<Filename>Foo.lhs</Filename> and <Filename>Baz.c</Filename>.)
+
+</Para>
+</ListItem>
+<ListItem>
+
+<Para>
+ The last section includes a second file of standard code,
+called <Filename>target.mk</Filename><IndexTerm><Primary>target.mk</Primary></IndexTerm>. It contains the rules that tell
+<Command>gmake</Command> how to make the standard targets (<Xref LinkEnd="sec-standard-targets">). Why, you ask,
+can't this standard code be part of <Filename>boilerplate.mk</Filename>? Good question.
+We discuss the reason later, in <Xref LinkEnd="sec-boiler-arch">.
+
+You do not <Emphasis>have</Emphasis> to <Literal>include</Literal> the <Filename>target.mk</Filename> file. Instead, you
+can write rules of your own for all the standard targets. Usually,
+though, you will find quite a big payoff from using the canned rules
+in <Filename>target.mk</Filename>; the price tag is that you have to understand what
+canned rules get enabled, and what they do (<Xref LinkEnd="sec-targets">).
+
+</Para>
+</ListItem>
+
+</OrderedList>
+
+</Para>
+
+<Para>
+In our example <Filename>Makefile</Filename>, most of the work is done by the two
+<Literal>include</Literal>d files. When you say <Command>gmake all</Command>, the following things
+happen:
+</Para>
+
+<Para>
+
+<ItemizedList>
+<ListItem>
+
+<Para>
+ <Command>gmake</Command> figures out that the object files are <Filename>Foo.o</Filename> and
+<Filename>Baz.o</Filename>.
+
+</Para>
+</ListItem>
+<ListItem>
+
+<Para>
+ It uses a boilerplate pattern rule to compile <Filename>Foo.lhs</Filename> to
+<Filename>Foo.o</Filename> using a Haskell compiler. (Which one? That is set in the
+build configuration.)
+
+</Para>
+</ListItem>
+<ListItem>
+
+<Para>
+ It uses another standard pattern rule to compile <Filename>Baz.c</Filename> to
+<Filename>Baz.o</Filename>, using a C compiler. (Ditto.)
+
+</Para>
+</ListItem>
+<ListItem>
+
+<Para>
+ It links the resulting <Filename>.o</Filename> files together to make <Literal>small</Literal>,
+using the Haskell compiler to do the link step. (Why not use <Command>ld</Command>?
+Because the Haskell compiler knows what standard libraries to link in.
+How did <Command>gmake</Command> know to use the Haskell compiler to do the link,
+rather than the C compiler? Because we set the variable <Constant>HS_PROG</Constant>
+rather than <Constant>C_PROG</Constant>.)
+
+</Para>
+</ListItem>
+
+</ItemizedList>
+
+</Para>
+
+<Para>
+All <Filename>Makefile</Filename>s should follow the above three-section format.
+</Para>
+
+</Sect2>
+
+<Sect2>
+<Title>A larger project</Title>
+
+<Para>
+Larger projects are usually structured into a number of sub-directories,
+each of which has its own <Filename>Makefile</Filename>. (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:
+</Para>
+
+<Para>
+
+<Screen>
+$(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...
+</Screen>
+
+</Para>
+
+<Para>
+The sub-directories <Filename>docs</Filename>, <Filename>driver</Filename>, <Filename>compiler</Filename>, and so on, each
+contains a sub-component of GHC, and each has its own <Filename>Makefile</Filename>.
+There must also be a <Filename>Makefile</Filename> in <Filename><Constant>$(FPTOOLS_TOP)</Constant>/ghc</Filename>. It does most
+of its work by recursively invoking <Command>gmake</Command> on the <Filename>Makefile</Filename>s in the
+sub-directories. We say that <Filename>ghc/Makefile</Filename> is a <Emphasis>non-leaf
+<Filename>Makefile</Filename></Emphasis>, because it does little except organise its children,
+while the <Filename>Makefile</Filename>s in the sub-directories are all <Emphasis>leaf
+<Filename>Makefile</Filename>s</Emphasis>. (In principle the sub-directories might themselves
+contain a non-leaf <Filename>Makefile</Filename> and several sub-sub-directories, but
+that does not happen in GHC.)
+</Para>
+
+<Para>
+The <Filename>Makefile</Filename> in <Filename>ghc/compiler</Filename> is considered a leaf <Filename>Makefile</Filename> even
+though the <Filename>ghc/compiler</Filename> has sub-directories, because these sub-directories
+do not themselves have <Filename>Makefile</Filename>s in them. They are just used to structure
+the collection of modules that make up GHC, but all are managed by the
+single <Filename>Makefile</Filename> in <Filename>ghc/compiler</Filename>.
+</Para>
+
+<Para>
+You will notice that <Filename>ghc/</Filename> also contains a directory <Filename>ghc/mk/</Filename>. It
+contains GHC-specific <Filename>Makefile</Filename> boilerplate code. More precisely:
+</Para>
+
+<Para>
+
+<ItemizedList>
+<ListItem>
+
+<Para>
+ <Filename>ghc/mk/boilerplate.mk</Filename> is included at the top of
+<Filename>ghc/Makefile</Filename>, and of all the leaf <Filename>Makefile</Filename>s in the
+sub-directories. It in turn <Literal>include</Literal>s the main boilerplate file
+<Filename>mk/boilerplate.mk</Filename>.
+
+
+</Para>
+</ListItem>
+<ListItem>
+
+<Para>
+ <Filename>ghc/mk/target.mk</Filename> is <Literal>include</Literal>d at the bottom of
+<Filename>ghc/Makefile</Filename>, and of all the leaf <Filename>Makefile</Filename>s in the
+sub-directories. It in turn <Literal>include</Literal>s the file <Filename>mk/target.mk</Filename>.
+
+</Para>
+</ListItem>
+
+</ItemizedList>
+
+</Para>
+
+<Para>
+So these two files are the place to look for GHC-wide customisation
+of the standard boilerplate.
+</Para>
+
+</Sect2>
+
+<Sect2 id="sec-boiler-arch">
+<Title>Boilerplate architecture
+<IndexTerm><Primary>boilerplate architecture</Primary></IndexTerm>
+</Title>
+
+<Para>
+Every <Filename>Makefile</Filename> includes a <Filename>boilerplate.mk</Filename><IndexTerm><Primary>boilerplate.mk</Primary></IndexTerm> file
+at the top, and <Filename>target.mk</Filename><IndexTerm><Primary>target.mk</Primary></IndexTerm> file at the bottom. In
+this section we discuss what is in these files, and why there have to
+be two of them. In general:
+</Para>
+
+<Para>
+
+<ItemizedList>
+<ListItem>
+
+<Para>
+ <Filename>boilerplate.mk</Filename> consists of:
+
+<ItemizedList>
+<ListItem>
+
+<Para>
+ <Emphasis>Definitions of millions of <Command>make</Command> variables</Emphasis> that
+collectively specify the build configuration. Examples:
+<Constant>HC_OPTS</Constant><IndexTerm><Primary>HC_OPTS</Primary></IndexTerm>, the options to feed to the Haskell compiler;
+<Constant>NoFibSubDirs</Constant><IndexTerm><Primary>NoFibSubDirs</Primary></IndexTerm>, the sub-directories to enable within the
+<Literal>nofib</Literal> project; <Constant>GhcWithHc</Constant><IndexTerm><Primary>GhcWithHc</Primary></IndexTerm>, the name of the Haskell
+compiler to use when compiling GHC in the <Literal>ghc</Literal> project.
+</Para>
+</ListItem>
+<ListItem>
+
+<Para>
+<Emphasis>Standard pattern rules</Emphasis> that tell <Command>gmake</Command> how to construct one
+file from another.
+</Para>
+</ListItem>
+
+</ItemizedList>
+
+
+<Filename>boilerplate.mk</Filename> needs to be <Literal>include</Literal>d at the <Emphasis>top</Emphasis>
+of each <Filename>Makefile</Filename>, so that the user can replace the
+boilerplate definitions or pattern rules by simply giving a new
+definition or pattern rule in the <Filename>Makefile</Filename>. <Command>gmake</Command>
+simply takes the last definition as the definitive one.
+
+Instead of <Emphasis>replacing</Emphasis> boilerplate definitions, it is also quite
+common to <Emphasis>augment</Emphasis> them. For example, a <Filename>Makefile</Filename> might say:
+
+
+<ProgramListing>
+SRC_HC_OPTS += -O
+</ProgramListing>
+
+
+thereby adding ``<Option>-O</Option>'' to the end of <Constant>SRC_HC_OPTS</Constant><IndexTerm><Primary>SRC_HC_OPTS</Primary></IndexTerm>.
+
+</Para>
+</ListItem>
+<ListItem>
+
+<Para>
+ <Filename>target.mk</Filename> contains <Command>make</Command> rules for the standard
+targets described in <Xref LinkEnd="sec-standard-targets">. These rules are selectively included,
+depending on the setting of certain <Command>make</Command> variables. These
+variables are usually set in the middle section of the
+<Filename>Makefile</Filename> between the two <Literal>include</Literal>s.
+
+<Filename>target.mk</Filename> must be included at the end (rather than being part of
+<Filename>boilerplate.mk</Filename>) for several tiresome reasons:
+
+
+<ItemizedList>
+<ListItem>
+
+<Para>
+ <Command>gmake</Command> commits target and dependency lists earlier than
+it should. For example, <FIlename>target.mk</FIlename> has a rule that looks like
+this:
+
+
+<ProgramListing>
+$(HS_PROG) : $(OBJS)
+ $(HC) $(LD_OPTS) $< -o $@
+</ProgramListing>
+
+
+If this rule was in <Filename>boilerplate.mk</Filename> then <Constant>$(HS_PROG)</Constant><IndexTerm><Primary>HS_PROG</Primary></IndexTerm>
+and <Constant>$(OBJS)</Constant><IndexTerm><Primary>OBJS</Primary></IndexTerm> would not have their final values at the
+moment <Command>gmake</Command> encountered the rule. Alas, <Command>gmake</Command> 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 of firing.) So, the rule must follow the
+definitions given in the <Filename>Makefile</Filename> itself.
+
+</Para>
+</ListItem>
+<ListItem>
+
+<Para>
+ Unlike pattern rules, ordinary rules cannot be overriden or
+replaced by subsequent rules for the same target (at least, not without an
+error message). Including ordinary rules in <Filename>boilerplate.mk</Filename> would
+prevent the user from writing rules for specific targets in specific cases.
+
+</Para>
+</ListItem>
+<ListItem>
+
+<Para>
+ There are a couple of other reasons I've forgotten, but it doesn't
+matter too much.
+</Para>
+</ListItem>
+
+</ItemizedList>
+
+</Para>
+</ListItem>
+
+</ItemizedList>
+
+</Para>
+
+</Sect2>
+
+<Sect2 id="sec-boiler">
+<Title>The main <Filename>mk/boilerplate.mk</Filename> file
+
+<IndexTerm><Primary>boilerplate.mk</Primary></IndexTerm></Title>
+
+<Para>
+If you look at <Filename><Constant>$(FPTOOLS_TOP)</Constant>/mk/boilerplate.mk</Filename> you will find
+that it consists of the following sections, each held in a separate
+file:
+</Para>
+
+<Para>
+<VariableList>
+
+<VarListEntry>
+<Term><Filename>config.mk</Filename><IndexTerm><Primary>config.mk</Primary></IndexTerm></Term>
+<ListItem>
+<Para>
+is the build configuration file we
+discussed at length in <Xref LinkEnd="sec-build-config">.
+</Para>
+</ListItem></VarListEntry>
+<VarListEntry>
+<Term><Filename>paths.mk</Filename><IndexTerm><Primary>paths.mk</Primary></IndexTerm></Term>
+<ListItem>
+<Para>
+defines <Command>make</Command> variables for
+pathnames and file lists. In particular, it gives definitions for:
+</Para>
+
+<Para>
+<VariableList>
+
+<VarListEntry>
+<Term><Constant>SRCS</Constant><IndexTerm><Primary>SRCS</Primary></IndexTerm>:</Term>
+<ListItem>
+<Para>
+all source files in the current directory.
+</Para>
+</ListItem></VarListEntry>
+<VarListEntry>
+<Term><Constant>HS_SRCS</Constant><IndexTerm><Primary>HS_SRCS</Primary></IndexTerm>:</Term>
+<ListItem>
+<Para>
+all Haskell source files in the current directory.
+It is derived from <Constant>$(SRCS)</Constant>, so if you override <Constant>SRCS</Constant> with a new value
+<Constant>HS_SRCS</Constant> will follow suit.
+</Para>
+</ListItem></VarListEntry>
+<VarListEntry>
+<Term><Constant>C_SRCS</Constant><IndexTerm><Primary>C_SRCS</Primary></IndexTerm>:</Term>
+<ListItem>
+<Para>
+similarly for C source files.
+</Para>
+</ListItem></VarListEntry>
+<VarListEntry>
+<Term><Constant>HS_OBJS</Constant><IndexTerm><Primary>HS_OBJS</Primary></IndexTerm>:</Term>
+<ListItem>
+<Para>
+the <Filename>.o</Filename> files derived from <Constant>$(HS_SRCS)</Constant>.
+</Para>
+</ListItem></VarListEntry>
+<VarListEntry>
+<Term><Constant>C_OBJS</Constant><IndexTerm><Primary>C_OBJS</Primary></IndexTerm>:</Term>
+<ListItem>
+<Para>
+similarly for <Constant>$(C_SRCS)</Constant>.
+</Para>
+</ListItem></VarListEntry>
+<VarListEntry>
+<Term><Constant>OBJS</Constant><IndexTerm><Primary>OBJS</Primary></IndexTerm>:</Term>
+<ListItem>
+<Para>
+the concatenation of <Constant>$(HS_OBJS)</Constant> and <Constant>$(C_OBJS)</Constant>.
+</Para>
+</ListItem></VarListEntry>
+</VariableList>
+</Para>
+
+<Para>
+Any or all of these definitions can easily be overriden by giving new
+definitions in your <Filename>Makefile</Filename>. For example, if there are things in
+the current directory that look like source files but aren't, then
+you'll need to set <Constant>SRCS</Constant> manually in your <Filename>Makefile</Filename>. The other
+definitions will then work from this new definition.
+</Para>
+
+<Para>
+What, exactly, does <Filename>paths.mk</Filename> consider a ``source file'' to be? It's
+based on the file's suffix (e.g. <Filename>.hs</Filename>, <Filename>.lhs</Filename>, <Filename>.c</Filename>, <Filename>.lc</Filename>, etc), but
+this is the kind of detail that changes, so rather than
+enumerate the source suffices here the best thing to do is to look in
+<Filename>paths.mk</Filename>.
+</Para>
+</ListItem></VarListEntry>
+<VarListEntry>
+<Term><Filename>opts.mk</Filename><IndexTerm><Primary>opts.mk</Primary></IndexTerm></Term>
+<ListItem>
+<Para>
+defines <Command>make</Command> variables for option
+strings to pass to each program. For example, it defines
+<Constant>HC_OPTS</Constant><IndexTerm><Primary>HC_OPTS</Primary></IndexTerm>, the option strings to pass to the Haskell
+compiler. See <Xref LinkEnd="sec-suffix">.
+</Para>
+</ListItem></VarListEntry>
+<VarListEntry>
+<Term><Filename>suffix.mk</Filename><IndexTerm><Primary>suffix.mk</Primary></IndexTerm></Term>
+<ListItem>
+<Para>
+defines standard pattern rules—see <Xref LinkEnd="sec-suffix">.
+</Para>
+</ListItem></VarListEntry>
+</VariableList>
+</Para>
+
+<Para>
+Any of the variables and pattern rules defined by the boilerplate file
+can easily be overridden in any particular <Filename>Makefile</Filename>, because the
+boilerplate <Literal>include</Literal> comes first. Definitions after this <Literal>include</Literal>
+directive simply override the default ones in <Filename>boilerplate.mk</Filename>.
+</Para>
+
+</Sect2>
+
+<Sect2 id="sec-suffix">
+<Title>Pattern rules and options
+
+<IndexTerm><Primary>Pattern rules</Primary></IndexTerm></Title>
+
+<Para>
+The file <Filename>suffix.mk</Filename><IndexTerm><Primary>suffix.mk</Primary></IndexTerm> defines standard <Emphasis>pattern
+rules</Emphasis> that say how to build one kind of file from another, for
+example, how to build a <Filename>.o</Filename> file from a <Filename>.c</Filename> file. (GNU <Command>make</Command>'s
+<Emphasis>pattern rules</Emphasis> are more powerful and easier to use than Unix
+<Command>make</Command>'s <Emphasis>suffix rules</Emphasis>.)
+</Para>
+
+<Para>
+Almost all the rules look something like this:
+</Para>
+
+<Para>
+
+<ProgramListing>
+%.o : %.c
+ $(RM) $@
+ $(CC) $(CC_OPTS) -c $< -o $@
+</ProgramListing>
+
+</Para>
+
+<Para>
+Here's how to understand the rule. It says that
+<Emphasis>something</Emphasis><Filename>.o</Filename> (say <Filename>Foo.o</Filename>) can be built from
+<Emphasis>something</Emphasis><Filename>.c</Filename> (<Filename>Foo.c</Filename>), by invoking the C compiler
+(path name held in <Constant>$(CC)</Constant>), passing to it the options
+<Constant>$(CC_OPTS)</Constant> and the rule's dependent file of the rule
+<Literal>$<</Literal> (<Filename>Foo.c</Filename> in this case), and putting the result in
+the rule's target <Literal>$@</Literal> (<Filename>Foo.o</Filename> in this case).
+</Para>
+
+<Para>
+Every program is held in a <Command>make</Command> variable defined in
+<Filename>mk/config.mk</Filename>—look in <Filename>mk/config.mk</Filename> for the
+complete list. One important one is the Haskell compiler, which is
+called <Constant>$(HC)</Constant>.
+</Para>
+
+<Para>
+Every program's options are are held in a <Command>make</Command> variables called
+<Constant><prog>_OPTS</Constant>. the <Constant><prog>_OPTS</Constant> variables are defined in
+<Filename>mk/opts.mk</Filename>. Almost all of them are defined like this:
+</Para>
+
+<Para>
+
+<ProgramListing>
+CC_OPTS = $(SRC_CC_OPTS) $(WAY$(_way)_CC_OPTS) $($*_CC_OPTS) $(EXTRA_CC_OPTS)
+</ProgramListing>
+
+</Para>
+
+<Para>
+The four variables from which <Constant>CC_OPTS</Constant> is built have the following meaning:
+</Para>
+
+<Para>
+<VariableList>
+
+<VarListEntry>
+<Term><Constant>SRC_CC_OPTS</Constant><IndexTerm><Primary>SRC_CC_OPTS</Primary></IndexTerm>:</Term>
+<ListItem>
+<Para>
+options passed to all C
+compilations.
+</Para>
+</ListItem></VarListEntry>
+<VarListEntry>
+<Term><Constant>WAY_<way>_CC_OPTS</Constant>:</Term>
+<ListItem>
+<Para>
+options passed to C
+compilations for way <Literal><way></Literal>. For example,
+<Constant>WAY_mp_CC_OPTS</Constant> gives options to pass to the C compiler when
+compiling way <Literal>mp</Literal>. The variable <Constant>WAY_CC_OPTS</Constant> holds
+options to pass to the C compiler when compiling the standard way.
+(<Xref LinkEnd="sec-ways"> dicusses multi-way
+compilation.)
+</Para>
+</ListItem></VarListEntry>
+<VarListEntry>
+<Term><Constant><module>_CC_OPTS</Constant>:</Term>
+<ListItem>
+<Para>
+options to
+pass to the C compiler that are specific to module <Literal><module></Literal>. For example, <Constant>SMap_CC_OPTS</Constant> gives the specific options
+to pass to the C compiler when compiling <Filename>SMap.c</Filename>.
+</Para>
+</ListItem></VarListEntry>
+<VarListEntry>
+<Term><Constant>EXTRA_CC_OPTS</Constant><IndexTerm><Primary>EXTRA_CC_OPTS</Primary></IndexTerm>:</Term>
+<ListItem>
+<Para>
+extra options to pass to all
+C compilations. This is intended for command line use, thus:
+</Para>
+
+<Para>
+
+<ProgramListing>
+gmake libHS.a EXTRA_CC_OPTS="-v"
+</ProgramListing>
+
+</Para>
+</ListItem></VarListEntry>
+</VariableList>
+</Para>
+
+</Sect2>
+
+<Sect2 id="sec-targets">
+<Title>The main <Filename>mk/target.mk</Filename> file
+
+<IndexTerm><Primary>target.mk</Primary></IndexTerm></Title>
+
+<Para>
+<Filename>target.mk</Filename> contains canned rules for all the standard targets
+described in <Xref LinkEnd="sec-standard-targets">. It is complicated by the fact that you don't want all of
+these rules to be active in every <Filename>Makefile</Filename>. Rather than have a
+plethora of tiny files which you can include selectively, there is a
+single file, <Filename>target.mk</Filename>, which selectively includes rules based on
+whether you have defined certain variables in your <Filename>Makefile</Filename>. This
+section explains what rules you get, what variables control them, and
+what the rules do. Hopefully, you will also get enough of an idea of
+what is supposed to happen that you can read and understand any weird
+special cases yourself.
+</Para>
+
+<Para>
+<VariableList>
+
+<VarListEntry>
+<Term><Constant>HS_PROG</Constant><IndexTerm><Primary>HS_PROG</Primary></IndexTerm>.</Term>
+<ListItem>
+<Para>
+If <Constant>HS_PROG</Constant> is defined, you get
+rules with the following targets:
+<VariableList>
+
+<VarListEntry>
+<Term><Filename>HS_PROG</Filename><IndexTerm><Primary>HS_PROG</Primary></IndexTerm></Term>
+<ListItem>
+<Para>
+itself. This rule links <Constant>$(OBJS)</Constant>
+with the Haskell runtime system to get an executable called
+<Constant>$(HS_PROG)</Constant>.
+</Para>
+</ListItem></VarListEntry>
+<VarListEntry>
+<Term><Literal>install</Literal><IndexTerm><Primary>install</Primary></IndexTerm></Term>
+<ListItem>
+<Para>
+installs <Constant>$(HS_PROG)</Constant>
+in <Constant>$(bindir)</Constant>.
+</Para>
+</ListItem></VarListEntry>
+</VariableList>
+</Para>
+</ListItem></VarListEntry>
+<VarListEntry>
+<Term><Constant>C_PROG</Constant><IndexTerm><Primary>C_PROG</Primary></IndexTerm></Term>
+<ListItem>
+<Para>
+is similar to <Constant>HS_PROG</Constant>, except that
+the link step links <Constant>$(C_OBJS)</Constant> with the C runtime system.
+</Para>
+</ListItem></VarListEntry>
+<VarListEntry>
+<Term><Constant>LIBRARY</Constant><IndexTerm><Primary>LIBRARY</Primary></IndexTerm></Term>
+<ListItem>
+<Para>
+is similar to <Constant>HS_PROG</Constant>, except that
+it links <Constant>$(LIB_OBJS)</Constant> to make the library archive <Constant>$(LIBRARY)</Constant>, and
+<Literal>install</Literal> installs it in <Constant>$(libdir)</Constant>.
+</Para>
+</ListItem></VarListEntry>
+<VarListEntry>
+<Term><Constant>LIB_DATA</Constant><IndexTerm><Primary>LIB_DATA</Primary></IndexTerm></Term>
+<ListItem>
+<Para>
+…
+</Para>
+</ListItem></VarListEntry>
+<VarListEntry>
+<Term><Constant>LIB_EXEC</Constant><IndexTerm><Primary>LIB_EXEC</Primary></IndexTerm></Term>
+<ListItem>
+<Para>
+…
+</Para>
+</ListItem></VarListEntry>
+<VarListEntry>
+<Term><Constant>HS_SRCS</Constant><IndexTerm><Primary>HS_SRCS</Primary></IndexTerm>, <Constant>C_SRCS</Constant><IndexTerm><Primary>C_SRCS</Primary></IndexTerm>.</Term>
+<ListItem>
+<Para>
+If <Constant>HS_SRCS</Constant>
+is defined and non-empty, a rule for the target <Literal>depend</Literal> is included,
+which generates dependency information for Haskell programs.
+Similarly for <Constant>C_SRCS</Constant>.
+</Para>
+</ListItem></VarListEntry>
+</VariableList>
+</Para>
+
+<Para>
+All of these rules are ``double-colon'' rules, thus
+</Para>
+
+<Para>
+
+<ProgramListing>
+install :: $(HS_PROG)
+ ...how to install it...
+</ProgramListing>
+
+</Para>
+
+<Para>
+GNU <Command>make</Command> treats double-colon rules as separate entities. If there
+are several double-colon rules for the same target it takes each in
+turn and fires it if its dependencies say to do so. This means that
+you can, for example, define both <Constant>HS_PROG</Constant> and <Constant>LIBRARY</Constant>, which will
+generate two rules for <Literal>install</Literal>. When you type <Command>gmake install</Command> both
+rules will be fired, and both the program and the library will be
+installed, just as you wanted.
+</Para>
+
+</Sect2>
+
+<Sect2 id="sec-subdirs">
+<Title>Recursion
+
+<IndexTerm><Primary>recursion, in makefiles</Primary></IndexTerm>
+<IndexTerm><Primary>Makefile, recursing into subdirectories</Primary></IndexTerm></Title>
+
+<Para>
+In leaf <Filename>Makefile</Filename>s the variable <Constant>SUBDIRS</Constant><IndexTerm><Primary>SUBDIRS</Primary></IndexTerm> is undefined.
+In non-leaf <Filename>Makefile</Filename>s, <Constant>SUBDIRS</Constant> is set to the list of
+sub-directories that contain subordinate <Filename>Makefile</Filename>s. <Emphasis>It is up to
+you to set <Constant>SUBDIRS</Constant> in the <Filename>Makefile</Filename>.</Emphasis> There is no automation here—<Constant>SUBDIRS</Constant> is too important to automate.
+</Para>
+
+<Para>
+When <Constant>SUBDIRS</Constant> is defined, <Filename>target.mk</Filename> includes a rather
+neat rule for the standard targets (<Xref LinkEnd="sec-standard-targets"> that simply invokes
+<Command>make</Command> recursively in each of the sub-directories.
+</Para>
+
+<Para>
+<Emphasis>These recursive invocations are guaranteed to occur in the order
+in which the list of directories is specified in <Constant>SUBDIRS</Constant>. </Emphasis>This
+guarantee can be important. For example, when you say <Command>gmake boot</Command> it
+can be important that the recursive invocation of <Command>make boot</Command> is done
+in one sub-directory (the include files, say) before another (the
+source files). Generally, put the most independent sub-directory
+first, and the most dependent last.
+</Para>
+
+</Sect2>
+
+<Sect2 id="sec-ways">
+<Title>Way management
+
+<IndexTerm><Primary>way management</Primary></IndexTerm></Title>
+
+<Para>
+We sometimes want to build essentially the same system in several
+different ``ways''. For example, we want to build GHC's <Literal>Prelude</Literal>
+libraries with and without profiling, with and without concurrency,
+and so on, so that there is an appropriately-built library archive to
+link with when the user compiles his program. It would be possible to
+have a completely separate build tree for each such ``way'', but it
+would be horribly bureaucratic, especially since often only parts of
+the build tree need to be constructed in multiple ways.
+</Para>
+
+<Para>
+Instead, the <Filename>target.mk</Filename><IndexTerm><Primary>target.mk</Primary></IndexTerm> contains some clever magic to
+allow you to build several versions of a system; and to control
+locally how many versions are built and how they differ. This section
+explains the magic.
+</Para>
+
+<Para>
+The files for a particular way are distinguished by munging the
+suffix. The ``normal way'' is always built, and its files have the
+standard suffices <Filename>.o</Filename>, <Filename>.hi</Filename>, and so on. In addition, you can build
+one or more extra ways, each distinguished by a <Emphasis>way tag</Emphasis>. The
+object files and interface files for one of these extra ways are
+distinguished by their suffix. For example, way <Literal>mp</Literal> has files
+<Filename>.mp_o</Filename> and <Filename>.mp_hi</Filename>. Library archives have their way tag the other
+side of the dot, for boring reasons; thus, <Filename>libHS_mp.a</Filename>.
+</Para>
+
+<Para>
+A <Command>make</Command> variable called <Constant>way</Constant> holds the current way tag. <Emphasis><Constant>way</Constant>
+is only ever set on the command line of a recursive invocation of
+<Command>gmake</Command>.</Emphasis> It is never set inside a <Filename>Makefile</Filename>. So it is a global
+constant for any one invocation of <Command>gmake</Command>. Two other <Command>make</Command>
+variables, <Constant>way_</Constant> and <Constant>_way</Constant> are immediately derived from <Constant>$(way)</Constant> and
+never altered. If <Constant>way</Constant> is not set, then neither are <Constant>way_</Constant> and
+<Constant>_way</Constant>, and the invocation of <Command>make</Command> will build the ``normal way''.
+If <Constant>way</Constant> is set, then the other two variables are set in sympathy.
+For example, if <Constant>$(way)</Constant> is ``<Literal>mp</Literal>'', then <Constant>way_</Constant> is set to ``<Literal>mp_</Literal>''
+and <Constant>_way</Constant> is set to ``<Literal>_mp</Literal>''. These three variables are then used
+when constructing file names.
+</Para>
+
+<Para>
+So how does <Command>make</Command> ever get recursively invoked with <Constant>way</Constant> set? There
+are two ways in which this happens:
+</Para>
+
+<Para>
+
+<ItemizedList>
+<ListItem>
+
+<Para>
+ For some (but not all) of the standard targets, when in a leaf
+sub-directory, <Command>make</Command> is recursively invoked for each way tag in
+<Constant>$(WAYS)</Constant>. You set <Constant>WAYS</Constant> to the list of way tags you want these
+targets built for. The mechanism here is very much like the recursive
+invocation of <Command>make</Command> in sub-directories (<Xref LinkEnd="sec-subdirs">).
+
+It is up to you to set <Constant>WAYS</Constant> in your <Filename>Makefile</Filename>; this is how you
+control what ways will get built.
+</Para>
+</ListItem>
+<ListItem>
+
+<Para>
+ For a useful collection of
+targets (such as <Filename>libHS_mp.a</Filename>, <Filename>Foo.mp_o</Filename>) there is a rule which
+recursively invokes <Command>make</Command> to make the specified target, setting the
+<Constant>way</Constant> variable. So if you say <Command>gmake Foo.mp_o</Command> you should see a
+recursive invocation <Command>gmake Foo.mp_o way=mp</Command>, and <Emphasis>in this
+recursive invocation the pattern rule for compiling a Haskell file
+into a <Filename>.o</Filename> file will match</Emphasis>. The key pattern rules (in <Filename>suffix.mk</Filename>)
+look like this:
+
+
+<ProgramListing>
+%.$(way_)o : %.lhs
+ $(HC) $(HC_OPTS) $< -o $@
+</ProgramListing>
+
+
+Neat, eh?
+</Para>
+</ListItem>
+
+</ItemizedList>
+
+</Para>
+
+</Sect2>
+
+<Sect2>
+<Title>When the canned rule isn't right</Title>
+
+<Para>
+Sometimes the canned rule just doesn't do the right thing. For
+example, in the <Literal>nofib</Literal> suite we want the link step to print out
+timing information. The thing to do here is <Emphasis>not</Emphasis> to define
+<Constant>HS_PROG</Constant> or <Constant>C_PROG</Constant>, and instead define a special purpose rule in
+your own <Filename>Makefile</Filename>. By using different variable names you will avoid
+the canned rules being included, and conflicting with yours.
+</Para>
+
+</Sect2>
+
+</Sect1>
+
+<Sect1 id="sec-booting-from-C">
+<Title>Booting/porting from C (<Filename>.hc</Filename>) files
+
+<IndexTerm><Primary>building GHC from .hc files</Primary></IndexTerm>
+<IndexTerm><Primary>booting GHC from .hc files</Primary></IndexTerm>
+<IndexTerm><Primary>porting GHC</Primary></IndexTerm></Title>
+
+<Para>
+This section is for people trying to get GHC going by using the
+supplied intermediate C (<Filename>.hc</Filename>) files. This would probably be because
+no binaries have been provided, or because the machine is not ``fully
+supported''.
+</Para>
+
+<Para>
+The intermediate C files are normally made available together with a
+source release, please check the announce message for exact directions
+of where to find them. If we haven't made them available or you
+can't find them, please ask.
+</Para>
+
+<Para>
+Assuming you've got them, unpack them on top of a fresh source tree.
+Then follow the `normal' instructions in <Xref LinkEnd="sec-building-from-source"> for setting
+up a build tree. When you invoke the configure script, you'll have
+to tell the script about your intentions:
+</Para>
+
+<Para>
+
+<Screen>
+foo% ./configure --enable-hc-boot
+</Screen>
+
+<IndexTerm><Primary>--enable-hc-boot</Primary></IndexTerm>
+<IndexTerm><Primary>--disable-hc-boot</Primary></IndexTerm>
+</Para>
+
+<Para>
+Assuming it configures OK and you don't need to create <Filename>mk/build.mk</Filename>
+for any other purposes, the next step is to proceed with a <Command>make boot</Command>
+followed by <Command>make all</Command>. At the successful completion of <Command>make all</Command>,
+you should end up with a binary of the compiler proper,
+<Filename>ghc/compiler/hsc</Filename>, plus archives (but no <Filename>.hi</Filename> files!) of the prelude
+libraries. To generate the Prelude interface files (and test drive the
+bootstrapped compiler), re-run the <Command>configure</Command> script, but this time
+without the <Option>--enable-hc-boot</Option> option. After that re-create the
+contents of <Filename>ghc/lib</Filename>:
+</Para>
+
+<Para>
+
+<Screen>
+foo% ./configure
+ ....
+foo% cd ghc/lib
+foo% make clean
+foo% make boot
+foo% make all
+</Screen>
+
+</Para>
+
+<Para>
+That's the mechanics of the boot process, but, of course, if you're
+trying to boot on a platform that is not supported and significantly
+`different' from any of the supported ones, this is only the start of
+the adventure…(ToDo: porting tips—stuff to look out for, etc.)
+</Para>
+
+</Sect1>
+
+<Sect1 id="sec-build-pitfalls">
+<Title>Known pitfalls in building Glasgow Haskell
+
+<IndexTerm><Primary>problems, building</Primary></IndexTerm>
+<IndexTerm><Primary>pitfalls, in building</Primary></IndexTerm>
+<IndexTerm><Primary>building pitfalls</Primary></IndexTerm></Title>
+
+<Para>
+WARNINGS about pitfalls and known ``problems'':
+</Para>
+
+<Para>
+
+<OrderedList>
+<ListItem>
+
+<Para>
+One difficulty that comes up from time to time is running out of space
+in <Filename>/tmp</Filename>. (It is impossible for the configuration stuff to
+compensate for the vagaries of different sysadmin approaches to temp
+space.)
+<IndexTerm><Primary>tmp, running out of space in</Primary></IndexTerm>
+
+The quickest way around it is <Command>setenv TMPDIR /usr/tmp</Command><IndexTerm><Primary>TMPDIR</Primary></IndexTerm> or
+even <Command>setenv TMPDIR .</Command> (or the equivalent incantation with your shell
+of choice).
+
+The best way around it is to say
+
+<ProgramListing>
+export TMPDIR=<dir>
+</ProgramListing>
+
+in your <Filename>build.mk</Filename> file.
+Then GHC and the other <Literal>fptools</Literal> programs will use the appropriate directory
+in all cases.
+
+
+</Para>
+</ListItem>
+<ListItem>
+
+<Para>
+In compiling some support-code bits, e.g., in <Filename>ghc/rts/gmp</Filename> and even
+in <Filename>ghc/lib</Filename>, you may get a few C-compiler warnings. We think these
+are OK.
+
+</Para>
+</ListItem>
+<ListItem>
+
+<Para>
+When compiling via C, you'll sometimes get ``warning: assignment from
+incompatible pointer type'' out of GCC. Harmless.
+
+</Para>
+</ListItem>
+<ListItem>
+
+<Para>
+Similarly, <Command>ar</Command>chiving warning messages like the following are not
+a problem:
+
+<Screen>
+ar: filename GlaIOMonad__1_2s.o truncated to GlaIOMonad_
+ar: filename GlaIOMonad__2_2s.o truncated to GlaIOMonad_
+...
+</Screen>
+
+
+</Para>
+</ListItem>
+<ListItem>
+
+<Para>
+ In compiling the compiler proper (in <Filename>compiler/</Filename>), you <Emphasis>may</Emphasis>
+get an ``Out of heap space'' error message. These can vary with the
+vagaries of different systems, it seems. The solution is simple:
+
+
+<ItemizedList>
+<ListItem>
+
+<Para>
+ If you're compiling with GHC 4.00 or above, then the
+<Emphasis>maximum</Emphasis> heap size must have been reached. This is somewhat
+unlikely, since the maximum is set to 64M by default. Anyway, you can
+raise it with the <Option>-optCrts-M<size></Option> flag (add this flag to
+<Constant><module>_HC_OPTS</Constant> <Command>make</Command> variable in the appropriate <Filename>Makefile</Filename>).
+
+</Para>
+</ListItem>
+<ListItem>
+
+<Para>
+ For GHC < 4.00, add a suitable <Option>-H</Option> flag to the <Filename>Makefile</Filename>, as
+above.
+
+</Para>
+</ListItem>
+
+</ItemizedList>
+
+
+and try again: <Command>gmake</Command>. (see <Xref LinkEnd="sec-suffix"> for information about
+<Constant><module>_HC_OPTS</Constant>.)
+
+Alternatively, just cut to the chase:
+
+<Screen>
+% cd ghc/compiler
+% make EXTRA_HC_OPTS=-optCrts-M128M
+</Screen>
+
+
+</Para>
+</ListItem>
+<ListItem>
+
+<Para>
+If you try to compile some Haskell, and you get errors from GCC about
+lots of things from <Filename>/usr/include/math.h</Filename>, then your GCC was
+mis-installed. <Command>fixincludes</Command> wasn't run when it should've been.
+
+As <Command>fixincludes</Command> is now automagically run as part of GCC installation,
+this bug also suggests that you have an old GCC.
+
+
+</Para>
+</ListItem>
+<ListItem>
+
+<Para>
+You <Emphasis>may</Emphasis> need to re-<Command>ranlib</Command><IndexTerm><Primary>ranlib</Primary></IndexTerm> your libraries (on Sun4s).
+
+
+<Screen>
+% 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
+</Screen>
+
+
+We'd be interested to know if this is still necessary.
+
+
+</Para>
+</ListItem>
+<ListItem>
+
+<Para>
+GHC's sources go through <Command>cpp</Command> before being compiled, and <Command>cpp</Command> varies
+a bit from one Unix to another. One particular gotcha is macro calls
+like this:
+
+
+<ProgramListing>
+SLIT("Hello, world")
+</ProgramListing>
+
+
+Some <Command>cpp</Command>s treat the comma inside the string as separating two macro
+arguments, so you get
+
+
+<Screen>
+:731: macro `SLIT' used with too many (2) args
+</Screen>
+
+
+Alas, <Command>cpp</Command> doesn't tell you the offending file!
+
+Workaround: don't put weird things in string args to <Command>cpp</Command> macros.
+</Para>
+</ListItem>
+
+</OrderedList>
+
+</Para>
+
+</Sect1>
+
+
+<Sect1 id="winbuild"><Title>Notes for building under Windows</Title>
+
+<Para>
+This section summarises how to get the utilities you need on your
+Win95/98/NT/2000 machine to use CVS and build GHC. Similar notes for installing and running GHC may be found in the user guide. In general, Win95/Win98 behave the same, and WinNT/Win2k behave the same. It is based largely on detailed advice from Sigbjørn Finne.
+</Para>
+
+
+<Sect2><Title>Installing ssh</Title>
+
+<ItemizedList>
+
+<ListItem>
+<Para>
+Extract the whole of <ULink URL="http://research.microsoft.com/~simonpj/ssh-1_2_26-cygwinb19.tar.gz">the ssh archive</ULink> into your <Filename>C:\</Filename> directory, and use the ``All files'' and ``User folder names'' options in WinZip extract dialogue box. This populates your <Filename>C:\usr\local</Filename> tree.
+</Para>
+</ListItem>
+
+<ListItem>
+<Para>
+Extract <ULink URL="http://research.microsoft.com/~simonpj/cygwinb19.dll.zip">cygwinb19.dll</ULink> into <Filename>/usr/local/bin</Filename>. The current version
+of Cywin is b20, but this version of ssh was compiled with b19.
+</Para>
+</ListItem>
+
+<ListItem>
+<Para>
+On a Win2k machine, open up a bash and do
+</Para>
+
+<Screen>
+foo$ cd /etc
+foo$ mkpasswd -l > passwd
+</Screen>
+
+<Para>
+Check that your login entry is on the first line
+of that file. If not, move it to the top. It's OK
+for 'Administrator' to be the first entry, assuming you are one.
+</Para>
+
+<Para>
+However, Win9x doesn't support the calls that <Command>mkpasswd</Command> relies on
+(e.g., <Function>NetUserEnum</Function>). If you run <Command>mkpasswd</Command> you
+get errors like:
+</Para>
+
+<Screen>
+linked to missing export netapi32.dll:NetUserEnum
+</Screen>
+
+<Para>
+The passwd file is used
+by ssh in a fairly rudimentary manner, so I'd simply
+synthesise/copy an existing Unix <Filename>/etc/passwd</Filename>, i.e., create
+an <Filename>/etc/passwd</Filename> file containing the line
+</Para>
+
+<Screen>
+<login>::500:513:::/bin/sh
+</Screen>
+
+<Para>
+where <Literal><login></Literal> is your login id.
+</Para>
+</ListItem>
+
+<ListItem>
+<Para>
+Generate a key, by running <Filename>c:/user/local/bin/ssh-keygen1</Filename>.
+ This generates a public key in <Filename>.ssh/identity.pub</Filename>, and a
+ private key in <Filename>.ssh/identity</Filename>
+</Para>
+
+<Para>
+ In response to the 'Enter passphrase' question, just hit
+ return (i.e. use an empty passphrase). The passphrase is
+ a password that protects your private key. But it's a pain
+ to type this passphrase everytime you use <Command>ssh</Command>, so the best
+ thing to do is simply to protect your <Filename>.ssh</Filename> directory, and
+ <Filename>.ssh/identity</Filename> from access by anyone else. To do this
+ right-click your <Filename>.ssh</Filename> directory, and select Properties.
+ If you are not on the access control list, add yourself, and
+ give yourself full permissions (the second panel).
+ Remove everyone else from the access control list. (Don't
+ leave them there but deny them access, because 'they' may be
+ a list that includes you!)
+</Para>
+
+<Para>
+ If you have problems running <Command>ssh-keygen1</Command>
+ from within <Command>bash</Command>, start up <Filename>cmd.exe</Filename> and run it as follows:
+</Para>
+
+<Screen>
+c:\tmp> set CYGWIN32=tty
+c:\tmp> c:/user/local/bin/ssh-keygen1
+</Screen>
+</ListItem>
+
+<ListItem>
+<Para>
+If you don't have an account on <Literal>cvs.haskell.org</Literal>, send
+ your <Filename>.ssh/identity.pub</Filename> to the CVS repository administrator
+ (currently Jeff Lewis <Email>jlewis@cse.ogi.edu</Email>). He will set up
+ your account.
+</Para>
+
+<Para>
+ If you do have an account on <Literal>cvs.haskell.org</Literal>, use TeraTerm
+ to logon to it. Once in, copy the
+ key that <Command>ssh-keygen1</Command> deposited in <Filename>/.ssh/identity.pub</Filename> into
+ your <Filename>~/.ssh/authorized_keys</Filename>. Make sure that the new version
+ of <Filename>authorized_keys</Filename> still has 600 file permission.
+</Para>
+</ListItem>
+
+</ItemizedList>
+
+</Sect2>
+
+
+<Sect2><Title>Installing CVS</Title>
+
+<ItemizedList>
+
+<ListItem>
+<Para>
+Unpack
+<ULink URL="http://research.microsoft.com/~simonpj/cvs-1_10-win.zip">
+CVS</ULink> and, following the instructions in the <Filename>README</Filename>, copy the
+appropriate files into <Filename>/usr/local/bin</Filename>.
+</Para>
+</ListItem>
+
+<ListItem>
+<Para>
+From the System control panel,
+set the following <Emphasis>user</Emphasis> environment variables (see the GHC user guide)
+</Para>
+
+<ItemizedList>
+<ListItem>
+<Para>
+<Constant>HOME</Constant>: points to your home directory. This is where CVS
+will look for its <Filename>.cvsrc</Filename> file.
+</Para>
+</ListItem>
+
+<ListItem>
+<Para>
+<Constant>CVS_RSH</Constant>: <Filename>c:/usr/local/bin/ssh1</Filename>
+</Para>
+</ListItem>
+
+<ListItem>
+<Para>
+<Constant>CVSROOT</Constant>: <Literal>:ext:username@cvs.haskell.org:/home/cvs/root</Literal>,
+where <Literal>username</Literal> is your userid
+</Para>
+</ListItem>
+
+<ListItem>
+<Para>
+<Constant>CVSEDITOR</Constant>: <Filename>bin/gnuclient.exe</Filename> if you want to use an Emacs buffer for typing in those long commit messages.
+</Para>
+</ListItem>
+</ItemizedList>
+</ListItem>
+
+<ListItem>
+<Para>
+Put the following in <Filename>$HOME/.cvsrc</Filename>:
+</Para>
+
+<ProgramListing>
+checkout -P
+release -d
+update -P
+diff -u
+</ProgramListing>
+
+<Para>
+These are the default options for the specified CVS commands,
+and represent better defaults than the usual ones. (Feel
+free to change them.)
+</Para>
+
+<Para>
+Filenames starting with "<Filename>.</Filename>" were illegal in
+the 8.3 DOS filesystem, but that restriction should have
+been lifted by now (i.e., you're using VFAT or later filesystems.) If
+you're still having problems creating it, don't worry; <Filename>.cvsrc</Filename> is entirely
+optional.
+</Para>
+</ListItem>
+
+<ListItem>
+<Para>
+Try doing <Command>cvs co fpconfig</Command>. All being well, bytes should
+start to trickle through, leaving a directory <Filename>fptools</Filename>
+in your current directory. (You can <Command>rm</Command> it if you don't want to keep it.) The following messages appear to be harmless:
+</Para>
+
+<Screen>
+setsockopt IPTOS_LOWDELAY: Invalid argument
+setsockopt IPTOS_THROUGHPUT: Invalid argument
+</Screen>
+
+<Para>
+At this point I found that CVS tried to invoke a little dialogue with
+me (along the lines of `do you want to talk to this host'), but
+somehow bombed out. This was from a bash shell running in emacs.
+I solved this by invoking a Cygnus shell, and running CVS from there.
+Once things are dialogue free, it seems to work OK from within emacs.
+</Para>
+</ListItem>
+
+<ListItem>
+<Para>
+If you want to check out part of large tree, proceed as follows:
+</Para>
+
+<ProgramListing>
+cvs -f checkout -l papers
+cd papers
+cvs update cpr
+</ProgramListing>
+
+<Para>
+This sequence checks out the <Literal>papers</Literal> module, but none
+of its sub-directories.
+The "<Option>-l</Option>" flag says not to check out sub-directories.
+The "<Option>-f</Option>" flag says not to read the <Filename>.cvsrc</Filename> file
+whose <Option>-P</Option> default (don't check out empty directories) is
+in this case bogus.
+</Para>
+
+<Para>
+The <Command>cvs update</Command> command sucks in a named sub-directory.
+</Para>
+</ListItem>
+
+</ItemizedList>
+
+<Para>
+There is a very nice graphical front-end to CVS for Win32 platforms,
+with a UI that people will be familiar with, at
+<ULink URL="http://www.wincvs.org/">wincvs.org</ULink>.
+I have not tried it yet.
+</Para>
+
+</Sect2>
+
+
+<Sect2><Title>Installing autoconf</Title>
+
+<Para>
+Only required if you are doing builds from GHC's sources
+checked out from the CVS tree.
+</Para>
+
+<ItemizedList>
+<ListItem>
+<Para>
+Fetch the (standard, Unix) <Command>autoconf</Command> distribution from
+<ULink URL="ftp://ftp.gnu.org/gnu/autoconf">ftp.gnu.org</ULink>.
+</Para>
+</ListItem>
+<ListItem>
+<Para>
+Unpack it into an arbitrary directory.
+</Para>
+</ListItem>
+<ListItem>
+<Para>
+Make sure that the directory <Filename>/usr/local/bin</Filename> exists.
+</Para>
+</ListItem>
+<ListItem>
+<Para>
+Say "<Filename>./configure</Filename>".
+</Para>
+</ListItem>
+<ListItem>
+<Para>
+Now <Command>make install</Command>. This should put <Filename>autoheader</Filename>
+and <Filename>autoconf</Filename> in <Filename>/usr/local/bin</Filename>.
+</Para>
+</ListItem>
+</ItemizedList>
+
+<Para>
+<Command>autoheader</Command> doesn't seem to work, but you don't need it
+for GHC.
+</Para>
+
+</Sect2>
+
+
+<Sect2><Title>Building GHC</Title>
+
+<ItemizedList>
+
+<ListItem>
+<Para>
+In the <Filename>./configure</Filename> output, ignore
+"<Literal>
+checking whether #! works in shell scripts...
+./configure: ./conftest: No such file or directory</Literal>",
+and "<Literal>not updating unwritable cache ./config.cache</Literal>".
+Nobody knows why these happen, but they seem to be harmless.
+</Para>
+</ListItem>
+
+<ListItem>
+<Para>
+You have to run <Command>autoconf</Command> both in <Filename>fptools</Filename>
+and in <Filename>fptools/ghc</Filename>. If you omit the latter step you'll
+get an error when you run <Filename>./configure</Filename>:
+</Para>
+
+<Screen>
+...lots of stuff...
+creating mk/config.h
+mk/config.h is unchanged
+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
+</Screen>
+</ListItem>
+
+<ListItem>
+<Para>
+You need <Filename>ghc</Filename> to be in your <Constant>PATH</Constant> before you run
+<Command>configure</Command>. The default GHC InstallShield creates only
+<Filename>ghc-4.05</Filename>, so you may need to duplicate this file as <Filename>ghc</Filename>
+in the same directory, in order that <Command>configure</Command> will see it (or
+just rename <Filename>ghc-4.05</Filename> to <Filename>ghc</Filename>.
+And make sure that the directory is in your path.
+</Para>
+</ListItem>
+
+<ListItem>
+<Para>
+Compile <Command>happy</Command> and <Command>ghc</Command>
+with <Option>-static</Option>. To do this, set
+</Para>
+
+<ProgramListing>
+GhcHcOpts=-static
+HappyHcOpts=-static
+</ProgramListing>
+
+<Para>
+in your <Filename>build.mk</Filename> file.
+[Actually, I successfully compiled Happy without <Option>-static</Option> on Win2k, but not GHC.]
+</Para>
+</ListItem>
+
+</ItemizedList>
+
+</Sect2>
+
+</Sect1>
+
+</Article>
projects / ghc-hetmet.git / commitdiff