Skip to content
Snippets Groups Projects
Commit 6857440d authored by Simon Marlow's avatar Simon Marlow
Browse files

[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.
parent 24519079
No related merge requests found
Hide whitespace changes
Inline Side-by-side
docs/cvs-cheat-sheet.html 0 → 100644
+ 393
− 0
View file @ 6857440d
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
<HTML>
<HEAD>
<TITLE>Access To The GHC CVS Repository</TITLE>
<META NAME="GENERATOR" CONTENT="Mozilla/3.04Gold (X11; I; SunOS 5.5.1 i86pc) [Netscape]">
</HEAD>
<BODY TEXT="#2C3361" BGCOLOR="#FFFFFF" ALINK="#11BBFF">
<H1><B>FP Tools CVS Cheat Sheet</B></H1>
<p> 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.
<p>Information on using CVS can be obtained from <a
href="http://www.cyclic.com">Cyclic Software</a>. 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" <a
href="http://arch.cs.yale.edu:8080/~bradley/cvs-instructions">introduction
to CVS</a>.
<p>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
<a href="mailto:simonm@dcs.gla.ac.uk">Simon Marlow</a>).
<p><b>Contents</b>
<ul>
<li><a href="#read-only">Read-only remote access</a>
<li><a href="#read-write">Read-write remote access</a>
<li><a href="#first">Using CVS for the first time</a>
<li><a href="#checkout">Checking out a source tree</a>
<li><a href="#commit">Committing changes</a>
<li><a href="#update">Updating your source tree</a>
<li><a href="#hints">General Hints</a>
</ul>
<h2><b><a name="read-only">Remote Read-only CVS Access</a></b></h2>
<p> Read-only access is available to anyone - there's no need to ask
us first. We use the <a
href="http://openbsd.org/anoncvs.html">anoncvs</a> mechanism pioneered
by the <a href="http://openbsd.org/">OpenBSD</a> folks. To get
read-only access to our repository, just set your CVSROOT environment
variable to
<pre>
anoncvs@solander.dcs.gla.ac.uk:/cvs
</pre>
<p>and you can then check out a source tree using normal CVS commands.
For example:
<pre>
$ cvs checkout fpconfig
$ cd fptools
$ cvs checkout ghc
</pre>
<p> gets a brand spanking new set of GHC sources. The layout of our
CVS repository is described below, under <a
href="cvs-cheat-sheet.html#first">Using CVS for the first time</a>.
<p>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.
<p>If you like, you can use <a
href="http://www.cs.hut.fi/ssh/">ssh</a> instead of the standard
<code>rsh</code> to connect to the CVS server. Just set your
<code>CVS_RSH</code> variable to <code>ssh</code>.
<h2><b><a name="read-write">Remote Read-Write CVS Access</a></b></h2>
<p>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.
<p>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:
<pre>
cvs -d &lt;username&gt;@solander.dcs.gla.ac.uk:/local/fp/src/cvsroot login
</pre>
<p>CVS will ask for a password. You only need to enter the password
once, it will be recorded in .cvspass in your home directory.
<pre>
setenv CVSROOT :pserver:&lt;username&gt;@solander.dcs.gla.ac.uk:/local/fp/src/cvsroot
</pre>
<p>The <code>CVSROOT</code> 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 <code>CVSROOT</code> below.
<h2><b><a name="first">Using CVS for the First Time</a></b></h2>
<ul>
<li>
ok, everybody now...) Firstly, identify which areas of the source
tree you'll be working on. The directory structure looks like this:
<p>
<center>
<table>
<tr> <td>fptools/ghc <td>GHC
<tr> <td>fptools/happy <td>Happy
<tr> <td>fptools/haggis <td>Haggis
<tr> <td>fptools/green-card <td>Green Card
<tr> <td>fptools/nofib <td>Nofib test suite
<tr> <td>fptools/hdirect <td>IDL-to-Haskell compiler
<tr> <td>fptools/common-rts <td>GHC/Hugs combined run-time system
</table>
</center>
<p>For each directory, there's a mailing list:
<code>fp-cvs-ghc</code>, <code>fp-cvs-nofib</code> 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.
<p>
<li>
Create a .cvsrc file. Mine looks like this:
<pre>
checkout -P
release -d
update -P
diff -c
</pre>
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.
</ul>
<h2><b><a name="checkout">Checking Out a Source Tree</a></b></h2>
<ul>
<li> Check out your sources. If you're not at Glasgow, make sure you
set your <code>CVSROOT</code> environment variable according to either of the
remote methods above. Glasgow folk need to set their
<code>CVSROOT</code> environment variables as follows:
<pre>
$ CVSROOT=/local/fp/src/cvsroot
$ export CVSROOT
</pre>
or, if you're using csh or tcsh:
<pre>
$ setenv CVSROOT=/local/fp/src/cvsroot
</pre>
The Approved Way (at least by me) to check out a source tree is as
follows:
<pre>
$ cvs checkout fpconfig
</pre>
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.
<pre>
$ mv fptools &lt;directory&gt;
</pre>
You can call the fptools directory whatever you like, CVS won't mind.
<pre>
$ cd &lt;directory&gt;
$ cvs checkout ghc happy
</pre>
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
<code>ghc</code> module (in fact you can get away with just that).
</ul>
<h2><b><a name="commit">Committing Your Changes</a></b></h2>
<p>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.
<ul>
<li>
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.<p>
<li> Make changes. Preferably small ones first.<p>
<li> Test them. You can see exactly what changes you've made by using
the <code>cvs diff</code> command. For example,<p>
<pre>
$ cvs diff
</pre>
lists all the changes (using the <code>diff</code> command) in and
below the current directory. In emacs, C-c C-v C-= runs <code>cvs
diff</code> on the current buffer and shows you the results.<p>
<li> Before checking in a change, you need to update your source tree:
<pre>
$ cd fptools
$ cvs update
</pre>
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.
<p> 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.<p>
<li> When you're happy that your change isn't going to break anything,
check it in. For a one-file change:
<pre>
$ cvs commit &lt;filename&gt;
</pre>
<p>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.
<p>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.
<p>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
<pre>
$ cvs commit -F &lt;commit-message&gt; &lt;file_1&gt; .... &lt;file_n&gt;
</pre>
or, if nothing else has changed in this part of the source tree,
<pre>
$ cvs commit -F &lt;commit-message&gt; &lt;directory&gt;
</pre>
where &lt;directory> is a common parent directory for all your changes,
and &lt;commit-message> is the name of the file containing the commit
message.
<p>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.
</ul>
<h2><b><a name="update">Updating Your Source Tree</a></b></h2>
<p>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 <code>mk/*.mk</code> files are a good example where problems
crop up quite often). Having an inconsistent tree is a major cause of
headaches.
<p>So, to avoid a lot of hassle, follow this recipe for updating your
tree:
<pre>
$ cd fptools
$ cvs update -Pd 2>&1 | tee log
</pre>
<p>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:
<pre>
$ cd &lt;build-tree&gt;
$ lndir &lt;source-tree&gt;
</pre>
<p>Some files might have been removed, so you need to remove the links
pointing to these non-existent files:
<pre>
$ find . -xtype l -exec rm '{}' \;
</pre>
<p>And finally, re-configure to take into accound any changes in
mk/config.mk.in.
<pre>
$ ./configure
</pre>
<p>To be *really* safe, you should do
<pre>
$ gmake boot && gmake all
</pre>
<p>from the top-level, to update the dependencies and build any changed
files.
<h2><b><a name="hints">General Hints</a></b></h2>
<ul>
<li> 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.<p>
<li> 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!<p>
<li> 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:
<pre>
cd fptools
cvs checkout nofib
</pre>
or:
<pre>
cd fptools
cvs update -d nofib
</pre>
(the -d flag tells update to create a new directory). If you just want
part of the nofib suite, you can do
<pre>
cd fptools
cvs checkout nofib/spectral
</pre>
This works because <code>nofib</code> 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 <code>update</code>.
</ul>
Ok, that'll do for now. If there's anything else you'd like to see in
this file, just let me know.
<p><a href="mailto:simonm@dcs.gla.ac.uk">Simon Marlow</a>
</body>
</html>
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment