--- /dev/null
+<!DOCTYPE Article PUBLIC "-//OASIS//DTD DocBook V3.1//EN">
+
+<Article id="building-guide">
+
+<ArtHeader>
+
+<Title>Building the Glasgow Functional Programming Tools Suite</Title>
+<Author><OtherName>The GHC Team</OtherName></Author>
+<Address><Email>glasgow-haskell-{users,bugs}@haskell.org</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>Binary distribution.</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>Source distribution.</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 GHC 4.xx can be compiled up using GHC 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 in the <ULink
+URL="http://www.haskell.org/ghc/cvs-cheat-sheet.html" >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 id="sec-build-checks">
+<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>
+Disk space needed: About 40MB (one tenth of one hamburger's 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 up to one fifth of a hamburger. You'll need
+over 100MB (say, one fifth a hamburger's worth) if you need to build the
+basic stuff from scratch. All of the above are
+<Emphasis>estimates</Emphasis> of disk-space needs. (Note: our benchmark hamburger is a standard Double Whopper with Cheese, with an RRP of UKP2.99.)
+</Para>
+</ListItem>
+<ListItem>
+
+<Para>
+Use an appropriate machine, compilers, and things.
+SPARC boxes, and PCs running Linux, FreeBSD, NetBSD, or Solaris are
+all fully supported. Win32 and HP boxes are in pretty good shape.
+DEC Alphas running OSF/1, Linux or some BSD variant, MIPS and AIX
+boxes will need some minimal porting effort before they work (as of
+4.06). <Xref LinkEnd="sec-port-info"> gives the full run-down on
+ports or lack thereof.
+</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 FAQ for the version
+you're building, which should be available from the relevant download
+page on the <ULink URL="http://www.haskell.org/ghc/" >GHC web
+site</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 GHC Users' 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@haskell.org</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>
+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>
+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>
+The native code generator is currently non-functional (as of GHC
+version 4.06), but we're actively working on getting it going again.
+</Para>
+
+<Para>
+We use Sparcs running Solaris 2.7 and x86 boxes running FreeBSD and
+Linux, so those are the best supported platforms, unsurprisingly.
+</Para>
+
+<Para>
+Here's everything that's known about GHC ports. We identify platforms
+by their ``canonical'' CPU/Manufacturer/OS triple.
+</Para>
+
+<Para>
+<VariableList>
+
+<VarListEntry>
+<Term>alpha-dec-{osf,linux,freebsd,openbsd,netbsd}:</Term>
+<IndexTerm><Primary>alpha-dec-osf</Primary></IndexTerm>
+<IndexTerm><Primary>alpha-dec-linux</Primary></IndexTerm>
+<IndexTerm><Primary>alpha-dec-freebsd</Primary></IndexTerm>
+<IndexTerm><Primary>alpha-dec-openbsd</Primary></IndexTerm>
+<IndexTerm><Primary>alpha-dec-netbsd</Primary></IndexTerm>
+<ListItem>
+
+<Para>
+Currently non-working. The last working version (osf[1-3]) is GHC
+3.02. A small amount of porting effort will be required to get Alpha
+support into GHC 4.xx, but we don't have easy access to machines right
+now, and there hasn't been a massive demand for support, so Alphas
+remain unsupported for the time being. Please get in touch if you
+either need Alpha support and/or can provide access to boxes.
+</Para>
+
+</ListItem></VarListEntry>
+<VarListEntry>
+<Term>sparc-sun-sunos4:</Term>
+<IndexTerm><Primary>sparc-sun-sunos4</Primary></IndexTerm>
+<ListItem>
+
+<Para>
+Probably works with minor tweaks, hasn't been tested for a while.
+</Para>
+
+</ListItem></VarListEntry>
+<VarListEntry>
+<Term>sparc-sun-solaris2:</Term>
+<IndexTerm><Primary>sparc-sun-solaris2</Primary></IndexTerm>
+<ListItem>
+
+<Para>
+Fully supported, including native-code generator.
+</Para>
+
+</ListItem></VarListEntry>
+<VarListEntry>
+<Term>hppa1.1-hp-hpux (HP-PA boxes running HPUX 9.x)</Term>
+<IndexTerm><Primary>hppa1.1-hp-hpux</Primary></IndexTerm>
+<ListItem>
+
+<Para>
+Works registerised. No native-code generator.
+</Para>
+
+</ListItem></VarListEntry>
+<VarListEntry>
+<Term>i386-unknown-linux (PCs running Linux—ELF binary format):</Term>
+<IndexTerm><Primary>i386-*-linux</Primary></IndexTerm>
+<ListItem>
+
+<Para>
+GHC works registerised. You <Emphasis>must</Emphasis> have GCC 2.7.x
+or later. NOTE about <literal>glibc</literal> versions: GHC binaries
+built on a system running <literal>glibc 2.0</literal> won't work on a
+system running <literal>glibc 2.1</literal>, and vice version. In
+general, don't expect compatibility between <literal>glibc</literal>
+versions, even if the shared library version hasn't changed.
+</Para>
+
+</ListItem></VarListEntry>
+<VarListEntry>
+<Term>i386-unknown-{freebsd,netbsd,openbsd) (PCs running FreeBSD 2.2
+or higher, NetBSD, and possibly OpenBSD):</Term>
+<IndexTerm><Primary>i386-unknown-freebsd</Primary></IndexTerm>
+<IndexTerm><Primary>i386-unknown-netbsd</Primary></IndexTerm>
+<IndexTerm><Primary>i386-unknown-openbsd</Primary></IndexTerm>
+<ListItem>
+
+<Para>
+GHC works registerised. These systems provide ready-built packages of
+GHC, so if you just need binaries you're better off just installing
+the package.
+</Para>
+
+</ListItem></VarListEntry>
+<VarListEntry>
+<Term>i386-unknown-cygwin32:</Term>
+<IndexTerm><Primary>i386-unknown-cygwin32</Primary></IndexTerm>
+<ListItem>
+
+<Para>
+Fully supported under Win9x/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.).
+</Para>
+
+</ListItem></VarListEntry>
+<VarListEntry>
+<Term>mips-sgi-irix5:</Term>
+<IndexTerm><Primary>mips-sgi-irix[5-6]</Primary></IndexTerm>
+<ListItem>
+
+<Para>
+Port currently doesn't work, needs some minimal porting effort. As
+usual, we don't have access to machines and there hasn't been an
+overwhelming demand for this port, but feel free to get in touch.
+</Para>
+</ListItem></VarListEntry>
+
+<VarListEntry>
+<Term>powerpc-ibm-aix:</Term>
+<ListItem>
+<Para>
+<IndexTerm><Primary>powerpc-ibm-aix</Primary></IndexTerm>
+Port currently doesn't work, needs some minimal porting effort. As
+usual, we don't have access to machines and there hasn't been an
+overwhelming demand for this port, but feel free to get in touch.
+</Para>
+</ListItem></VarListEntry>
+
+</VariableList>
+</Para>
+
+<para>
+Various other systems have had GHC ported to them in the distant past,
+including various Motorola 68k boxes. The 68k support still remains,
+but porting to one of these systems will certainly be a non-trivial
+task.
+</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>
+
+</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>, <Command>gcc</Command> and
+<command>happy</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>
+<IndexTerm><Primary>pre-supposed: Perl</Primary></IndexTerm>
+<IndexTerm><Primary>Perl, pre-supposed</Primary></IndexTerm>
+<ListItem>
+<Para>
+<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>
+<IndexTerm><Primary>pre-supposed: GCC (GNU C compiler)</Primary></IndexTerm>
+<IndexTerm><Primary>GCC (GNU C compiler), pre-supposed</Primary></IndexTerm>
+<ListItem>
+
+<Para>
+We recommend using GCC version 2.95.2 on all platforms. Failing that,
+version 2.7.2 is stable on most platforms. Earlier versions of GCC
+can be assumed not to work, and versions in between 2.7.2 and 2.95.2
+(including <command>egcs</command>) have varying degrees of stability
+depending on the platform.
+</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>Happy:</term>
+<indexterm><primary>Happy</primary></indexterm>
+<listitem>
+<para>Happy is a parser generator tool for Haskell, and is used to
+generate GHC's parsers. Happy is written in Haskell, and is a project
+in the CVS repository (<literal>fptools/happy</literal>). It can be
+built from source, but bear in mind that you'll need GHC installed in
+order to build it. To avoid the chicken/egg problem, install a binary
+distribtion of either Happy or GHC to get started. Happy
+distributions are available from <ulink
+url="http://www.haskell.org/happy/">Happy's Web Page</ulink>.
+</para>
+</listitem>
+</varlistentry>
+
+<VarListEntry>
+<Term>Autoconf:</Term>
+<IndexTerm><Primary>pre-supposed: Autoconf</Primary></IndexTerm>
+<IndexTerm><Primary>Autoconf, pre-supposed</Primary></IndexTerm>
+<ListItem>
+<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>
+<IndexTerm><Primary>pre-supposed: sed</Primary></IndexTerm>
+<IndexTerm><Primary>sed, pre-supposed</Primary></IndexTerm>
+<ListItem>
+<Para>
+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>
+<IndexTerm><Primary>pre-supposed: PVM3 (Parallel Virtual Machine)</Primary></IndexTerm>
+<IndexTerm><Primary>PVM3 (Parallel Virtual Machine), pre-supposed</Primary></IndexTerm>
+<ListItem>
+
+<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>
+<IndexTerm><Primary>bash, presupposed (Parallel Haskell only)</Primary></IndexTerm>
+<ListItem>
+<Para>
+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>
+<IndexTerm><Primary>pre-supposed: DocBook</Primary></IndexTerm>
+<IndexTerm><Primary>DocBook, pre-supposed</Primary></IndexTerm>
+<ListItem>
+<Para>
+All our documentation is written in SGML, using the DocBook DTD.
+Instructions on installing and configuring the DocBook tools are in the
+installation guide (in the GHC user guide).
+</Para>
+
+</ListItem></VarListEntry>
+<VarListEntry>
+<Term>TeX:</Term>
+<IndexTerm><Primary>pre-supposed: TeX</Primary></IndexTerm>
+<IndexTerm><Primary>TeX, pre-supposed</Primary></IndexTerm>
+<ListItem>
+<Para>
+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>
+
+<VariableList>
+<VarListEntry>
+<Term>Flex:</Term>
+<IndexTerm><Primary>pre-supposed: flex</Primary></IndexTerm>
+<IndexTerm><Primary>flex, pre-supposed</Primary></IndexTerm>
+<ListItem>
+
+<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>
+
+</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>
+Some projects, including GHC, have their own configure script. If
+there's an
+<Constant>$(FPTOOLS_TOP)/<project>/configure.in</Constant>,
+then you need to run <command>autoconf</command> in that directory too.
+</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). Notably, you should say
+<Command>gmake boot</Command> before you say <Command>gmake clean</Command>.
+</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>, or by running
+<command>configure</command> with command-line arguments like
+<literal>--bindir=/home/simonpj/bin</literal>; see <literal>./configure
+--help</literal> for the full details.
+</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>
+Delete all files from the current directory that are normally created
+by building the program. Don't delete the files that record the
+configuration, or files generated by <Command>gmake boot</Command>.
+Also preserve files that could be made by building, but normally
+aren't because the distribution comes with them.</para>
+</ListItem></VarListEntry>
+
+<varlistentry>
+<term><literal>distclean</literal>:</term>
+<listitem>
+<para>Delete all files from the current directory that are created by
+configuring or building the program. If you have unpacked the source
+and built the program without creating any other files, <literal>make
+distclean</literal> should leave only the files that were in the
+distribution.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><literal>mostlyclean</literal>:</term>
+<listitem>
+<para>Like <literal>clean</literal>, but may refrain from deleting a
+few files that people normally don't want to recompile.</para>
+</listitem>
+</varlistentry>
+
+<VarListEntry>
+<Term><Literal>maintainer-clean</Literal>:</Term>
+<ListItem>
+<Para>
+Delete everything from the current directory that can be reconstructed
+with this Makefile. This typically includes everything deleted by
+<literal>distclean</literal>, plus more: C source files produced by
+Bison, tags tables, Info files, and so on.</para>
+
+<para>One exception, however: <literal>make maintainer-clean</literal>
+should not delete <filename>configure</filename> even if
+<filename>configure</filename> can be remade using a rule in the
+<filename>Makefile</filename>. More generally, <literal>make
+maintainer-clean</literal> should not delete anything that needs to
+exist in order to run <filename>configure</filename> and then begin to
+build the program.</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>Using a project from the build tree</title>
+<para>
+If you want to build GHC (say) and just use it direct from the build
+tree without doing <literal>make install</literal> first, you can run
+the in-place driver script:
+<filename>ghc/driver/ghc-inplace</filename>.
+</para>
+
+<para> Do <emphasis>NOT</emphasis> use
+<filename>ghc/driver/ghc</filename>, or
+<filename>ghc/driver/ghc-4.xx</filename>, as these are the scripts
+intended for installation, and contain hard-wired paths to the
+installed libraries, rather than the libraries in the build tree.
+</para>
+
+<para>
+Happy can similarly be run from the build tree, using
+<filename>happy/src/happy-inplace</filename>.
+</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 id="sec-makefile-arch">
+<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. This
+will place matching <Filename>.hc</Filename> files next to the corresponding
+Haskell source in the compiler subdirectory <Filename>ghc</Filename> and in
+the language package of hslibs (i.e., in <Filename>hslibs/lang</Filename>).
+Then follow the `normal' instructions in <Xref
+LinkEnd="sec-building-from-source"> for setting up a build tree.
+</Para>
+
+<Para>
+The actual build process is fully automated by the
+<Filename>hc-build</Filename> script located in the
+<Filename>distrib</Filename> directory. If you eventually want to install GHC
+into the directory <Filename>INSTALL_DIRECTORY</Filename>, the following
+command will execute the whole build process (it won't install yet):
+</Para>
+<Screen>
+foo% distrib/hc-build --prefix=INSTALL_DIRECTORY
+</Screen>
+<IndexTerm><Primary>--hc-build</Primary></IndexTerm>
+<Para>
+By default, the installation directory is <Filename>/usr/local</Filename>. If
+that is what you want, you may omit the argument to
+<Filename>hc-build</Filename>. Generally, any option given to
+<Filename>hc-build</Filename> is passed through to the configuration script
+<Filename>configure</Filename>. If <Filename>hc-build</Filename>
+successfully completes the build process, you can install the resulting
+system, as normal, with
+</Para>
+<Screen>
+foo% make install
+</Screen>
+
+<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 later, 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. You should read the
+GHC installation guide sections on Windows (in the user guide) before
+continuing to read these notes.
+</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.08</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.08</Filename> to <Filename>ghc</Filename>.
+And make sure that the directory is in your path.
+</Para>
+</ListItem>
+
+</ItemizedList>
+
+</Sect2>
+
+</Sect1>
+
+</Article>