Make sure you set your CVSROOT environment variable according to either of the remote methods above. The Approved Way to check out a source tree is as follows:

$ cvs checkout fpconfig

At this point you have a new directory called fptools which contains the basic stuff for the fptools suite, including the configuration files and some other junk.

[Windows users.] The following messages appear to be harmless:

setsockopt IPTOS_LOWDELAY: Invalid argument
setsockopt IPTOS_THROUGHPUT: Invalid argument

You can call the fptools directory whatever you like, CVS won't mind:

$ mv fptools directory

NB: after you've read the CVS manual you might be tempted to try

$ cvs checkout -d directory fpconfig

instead of checking out fpconfig and then renaming it. But this doesn't work, and will result in checking out the entire repository instead of just the fpconfig bit.

$ cd directory
$ cvs checkout ghc hslibs libraries

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 ghc, hslibs and libraries modules (for a full list of the projects available, see Section 3, “What projects are there?”).

Remember that if you do not have happy and/or Alex installed, you need to check them out as well.

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.

Make changes. Preferably small ones first.

Test them. You can see exactly what changes you've made by using the cvs diff command:

$ cvs diff

lists all the changes (using the diff command) in and below the current directory. In emacs, C-c C-v = runs cvs diff on the current buffer and shows you the results.

If you changed something in the fptools/libraries subdirectories, also run make html to check if the documentation can be generated successfully, too.

Before checking in a change, you need to update your source tree:

$ cd fptools
$ cvs update

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.

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.

When you're happy that your change isn't going to break anything, check it in. For a one-file change:

$ cvs commit filename

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.

If you're using emacs, simply load up the file into a buffer and type C-x C-q, and emacs will prompt for a commit message and then check in the file for you.

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

$ cvs commit -F commit-message file_1 .... file_n

or, if nothing else has changed in this part of the source tree,

$ cvs commit -F commit-message directory

where directory is a common parent directory for all your changes, and commit-message is the name of the file containing the commit message.

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 one message.

The tree is branched before every major release. The branch tag is ghc-x-xx-branch, where x-xx is the version number of the release with the '.' replaced by a '-'. For example, the 4.04 release lives on ghc-4-04-branch.

The release itself is tagged with ghc-x-xx (on the branch). eg. 4.06 is called ghc-4-06.

We didn't always follow these guidelines, so to see what tags there are for previous versions, do cvs log on a file that's been around for a while (like fptools/ghc/README).

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

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!

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:

$ cd fptools
$ cvs checkout nofib

or:

$ cd fptools
$ cvs update -d nofib

(the -d flag tells update to create a new directory). If you just want part of the nofib suite, you can do

$ cd fptools
$ cvs checkout nofib/spectral

This works because nofib 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 update.