-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">\r
-<html>\r
-\r
-<head>\r
-<meta HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">\r
-<meta NAME="GENERATOR" CONTENT="Microsoft FrontPage 3.0">\r
-<title>Access To The GHC CVS Repository</title>\r
-</head>\r
-\r
-<body TEXT="#2C3361" BGCOLOR="#FFFFFF" ALINK="#11BBFF">\r
-\r
-<h1><b>FP Tools CVS Cheat Sheet</b></h1>\r
-\r
-<p>We use CVS (Concurrent Version System) to keep track of our sources for various\r
-software projects. CVS lets several people work on the same software at the same time,\r
-allowing changes to be checked in incrementally. </p>\r
-\r
-<p>Information on using CVS can be obtained from <a HREF="http://www.cyclic.com">Cyclic\r
-Software</a>. </p>\r
-\r
-<p>This note is supposed to be a set of guidelines for how to use our CVS repository, and\r
-will probably evolve in time. The main thing to remember is that most mistakes can be\r
-undone, but if there's anything you're not sure about feel free to bug the local CVS\r
-meister (namely <a HREF="mailto:jlewis@cse.ogi.edu">Jeff Lewis</a>). </p>\r
-\r
-<p><b>Contents</b> \r
-\r
-<ul>\r
- <li><a HREF="#read-only">Read-only remote access</a></li>\r
- <li><a HREF="#read-write">Read-write remote access</a></li>\r
- <li><a HREF="#first">Using CVS for the first time</a></li>\r
- <li><a HREF="#checkout">Checking out a source tree</a></li>\r
- <li><a HREF="#commit">Committing changes</a></li>\r
- <li><a HREF="#update">Updating your source tree</a></li>\r
- <li><a HREF="#hints">General Hints</a></li>\r
-</ul>\r
-\r
-<h2><a NAME="read-only"></a><b>Remote Read-only CVS Access</b></h2>\r
-\r
-<p>Read-only access is available to anyone - there's no need to ask us first. To get\r
-read-only access to our repository:\r
-\r
-<ul>\r
- <li>set your CVSROOT environment variable to <tt>:pserver:anoncvs@glass.cse.ogi.edu:/cvs</tt></li>\r
- <li>The first time you access the repository, you'll need to do <tt>cvs login</tt>. \r
- The password is simply <tt>cvs</tt>. This sets up a file in your home directory\r
- called <tt>.cvspass</tt>, which squirrels away the dummy password, so you only need to do\r
- this step one time.</li>\r
- <li>Now, you can check out a source tree using normal CVS commands. For example:</li>\r
- <pre> $ cvs checkout fpconfig\r
- $ cd fptools\r
- $ cvs checkout ghc</pre>\r
- <p>gets a brand spanking new set of GHC sources.</p>\r
-</ul>\r
-\r
-<p>The layout of our CVS repository is described below, under <a HREF="#first">Using CVS\r
-for the first time</a>. </p>\r
-\r
-<p>With read-only CVS access you can do anything except commit changes to the repository.\r
-You can make changes to your local tree, and still use CVS's merge facility to keep your\r
-tree up to date, and you can generate patches using 'cvs diff' in order to send to us for\r
-inclusion. </p>\r
-\r
-<h2><a NAME="read-write"></a><b>Remote Read-Write CVS Access</b></h2>\r
-\r
-<p>We generally supply read-write access to folk doing serious development on some part of\r
-the source tree, when going through us would be a pain. If you're developing some feature,\r
-or think you have the time and inclination to fix bugs in our sources, feel free to ask\r
-for read-write access. There is a certain amount of responsibility that goes with commit\r
-privileges; we are more likely to grant you access if you've demonstrated your competence\r
-by sending us patches via mail in the past. </p>\r
-\r
-<p>To use remote CVS, you need to supply me with a username and\r
-encrypted password. Once you've done that and the account on\r
-cvs.haskell.org has been set up, you need to install <a\r
-HREF="http://www.ssh.fi/">ssh</a>, which is relatively painless. Log\r
-in to cvs.haskell.org, and set up your <tt>.ssh/authorized_keys</tt>\r
-file to allow logins from your local machine without a password (the\r
-ssh documentation has details on how to do this). Then, just\r
-\r
-<ul>\r
- <li> set your <tt>CVSROOT</tt> environment variable to <tt>:ext:<username>@cvs.haskell.org:/home/cvs/root</tt>.\r
- </li>\r
- <li>set your<tt> CVS_RSH </tt>environment variable to <tt>ssh</tt>.</li>\r
-</ul>\r
-\r
-<p>The <tt>CVSROOT</tt> environment variable will be recorded in the checked-out tree, so\r
-you don't need to set this every time either. Ignore the instructions for setting <tt>CVSROOT</tt>\r
-below. </p>\r
-<b>\r
-\r
-<p>Caveats:</b> \r
-\r
-<ul>\r
- <li>Setting your <tt>CVS_RSH</tt> to <tt>ssh</tt> assumes that your CVS client understands\r
- how to execute shell script ("#!"s,really), which is what <tt>ssh</tt> is. This\r
- may not be the case on some platforms (read: Win32), so in that case set <tt>CVS_RSH</tt>\r
- to <tt>ssh1</tt>.</li>\r
-</ul>\r
-\r
-<h2><a NAME="first"></a><b>Using CVS for the First Time</b></h2>\r
-\r
-<ul>\r
- <li>(ok, everybody now...) Firstly, identify which areas of the source tree you'll be\r
- working on. The directory structure looks like this:</li>\r
- <div align="center"><center><table>\r
- <tr>\r
- <td>fptools/ghc </td>\r
- <td>GHC</td>\r
- </tr>\r
- <tr>\r
- <td>fptools/happy </td>\r
- <td>Happy</td>\r
- </tr>\r
- <tr>\r
- <td>fptools/green-card </td>\r
- <td>Green Card</td>\r
- </tr>\r
- <tr>\r
- <td>fptools/nofib </td>\r
- <td>Nofib test suite</td>\r
- </tr>\r
- <tr>\r
- <td>fptools/hdirect </td>\r
- <td>IDL-to-Haskell compiler</td>\r
- </tr>\r
- </table>\r
- </center></div><p>For each directory, there's a mailing list: <tt>cvs-ghc</tt>, <tt>cvs-nofib</tt>\r
- etc. Everyone on the mailing list is sent a message automatically by CVS whenever someone\r
- checks in a change, this helps to keep track of what's going on when several people are\r
- working on related stuff. To join any of these mailing lists, mail <a\r
- href="mailto:majordomo@haskell.org">majordomo@haskell.org</a>. </p>\r
- <li>Create a .cvsrc file. Mine looks like this:</li>\r
- <pre> checkout -P\r
- release -d\r
- update -P\r
- diff -c</pre>\r
- <p>It just gives default flags for some of the CVS commands. For instance, the -P flag to\r
- 'checkout' says prune empty directories, which is normally what you want.</p>\r
-</ul>\r
-\r
-<h2><a NAME="checkout"></a><b>Checking Out a Source Tree</b></h2>\r
-\r
-<ul>\r
- <li>Check out your sources. Make sure you set your <tt>CVSROOT</tt> environment variable\r
- according to either of the remote methods above. The Approved Way (at least by me) to\r
- check out a source tree is as follows:</li>\r
- <pre> $ cvs checkout fpconfig</pre>\r
- <p>At this point you have a new directory called 'fptools' which contains the basic stuff\r
- for the fptools suite - including the configuration files and some other junk. </p>\r
- <pre> $ mv fptools <directory></pre>\r
- <p>You can call the fptools directory whatever you like, CVS won't mind. </p>\r
- <pre> $ cd <directory>\r
- $ cvs checkout ghc happy</pre>\r
- <p>The second command here checks out the relevant modules you want to work on. For a GHC\r
- build, for instance, you need at least the <tt>ghc</tt> module (in fact you can get away\r
- with just that).</p>\r
-</ul>\r
-\r
-<h2><a NAME="commit"></a><b>Committing Your Changes</b></h2>\r
-\r
-<p>This is only if you have read-write access to the repository. For anoncvs users, CVS\r
-will issue a "read-only repository" error if you try to commit changes. \r
-\r
-<ul>\r
- <li>Build the software, if necessary. Unless you're just working on documentation, you'll\r
- probably want to build the software in order to test any changes you make. For GHC,\r
- instructions can be found in the GHC installation guide.</li>\r
- <li>Make changes. Preferably small ones first.</li>\r
- <li>Test them. You can see exactly what changes you've made by using the <tt>cvs diff</tt>\r
- command. For example, <pre> $ cvs diff</pre>\r
- <p>lists all the changes (using the <tt>diff</tt> command) in and below the current\r
- directory. In emacs, C-c C-v C-= runs <tt>cvs diff</tt> on the current buffer and shows\r
- you the results.</p>\r
- </li>\r
- <li>Before checking in a change, you need to update your source tree:</li>\r
- <pre> $ cd fptools\r
- $ cvs update</pre>\r
- <p>This pulls in any changes that other people have made, and merges them with yours. If\r
- there are any conflicts, CVS will tell you, and you'll have to resolve them before you can\r
- check your changes in. The documentation describes what to do in the event of a conflict. </p>\r
- <p>It's not always necessary to do a full cvs update before checking in a change, since\r
- CVS will always tell you if you try to check in a file that someone else has changed.\r
- However, you should still update at regular intervals to avoid making changes that don't\r
- work in conjuction with changes that someone else made. Keeping an eye on what goes by on\r
- the mailing list can help here. <br>\r
- <br>\r
- </p>\r
- <li>When you're happy that your change isn't going to break anything, check it in. For a\r
- one-file change:</li>\r
- <pre> $ cvs commit <filename></pre>\r
- <p>CVS will then pop up an editor for you to enter a "commit message", this is\r
- just a short description of what your change does, and will be kept in the history of the\r
- file. </p>\r
- <p>If you're using emacs, simply load up the file into a buffer and type C-x C-q, and\r
- emacs will prompt for a commit message and then check in the file for you. </p>\r
- <p>For a multiple-file change, things are a bit trickier. There are several ways to do\r
- this, but this is the way I find easiest. First type the commit message into a temporary\r
- file. Then either </p>\r
- <pre> $ cvs commit -F <commit-message> <file_1> .... <file_n></pre>\r
- <p>or, if nothing else has changed in this part of the source tree, </p>\r
- <pre> $ cvs commit -F <commit-message> <directory></pre>\r
- <p>where <directory> is a common parent directory for all your changes, and\r
- <commit-message> is the name of the file containing the commit message. </p>\r
- <p>Shortly afterwards, you'll get some mail from the relevant mailing list saying which\r
- files changed, and giving the commit message. For a multiple-file change, you should still\r
- get only *one* message.</p>\r
-</ul>\r
-\r
-<h2><a NAME="update"></a><b>Updating Your Source Tree</b></h2>\r
-\r
-<p>It can be tempting to cvs update just part of a source tree to bring in some changes\r
-that someone else has made, or before committing your own changes. This is NOT\r
-RECOMMENDED! Quite often changes in one part of the tree are dependent on changes in\r
-another part of the tree (the <tt>mk/*.mk</tt> files are a good example where problems\r
-crop up quite often). Having an inconsistent tree is a major cause of headaches. </p>\r
-\r
-<p>So, to avoid a lot of hassle, follow this recipe for updating your tree: </p>\r
-\r
-<pre>$ cd fptools\r
-$ cvs update -Pd 2>&1 | tee log</pre>\r
-\r
-<p>Look at the log file, and fix any conflicts (denoted by a 'C' in the first column). If\r
-you're using multiple build trees, then for every build tree you have pointing at this\r
-source tree, you need to update the links in case any new files have appeared: </p>\r
-\r
-<pre>$ cd <build-tree>\r
-$ lndir <source-tree></pre>\r
-\r
-<p>Some files might have been removed, so you need to remove the links pointing to these\r
-non-existent files: </p>\r
-\r
-<pre>$ find . -xtype l -exec rm '{}' \;</pre>\r
-\r
-<p>And finally, re-configure to take into accound any changes in mk/config.mk.in. </p>\r
-\r
-<pre>$ ./configure</pre>\r
-\r
-<p>To be *really* safe, you should do </p>\r
-\r
-<pre>$ gmake boot && gmake all</pre>\r
-\r
-<p>from the top-level, to update the dependencies and build any changed files. </p>\r
-\r
-<h2><a NAME="tags"></a><b>GHC Tag Policy</b></h2>\r
-\r
-If you want to check out a particular version of GHC, you'll need to\r
-know how we tag versions in the repository. The policy (as of 4.04)\r
-is:\r
-\r
-<ul>\r
- <li> The tree is branched before every major release. The branch\r
- tag is <tt>ghc-x-xx-branch</tt>, where <tt>x-xx</tt> is the version\r
- number of the release with the <tt>'.'</tt> replaced by a\r
- <tt>'-'</tt>. For example, the 4.04 release lives on\r
- <tt>ghc-4-04-branch</tt>.</li>\r
-\r
- <li> The release itself is tagged with <tt>ghc-x-xx</tt> (on the\r
- branch). eg. 4.06 is called <tt>ghc-4-06</tt>.</li>\r
-\r
- <li> We didn't always follow these guidelines, so to see what tags\r
- there are for previous versions, do <tt>cvs log</tt> on a file\r
- that's been around for a while (like <tt>fptools/ghc/README</tt>).\r
-</ul>\r
-\r
-So, to check out a fresh GHC 4.06 tree you would do:\r
-\r
-<pre>\r
- $ cvs co -r ghc-4-06 fpconfig\r
- $ cd fptools\r
- $ cvs co -r ghc-4-06 ghc hslibs\r
-</pre>\r
-\r
-\r
-<h2><a NAME="hints"></a><b>General Hints</b></h2>\r
-\r
-<ul>\r
- <li>As a general rule: commit changes in small units, preferably addressing one issue or\r
- implementing a single feature. Provide a descriptive log message so that the repository\r
- records exactly which changes were required to implement a given feature/fix a bug. I've\r
- found this *very* useful in the past for finding out when a particular bug was introduced:\r
- you can just wind back the CVS tree until the bug disappears.</li>\r
- <li>Keep the sources at least *buildable* at any given time. No doubt bugs will creep in,\r
- but it's quite easy to ensure that any change made at least leaves the tree in a buildable\r
- state. We do nightly builds of GHC to keep an eye on what things work/don't work each day\r
- and how we're doing in relation to previous verions. This idea is truely wrecked if the\r
- compiler won't build in the first place!</li>\r
- <li>To check out extra bits into an already-checked-out tree, use the following procedure.\r
- Suppose you have a checked-out fptools tree containing just ghc, and you want to add nofib\r
- to it:</li>\r
- <pre> cd fptools\r
- cvs checkout nofib</pre>\r
- <p>or: </p>\r
- <pre> cd fptools\r
- cvs update -d nofib</pre>\r
- <p>(the -d flag tells update to create a new directory). If you just want part of the\r
- nofib suite, you can do </p>\r
- <pre> cd fptools\r
- cvs checkout nofib/spectral</pre>\r
- <p>This works because <tt>nofib</tt> is a module in its own right, and spectral is a\r
- subdirectory of the nofib module. The path argument to checkout must always start with a\r
- module name. There's no equivalent form of this command using <tt>update</tt>.</p>\r
-</ul>\r
-\r
-<h2>Reporting Bugs in the CVS sources</h2>\r
-\r
-<p> If you are reporting a bug or infelicity in the CVS version of\r
-GHC, please send your message to </p>\r
-\r
-<table align="center">\r
-<tr><td>\r
- <a href="mailto:cvs-ghc@haskell.org">cvs-ghc@haskell.org</a><td></td>\r
-</td></tr>\r
-<tr><td>\r
- <a href="mailto:cvs-hslibs@haskell.org">cvs-hslibs@haskell.org</a> \r
- <td>(for hslibs/ stuff)</td>\r
-</td></tr>\r
-<tr><td>\r
- <a href="mailto:cvs-nofib@haskell.org">cvs-nofib@haskell.org</a>\r
- <td>(for nofib/ stuff)</td>\r
-</td></tr>\r
-</table>\r
-\r
-<p>(not to glasgow-haskell-bugs). Two reasons:</p>\r
-\r
-<ul>\r
-<li> Readers of glasgow-haskell-bugs will get less junk mail</li>\r
-\r
-<li> I'm a little worried that ghc-bugs readers are beginning to think\r
- "is ghc really this unreliable?"! The checked-in-last-night version\r
- of GHC just isn't going to be solid. No one expects it to be. But\r
- a casual reader might not distinguish.</li>\r
-</ul>\r
-\r
-<p>Please don't stop sending bug reports though. They are really useful.</p>\r
-\r
-<hr>\r
-\r
-<p>Ok, that'll do for now. If there's anything else you'd like to see\r
-in this file, just let us know. </p>\r
-\r
-<table>\r
- <tr>\r
- <td><a HREF="mailto:jlewis@cse.ogi.edu">Jeff Lewis</a> </td>\r
- </tr>\r
- <tr>\r
- <td><a HREF="mailto:simonm@dcs.gla.ac.uk">Simon Marlow</a> </td>\r
- </tr>\r
-</table>\r
-</body>\r
-</html>\r
+<!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 / blobdiff