- <para>More information about our CVS repository can be found
- in <xref linkend="sec-cvs"/>.</para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- <para>If you are going to do any building from sources (either
- from a source distribution or the CVS repository) then you need to
- read all of this manual in detail.</para>
- </sect1>
-
- <sect1 id="sec-cvs">
- <title>Using the CVS repository</title>
-
- <para>We use <ulink url="http://www.cvshome.org/">CVS</ulink> (Concurrent Version System) to keep track of our
- sources for various software projects. CVS lets several people
- work on the same software at the same time, allowing changes to be
- checked in incrementally. </para>
-
- <para>This section is a set of guidelines for how to use our CVS
- repository, and will probably evolve in time. The main thing to
- remember is that most mistakes can be undone, but if there's
- anything you're not sure about feel free to bug the local CVS
- meister (namely Jeff Lewis
- <email>jlewis@galois.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@cvs.haskell.org:/cvs</literal></para>
- <para>If you set <literal>$CVSROOT</literal> in a shell script, be sure not to
- have any trailing spaces on that line, otherwise CVS will respond with
- a perplexing message like
- <screen>/cvs : no such repository</screen></para>
- </listitem>
- <listitem>
- <para>Run the command</para>
-<screen>$ cvs login</screen>
- <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>
-<programlisting>BatchMode Yes
-
-Host cvs.haskell.org
-Protocol 1</programlisting>
-
- <para>In both cases, <literal>ssh-keygen</literal> will
- ask for a <firstterm>passphrase</firstterm>. The
- passphrase is a password that protects your private key.
- In response to the 'Enter passphrase' question, you can
- either:</para>
- <itemizedlist>
- <listitem>
- <para>[Recommended.] Enter a passphrase, which you
- will quote each time you use CVS.
- <literal>ssh-agent</literal> makes this entirely
- un-tiresome.</para>
- </listitem>
- <listitem>
- <para>[Deprecated.] Just hit return (i.e. use an empty
- passphrase); then you won't need to quote the
- passphrase when using CVS. The downside is that
- anyone who can see into your <literal>.ssh</literal>
- directory, and thereby get your private key, can mess
- up the repository. So you must keep the
- <literal>.ssh</literal> directory with draconian
- no-access permissions.</para>
- </listitem>
- </itemizedlist>
-
-
- <para>
- <emphasis>Windows users: see the notes in <xref linkend="configure-ssh"/> about <command>ssh</command> wrinkles!</emphasis>
- </para>
-
-
- </listitem>
-
- <listitem>
- <para>Send a message to to the CVS repository
- administrator (currently Jeff Lewis
- <email>jeff@galois.com</email>), containing:</para>
- <itemizedlist>
- <listitem>
- <para>Your desired user-name.</para>
- </listitem>
- <listitem>
- <para>Your <literal>.ssh/id_dsa.pub</literal> (or
- <literal>.ssh/identity.pub</literal>).</para>
- </listitem>
- </itemizedlist>
- <para>He will set up your account.</para>
- </listitem>
-
- <listitem>
- <para>Set the following environment variables:</para>
- <itemizedlist>
- <listitem>
- <para>
- <constant>$HOME</constant>: points to your home directory. This is where CVS
- will look for its <filename>.cvsrc</filename> file.
- </para>
- </listitem>
-
- <listitem>
- <para>
- <constant>$CVS_RSH</constant> to <filename>ssh</filename>
- </para>
- <para>[Windows users.] Setting your <literal>CVS_RSH</literal> to
- <literal>ssh</literal> assumes that your CVS client
- understands how to execute shell script
- ("#!"s,really), which is what
- <literal>ssh</literal> is. This may not be the case on
- Win32 platforms, so in that case set <literal>CVS_RSH</literal> to
- <literal>ssh1</literal>.</para>
- </listitem>
-
- <listitem>
- <para><literal>$CVSROOT</literal> to
- <literal>:ext:</literal><replaceable>your-username</replaceable>
- <literal>@cvs.haskell.org:/home/cvs/root</literal>
- where <replaceable>your-username</replaceable> is your user name on
- <literal>cvs.haskell.org</literal>.
- </para>
- <para>The <literal>CVSROOT</literal> environment variable will
- be recorded in the checked-out tree, so you don't need to set
- this every time. </para>
-
- </listitem>
-
- <listitem>
- <para>
- <constant>$CVSEDITOR</constant>: <filename>bin/gnuclient.exe</filename>
- if you want to use an Emacs buffer for typing in those long commit messages.
- </para>
- </listitem>
-
- <listitem>
- <para>
- <constant>$SHELL</constant>: To use bash as the shell in Emacs, you need to
- set this to point to <filename>bash.exe</filename>.
- </para>
- </listitem>
-
- </itemizedlist>
-
-
- </listitem>
-
- <listitem>
- <para>
- Put the following in <filename>$HOME/.cvsrc</filename>:
- </para>
-
-<programlisting>checkout -P
-release -d
-update -P
-diff -u</programlisting>
-
- <para>
- These are the default options for the specified CVS commands,
- and represent better defaults than the usual ones. (Feel
- free to change them.)
- </para>
-
- <para>
- [Windows users.] Filenames starting with <filename>.</filename> were illegal in
- the 8.3 DOS filesystem, but that restriction should have
- been lifted by now (i.e., you're using VFAT or later filesystems.) If
- you're still having problems creating it, don't worry; <filename>.cvsrc</filename> is entirely
- optional.
- </para>
- </listitem>
-
- </orderedlist>
-
-
- <para>[Experts.] Once your account is set up, you can get
- access from other machines without bothering Jeff, thus:</para>
- <orderedlist>
- <listitem>
- <para>Generate a public/private key pair on the new
- machine.</para>
- </listitem>
- <listitem>
- <para>Use ssh to log in to
- <literal>cvs.haskell.org</literal>, from your old
- machine.</para>
- </listitem>
- <listitem>
- <para>Add the public key for the new machine to the file
- <literal>$HOME/ssh/authorized_keys</literal> on
- <literal>cvs.haskell.org</literal>.
- (<literal>authorized_keys2</literal>, I think, for Version
- 2 protocol.)</para>
- </listitem>
- <listitem>
- <para>Make sure that the new version of
- <literal>authorized_keys</literal> still has 600 file
- permissions.</para>
- </listitem>
- </orderedlist>
- </sect3>
- </sect2>
-
-
-
- <sect2 id="cvs-first">
- <title>Checking Out a Source Tree</title>
-
- <itemizedlist>
- <listitem>
- <para>Make sure you set your <literal>CVSROOT</literal>
- environment variable according to either of the remote
- methods above. The Approved Way to check out a source tree
- is as follows:</para>
-
-<screen>$ cvs checkout fpconfig</screen>
-
- <para>At this point you have a new directory called
- <literal>fptools</literal> which contains the basic stuff
- for the fptools suite, including the configuration files and
- some other junk. </para>
-
-<para>[Windows users.] The following messages appear to be harmless:
-<screen>setsockopt IPTOS_LOWDELAY: Invalid argument
-setsockopt IPTOS_THROUGHPUT: Invalid argument</screen>
-</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 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>,
- 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> and/or <literal>Alex</literal>
- installed, you need to check them 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 libraries</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>alex</literal>
- <indexterm><primary><literal>alex</literal></primary><secondary>project</secondary></indexterm>
- </term>
- <listitem>
- <para>The <ulink
- url="http://www.haskell.org/alex/">Alex</ulink> lexical
- analyser generator for Haskell.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <literal>ghc</literal>
- <indexterm><primary><literal>ghc</literal></primary>
- <secondary>project</secondary></indexterm>
- </term>
- <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>
- <indexterm><primary><literal>glafp-utils</literal></primary><secondary>project</secondary></indexterm>
- </term>
- <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>greencard</literal>
- <indexterm><primary><literal>greencard</literal></primary><secondary>project</secondary></indexterm>
- </term>
- <listitem>
- <para>The <ulink
- url="http://www.haskell.org/greencard/">GreenCard</ulink>
- system for generating Haskell foreign function
- interfaces.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <literal>haggis</literal>
- <indexterm><primary><literal>haggis</literal></primary><secondary>project</secondary></indexterm>
- </term>
- <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>
- <indexterm><primary><literal>haddock</literal></primary><secondary>project</secondary></indexterm>
- </term>
- <listitem>
- <para>The <ulink
- url="http://www.haskell.org/haddock/">Haddock</ulink>
- documentation tool.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <literal>happy</literal>
- <indexterm><primary><literal>happy</literal></primary><secondary>project</secondary></indexterm>
- </term>
- <listitem>
- <para>The <ulink
- url="http://www.haskell.org/happy/">Happy</ulink> Parser
- generator.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <literal>hdirect</literal>
- <indexterm><primary><literal>hdirect</literal></primary><secondary>project</secondary></indexterm>
- </term>
- <listitem>
- <para>The <ulink
- url="http://www.haskell.org/hdirect/">H/Direct</ulink>
- Haskell interoperability tool.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <literal>hood</literal>
- <indexterm><primary><literal>hood</literal></primary><secondary>project</secondary></indexterm>
- </term>
- <listitem>
- <para>The <ulink url="http://www.haskell.org/hood/">Haskell
- Object Observation Debugger</ulink>.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <literal>hslibs</literal>
- <indexterm><primary><literal>hslibs</literal></primary><secondary>project</secondary></indexterm>
- </term>
- <listitem>
- <para>Old, now deprecated, libraries. Everything in here is in <literal>libraries</literal>.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <literal>libraries</literal>
- <indexterm><primary><literal></literal></primary><secondary>project</secondary></indexterm>
- </term>
- <listitem>
- <para>Hierarchical Haskell library suite
- (<emphasis>required</emphasis> for building GHC).</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <literal>mhms</literal>
- <indexterm><primary><literal></literal></primary><secondary>project</secondary></indexterm>
- </term>
- <listitem>
- <para>The Modular Haskell Metric System.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <literal>nofib</literal>
- <indexterm><primary><literal>nofib</literal></primary><secondary>project</secondary></indexterm>
- </term>
- <listitem>
- <para>The NoFib suite: A collection of Haskell programs used
- primarily for benchmarking.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <literal>testsuite</literal>
- <indexterm><primary><literal>testsuite</literal></primary><secondary>project</secondary></indexterm>
- </term>
- <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>libraries</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><para><indexterm><primary>Disk space needed</primary></indexterm>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}:
- <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>
- </term>
- <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
- <indexterm><primary>sparc-sun-sunos4</primary></indexterm>
- </term>
- <listitem>
- <para>Probably works with minor tweaks, hasn't been tested
- for a while.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>sparc-sun-solaris2
- <indexterm><primary>sparc-sun-solaris2</primary></indexterm>
- </term>
- <listitem>
- <para>Fully supported (at least for Solaris 2.7 and 2.6),
- including native-code generator.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>sparc-unknown-openbsd
- <indexterm><primary>sparc-unknown-openbsd</primary></indexterm>
- </term>
- <listitem>
- <para>Supported, including native-code generator. The
- same should also be true of NetBSD</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>hppa1.1-hp-hpux (HP-PA boxes running HPUX 9.x)
- <indexterm><primary>hppa1.1-hp-hpux</primary></indexterm>
- </term>
- <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)
- <indexterm><primary>i386-*-linux</primary></indexterm>
- </term>
- <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)
- <indexterm><primary>i386-unknown-freebsd</primary></indexterm>
- </term>
- <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)
- <indexterm><primary>i386-unknown-openbsd</primary></indexterm>
- </term>
- <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)
- <indexterm><primary>i386-unknown-netbsd</primary></indexterm>
- </term>
- <listitem>
- <para>Will require some minor porting effort, but should
- work registerised.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>i386-unknown-mingw32 (PCs running Windows)
- <indexterm><primary>i386-unknown-mingw32</primary></indexterm>
- </term>
- <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
- <indexterm><primary>ia64-unknown-linux</primary></indexterm>
- </term>
- <listitem>
- <para>Supported, except there is no native code
- generator.</para>
- </listitem>
- </varlistentry>