[project @ 2000-06-19 13:37:50 by chak]

[ghc-hetmet.git] / docs / building.sgml

diff --git a/docs/building.sgml b/docs/building.sgml
index b7c3fbb..eebe7aa 100644 (file)
--- a/docs/building.sgml
+++ b/docs/building.sgml
@@ -1,10 +1,10 @@
 <!DOCTYPE Article PUBLIC "-//OASIS//DTD DocBook V3.1//EN">
 
 <!DOCTYPE Article PUBLIC "-//OASIS//DTD DocBook V3.1//EN">
 

-<Article>
+<Article id="building-guide">

 
 <ArtHeader>
 
 
 <ArtHeader>
 

-<Title>Building and Installing the Glasgow Functional Programming Tools Suite</Title>
+<Title>Building the Glasgow Functional Programming Tools Suite</Title>

 <Author><OtherName>The GHC Team</OtherName></Author>
 <Address><Email>glasgow-haskell-&lcub;users,bugs&rcub;@haskell.org</Email></Address>
 <PubDate>January 2000</PubDate>
 <Author><OtherName>The GHC Team</OtherName></Author>
 <Address><Email>glasgow-haskell-&lcub;users,bugs&rcub;@haskell.org</Email></Address>
 <PubDate>January 2000</PubDate>

@@ -172,7 +172,7 @@ manual in detail.
 
 </Sect1>
 
 
 </Sect1>
 

-<Sect1>
+<Sect1 id="sec-build-checks">

 <Title>Things to check before you start typing</Title>
 
 <Para>
 <Title>Things to check before you start typing</Title>
 
 <Para>

@@ -182,32 +182,26 @@ Here's a list of things to check before you get started.
 <ListItem>
 
 <Para>
 <ListItem>
 
 <Para>

-<IndexTerm><Primary>Disk space needed</Primary></IndexTerm>Disk space needed: About 30MB (five hamburgers' worth) of disk space
-for the most basic binary distribution of GHC; more for some
-platforms, e.g., Alphas.  An extra ``bundle'' (e.g., concurrent
-Haskell libraries) might take you to 8&ndash;10 hamburgers.
-
-You'll need over 100MB (say, 20 hamburgers' worth) if you need to
-build the basic stuff from scratch.
-
-
-All of the above are <Emphasis>estimates</Emphasis> of disk-space needs. (I don't yet
-know the disk requirements for the non-GHC tools).
-
+<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.
 </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.
 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>
 </ListItem>
 <ListItem>

@@ -317,14 +311,12 @@ by their ``canonical'' CPU/Manufacturer/OS triple.
 
 <VarListEntry>
 <Term>alpha-dec-{osf,linux,freebsd,openbsd,netbsd}:</Term>
 
 <VarListEntry>
 <Term>alpha-dec-{osf,linux,freebsd,openbsd,netbsd}:</Term>

-<ListItem>
-<Para>

 <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>
 <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>

-</Para>
+<ListItem>

 
 <Para>
 Currently non-working.  The last working version (osf[1-3]) is GHC
 
 <Para>
 Currently non-working.  The last working version (osf[1-3]) is GHC

@@ -338,8 +330,8 @@ either need Alpha support and/or can provide access to boxes.
 </ListItem></VarListEntry>
 <VarListEntry>
 <Term>sparc-sun-sunos4:</Term>
 </ListItem></VarListEntry>
 <VarListEntry>
 <Term>sparc-sun-sunos4:</Term>

-<ListItem>

 <IndexTerm><Primary>sparc-sun-sunos4</Primary></IndexTerm>
 <IndexTerm><Primary>sparc-sun-sunos4</Primary></IndexTerm>

+<ListItem>

 
 <Para>
 Probably works with minor tweaks, hasn't been tested for a while.
 
 <Para>
 Probably works with minor tweaks, hasn't been tested for a while.

@@ -348,8 +340,8 @@ Probably works with minor tweaks, hasn't been tested for a while.
 </ListItem></VarListEntry>
 <VarListEntry>
 <Term>sparc-sun-solaris2:</Term>
 </ListItem></VarListEntry>
 <VarListEntry>
 <Term>sparc-sun-solaris2:</Term>

-<ListItem>

 <IndexTerm><Primary>sparc-sun-solaris2</Primary></IndexTerm>
 <IndexTerm><Primary>sparc-sun-solaris2</Primary></IndexTerm>

+<ListItem>

 
 <Para>
 Fully supported, including native-code generator.
 
 <Para>
 Fully supported, including native-code generator.

@@ -358,8 +350,8 @@ Fully supported, including native-code generator.
 </ListItem></VarListEntry>
 <VarListEntry>
 <Term>hppa1.1-hp-hpux (HP-PA boxes running HPUX 9.x)</Term>
 </ListItem></VarListEntry>
 <VarListEntry>
 <Term>hppa1.1-hp-hpux (HP-PA boxes running HPUX 9.x)</Term>

-<ListItem>

 <IndexTerm><Primary>hppa1.1-hp-hpux</Primary></IndexTerm>
 <IndexTerm><Primary>hppa1.1-hp-hpux</Primary></IndexTerm>

+<ListItem>

 
 <Para>
 Works registerised.  No native-code generator.
 
 <Para>
 Works registerised.  No native-code generator.

@@ -367,9 +359,9 @@ Works registerised.  No native-code generator.
 
 </ListItem></VarListEntry>
 <VarListEntry>
 
 </ListItem></VarListEntry>
 <VarListEntry>

-<Term>i386-unknown-linux (PCs running Linux&mdash;ELF format):</Term>
-<ListItem>
+<Term>i386-unknown-linux (PCs running Linux&mdash;ELF binary format):</Term>

 <IndexTerm><Primary>i386-*-linux</Primary></IndexTerm>
 <IndexTerm><Primary>i386-*-linux</Primary></IndexTerm>

+<ListItem>

 
 <Para>
 GHC works registerised.  You <Emphasis>must</Emphasis> have GCC 2.7.x
 
 <Para>
 GHC works registerised.  You <Emphasis>must</Emphasis> have GCC 2.7.x

@@ -384,12 +376,10 @@ versions, even if the shared library version hasn't changed.
 <VarListEntry>
 <Term>i386-unknown-{freebsd,netbsd,openbsd) (PCs running FreeBSD 2.2
 or higher, NetBSD, and possibly OpenBSD):</Term>
 <VarListEntry>
 <Term>i386-unknown-{freebsd,netbsd,openbsd) (PCs running FreeBSD 2.2
 or higher, NetBSD, and possibly OpenBSD):</Term>

-<ListItem>
-<Para>

 <IndexTerm><Primary>i386-unknown-freebsd</Primary></IndexTerm> 
 <IndexTerm><Primary>i386-unknown-netbsd</Primary></IndexTerm> 
 <IndexTerm><Primary>i386-unknown-openbsd</Primary></IndexTerm> 
 <IndexTerm><Primary>i386-unknown-freebsd</Primary></IndexTerm> 
 <IndexTerm><Primary>i386-unknown-netbsd</Primary></IndexTerm> 
 <IndexTerm><Primary>i386-unknown-openbsd</Primary></IndexTerm> 

-</Para>
+<ListItem>

 
 <Para>
 GHC works registerised.  These systems provide ready-built packages of
 
 <Para>
 GHC works registerised.  These systems provide ready-built packages of

@@ -400,10 +390,8 @@ the package.
 </ListItem></VarListEntry>
 <VarListEntry>
 <Term>i386-unknown-cygwin32:</Term>
 </ListItem></VarListEntry>
 <VarListEntry>
 <Term>i386-unknown-cygwin32:</Term>

-<ListItem>
-<Para>

 <IndexTerm><Primary>i386-unknown-cygwin32</Primary></IndexTerm>
 <IndexTerm><Primary>i386-unknown-cygwin32</Primary></IndexTerm>

-</Para>
+<ListItem>

 
 <Para>
 Fully supported under Win9x/NT, including a native code
 
 <Para>
 Fully supported under Win9x/NT, including a native code

@@ -415,10 +403,8 @@ etc.).
 </ListItem></VarListEntry>
 <VarListEntry>
 <Term>mips-sgi-irix5:</Term>
 </ListItem></VarListEntry>
 <VarListEntry>
 <Term>mips-sgi-irix5:</Term>

-<ListItem>
-<Para>

 <IndexTerm><Primary>mips-sgi-irix[5-6]</Primary></IndexTerm>
 <IndexTerm><Primary>mips-sgi-irix[5-6]</Primary></IndexTerm>

-</Para>
+<ListItem>

 
 <Para>
 Port currently doesn't work, needs some minimal porting effort.  As
 
 <Para>
 Port currently doesn't work, needs some minimal porting effort.  As

@@ -470,8 +456,11 @@ Unless you hear otherwise, the other tools work if GHC works.
 
 <Para>
 Here are the gory details about some utility programs you may need;
 
 <Para>
 Here are the gory details about some utility programs you may need;

-<Command>perl</Command> and <Command>gcc</Command> are the only important ones. (PVM<IndexTerm><Primary>PVM</Primary></IndexTerm> is important
-if you're going for Parallel Haskell.)  The <Command>configure</Command><IndexTerm><Primary>configure</Primary></IndexTerm>
+<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>
 
 script will tell you if you are missing something.
 </Para>
 

@@ -480,13 +469,13 @@ script will tell you if you are missing something.
 
 <VarListEntry>
 <Term>Perl:</Term>
 
 <VarListEntry>
 <Term>Perl:</Term>

-<ListItem>
-<Para>

 <IndexTerm><Primary>pre-supposed: Perl</Primary></IndexTerm>
 <IndexTerm><Primary>Perl, pre-supposed</Primary></IndexTerm>
 <IndexTerm><Primary>pre-supposed: Perl</Primary></IndexTerm>
 <IndexTerm><Primary>Perl, pre-supposed</Primary></IndexTerm>

-<Emphasis>You have to have Perl to proceed!</Emphasis> Perl is a language quite good
-for doing shell-scripty tasks that involve lots of text processing.
-It is pretty easy to install.
+<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>
 </Para>
 
 <Para>

@@ -508,11 +497,9 @@ systems.
 </ListItem></VarListEntry>
 <VarListEntry>
 <Term>GNU C (<Command>gcc</Command>):</Term>
 </ListItem></VarListEntry>
 <VarListEntry>
 <Term>GNU C (<Command>gcc</Command>):</Term>

-<ListItem>
-<Para>

 <IndexTerm><Primary>pre-supposed: GCC (GNU C compiler)</Primary></IndexTerm>
 <IndexTerm><Primary>GCC (GNU C compiler), pre-supposed</Primary></IndexTerm>
 <IndexTerm><Primary>pre-supposed: GCC (GNU C compiler)</Primary></IndexTerm>
 <IndexTerm><Primary>GCC (GNU C compiler), pre-supposed</Primary></IndexTerm>

-</Para>
+<ListItem>

 
 <Para>
 We recommend using GCC version 2.95.2 on all platforms.  Failing that,
 
 <Para>
 We recommend using GCC version 2.95.2 on all platforms.  Failing that,

@@ -530,14 +517,27 @@ please let us know, so we can report it and get things improved.
 </Para>
 </ListItem></VarListEntry>
 
 </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>
 <VarListEntry>
 <Term>Autoconf:</Term>

-<ListItem>
-<Para>

 <IndexTerm><Primary>pre-supposed: Autoconf</Primary></IndexTerm>
 <IndexTerm><Primary>Autoconf, pre-supposed</Primary></IndexTerm>
 <IndexTerm><Primary>pre-supposed: Autoconf</Primary></IndexTerm>
 <IndexTerm><Primary>Autoconf, pre-supposed</Primary></IndexTerm>

-</Para>
-
+<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
 <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

@@ -554,11 +554,10 @@ If you modify either of these files, you'll need Autoconf to rebuild
 </ListItem></VarListEntry>
 <VarListEntry>
 <Term><Command>sed</Command></Term>
 </ListItem></VarListEntry>
 <VarListEntry>
 <Term><Command>sed</Command></Term>

-<ListItem>
-<Para>

 <IndexTerm><Primary>pre-supposed: sed</Primary></IndexTerm>
 <IndexTerm><Primary>sed, pre-supposed</Primary></IndexTerm>
 <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
 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

@@ -586,11 +585,9 @@ particularly Glasgow-ish, but Occasionally Indispensable.  Like
 
 <VarListEntry>
 <Term>PVM version 3:</Term>
 
 <VarListEntry>
 <Term>PVM version 3:</Term>

-<ListItem>
-<Para>

 <IndexTerm><Primary>pre-supposed: PVM3 (Parallel Virtual Machine)</Primary></IndexTerm>
 <IndexTerm><Primary>PVM3 (Parallel Virtual Machine), pre-supposed</Primary></IndexTerm>
 <IndexTerm><Primary>pre-supposed: PVM3 (Parallel Virtual Machine)</Primary></IndexTerm>
 <IndexTerm><Primary>PVM3 (Parallel Virtual Machine), pre-supposed</Primary></IndexTerm>

-</Para>
+<ListItem>

 
 <Para>
 PVM is the Parallel Virtual Machine on which Parallel Haskell programs
 
 <Para>
 PVM is the Parallel Virtual Machine on which Parallel Haskell programs

@@ -613,9 +610,9 @@ the <Filename>Readme</Filename> instructions.
 </ListItem></VarListEntry>
 <VarListEntry>
 <Term><Command>bash</Command>:</Term>
 </ListItem></VarListEntry>
 <VarListEntry>
 <Term><Command>bash</Command>:</Term>

+<IndexTerm><Primary>bash, presupposed (Parallel Haskell only)</Primary></IndexTerm>

 <ListItem>
 <Para>
 <ListItem>
 <Para>

-<IndexTerm><Primary>bash, presupposed (Parallel Haskell only)</Primary></IndexTerm>

 Sadly, the <Command>gr2ps</Command> script, used to convert ``parallelism profiles''
 to PostScript, is written in Bash (GNU's Bourne Again shell).
 This bug will be fixed (someday).
 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).

@@ -640,25 +637,22 @@ documentation that comes with the <Literal>fptools</Literal> projects:
 
 <VarListEntry>
 <Term>DocBook:</Term>
 
 <VarListEntry>
 <Term>DocBook:</Term>

+<IndexTerm><Primary>pre-supposed: DocBook</Primary></IndexTerm>
+<IndexTerm><Primary>DocBook, pre-supposed</Primary></IndexTerm>

 <ListItem>
 <Para>
 <ListItem>
 <Para>

-<IndexTerm><Primary>pre-supposed: DocBook</Primary></IndexTerm>
-<IndexTerm><Primary>DocBook, pre-supposed</Primary></IndexTerm> All
-our documentation is written in SGML, using the DocBook DTD and
-processed using the <ULink
-URL="http://sourceware.cygnus.com/docbook-tools/">Cygnus DocBook
-tools</ULink>, which is the most shrink-wrapped SGML suite that we
-could find.  Unfortunately, it's only packaged as RPMs. You can use it
-to generate HTML, DVI (and hence PDF and Postscript) and RTF from any
-DocBook source file (including this manual). N.B. The <Emphasis>Cygnus</Emphasis> version of the tools is assumed. Others, such as the SuSE version, may not work.
+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>
 </Para>

+

 </ListItem></VarListEntry>
 <VarListEntry>
 <Term>TeX:</Term>
 </ListItem></VarListEntry>
 <VarListEntry>
 <Term>TeX:</Term>

-<ListItem>
-<Para>

 <IndexTerm><Primary>pre-supposed: TeX</Primary></IndexTerm>
 <IndexTerm><Primary>TeX, pre-supposed</Primary></IndexTerm>
 <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.
 A decent TeX distribution is required if you want to produce printable
 documentation.  We recomment teTeX, which includes just about
 everything you need.

@@ -673,16 +667,12 @@ everything you need.
 <Title>Other useful tools
 </Title>
 
 <Title>Other useful tools
 </Title>
 

-<Para>

 <VariableList>
 <VariableList>

-

 <VarListEntry>
 <Term>Flex:</Term>
 <VarListEntry>
 <Term>Flex:</Term>

-<ListItem>
-<Para>

 <IndexTerm><Primary>pre-supposed: flex</Primary></IndexTerm> 
 <IndexTerm><Primary>flex, pre-supposed</Primary></IndexTerm>
 <IndexTerm><Primary>pre-supposed: flex</Primary></IndexTerm> 
 <IndexTerm><Primary>flex, pre-supposed</Primary></IndexTerm>

-</Para>
+<ListItem>

 
 <Para>
 This is a quite-a-bit-better-than-Lex lexer.  Used to build a couple
 
 <Para>
 This is a quite-a-bit-better-than-Lex lexer.  Used to build a couple

@@ -692,7 +682,6 @@ work; you should get the GNU version.
 </Para>
 </ListItem></VarListEntry>
 </VariableList>
 </Para>
 </ListItem></VarListEntry>
 </VariableList>

-</Para>

 
 </Sect2>
 
 
 </Sect2>
 

@@ -897,6 +886,13 @@ no arguments). This GNU program converts <Filename><Constant>&dollar;(FPTOOLS&lo
 to a shell script called <Filename><Constant>&dollar;(FPTOOLS&lowbar;TOP)</Constant>/configure</Filename>.
 </Para>
 
 to a shell script called <Filename><Constant>&dollar;(FPTOOLS&lowbar;TOP)</Constant>/configure</Filename>.
 </Para>
 

+<para>
+Some projects, including GHC, have their own configure script.  If
+there's an
+<Constant>&dollar;(FPTOOLS&lowbar;TOP)/&lt;project&gt;/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
 <Para>
 Both these steps are completely platform-independent; they just mean
 that the human-written file (<Filename>configure.in</Filename>) can be short, although

@@ -1267,23 +1263,56 @@ install them?  That is specified by
 reverses the effect of <Literal>install</Literal>.
 </Para>
 </ListItem></VarListEntry>
 reverses the effect of <Literal>install</Literal>.
 </Para>
 </ListItem></VarListEntry>

+

 <VarListEntry>
 <Term><Literal>clean</Literal>:</Term>
 <ListItem>
 <Para>
 <VarListEntry>
 <Term><Literal>clean</Literal>:</Term>
 <ListItem>
 <Para>

-remove all easily-rebuilt files.
-</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. Also preserve files that could be made
+by building, but normally aren't because the distribution comes
+with them.</para>

 </ListItem></VarListEntry>
 </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>
 <VarListEntry>

-<Term><Literal>veryclean</Literal>:</Term>
+<Term><Literal>maintainer-clean</Literal>:</Term>

 <ListItem>
 <Para>
 <ListItem>
 <Para>

-remove all files that can be rebuilt at all.
-There's a danger here that you may remove a file that needs a more
-obscure utility to rebuild it (especially if you started from a source
-distribution).
-</Para>
-</ListItem></VarListEntry>
+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>
 <VarListEntry>
 <Term><Literal>check</Literal>:</Term>
 <ListItem>

@@ -1360,11 +1389,33 @@ Most <Filename>Makefile</Filename>s have targets other than these.  You can disc
 
 </Sect2>
 
 
 </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>
 <Sect2>

-<Title>Fast Making
-<IndexTerm><Primary>fastmake</Primary></IndexTerm>
+<Title>Fast Making <IndexTerm><Primary>fastmake</Primary></IndexTerm>

 <IndexTerm><Primary>dependencies, omitting</Primary></IndexTerm>
 <IndexTerm><Primary>dependencies, omitting</Primary></IndexTerm>

-<IndexTerm><Primary>FAST, makefile variable</Primary></IndexTerm></Title>
+<IndexTerm><Primary>FAST, makefile
+variable</Primary></IndexTerm></Title>

 
 <Para>
 Sometimes the dependencies get in the way: if you've made a small
 
 <Para>
 Sometimes the dependencies get in the way: if you've made a small

@@ -1400,7 +1451,7 @@ User's Guide section on "Separate Compilation").
 
 </Sect1>
 
 
 </Sect1>
 

-<Sect1>
+<Sect1 id="sec-makefile-arch">

 <Title>The <Filename>Makefile</Filename> architecture
 <IndexTerm><Primary>makefile architecture</Primary></IndexTerm></Title>
 
 <Title>The <Filename>Makefile</Filename> architecture
 <IndexTerm><Primary>makefile architecture</Primary></IndexTerm></Title>
 

@@ -2335,61 +2386,52 @@ the canned rules being included, and conflicting with yours.
 <IndexTerm><Primary>porting GHC</Primary></IndexTerm></Title>
 
 <Para>
 <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
+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>
 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.
+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>
 </Para>
 
 <Para>

-Assuming you've got them, unpack them on top of a fresh source tree.
-Then follow the `normal' instructions in <Xref LinkEnd="sec-building-from-source"> for setting
-up a build tree. When you invoke the configure script, you'll have
-to tell the script about your intentions:
+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>
 </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>
 <Screen>

-foo% ./configure --enable-hc-boot
+foo% distrib/hc-build --prefix=INSTALL_DIRECTORY

 </Screen>
 </Screen>

-
-<IndexTerm><Primary>--enable-hc-boot</Primary></IndexTerm>
-<IndexTerm><Primary>--disable-hc-boot</Primary></IndexTerm>
-</Para>
-
+<IndexTerm><Primary>--hc-build</Primary></IndexTerm>

 <Para>
 <Para>

-Assuming it configures OK and you don't need to create <Filename>mk/build.mk</Filename>
-for any other purposes, the next step is to proceed with a <Command>make boot</Command>
-followed by <Command>make all</Command>. At the successful completion of <Command>make all</Command>,
-you should end up with a binary of the compiler proper,
-<Filename>ghc/compiler/hsc</Filename>, plus archives (but no <Filename>.hi</Filename> files!) of the prelude
-libraries. To generate the Prelude interface files (and test drive the
-bootstrapped compiler), re-run the <Command>configure</Command> script, but this time
-without the <Option>--enable-hc-boot</Option> option. After that re-create the
-contents of <Filename>ghc/lib</Filename>:
+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>
 </Para>

-
-<Para>
-

 <Screen>
 <Screen>

-foo% ./configure
- ....
-foo% cd ghc/lib
-foo% make clean
-foo% make boot
-foo% make all
+foo% make install

 </Screen>
 
 </Screen>
 

-</Para>
-

 <Para>
 That's the mechanics of the boot process, but, of course, if you're
 trying to boot on a platform that is not supported and significantly
 <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