-<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>
+ <para>You can call the fptools directory whatever you like,
+ CVS won't mind: </para>
+
+<screen>
+ $ mv fptools <replaceable>directory</replaceable>
+</screen>
+
+ <para> NB: after you've read the CVS manual you might be
+ tempted to try</para>
+<screen>
+ $ cvs checkout -d <replaceable>directory</replaceable> fpconfig
+</screen>
+
+ <para>instead of checking out <literal>fpconfig</literal>
+ and then renaming it. But this doesn't work, and will
+ result in checking out the entire repository instead of just
+ the <literal>fpconfig</literal> bit.</para>
+<screen>
+ $ cd <replaceable>directory</replaceable>
+ $ cvs checkout ghc hslibs libraries
+</screen>
+
+ <para>The second command here checks out the relevant
+ modules you want to work on. For a GHC build, for instance,
+ you need at least the <literal>ghc</literal>,
+ <literal>hslibs</literal> and <literal>libraries</literal>
+ modules (for a full list of the projects available, see
+ <xref linkend="projects">).</para>
+
+ <para>Remember that if you do not have
+ <literal>happy</literal> installed, you need to check it out
+ as well.</para>
+ </listitem>
+ </itemizedlist>
+ </sect2>
+
+ <sect2 id="cvs-committing">
+ <title>Committing Changes</title>
+
+ <para>This is only if you have read-write access to the
+ repository. For anoncvs users, CVS will issue a "read-only
+ repository" error if you try to commit changes.</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Build the software, if necessary. Unless you're just
+ working on documentation, you'll probably want to build the
+ software in order to test any changes you make.</para>
+ </listitem>
+
+ <listitem>
+ <para>Make changes. Preferably small ones first.</para>
+ </listitem>
+
+ <listitem>
+ <para>Test them. You can see exactly what changes you've
+ made by using the <literal>cvs diff</literal> command:</para>
+<screen>
+$ cvs diff
+</screen>
+ <para>lists all the changes (using the
+ <literal>diff</literal> command) in and below the current
+ directory. In emacs, <literal>C-c C-v =</literal> runs
+ <literal>cvs diff</literal> on the current buffer and shows
+ you the results.</para>
+ </listitem>
+
+ <listitem>
+ <para>If you changed something in the
+ <literal>fptools/libraries</literal> subdirectories, also run
+ <literal>make html</literal> to check if the documentation can
+ be generated successfully, too.</para>
+ </listitem>
+
+ <listitem>
+ <para>Before checking in a change, you need to update your
+ source tree:</para>
+
+<screen>
+$ cd fptools
+$ cvs update
+</screen>
+ <para>This pulls in any changes that other people have made,
+ and merges them with yours. If there are any conflicts, CVS
+ will tell you, and you'll have to resolve them before you
+ can check your changes in. The documentation describes what
+ to do in the event of a conflict.</para>
+
+ <para>It's not always necessary to do a full cvs update
+ before checking in a change, since CVS will always tell you
+ if you try to check in a file that someone else has changed.
+ However, you should still update at regular intervals to
+ avoid making changes that don't work in conjuction with
+ changes that someone else made. Keeping an eye on what goes
+ by on the mailing list can help here.</para>
+ </listitem>
+
+ <listitem>
+ <para>When you're happy that your change isn't going to
+ break anything, check it in. For a one-file change:</para>
+
+<screen>
+$ cvs commit <replaceable>filename</replaceable>
+</screen>
+
+ <para>CVS will then pop up an editor for you to enter a
+ "commit message", this is just a short description
+ of what your change does, and will be kept in the history of
+ the file.</para>
+
+ <para>If you're using emacs, simply load up the file into a
+ buffer and type <literal>C-x C-q</literal>, and emacs will
+ prompt for a commit message and then check in the file for
+ you.</para>
+
+ <para>For a multiple-file change, things are a bit
+ trickier. There are several ways to do this, but this is the
+ way I find easiest. First type the commit message into a
+ temporary file. Then either</para>
+
+<screen>
+$ cvs commit -F <replaceable>commit-message</replaceable> <replaceable>file_1</replaceable> .... <replaceable>file_n</replaceable>
+</screen>
+
+ <para>or, if nothing else has changed in this part of the
+ source tree, </para>
+
+<screen>
+$ cvs commit -F <replaceable>commit-message</replaceable> <replaceable>directory</replaceable>
+</screen>
+
+ <para>where <replaceable>directory</replaceable> is a common
+ parent directory for all your changes, and
+ <replaceable>commit-message</replaceable> is the name of the
+ file containing the commit message.</para>
+
+ <para>Shortly afterwards, you'll get some mail from the
+ relevant mailing list saying which files changed, and giving
+ the commit message. For a multiple-file change, you should
+ still get only <emphasis>one</emphasis> message.</para>
+ </listitem>
+ </itemizedlist>
+ </sect2>
+
+ <sect2 id="cvs-update">
+ <title>Updating Your Source Tree</title>
+
+ <para>It can be tempting to cvs update just part of a source
+ tree to bring in some changes that someone else has made, or
+ before committing your own changes. This is NOT RECOMMENDED!
+ Quite often changes in one part of the tree are dependent on
+ changes in another part of the tree (the
+ <literal>mk/*.mk</literal> files are a good example where
+ problems crop up quite often). Having an inconsistent tree is a
+ major cause of headaches. </para>
+
+ <para>So, to avoid a lot of hassle, follow this recipe for
+ updating your tree:</para>
+
+<screen>
+$ cd fptools
+$ cvs update -P 2>&1 | tee log</screen>
+
+ <para>Look at the log file, and fix any conflicts (denoted by a
+ <quote>C</quote> in the first column). New directories may have
+ appeared in the repository; CVS doesn't check these out by
+ default, so to get new directories you have to explicitly do
+<screen>
+$ cvs update -d</screen>
+ in each project subdirectory. Don't do this at the top level,
+ because then <emphasis>all</emphasis> the projects will be
+ checked out.</para>
+
+ <para>If you're using multiple build trees, then for every build
+ tree you have pointing at this source tree, you need to update
+ the links in case any new files have appeared: </para>
+
+<screen>
+$ cd <replaceable>build-tree</replaceable>
+$ lndir <replaceable>source-tree</replaceable>
+</screen>
+
+ <para>Some files might have been removed, so you need to remove
+ the links pointing to these non-existent files:</para>
+
+<screen>
+$ find . -xtype l -exec rm '{}' \;
+</screen>
+
+ <para>To be <emphasis>really</emphasis> safe, you should do
+ </para>
+
+<screen>$ gmake all</screen>
+
+ <para>from the top-level, to update the dependencies and build
+ any changed files. </para>
+ </sect2>
+
+ <sect2 id="cvs-tags">
+ <title>GHC Tag Policy</title>
+
+ <para>If you want to check out a particular version of GHC,
+ you'll need to know how we tag versions in the repository. The
+ policy (as of 4.04) is:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>The tree is branched before every major release. The
+ branch tag is <literal>ghc-x-xx-branch</literal>, where
+ <literal>x-xx</literal> is the version number of the release
+ with the <literal>'.'</literal> replaced by a
+ <literal>'-'</literal>. For example, the 4.04 release lives
+ on <literal>ghc-4-04-branch</literal>.</para>
+ </listitem>
+
+ <listitem>
+ <para>The release itself is tagged with
+ <literal>ghc-x-xx</literal> (on the branch). eg. 4.06 is
+ called <literal>ghc-4-06</literal>.</para>
+ </listitem>
+
+ <listitem>
+ <para>We didn't always follow these guidelines, so to see
+ what tags there are for previous versions, do <literal>cvs
+ log</literal> on a file that's been around for a while (like
+ <literal>fptools/ghc/README</literal>).</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>So, to check out a fresh GHC 4.06 tree you would
+ do:</para>
+
+<screen>
+ $ cvs co -r ghc-4-06 fpconfig
+ $ cd fptools
+ $ cvs co -r ghc-4-06 ghc hslibs
+</screen>
+ </sect2>
+
+ <sect2 id="cvs-hints">
+ <title>General Hints</title>
+
+ <itemizedlist>
+ <listitem>
+ <para>As a general rule: commit changes in small units,
+ preferably addressing one issue or implementing a single
+ feature. Provide a descriptive log message so that the
+ repository records exactly which changes were required to
+ implement a given feature/fix a bug. I've found this
+ <emphasis>very</emphasis> useful in the past for finding out
+ when a particular bug was introduced: you can just wind back
+ the CVS tree until the bug disappears.</para>
+ </listitem>
+
+ <listitem>
+ <para>Keep the sources at least *buildable* at any given
+ time. No doubt bugs will creep in, but it's quite easy to
+ ensure that any change made at least leaves the tree in a
+ buildable state. We do nightly builds of GHC to keep an eye
+ on what things work/don't work each day and how we're doing
+ in relation to previous verions. This idea is truely wrecked
+ if the compiler won't build in the first place!</para>
+ </listitem>
+
+ <listitem>
+ <para>To check out extra bits into an already-checked-out
+ tree, use the following procedure. Suppose you have a
+ checked-out fptools tree containing just ghc, and you want
+ to add nofib to it:</para>
+
+<screen>
+$ cd fptools
+$ cvs checkout nofib
+</screen>
+
+ <para>or: </para>
+
+<screen>
+$ cd fptools
+$ cvs update -d nofib
+</screen>
+
+ <para>(the -d flag tells update to create a new
+ directory). If you just want part of the nofib suite, you
+ can do </para>
+
+<screen>
+$ cd fptools
+$ cvs checkout nofib/spectral
+</screen>
+
+ <para>This works because <literal>nofib</literal> is a
+ module in its own right, and spectral is a subdirectory of
+ the nofib module. The path argument to checkout must always
+ start with a module name. There's no equivalent form of this
+ command using <literal>update</literal>.</para>
+ </listitem>
+ </itemizedlist>
+ </sect2>
+ </sect1>
+
+ <sect1 id="projects">
+ <title>What projects are there?</title>
+
+ <para>The <literal>fptools</literal> suite consists of several
+ <firstterm>projects</firstterm>, most of which can be downloaded,
+ built and installed individually. Each project corresponds to a
+ subdirectory in the source tree, and if checking out from CVS then
+ each project can be checked out individually by sitting in the top
+ level of your source tree and typing <command>cvs checkout
+ <replaceable>project</replaceable></command>.</para>
+
+ <para>Here is a list of the projects currently available:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term><literal>ghc</literal></term>
+ <indexterm><primary><literal>ghc</literal></primary>
+ <secondary>project</secondary></indexterm>
+ <listitem>
+ <para>The <ulink url="http://www.haskell.org/ghc/">Glasgow
+ Haskell Compiler</ulink> (minus libraries). Absolutely
+ required for building GHC.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>glafp-utils</literal></term>
+ <indexterm><primary><literal>glafp-utils</literal></primary><secondary>project</secondary></indexterm>
+ <listitem>
+ <para>Utility programs, some of which are used by the
+ build/installation system. Required for pretty much
+ everything.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>green-card</literal></term>
+ <indexterm><primary><literal>green-card</literal></primary><secondary>project</secondary></indexterm>
+ <listitem>
+ <para>The <ulink
+ url="http://www.haskell.org/greencard/">Green Card</ulink>
+ system for generating Haskell foreign function
+ interfaces.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>haggis</literal></term>
+ <indexterm><primary><literal>haggis</literal></primary><secondary>project</secondary></indexterm>
+ <listitem>
+ <para>The <ulink
+ url="http://www.dcs.gla.ac.uk/fp/software/haggis/">Haggis</ulink>
+ Haskell GUI framework.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>haddock</literal></term>
+ <indexterm><primary><literal>haddock</literal></primary><secondary>project</secondary></indexterm>
+ <listitem>
+ <para>The <ulink
+ url="http://www.haskell.org/haddock/">Haddock</ulink>
+ documentation tool.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>happy</literal></term>
+ <indexterm><primary><literal>happy</literal></primary><secondary>project</secondary></indexterm>
+ <listitem>
+ <para>The <ulink
+ url="http://www.haskell.org/happy/">Happy</ulink> Parser
+ generator.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>hdirect</literal></term>
+ <indexterm><primary><literal>hdirect</literal></primary><secondary>project</secondary></indexterm>
+ <listitem>
+ <para>The <ulink
+ url="http://www.haskell.org/hdirect/">H/Direct</ulink>
+ Haskell interoperability tool.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>hood</literal></term>
+ <indexterm><primary><literal>hood</literal></primary><secondary>project</secondary></indexterm>
+ <listitem>
+ <para>The <ulink url="http://www.haskell.org/hood/">Haskell
+ Object Observation Debugger</ulink>.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>hslibs</literal></term>
+ <indexterm><primary><literal>hslibs</literal></primary><secondary>project</secondary></indexterm>
+ <listitem>
+ <para>Supplemental libraries for GHC
+ (<emphasis>required</emphasis> for building GHC).</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>libraries</literal></term>
+ <indexterm><primary><literal></literal></primary><secondary>project</secondary></indexterm>
+ <listitem>
+ <para>Hierarchical Haskell library suite
+ (<emphasis>required</emphasis> for building GHC).</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>mhms</literal></term>
+ <indexterm><primary><literal></literal></primary><secondary>project</secondary></indexterm>
+ <listitem>
+ <para>The Modular Haskell Metric System.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>nofib</literal></term>
+ <indexterm><primary><literal>nofib</literal></primary><secondary>project</secondary></indexterm>
+ <listitem>
+ <para>The NoFib suite: A collection of Haskell programs used
+ primarily for benchmarking.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>testsuite</literal></term>
+ <indexterm><primary><literal>testsuite</literal></primary><secondary>project</secondary></indexterm>
+ <listitem>
+ <para>A testing framework, including GHC's regression test
+ suite.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>So, to build GHC you need at least the
+ <literal>ghc</literal>, <literal>libraries</literal> and
+ <literal>hslibs</literal> projects (a GHC source distribution will
+ already include the bits you need).</para>
+ </sect1>
+
+ <sect1 id="sec-build-checks">
+ <title>Things to check before you start</title>
+
+ <para>Here's a list of things to check before you get
+ started.</para>
+
+ <orderedlist>
+
+ <listitem>
+ <indexterm><primary>Disk space needed</primary></indexterm>
+ <para>Disk space needed: from about 100Mb for a basic GHC
+ build, up to probably 500Mb for a GHC build with everything
+ included (libraries built several different ways,
+ etc.).</para>
+ </listitem>
+
+ <listitem>
+ <para>Use an appropriate machine / operating system. <xref
+ linkend="sec-port-info"> lists the supported platforms; if
+ yours isn't amongst these then you can try porting GHC (see
+ <xref linkend="sec-porting-ghc">).</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 is part of the User's Guide and
+ available on the <ulink URL="http://www.haskell.org/ghc/" >GHC web
+ site</ulink>.</para>
+
+ <indexterm><primary>bugs</primary><secondary>known</secondary></indexterm>
+
+ <para>If you feel there is still some shortcoming in our
+ procedure or instructions, please report it.</para>
+
+ <para>For GHC, please see the <ulink
+ url="http://www.haskell.org/ghc/docs/latest/set/bug-reporting.html">bug-reporting
+ section of the GHC Users' Guide</ulink>, to maximise the
+ usefulness of your report.</para>
+
+ <indexterm><primary>bugs</primary><secondary>seporting</secondary></indexterm>
+ <para>If in doubt, please send a message to
+ <email>glasgow-haskell-bugs@haskell.org</email>.
+ <indexterm><primary>bugs</primary><secondary>mailing
+ list</secondary></indexterm></para>
+ </listitem>
+ </orderedlist>
+ </sect1>
+
+ <sect1 id="sec-port-info">
+ <title>What machines the Glasgow tools run on</title>
+
+<indexterm><primary>ports</primary><secondary>GHC</secondary></indexterm>
+<indexterm><primary>GHC</primary><secondary>ports</secondary></indexterm>
+<indexterm><primary>platforms</primary><secondary>supported</secondary></indexterm>
+
+ <para>The main question is whether or not the Haskell compiler
+ (GHC) runs on your platform.</para>
+
+ <para>A “platform” is a
+ architecture/manufacturer/operating-system combination, such as
+ <literal>sparc-sun-solaris2</literal>. Other common ones are
+ <literal>alpha-dec-osf2</literal>,
+ <literal>hppa1.1-hp-hpux9</literal>,
+ <literal>i386-unknown-linux</literal>,
+ <literal>i386-unknown-solaris2</literal>,
+ <literal>i386-unknown-freebsd</literal>,
+ <literal>i386-unknown-cygwin32</literal>,
+ <literal>m68k-sun-sunos4</literal>,
+ <literal>mips-sgi-irix5</literal>,
+ <literal>sparc-sun-sunos4</literal>,
+ <literal>sparc-sun-solaris2</literal>,
+ <literal>powerpc-ibm-aix</literal>.</para>
+
+ <para>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>
+
+ <indexterm><primary>fully-supported platforms</primary></indexterm>
+ <indexterm><primary>native-code generator</primary></indexterm>
+ <indexterm><primary>registerised ports</primary></indexterm>
+ <indexterm><primary>unregisterised ports</primary></indexterm>
+
+ <para>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>
+
+ <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>The OSF port is currently working (as of GHC version
+ 5.02.1) and well supported. The native code generator is
+ currently non-working. Other operating systems will
+ require some minor porting.</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 (at least for Solaris 2.7),
+ 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>A registerised port is available for version 4.08,
+ but GHC hasn't been built on that platform since (as far
+ as we know). 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 and 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 (PCs running FreeBSD 2.2 or
+ higher)</term>
+ <indexterm><primary>i386-unknown-freebsd</primary></indexterm>
+ <listitem>
+ <para>GHC works registerised. Pre-built packages are
+ available in the native package format, so if you just
+ need binaries you're better off just installing the
+ package (it might even be on your installation
+ CD!).</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>i386-unknown-openbsd (PCs running OpenBSD)</term>
+ <indexterm><primary>i386-unknown-openbsd</primary></indexterm>
+ <listitem>
+ <para>Supported, with native code generator. Packages are
+ available through the ports system in the native package
+ format.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>i386-unknown-netbsd (PCs running NetBSD and
+ OpenBSD)</term>
+ <indexterm><primary>i386-unknown-netbsd</primary></indexterm>
+ <listitem>
+ <para>Will require some minor porting effort, but should
+ work registerised.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>i386-unknown-mingw32 (PCs running Windows)</term>
+ <indexterm><primary>i386-unknown-mingw32</primary></indexterm>
+ <listitem>
+ <para>Fully supported under Win9x, WinNT, Win2k, and
+ WinXP. Includes a native code generator. Building from
+ source requires a recent <ulink
+ url="http://www.cygwin.com/">Cygwin</ulink> distribution
+ to be installed.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ia64-unknown-linux</term>
+ <indexterm><primary>ia64-unknown-linux</primary></indexterm>
+ <listitem>
+ <para>GHC currently works unregisterised. A registerised
+ port is in progress.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>mips-sgi-irix5</term>
+ <indexterm><primary>mips-sgi-irix[5-6]</primary></indexterm>
+ <listitem>
+ <para>Port has worked in the past, but hasn't been tested
+ for some time (and will certainly have rotted in various
+ ways). 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>
+ <indexterm><primary>powerpc-ibm-aix</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-apple-darwin</term>
+ <indexterm><primary>powerpc-apple-darwin</primary></indexterm>
+ <listitem>
+ <para>Supported registerised. No native code
+ generator.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>powerpc-apple-linux</term>
+ <indexterm><primary>powerpc-apple-linux</primary></indexterm>
+ <listitem>
+ <para>Not supported (yet).</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <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</title>
+
+ <indexterm><primary>pre-supposed utilities</primary></indexterm>
+ <indexterm><primary>utilities, pre-supposed</primary></indexterm>
+
+ <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>
+
+ <variablelist>
+
+ <varlistentry>
+ <term>GHC</term>
+ <indexterm><primary>pre-supposed: GHC</primary></indexterm>
+ <indexterm><primary>GHC, pre-supposed</primary></indexterm>
+ <listitem>
+ <para>GHC is required to build many of the tools, including
+ GHC itself. If you need to port GHC to your platform
+ because there isn't a binary distribution of GHC available,
+ then see <xref linkend="sec-porting-ghc">.</para>
+
+ <para>Which version of GHC you need will depend on the
+ packages you intend to build. GHC itself will normally
+ build using one of several older versions of itself - check
+ the announcement or release notes for details.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Perl</term>
+ <indexterm><primary>pre-supposed: Perl</primary></indexterm>
+ <indexterm><primary>Perl, pre-supposed</primary></indexterm>
+ <listitem>
+ <para><emphasis>You have to have Perl to proceed!</emphasis>
+ Perl version 5 at least is required. GHC has been known to
+ tickle bugs in Perl, so if you find that Perl crashes when
+ running GHC try updating (or downgrading) your Perl
+ installation. Versions of Perl that we use and are known to
+ be fairly stable are 5.005 and 5.6.1.</para>
+
+ <para>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>GCC 3.2 is currently known to have problems building
+ GHC on Sparc, but is stable on x86.</para>
+
+ <para>GCC 3.3 currently cannot be used to build GHC, due to
+ some problems with the new C preprocessor.</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>GNU Make</term>
+ <indexterm><primary>make</primary><secondary>GNU</secondary>
+ </indexterm>
+ <listitem>
+ <para>The fptools build system makes heavy use of features
+ specific to GNU <command>make</command>, so you must have
+ this installed in order to build any of the fptools
+ suite.</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 distribution 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>Version 2.52 or later of autoconf is required.
+ NB. vesrion 2.13 will no longer work, as of GHC version
+ 6.1.</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>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>
+
+ <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. Concurrent 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>
+ </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>
+
+ <para>More tools are required if you want to format the documentation
+ that comes with GHC and other fptools projects. See <xref
+ linkend="building-docs">.</para>
+ </sect2>
+ </sect1>
+
+ <sect1 id="sec-building-from-source">
+ <title>Building from source</title>
+
+ <indexterm><primary>Building from source</primary></indexterm>
+ <indexterm><primary>Source, building from</primary></indexterm>
+
+ <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="quick-start">
+ <title>Quick Start</title>
+
+ <para>If you are starting from a source distribution, and just
+ want a completely standard build, then the following should
+ work:</para>
+
+<screen>$ ./configure
+$ make
+$ make install
+</screen>
+
+ <para>For GHC, this will do a 2-stage bootstrap build of the
+ compiler, with profiling libraries, and install the
+ results.</para>
+
+ <para>If you want to do anything at all non-standard, or you
+ want to do some development, read on...</para>
+ </sect2>
+
+ <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>
+
+ <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>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</title>
+ <indexterm><primary>build trees</primary></indexterm>
+ <indexterm><primary>link trees, for building</primary></indexterm>
+
+ <para>If you just want to build the software once on a single
+ platform, then your source tree can also be your build tree, and
+ you can skip the rest of this section.</para>
+
+ <para>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.</para>
+
+ <variablelist>
+ <varlistentry>
+ <term>Step 1: get ready for configuration.</term>
+ <listitem>
+ <para>NOTE: if you're starting from a source distribution,
+ rather than CVS sources, you can skip this step.</para>
+
+ <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>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Step 2: system configuration.</term>
+ <listitem>
+ <para>Runs the newly-created <command>configure</command>
+ script, thus:</para>