-<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>happy</Command><IndexTerm><Primary>happy</Primary></IndexTerm>
-you'll find it convenient that the source distribution contains the
-result of running <Command>happy</Command> on the parser
-specifications. If you don't want to alter the parser then this saves
-you having to find and install <Command>happy</Command>. You will
-still need a working version of GHC (preferably version 4.08+) on your
-machine in order to compile (most of) the sources, however.
-</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 releases 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, BSD (any variant), 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>
-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, has a native code generator. 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 versa. 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>
-It is pretty easy to install.
-</para>
-
-<para>
-Perl 5 is required. For Win32 platforms, you should use the binary
-supplied in the InstallShield (copy it to <filename>/bin</filename>).
-The Cygwin-supplied Perl seems not to work.
-</para>
-
-<para>
-Perl should be put somewhere so that it can be invoked by the
-<Literal>#!</Literal> script-invoking mechanism. The full
-pathname 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
-<command>autoconf</command> 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:</para>
-
-<ProgramListing>
-./configure <optional><parameter>args</parameter></optional>
-</ProgramListing>
-
- <para><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>
-
- <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><command>configure</command> takes some optional
- arguments. Use <literal>./configure --help</literal> to
- get a list of the available arguments. Here are some of
- the ones you might need:</para>
-
- <variablelist>
- <varlistentry>
- <term><literal>--with-ghc=<parameter>path</parameter></literal></term>
- <indexterm><primary><literal>--with-ghc</literal></primary>
- </indexterm>
- <listitem>
- <para>Specifies the path to an installed GHC which
- you would like to use. This compiler will be used
- for compiling GHC-specific code (eg. GHC itself).
- This option <emphasis>cannot</emphasis> be
- specified using <filename>build.mk</filename> (see
- later), because <command>configure</command> needs
- to auto-detect the version of GHC you're using.
- The default is to look for a compiler named
- <literal>ghc</literal> in your path.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>--with-hc=<parameter>path</parameter></literal></term>
- <indexterm><primary><literal>--with-hhc</literal></primary>
- </indexterm>
- <listitem>
- <para>Specifies the path to any installed Haskell
- compiler. This compiler will be used for
- compiling generic Haskell code. The default is to
- use <literal>ghc</literal>.</para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- <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>
-
-<ProgramListing>
-GhcHcOpts=-O -Rghc-timing
-</ProgramListing>
-
- <para>The accompanying comment explains that this is the list of
- flags passed to GHC when building GHC itself. For doing
- development, it is wise to add <literal>-DDEBUG</literal>, to
- enable debugging code. So you would add the following to
- <filename>build.mk</filename>:</para>
-
- <para>or, if you prefer,</para>
-
-<ProgramListing>
-GhcHcOpts += -DDEBUG
-</ProgramListing>
-
- <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>If you want to remove the <literal>-O</literal> as well (a
- good idea when developing, because the turn-around cycle gets a
- lot quicker), you can just override
- <literal>GhcLibHcOpts</literal> altogether:</para>
-
-<ProgramListing>
-GhcHcOpts=-DDEBUG -Rghc-timing
-</ProgramListing>
-
- <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>
-
-<ProgramListing>
-YACC = @YaccCmd@
-</ProgramListing>
-
- <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>
-
-<ProgramListing>
-YACC = myyacc
-</ProgramListing>
-
- <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>
-
- <para>To just build the whole thing, <command>cd</command> to
- the top of your <literal>fptools</literal> tree and type
- <command>gmake</command>. This will prepare the tree and build
- the various projects in the correct order.</para>
-
- </Sect2>
-
- <Sect2 id="sec-standard-targets">
- <Title>Standard Targets</title>
- <IndexTerm><Primary>targets, standard makefile</Primary></IndexTerm>
- <IndexTerm><Primary>makefile targets</Primary></IndexTerm>
-
- <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>Invoking the <literal>boot</literal> target explicitly is not
-normally necessary. From the top-level <literal>fptools</literal>
-directory, invoking <literal>gmake</literal> causes <literal>gmake
-boot all</literal> to be invoked in each of the project
-subdirectories, in the order specified by
-<literal>$(AllTargets)</literal> in
-<literal>config.mk</literal>.</para>
-
-<para>If you're working in a subdirectory somewhere and need to update
-the dependencies, <literal>gmake boot</literal> is a good way to do it.</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. Note that this target does “make
-distclean” as part of its work; don't use it if you want to keep
-what you've built.
-</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/compiler/ghc-inplace</filename>.
-</para>
-
-<para> Do <emphasis>NOT</emphasis> use
-<filename>ghc/compiler/ghc</filename>, or
-<filename>ghc/compiler/ghc-5.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>
-
+<PubDate>November 2001</PubDate>
+
+ <abstract>
+ <para>The Glasgow fptools suite is a collection of Functional
+ Programming related tools, including the Glasgow Haskell
+ Compiler (GHC). The source code for the whole suite is kept in
+ a single CVS repository and shares a common build and
+ installation system.</para>
+
+ <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 sources</title>
+
+ <para>You can get your hands on the <literal>fptools</literal>
+ in two ways:</para>
+
+ <variablelist>
+
+ <varlistentry>
+ <term><indexterm><primary>Source
+ distributions</primary></indexterm>Source distributions</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>happy</command><indexterm><primary>happy</primary></indexterm>
+ you'll find it convenient that the source distribution
+ contains the result of running <command>happy</command> on
+ the parser specifications. If you don't want to alter the
+ parser then this saves you having to find and install
+ <command>happy</command>. You will still need a working
+ version of GHC (version 5.x or later) on your machine in
+ order to compile (most of) the sources, however.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>The CVS repository.</term>
+ <indexterm><primary>CVS repository</primary>
+ </indexterm>
+ <listitem>
+ <para>We make releases 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 can be found
+ in <xref linkend="sec-cvs">.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <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-cvs">
+ <title>Using the CVS repository</title>
+
+ <para>We use <ulink url="http://www.cvshome.org/">CVS</ulink> (Concurrent Version System) to keep track of our
+ sources for various software projects. CVS lets several people
+ work on the same software at the same time, allowing changes to be
+ checked in incrementally. </para>
+
+ <para>This section is a set of guidelines for how to use our CVS
+ repository, and will probably evolve in time. The main thing to
+ remember is that most mistakes can be undone, but if there's
+ anything you're not sure about feel free to bug the local CVS
+ meister (namely Jeff Lewis
+ <email>jlewis@galconn.com</email>). </para>
+
+ <sect2 id="cvs-access">
+ <title>Getting access to the CVS Repository</title>
+
+ <para>You can access the repository in one of two ways:
+ read-only (<xref linkend="cvs-read-only">), or read-write (<xref
+ linkend="cvs-read-write">).</para>
+
+ <sect3 id="cvs-read-only">
+ <title>Remote Read-only CVS Access</title>
+
+ <para>Read-only access is available to anyone - there's no
+ need to ask us first. With read-only CVS access you can do
+ anything except commit changes to the repository. You can
+ make changes to your local tree, and still use CVS's merge
+ facility to keep your tree up to date, and you can generate
+ patches using 'cvs diff' in order to send to us for
+ inclusion. </para>
+
+ <para>To get read-only access to the repository:</para>
+
+ <orderedlist>
+ <listitem>
+ <para>Make sure that <application>cvs</application> is
+ installed on your machine.</para>
+ </listitem>
+ <listitem>
+ <para>Set your <literal>$CVSROOT</literal> environment variable to
+ <literal>:pserver:anoncvs@glass.cse.ogi.edu:/cvs</literal></para>
+ <para>If you set <literal>$CVSROOT</literal> in a shell script, be sure not to
+ have any trailing spaces on that line, otherwise CVS will respond with
+ a perplexing message like
+ <programlisting>
+ /cvs : no such repository
+ </programlisting></para>
+ </listitem>
+ <listitem>
+ <para>Run the command</para>
+<programlisting>
+ $ cvs login
+</programlisting>
+ <para>The password is simply <literal>cvs</literal>. This
+ sets up a file in your home directory called
+ <literal>.cvspass</literal>, which squirrels away the
+ dummy password, so you only need to do this step once.</para>
+ </listitem>
+
+ <listitem>
+ <para>Now go to <xref linkend="cvs-first">.</para>
+ </listitem>
+ </orderedlist>
+ </sect3>
+
+ <sect3 id="cvs-read-write">
+ <title>Remote Read-Write CVS Access</title>
+
+ <para>We generally supply read-write access to folk doing
+ serious development on some part of the source tree, when
+ going through us would be a pain. If you're developing some
+ feature, or think you have the time and inclination to fix
+ bugs in our sources, feel free to ask for read-write
+ access. There is a certain amount of responsibility that goes
+ with commit privileges; we are more likely to grant you access
+ if you've demonstrated your competence by sending us patches
+ via mail in the past.</para>
+
+ <para>To get remote read-write CVS access, you need to do the
+ following steps.</para>
+
+ <orderedlist>
+ <listitem>
+ <para>Make sure that <literal>cvs</literal> and
+ <literal>ssh</literal> are both installed on your
+ machine.</para>
+ </listitem>
+
+ <listitem>
+ <para>Generate a DSA private-key/public-key pair, thus:</para>
+<screen>
+ $ ssh-keygen -d
+</screen>
+ <para>(<literal>ssh-keygen</literal> comes with
+ <literal>ssh</literal>.) Running <literal>ssh-keygen
+ -d</literal> creates the private and public keys in
+ <literal>$HOME/.ssh/id_dsa</literal> and
+ <literal>$HOME/.ssh/id_dsa.pub</literal> respectively
+ (assuming you accept the standard defaults).</para>
+
+ <para><literal>ssh-keygen -d</literal> will only work if
+ you have Version 2 <literal>ssh</literal> installed; it
+ will fail harmlessly otherwise. If you only have Version
+ 1 you can instead generate an RSA key pair using plain</para>
+<screen>
+ $ ssh-keygen
+</screen>
+
+ <para>Doing so creates the private and public RSA keys in
+ <literal>$HOME/.ssh/identity</literal> and
+ <literal>$HOME/.ssh/identity.pub</literal>
+ respectively.</para>
+
+ <para>[Deprecated.] Incidentally, you can force a Version
+ 2 <literal>ssh</literal> to use the Version 1 protocol by
+ creating <literal>$HOME/config</literal> with the
+ following in it:</para>
+<screen>
+ BatchMode Yes
+
+ Host cvs.haskell.org
+ Protocol 1
+</screen>
+
+ <para>In both cases, <literal>ssh-keygen</literal> will
+ ask for a <firstterm>passphrase</firstterm>. The
+ passphrase is a password that protects your private key.
+ In response to the 'Enter passphrase' question, you can
+ either:</para>
+ <itemizedlist>
+ <listitem>
+ <para>[Recommended.] Enter a passphrase, which you
+ will quote each time you use CVS.
+ <literal>ssh-agent</literal> makes this entirely
+ un-tiresome.</para>
+ </listitem>
+ <listitem>
+ <para>[Deprecated.] Just hit return (i.e. use an empty
+ passphrase); then you won't need to quote the
+ passphrase when using CVS. The downside is that
+ anyone who can see into your <literal>.ssh</literal>
+ directory, and thereby get your private key, can mess
+ up the repository. So you must keep the
+ <literal>.ssh</literal> directory with draconian
+ no-access permissions.</para>
+ </listitem>
+ </itemizedlist>
+
+
+ <para>
+ <emphasis>Windows users: see the notes in <xref linkend="configure-ssh"> about <command>ssh</command> wrinkles!</emphasis>
+ </para>
+
+
+ </listitem>
+
+ <listitem>
+ <para>Send a message to to the CVS repository
+ administrator (currently Jeff Lewis
+ <email>jeff@galconn.com</email>), containing:</para>
+ <itemizedlist>
+ <listitem>
+ <para>Your desired user-name.</para>
+ </listitem>
+ <listitem>
+ <para>Your <literal>.ssh/id_dsa.pub</literal> (or
+ <literal>.ssh/identity.pub</literal>).</para>
+ </listitem>
+ </itemizedlist>
+ <para>He will set up your account.</para>
+ </listitem>
+
+ <listitem>
+ <para>Set the following environment variables:</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> to <filename>ssh</filename>
+ </para>
+ <para>[Windows users.] Setting your <literal>CVS_RSH</literal> to
+ <literal>ssh</literal> assumes that your CVS client
+ understands how to execute shell script
+ ("#!"s,really), which is what
+ <literal>ssh</literal> is. This may not be the case on
+ Win32 platforms, so in that case set <literal>CVS_RSH</literal> to
+ <literal>ssh1</literal>.</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>$CVSROOT</literal> to
+ <literal>:ext:</literal><replaceable>your-username</replaceable>
+ <literal>@cvs.haskell.org:/home/cvs/root</literal>
+ where <replaceable>your-username</replaceable> is your user name on
+ <literal>cvs.haskell.org</literal>.
+ </para>
+ <para>The <literal>CVSROOT</literal> environment variable will
+ be recorded in the checked-out tree, so you don't need to set
+ this every time. </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>
+
+ <listitem>
+ <para>
+ <constant>$SHELL</constant>: To use bash as the shell in Emacs, you need to
+ set this to point to <filename>bash.exe</filename>.
+ </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>
+ [Windows users.] 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>
+
+ </orderedlist>
+
+
+ <para>[Experts.] Once your account is set up, you can get
+ access from other machines without bothering Jeff, thus:</para>
+ <orderedlist>
+ <listitem>
+ <para>Generate a public/private key pair on the new
+ machine.</para>
+ </listitem>
+ <listitem>
+ <para>Use ssh to log in to
+ <literal>cvs.haskell.org</literal>, from your old
+ machine.</para>
+ </listitem>
+ <listitem>
+ <para>Add the public key for the new machine to the file
+ <literal>$HOME/ssh/authorized_keys</literal> on
+ <literal>cvs.haskell.org</literal>.
+ (<literal>authorized_keys2</literal>, I think, for Version
+ 2 protocol.)</para>
+ </listitem>
+ <listitem>
+ <para>Make sure that the new version of
+ <literal>authorized_keys</literal> still has 600 file
+ permissions.</para>
+ </listitem>
+ </orderedlist>
+ </sect3>
+ </sect2>
+
+
+
+ <sect2 id="cvs-first">
+ <title>Checking Out a Source Tree</title>
+
+ <itemizedlist>
+ <listitem>
+ <para>Make sure you set your <literal>CVSROOT</literal>
+ environment variable according to either of the remote
+ methods above. The Approved Way to check out a source tree
+ is as follows:</para>
+
+<screen>
+ $ cvs checkout fpconfig
+</screen>
+
+ <para>At this point you have a new directory called
+ <literal>fptools</literal> which contains the basic stuff
+ for the fptools suite, including the configuration files and
+ some other junk. </para>
+
+<para>[Windows users.] The following messages appear to be harmless: