From 6857440d8b99a0d6d56e1e567a06830f4ed30efd Mon Sep 17 00:00:00 2001 From: simonm Date: Tue, 7 Apr 1998 11:21:58 +0000 Subject: [PATCH] [project @ 1998-04-07 11:21:58 by simonm] Add new HTML version of the CVS Cheat Sheet with instructions on how to use remote read-only CVS. --- docs/cvs-cheat-sheet.html | 393 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 393 insertions(+) create mode 100644 docs/cvs-cheat-sheet.html diff --git a/docs/cvs-cheat-sheet.html b/docs/cvs-cheat-sheet.html new file mode 100644 index 0000000..3990999 --- /dev/null +++ b/docs/cvs-cheat-sheet.html @@ -0,0 +1,393 @@ + + + + Access To The GHC CVS Repository + + + + +

FP Tools CVS Cheat Sheet

+ +

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 remote access +
Read-write remote access +
Using CVS for the first time +
Checking out a source tree +
Committing changes +
Updating your source tree +
General Hints +

+ +

Remote Read-only CVS Access

+ +

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

Remote Read-Write CVS Access

+ +

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

Using CVS for the First Time

+ +

+ok, everybody now...) Firstly, identify which areas of the source +tree you'll be working on. The directory structure looks like this: +

+ +

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

+ +

+ Create a .cvsrc file. Mine looks like this: + +
```
+	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. +

+ +

Checking Out a Source Tree

+ +

Check out your sources. If you're not at Glasgow, make sure you +set your 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). +

+ + +

Committing Your 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. For GHC, instructions can be found +in the GHC installation guide.
+ +
Make changes. Preferably small ones first.
+ +
Test them. You can see exactly what changes you've made by using +the 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.
+ +
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. + +

+ +

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 '{}' \;
+

+ +

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

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

+ +Ok, that'll do for now. If there's anything else you'd like to see in +this file, just let me know. + +

Simon Marlow + + + -- 1.7.10.4