<Title>Building the Glasgow Functional Programming Tools Suite</Title>
<Author><OtherName>The GHC Team</OtherName></Author>
<Address><Email>glasgow-haskell-{users,bugs}@haskell.org</Email></Address>
-<PubDate>January 2000</PubDate>
+<PubDate>November 2001</PubDate>
-<Abstract>
+ <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>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>
+ <para>The bulk of this guide applies to building on Unix
+ systems; see <XRef LinkEnd="winbuild"> for Windows notes.</para>
+ </abstract>
-</Abstract>
+ </artheader>
-</ArtHeader>
+ <sect1 id="sec-getting">
+ <title>Getting the Glasgow <Literal>fptools</Literal> suite</title>
-<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>
-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>
-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>
</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</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>
+ <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>
+
+ <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 may be able
+ to bootstrap up from the intermediate C
+ (<filename>.hc</filename>) files that we provide. Building
+ GHC on an unsupported platform falls into this category.
+ Beware: this route is not for the faint hearted! 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>
+ </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>
+ </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>[Windows users. To protect your
+ <literal>.ssh</literal> from access by anyone else,
+ right-click your <literal>.ssh</literal> directory, and
+ select <literal>Properties</literal>. If you are not on
+ the access control list, add yourself, and give yourself
+ full permissions (the second panel). Remove everyone else
+ from the access control list. Don't leave them there but
+ deny them access, because 'they' may be a list that
+ includes you!]</para>
+ </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><literal>$CVS_RSH</literal> to
+ <literal>ssh</literal></para>
+ </listitem>
+ <listitem>
+ <para><literal>$CVSROOT</literal> to
+ <literal>:ext:</literal><replaceable>your-username</replaceable><literal>@cvs.haskell.org:/home/cvs/root</literal></para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+
+ </orderedlist>
+
+ <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 either. Ignore the instructions for setting
+ <literal>CVSROOT</literal> below. </para>
+
+ <para>Caveats:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>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
+ some platforms (read: Win32), so in that case set
+ <literal>CVS_RSH</literal> to
+ <literal>ssh1</literal>.</para>
+ </listitem>
+ </itemizedlist>
+
+ <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>
+
+<screen>
+ $ mv fptools <replaceable>directory</replaceable>
+</screen>
+
+ <para>You can call the fptools directory whatever you like,
+ CVS won't mind. </para>
+
+ <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
+</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> and
+ <literal>hslibs</literal> modules (for a full list of the
+ projects available, see <xref linkend="projects">).</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>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 -Pd 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). 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>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>GHC's libraries. Required 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
+ (experimental).</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> 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, compilers, and things.
+ SPARC boxes, PCs running Linux or FreeBSD, and Alphas running
+ OSF/1 are all fully supported. Win32 and HP boxes are in
+ pretty good shape. PCs running Solaris, DEC Alphas running
+ 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>.</para>
+
+ <indexterm><primary>known bugs</primary></indexterm>
+ <indexterm><primary>bugs, known</primary></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 bug-reporting section of the GHC
+ Users' Guide (separate document), 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
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 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,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>
+ <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, 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 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.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>i386-unknown-{netbsd,openbsd) (PCs running NetBSD
+ and OpenBSD)</term>
+ <indexterm><primary>i386-unknown-netbsd</primary></indexterm>
+ <indexterm><primary>i386-unknown-openbsd</primary></indexterm>
+ <listitem>
+ <para>Will require some minor porting effort, but should
+ work registerised.</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>
+ <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-macosx</term>
+ <indexterm><primary>powerpc-apple-macosx</primary></indexterm>
+ <listitem>
+ <para>Works, unregisterised only at the moment.</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">
</VariableList>
</para>
+ <para>
+ In order to actually build any documentation, you need to set
+ <constant>SGMLDocWays</constant> in your
+ <filename>build.mk</filename>. Valid values to add to this
+ list are: <literal>dvi</literal>, <literal>ps</literal>,
+ <literal>pdf</literal>, <literal>html</literal>, and
+ <literal>rtf</literal>.
+ </para>
+
</Sect2>
<Sect2 id="pre-supposed-other-tools">
</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>
+ <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>
+
+ <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>(Optional) Use <Command>lndir</Command> or
+ <Command>mkshadowdir</Command> to create a build tree.</para>
+
+<programlisting>
+$ cd myfptools
+$ mkshadowdir . /scratch/joe-bloggs/myfptools-sun4
+</programlisting>
+
+ <para>(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.</para>
+
+<programlisting>
+$ cd /scratch/joe-bloggs/myfptools-sun4
+</programlisting>
+
+ </listitem>
+
+ <listitem>
+ <para>Prepare for system configuration:</para>
+
+<programlisting>
+$ autoconf
+</programlisting>
+
+ <para>(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>
+
+ <para>Some projects, including GHC itself, have their own
+ configure scripts, so it is necessary to run autoconf again
+ in the appropriate subdirectories. eg:</para>
+
+<programlisting>
+$ (cd ghc; autoconf)
+</programlisting>
+ </listitem>
+
+ <listitem>
+ <para>Do system configuration:</para>
+
+<programlisting>
+$ ./configure
+</programlisting>
+
+ <para>Don't forget to check whether you need to add any
+ arguments to <literal>configure</literal>; for example, a
+ common requirement is to specify which GHC to use with
+ <option>--with-ghc=<replaceable>ghc</replaceable></option>.</para>
+ </listitem>
+
+ <listitem>
+ <para>Create the file <filename>mk/build.mk</filename>,
+ adding definitions for your desired configuration
+ options.</para>
+
+<programlisting>
+$ emacs mk/build.mk
+</programlisting>
+ </listitem>
+ </orderedlist>
+
+ <para>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
<Term><Literal>install</Literal>:</Term>
<ListItem>
<para>
-installs the things built by <Literal>all</Literal>. Where does it
+installs the things built by <Literal>all</Literal> (except for the documentation). 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
</para>
</ListItem></VarListEntry>
<VarListEntry>
+<Term><Literal>install-docs</Literal>:</Term>
+<ListItem>
+<para>
+installs the documentation. Otherwise behaves just like <literal>install</literal>.
+</para>
+</ListItem></VarListEntry>
+<VarListEntry>
<Term><Literal>uninstall</Literal>:</Term>
<ListItem>
<para>
<para>
If you don't have an account on <Literal>cvs.haskell.org</Literal>, send
your <filename>.ssh/identity.pub</filename> to the CVS repository administrator
- (currently Jeff Lewis <Email>jlewis@cse.ogi.edu</Email>). He will set up
+ (currently Jeff Lewis <Email>jlewis@galconn.com</Email>). He will set up
your account.
</para>
</Sect2>
+ <sect2>
+ <title>Building the Windows InstallShield® Installer</title>
+
+ <para>
+ This section is intended for GHC developers only; no-one else
+ should need to build an InstallShield.
+ </para>
+
+ <para>
+ Having built a second-stage tree and done <command>make
+ install</command> on it, open the InstallShield
+ (<filename>.ism</filename>) file. Open the Project screen, and
+ then the Project subfolder of the Path variables folder, and
+ set <literal>SourceFiles</literal> to the top of your
+ tree. You might also need to set <literal>GHCBITS</literal> to
+ point to the tree of various external bits that are added into
+ the IS mix. You should then be able to build an InstallShield.
+ </para>
+
+ <sect3>
+ <title>Extra features of the InstallShield</title>
+
+ <para>
+ The InstallShield has some IS-specific twiddles:
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ Two registry entries are set under
+ <literal>HKEY_LOCAL_MACHINE\SOFTWARE\GHC</literal>:
+ <literal>Path</literal> and
+ <literal>Version</literal>, which record respectively
+ the directory in which GHC was installed, and the
+ version number.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The InstallShield adds some entries to the Program
+ menu, for GHCi and for the documentation. See under
+ Setup Design and the individual components (each
+ component can add entries to the menu).
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </sect3>
+
+ <sect3>
+ <title>External add-ins</title>
+
+ <para>
+ The external add-ins consist of Mingwin gcc and Mingwin
+ Perl. The layout of the add-ins tree is as follows:
+
+ <screen>
+extra-bin/
+ gcc.exe
+ perl.exe (Mingwin perl)
+ perl56.dll
+gcc-lib/
+ Mingwin gcc binaries, libraries and headers
+imports/
+ com/
+ imports for HDirect's com library
+include/
+ Mingwin includes
+</screen>
+ </para>
+ </sect3>
+
+ </sect2>
+
</Sect1>
</Article>