At Glasgow, 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. If you're at +Glasgow, the full documentation for CVS is online, in info format (use +'info cvs' or run emacs and type C-h i). A good source of tips is the +CVS FAQ, in /local/doc/gnu/CVS.FAQ. Bradley C. Kuszmaul also provides +a "to the point" introduction +to CVS. + +
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 +Simon Marlow). + +
Contents + +
Read-only access is available to anyone - there's no need to ask +us first. We use the anoncvs mechanism pioneered +by the OpenBSD folks. To get +read-only access to our repository, just set your CVSROOT environment +variable to + +
+ anoncvs@solander.dcs.gla.ac.uk:/cvs ++ +
and you can then check out a source tree using normal CVS commands. +For example: + +
+ $ 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. + +
If you like, you can use ssh instead of the standard
+rsh to connect to the CVS server. Just set your
+CVS_RSH variable to ssh.
+
+
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 has been +set up, you need to do: + +
+ cvs -d <username>@solander.dcs.gla.ac.uk:/local/fp/src/cvsroot login ++ +
CVS will ask for a password. You only need to enter the password +once, it will be recorded in .cvspass in your home directory. + +
+ setenv CVSROOT :pserver:<username>@solander.dcs.gla.ac.uk:/local/fp/src/cvsroot ++ +
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.
+
+
+
+ +
| fptools/ghc | GHC + |
| fptools/happy | Happy + |
| fptools/haggis | Haggis + |
| fptools/green-card | Green Card + |
| fptools/nofib | Nofib test suite + |
| fptools/hdirect | IDL-to-Haskell compiler + |
| fptools/common-rts | GHC/Hugs combined run-time system + |
For each directory, there's a mailing list:
+fp-cvs-ghc, fp-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. Ask the CVS
+meister to put you on the relevant mailing lists.
+
+ +
+ 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. +
CVSROOT environment variable according to either of the
+remote methods above. Glasgow folk need to set their
+CVSROOT environment variables as follows:
+
++ $ CVSROOT=/local/fp/src/cvsroot + $ export CVSROOT ++ + or, if you're using csh or tcsh: + +
+ $ setenv CVSROOT=/local/fp/src/cvsroot ++ +The Approved Way (at least by me) 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. + +
+ $ 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 command. For example,+ +
+ $ 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. + + +
+ +
+ + +
+ 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.
+Simon Marlow + + + }