2. Using the CVS repository

2.1. Getting access to the CVS Repository

You can access the repository in one of two ways: read-only (Section 2.1.1), or read-write (Section 2.1.2).

2.2. Checking Out a Source Tree

• 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).

2.3. Committing Changes

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.

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

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

2.4. Updating Your Source Tree

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 mk/*.mk files are a good example where problems crop up quite often). Having an inconsistent tree is a major cause of headaches.

So, to avoid a lot of hassle, follow this recipe for updating your tree:

$ cd fptools
$ cvs update -Pd 2>&1 | tee log

Look at the log file, and fix any conflicts (denoted by a "C" 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:

$ cd build-tree
$ lndir source-tree

Some files might have been removed, so you need to remove the links pointing to these non-existent files:

$ find . -xtype l -exec rm '{}' \;

To be really safe, you should do

$ gmake all

from the top-level, to update the dependencies and build any changed files.

2.5. GHC Tag Policy

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:

• 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).

So, to check out a fresh GHC 4.06 tree you would do:

     $ cvs co -r ghc-4-06 fpconfig
     $ cd fptools
     $ cvs co -r ghc-4-06 ghc hslibs

2.6. General Hints

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