We use CVS (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.
Information on using CVS can be obtained from Cyclic Software.
This note is supposed to be 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).
Contents
Read-only access is available to anyone - there's no need to ask us first. To get read-only access to our repository:
$ cvs checkout fpconfig $ cd fptools $ cvs checkout ghc
gets a brand spanking new set of GHC sources.
The layout of our CVS repository is described below, under Using CVS for the first time.
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.
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.
To use remote CVS, you need to supply me with a username and encrypted password. Once you've done that and the account on cvs.haskell.org has been set up, you need to install ssh, which is relatively painless. Log in to cvs.haskell.org, and set up your .ssh/authorized_keys file to allow logins from your local machine without a password (the ssh documentation has details on how to do this). Then, just
The CVSROOT 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 CVSROOT below.
Caveats:
| fptools/ghc | GHC |
| fptools/happy | Happy |
| fptools/green-card | Green Card |
| fptools/nofib | Nofib test suite |
| fptools/hdirect | IDL-to-Haskell compiler |
For each directory, there's a mailing list: cvs-ghc, cvs-nofib etc. Everyone on the mailing list is sent a message automatically by CVS whenever someone checks in a change, this helps to keep track of what's going on when several people are working on related stuff. To join any of these mailing lists, go to http://www.haskell.org/mailman/listinfo/.
checkout -P release -d update -P diff -c
It just gives default flags for some of the CVS commands. For instance, the -P flag to 'checkout' says prune empty directories, which is normally what you want.
$ 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.
$ mv fptools <directory>
You can call the fptools directory whatever you like, CVS won't mind.
$ cd <directory> $ cvs checkout ghc happy
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 module (in fact you can get away with just that).
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.
$ cvs diff
lists all the changes (using the diff command) in and below the current directory. In emacs, C-c C-v C-= runs cvs diff on the current buffer and shows you the results.
$ 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.
$ 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.
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 '{}' \;
And finally, re-configure to take into accound any changes in mk/config.mk.in.
$ ./configure
To be *really* safe, you should do
$ gmake boot && gmake all
from the top-level, to update the dependencies and build any changed files.
$ cvs co -r ghc-4-06 fpconfig
$ cd fptools
$ cvs co -r ghc-4-06 ghc hslibs
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.
If you are reporting a bug or infelicity in the CVS version of GHC, please send your message to
| cvs-ghc@haskell.org | |
| cvs-hslibs@haskell.org | (for hslibs/ stuff) |
| cvs-nofib@haskell.org | (for nofib/ stuff) |
(not to glasgow-haskell-bugs). Two reasons:
Please don't stop sending bug reports though. They are really useful.
Ok, that'll do for now. If there's anything else you'd like to see in this file, just let us know.
| Jeff Lewis |
| Simon Marlow |