+++ /dev/null
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
-<html>
-
-<head>
-<meta HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
-<meta NAME="GENERATOR" CONTENT="Microsoft FrontPage 3.0">
-<title>Access To The GHC CVS Repository</title>
-</head>
-
-<body TEXT="#2C3361" BGCOLOR="#FFFFFF" ALINK="#11BBFF">
-
-<h1><b>FP Tools CVS Cheat Sheet</b></h1>
-
-<p>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>
-
-<p>Information on using CVS can be obtained from <a HREF="http://www.cyclic.com">Cyclic
-Software</a>. </p>
-
-<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:jlewis@cse.ogi.edu">Jeff Lewis</a>). </p>
-
-<p><b>Contents</b>
-
-<ul>
- <li><a HREF="#read-only">Read-only remote access</a></li>
- <li><a HREF="#read-write">Read-write remote access</a></li>
- <li><a HREF="#first">Using CVS for the first time</a></li>
- <li><a HREF="#checkout">Checking out a source tree</a></li>
- <li><a HREF="#commit">Committing changes</a></li>
- <li><a HREF="#update">Updating your source tree</a></li>
- <li><a HREF="#hints">General Hints</a></li>
-</ul>
-
-<h2><a NAME="read-only"></a><b>Remote Read-only CVS Access</b></h2>
-
-<p>Read-only access is available to anyone - there's no need to ask us first. To get
-read-only access to our repository:
-
-<ul>
- <li>set your CVSROOT environment variable to <tt>:pserver:anoncvs@glass.cse.ogi.edu:/cvs</tt></li>
- <li>The first time you access the repository, you'll need to do <tt>cvs login</tt>.
- The password is simply <tt>cvs</tt>. This sets up a file in your home directory
- called <tt>.cvspass</tt>, which squirrels away the dummy password, so you only need to do
- this step one time.</li>
- <li>Now, you can check out a source tree using normal CVS commands. For example:</li>
- <pre> $ cvs checkout fpconfig
- $ cd fptools
- $ cvs checkout ghc</pre>
- <p>gets a brand spanking new set of GHC sources.</p>
-</ul>
-
-<p>The layout of our CVS repository is described below, under <a HREF="#first">Using CVS
-for the first time</a>. </p>
-
-<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>
-
-<h2><a NAME="read-write"></a><b>Remote Read-Write CVS Access</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>
-
-<p>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 <a
-HREF="http://www.ssh.fi/">ssh</a>, which is relatively painless. Log
-in to cvs.haskell.org, and set up your <tt>.ssh/authorized_keys</tt>
-file to allow logins from your local machine without a password (the
-ssh documentation has details on how to do this). Then, just
-
-<ul>
- <li> set your <tt>CVSROOT</tt> environment variable to <tt>:ext:<username>@cvs.haskell.org:/home/cvs/root</tt>.
- </li>
- <li>set your<tt> CVS_RSH </tt>environment variable to <tt>ssh</tt>.</li>
-</ul>
-
-<p>The <tt>CVSROOT</tt> 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 <tt>CVSROOT</tt>
-below. </p>
-<b>
-
-<p>Caveats:</b>
-
-<ul>
- <li>Setting your <tt>CVS_RSH</tt> to <tt>ssh</tt> assumes that your CVS client understands
- how to execute shell script ("#!"s,really), which is what <tt>ssh</tt> is. This
- may not be the case on some platforms (read: Win32), so in that case set <tt>CVS_RSH</tt>
- to <tt>ssh1</tt>.</li>
-</ul>
-
-<h2><a NAME="first"></a><b>Using CVS for the First Time</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:</li>
- <div align="center"><center><table>
- <tr>
- <td>fptools/ghc </td>
- <td>GHC</td>
- </tr>
- <tr>
- <td>fptools/happy </td>
- <td>Happy</td>
- </tr>
- <tr>
- <td>fptools/green-card </td>
- <td>Green Card</td>
- </tr>
- <tr>
- <td>fptools/nofib </td>
- <td>Nofib test suite</td>
- </tr>
- <tr>
- <td>fptools/hdirect </td>
- <td>IDL-to-Haskell compiler</td>
- </tr>
- </table>
- </center></div><p>For each directory, there's a mailing list: <tt>cvs-ghc</tt>, <tt>cvs-nofib</tt>
- 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
-<a
-href="http://www.haskell.org/mailman/listinfo/">http://www.haskell.org/mailman/listinfo/</a>.</p>
- <li>Create a .cvsrc file. Mine looks like this:</li>
- <pre> checkout -P
- release -d
- update -P
- diff -c</pre>
- <p>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.</p>
-</ul>
-
-<h2><a NAME="checkout"></a><b>Checking Out a Source Tree</b></h2>
-
-<ul>
- <li>Check out your sources. Make sure you set your <tt>CVSROOT</tt> environment variable
- according to either of the remote methods above. The Approved Way (at least by me) to
- check out a source tree is as follows:</li>
- <pre> $ cvs checkout fpconfig</pre>
- <p>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. </p>
- <pre> $ mv fptools <directory></pre>
- <p>You can call the fptools directory whatever you like, CVS won't mind. </p>
- <pre> $ cd <directory>
- $ cvs checkout ghc happy</pre>
- <p>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 <tt>ghc</tt> module (in fact you can get away
- with just that).</p>
-</ul>
-
-<h2><a NAME="commit"></a><b>Committing Your Changes</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.</li>
- <li>Make changes. Preferably small ones first.</li>
- <li>Test them. You can see exactly what changes you've made by using the <tt>cvs diff</tt>
- command. For example, <pre> $ cvs diff</pre>
- <p>lists all the changes (using the <tt>diff</tt> command) in and below the current
- directory. In emacs, C-c C-v C-= runs <tt>cvs diff</tt> on the current buffer and shows
- you the results.</p>
- </li>
- <li>Before checking in a change, you need to update your source tree:</li>
- <pre> $ cd fptools
- $ cvs update</pre>
- <p>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>
- <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. <br>
- <br>
- </p>
- <li>When you're happy that your change isn't going to break anything, check it in. For a
- one-file change:</li>
- <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>
- <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>
- <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 </p>
- <pre> $ cvs commit -F <commit-message> <file_1> .... <file_n></pre>
- <p>or, if nothing else has changed in this part of the source tree, </p>
- <pre> $ cvs commit -F <commit-message> <directory></pre>
- <p>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>
- <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.</p>
-</ul>
-
-<h2><a NAME="update"></a><b>Updating Your Source Tree</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 <tt>mk/*.mk</tt> files are a good example where problems
-crop up quite often). Having an inconsistent tree is a major cause of headaches. </p>
-
-<p>So, to avoid a lot of hassle, follow this recipe for updating your tree: </p>
-
-<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: </p>
-
-<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: </p>
-
-<pre>$ find . -xtype l -exec rm '{}' \;</pre>
-
-<p>And finally, re-configure to take into accound any changes in mk/config.mk.in. </p>
-
-<pre>$ ./configure</pre>
-
-<p>To be *really* safe, you should do </p>
-
-<pre>$ gmake boot && gmake all</pre>
-
-<p>from the top-level, to update the dependencies and build any changed files. </p>
-
-<h2><a NAME="tags"></a><b>GHC Tag Policy</b></h2>
-
-If you want to check out a particular version of GHC, you'll need to
-know how we tag versions in the repository. The policy (as of 4.04)
-is:
-
-<ul>
- <li> The tree is branched before every major release. The branch
- tag is <tt>ghc-x-xx-branch</tt>, where <tt>x-xx</tt> is the version
- number of the release with the <tt>'.'</tt> replaced by a
- <tt>'-'</tt>. For example, the 4.04 release lives on
- <tt>ghc-4-04-branch</tt>.</li>
-
- <li> The release itself is tagged with <tt>ghc-x-xx</tt> (on the
- branch). eg. 4.06 is called <tt>ghc-4-06</tt>.</li>
-
- <li> We didn't always follow these guidelines, so to see what tags
- there are for previous versions, do <tt>cvs log</tt> on a file
- that's been around for a while (like <tt>fptools/ghc/README</tt>).
-</ul>
-
-So, to check out a fresh GHC 4.06 tree you would do:
-
-<pre>
- $ cvs co -r ghc-4-06 fpconfig
- $ cd fptools
- $ cvs co -r ghc-4-06 ghc hslibs
-</pre>
-
-
-<h2><a NAME="hints"></a><b>General Hints</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.</li>
- <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!</li>
- <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:</li>
- <pre> cd fptools
- cvs checkout nofib</pre>
- <p>or: </p>
- <pre> cd fptools
- cvs update -d nofib</pre>
- <p>(the -d flag tells update to create a new directory). If you just want part of the
- nofib suite, you can do </p>
- <pre> cd fptools
- cvs checkout nofib/spectral</pre>
- <p>This works because <tt>nofib</tt> 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 <tt>update</tt>.</p>
-</ul>
-
-<h2>Reporting Bugs in the CVS sources</h2>
-
-<p> If you are reporting a bug or infelicity in the CVS version of
-GHC, please send your message to </p>
-
-<table align="center">
-<tr><td>
- <a href="mailto:cvs-ghc@haskell.org">cvs-ghc@haskell.org</a><td></td>
-</td></tr>
-<tr><td>
- <a href="mailto:cvs-hslibs@haskell.org">cvs-hslibs@haskell.org</a>
- <td>(for hslibs/ stuff)</td>
-</td></tr>
-<tr><td>
- <a href="mailto:cvs-nofib@haskell.org">cvs-nofib@haskell.org</a>
- <td>(for nofib/ stuff)</td>
-</td></tr>
-</table>
-
-<p>(not to glasgow-haskell-bugs). Two reasons:</p>
-
-<ul>
-<li> Readers of glasgow-haskell-bugs will get less junk mail</li>
-
-<li> I'm a little worried that ghc-bugs readers are beginning to think
- "is ghc really this unreliable?"! The checked-in-last-night version
- of GHC just isn't going to be solid. No one expects it to be. But
- a casual reader might not distinguish.</li>
-</ul>
-
-<p>Please don't stop sending bug reports though. They are really useful.</p>
-
-<hr>
-
-<p>Ok, that'll do for now. If there's anything else you'd like to see
-in this file, just let us know. </p>
-
-<table>
- <tr>
- <td><a HREF="mailto:jlewis@cse.ogi.edu">Jeff Lewis</a> </td>
- </tr>
- <tr>
- <td><a HREF="mailto:simonm@dcs.gla.ac.uk">Simon Marlow</a> </td>
- </tr>
-</table>
-</body>
-</html>
projects / ghc-hetmet.git / commitdiff