--- /dev/null
+<!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 <username>@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:<username>@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 <directory>
+</pre>
+
+ You can call the fptools directory whatever you like, CVS won't mind.
+
+<pre>
+ $ cd <directory>
+ $ 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 <filename>
+</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 <commit-message> <file_1> .... <file_n>
+</pre>
+
+ or, if nothing else has changed in this part of the source tree,
+
+<pre>
+ $ cvs commit -F <commit-message> <directory>
+</pre>
+
+where <directory> is a common parent directory for all your changes,
+and <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 <build-tree>
+$ lndir <source-tree>
+</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>
projects / ghc-hetmet.git / commitdiff