docs/cvs-cheat-sheet.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
   2 <html>
   3
   4 <head>
   5 <meta HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
   6 <meta NAME="GENERATOR" CONTENT="Microsoft FrontPage 3.0">
   7 <title>Access To The GHC CVS Repository</title>
   8 </head>
   9
  10 <body TEXT="#2C3361" BGCOLOR="#FFFFFF" ALINK="#11BBFF">
  11
  12 <h1><b>FP Tools CVS Cheat Sheet</b></h1>
  13
  14 <p>We use CVS (Concurrent Version System) to keep track of our sources for various
  15 software projects. CVS lets several people work on the same software at the same time,
  16 allowing changes to be checked in incrementally. </p>
  17
  18 <p>Information on using CVS can be obtained from <a HREF="http://www.cyclic.com">Cyclic
  19 Software</a>. </p>
  20
  21 <p>This note is supposed to be a set of guidelines for how to use our CVS repository, and
  22 will probably evolve in time. The main thing to remember is that most mistakes can be
  23 undone, but if there's anything you're not sure about feel free to bug the local CVS
  24 meister (namely <a HREF="mailto:jlewis@cse.ogi.edu">Jeff Lewis</a>). </p>
  25
  26 <p><b>Contents</b>
  27
  28 <ul>
  29   <li><a HREF="#read-only">Read-only remote access</a></li>
  30   <li><a HREF="#read-write">Read-write remote access</a></li>
  31   <li><a HREF="#first">Using CVS for the first time</a></li>
  32   <li><a HREF="#checkout">Checking out a source tree</a></li>
  33   <li><a HREF="#commit">Committing changes</a></li>
  34   <li><a HREF="#update">Updating your source tree</a></li>
  35   <li><a HREF="#hints">General Hints</a></li>
  36 </ul>
  37
  38 <h2><a NAME="read-only"></a><b>Remote Read-only CVS Access</b></h2>
  39
  40 <p>Read-only access is available to anyone - there's no need to ask us first. To get
  41 read-only access to our repository:
  42
  43 <ul>
  44   <li>set your CVSROOT environment variable to <tt>:pserver:anoncvs@glass.cse.ogi.edu:/cvs</tt></li>
  45   <li>The first time you access the repository, you'll need to do <tt>cvs login</tt>.&nbsp;
  46     The password is simply <tt>cvs</tt>.&nbsp; This sets up a file in your home directory
  47     called <tt>.cvspass</tt>, which squirrels away the dummy password, so you only need to do
  48     this step one time.</li>
  49   <li>Now, you can check out a source tree using normal CVS commands. For example:</li>
  50   <pre>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; $ cvs checkout fpconfig
  51 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; $ cd fptools
  52 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; $ cvs checkout ghc</pre>
  53   <p>gets a brand spanking new set of GHC sources.</p>
  54 </ul>
  55
  56 <p>The layout of our CVS repository is described below, under <a HREF="#first">Using CVS
  57 for the first time</a>. </p>
  58
  59 <p>With read-only CVS access you can do anything except commit changes to the repository.
  60 You can make changes to your local tree, and still use CVS's merge facility to keep your
  61 tree up to date, and you can generate patches using 'cvs diff' in order to send to us for
  62 inclusion. </p>
  63
  64 <h2><a NAME="read-write"></a><b>Remote Read-Write CVS Access</b></h2>
  65
  66 <p>We generally supply read-write access to folk doing serious development on some part of
  67 the source tree, when going through us would be a pain. If you're developing some feature,
  68 or think you have the time and inclination to fix bugs in our sources, feel free to ask
  69 for read-write access. There is a certain amount of responsibility that goes with commit
  70 privileges; we are more likely to grant you access if you've demonstrated your competence
  71 by sending us patches via mail in the past. </p>
  72
  73 <p>To use remote CVS, you need to supply me with a username and
  74 encrypted password. Once you've done that and the account on
  75 cvs.haskell.org has been set up, you need to install <a
  76 HREF="http://www.ssh.fi/">ssh</a>, which is relatively painless.  Log
  77 in to cvs.haskell.org, and set up your <tt>.ssh/authorized_keys</tt>
  78 file to allow logins from your local machine without a password (the
  79 ssh documentation has details on how to do this).  Then, just
  80
  81 <ul>
  82   <li> set your <tt>CVSROOT</tt> environment variable to <tt>:ext:&lt;username&gt;@cvs.haskell.org:/home/cvs/root</tt>.
  83   </li>
  84   <li>set your<tt> CVS_RSH </tt>environment variable to <tt>ssh</tt>.</li>
  85 </ul>
  86
  87 <p>The <tt>CVSROOT</tt> environment variable will be recorded in the checked-out tree, so
  88 you don't need to set this every time either. Ignore the instructions for setting <tt>CVSROOT</tt>
  89 below. </p>
  90 <b>
  91
  92 <p>Caveats:</b>
  93
  94 <ul>
  95   <li>Setting your <tt>CVS_RSH</tt> to <tt>ssh</tt> assumes that your CVS client understands
  96     how to execute shell script (&quot;#!&quot;s,really), which is what <tt>ssh</tt> is. This
  97     may not be the case on some platforms (read: Win32), so in that case set <tt>CVS_RSH</tt>
  98     to <tt>ssh1</tt>.</li>
  99 </ul>
 100
 101 <h2><a NAME="first"></a><b>Using CVS for the First Time</b></h2>
 102
 103 <ul>
 104   <li>(ok, everybody now...) Firstly, identify which areas of the source tree you'll be
 105     working on. The directory structure looks like this:</li>
 106   <div align="center"><center><table>
 107     <tr>
 108       <td>fptools/ghc&nbsp;</td>
 109       <td>GHC</td>
 110     </tr>
 111     <tr>
 112       <td>fptools/happy&nbsp;</td>
 113       <td>Happy</td>
 114     </tr>
 115     <tr>
 116       <td>fptools/green-card&nbsp;</td>
 117       <td>Green Card</td>
 118     </tr>
 119     <tr>
 120       <td>fptools/nofib&nbsp;</td>
 121       <td>Nofib test suite</td>
 122     </tr>
 123     <tr>
 124       <td>fptools/hdirect&nbsp;</td>
 125       <td>IDL-to-Haskell compiler</td>
 126     </tr>
 127   </table>
 128   </center></div><p>For each directory, there's a mailing list: <tt>cvs-ghc</tt>, <tt>cvs-nofib</tt>
 129   etc. Everyone on the mailing list is sent a message automatically by CVS whenever someone
 130   checks in a change, this helps to keep track of what's going on when several people are
 131   working on related stuff. To join any of these mailing lists, go to
 132 <a
 133 href="http://www.haskell.org/mailman/listinfo/">http://www.haskell.org/mailman/listinfo/</a>.</p>
 134   <li>Create a .cvsrc file. Mine looks like this:</li>
 135   <pre>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; checkout -P
 136 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; release -d
 137 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; update -P
 138 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; diff -c</pre>
 139   <p>It just gives default flags for some of the CVS commands. For instance, the -P flag to
 140   'checkout' says prune empty directories, which is normally what you want.</p>
 141 </ul>
 142
 143 <h2><a NAME="checkout"></a><b>Checking Out a Source Tree</b></h2>
 144
 145 <ul>
 146   <li>Check out your sources. Make sure you set your <tt>CVSROOT</tt> environment variable
 147     according to either of the remote methods above. The Approved Way (at least by me) to
 148     check out a source tree is as follows:</li>
 149   <pre>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; $ cvs checkout fpconfig</pre>
 150   <p>At this point you have a new directory called 'fptools' which contains the basic stuff
 151   for the fptools suite - including the configuration files and some other junk. </p>
 152   <pre>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; $ mv fptools &lt;directory&gt;</pre>
 153   <p>You can call the fptools directory whatever you like, CVS won't mind. </p>
 154   <pre>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; $ cd &lt;directory&gt;
 155 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; $ cvs checkout ghc happy</pre>
 156   <p>The second command here checks out the relevant modules you want to work on. For a GHC
 157   build, for instance, you need at least the <tt>ghc</tt> module (in fact you can get away
 158   with just that).</p>
 159 </ul>
 160
 161 <h2><a NAME="commit"></a><b>Committing Your Changes</b></h2>
 162
 163 <p>This is only if you have read-write access to the repository. For anoncvs users, CVS
 164 will issue a &quot;read-only repository&quot; error if you try to commit changes.
 165
 166 <ul>
 167   <li>Build the software, if necessary. Unless you're just working on documentation, you'll
 168     probably want to build the software in order to test any changes you make. For GHC,
 169     instructions can be found in the GHC installation guide.</li>
 170   <li>Make changes. Preferably small ones first.</li>
 171   <li>Test them. You can see exactly what changes you've made by using the <tt>cvs diff</tt>
 172     command. For example, <pre>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; $ cvs diff</pre>
 173     <p>lists all the changes (using the <tt>diff</tt> command) in and below the current
 174     directory. In emacs, C-c C-v C-= runs <tt>cvs diff</tt> on the current buffer and shows
 175     you the results.</p>
 176   </li>
 177   <li>Before checking in a change, you need to update your source tree:</li>
 178   <pre>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; $ cd fptools
 179 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; $ cvs update</pre>
 180   <p>This pulls in any changes that other people have made, and merges them with yours. If
 181   there are any conflicts, CVS will tell you, and you'll have to resolve them before you can
 182   check your changes in. The documentation describes what to do in the event of a conflict. </p>
 183   <p>It's not always necessary to do a full cvs update before checking in a change, since
 184   CVS will always tell you if you try to check in a file that someone else has changed.
 185   However, you should still update at regular intervals to avoid making changes that don't
 186   work in conjuction with changes that someone else made. Keeping an eye on what goes by on
 187   the mailing list can help here. <br>
 188   &nbsp; <br>
 189   &nbsp; </p>
 190   <li>When you're happy that your change isn't going to break anything, check it in. For a
 191     one-file change:</li>
 192   <pre>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; $ cvs commit &lt;filename&gt;</pre>
 193   <p>CVS will then pop up an editor for you to enter a &quot;commit message&quot;, this is
 194   just a short description of what your change does, and will be kept in the history of the
 195   file. </p>
 196   <p>If you're using emacs, simply load up the file into a buffer and type C-x C-q, and
 197   emacs will prompt for a commit message and then check in the file for you. </p>
 198   <p>For a multiple-file change, things are a bit trickier. There are several ways to do
 199   this, but this is the way I find easiest. First type the commit message into a temporary
 200   file. Then either </p>
 201   <pre>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; $ cvs commit -F &lt;commit-message&gt; &lt;file_1&gt; .... &lt;file_n&gt;</pre>
 202   <p>or, if nothing else has changed in this part of the source tree, </p>
 203   <pre>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; $ cvs commit -F &lt;commit-message&gt; &lt;directory&gt;</pre>
 204   <p>where &lt;directory&gt; is a common parent directory for all your changes, and
 205   &lt;commit-message&gt; is the name of the file containing the commit message. </p>
 206   <p>Shortly afterwards, you'll get some mail from the relevant mailing list saying which
 207   files changed, and giving the commit message. For a multiple-file change, you should still
 208   get only *one* message.</p>
 209 </ul>
 210
 211 <h2><a NAME="update"></a><b>Updating Your Source Tree</b></h2>
 212
 213 <p>It can be tempting to cvs update just part of a source tree to bring in some changes
 214 that someone else has made, or before committing your own changes. This is NOT
 215 RECOMMENDED! Quite often changes in one part of the tree are dependent on changes in
 216 another part of the tree (the <tt>mk/*.mk</tt> files are a good example where problems
 217 crop up quite often). Having an inconsistent tree is a major cause of headaches. </p>
 218
 219 <p>So, to avoid a lot of hassle, follow this recipe for updating your tree: </p>
 220
 221 <pre>$ cd fptools
 222 $ cvs update -Pd 2&gt;&amp;1 | tee log</pre>
 223
 224 <p>Look at the log file, and fix any conflicts (denoted by a 'C' in the first column). If
 225 you're using multiple build trees, then for every build tree you have pointing at this
 226 source tree, you need to update the links in case any new files have appeared: </p>
 227
 228 <pre>$ cd &lt;build-tree&gt;
 229 $ lndir &lt;source-tree&gt;</pre>
 230
 231 <p>Some files might have been removed, so you need to remove the links pointing to these
 232 non-existent files: </p>
 233
 234 <pre>$ find . -xtype l -exec rm '{}' \;</pre>
 235
 236 <p>And finally, re-configure to take into accound any changes in mk/config.mk.in. </p>
 237
 238 <pre>$ ./configure</pre>
 239
 240 <p>To be *really* safe, you should do </p>
 241
 242 <pre>$ gmake boot &amp;&amp; gmake all</pre>
 243
 244 <p>from the top-level, to update the dependencies and build any changed files. </p>
 245
 246 <h2><a NAME="tags"></a><b>GHC Tag Policy</b></h2>
 247
 248 If you want to check out a particular version of GHC, you'll need to
 249 know how we tag versions in the repository.  The policy (as of 4.04)
 250 is:
 251
 252 <ul>
 253    <li> The tree is branched before every major release.  The branch
 254    tag is <tt>ghc-x-xx-branch</tt>, where <tt>x-xx</tt> is the version
 255    number of the release with the <tt>'.'</tt> replaced by a
 256    <tt>'-'</tt>.  For example, the 4.04 release lives on
 257    <tt>ghc-4-04-branch</tt>.</li>
 258
 259    <li> The release itself is tagged with <tt>ghc-x-xx</tt> (on the
 260    branch).  eg. 4.06 is called <tt>ghc-4-06</tt>.</li>
 261
 262    <li> We didn't always follow these guidelines, so to see what tags
 263    there are for previous versions, do <tt>cvs log</tt> on a file
 264    that's been around for a while (like <tt>fptools/ghc/README</tt>).
 265 </ul>
 266
 267 So, to check out a fresh GHC 4.06 tree you would do:
 268
 269 <pre>
 270      $ cvs co -r ghc-4-06 fpconfig
 271      $ cd fptools
 272      $ cvs co -r ghc-4-06 ghc hslibs
 273 </pre>
 274
 275
 276 <h2><a NAME="hints"></a><b>General Hints</b></h2>
 277
 278 <ul>
 279   <li>As a general rule: commit changes in small units, preferably addressing one issue or
 280     implementing a single feature. Provide a descriptive log message so that the repository
 281     records exactly which changes were required to implement a given feature/fix a bug. I've
 282     found this *very* useful in the past for finding out when a particular bug was introduced:
 283     you can just wind back the CVS tree until the bug disappears.</li>
 284   <li>Keep the sources at least *buildable* at any given time. No doubt bugs will creep in,
 285     but it's quite easy to ensure that any change made at least leaves the tree in a buildable
 286     state. We do nightly builds of GHC to keep an eye on what things work/don't work each day
 287     and how we're doing in relation to previous verions. This idea is truely wrecked if the
 288     compiler won't build in the first place!</li>
 289   <li>To check out extra bits into an already-checked-out tree, use the following procedure.
 290     Suppose you have a checked-out fptools tree containing just ghc, and you want to add nofib
 291     to it:</li>
 292   <pre>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; cd fptools
 293 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; cvs checkout nofib</pre>
 294   <p>or: </p>
 295   <pre>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; cd fptools
 296 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; cvs update -d nofib</pre>
 297   <p>(the -d flag tells update to create a new directory). If you just want part of the
 298   nofib suite, you can do </p>
 299   <pre>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; cd fptools
 300 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; cvs checkout nofib/spectral</pre>
 301   <p>This works because <tt>nofib</tt> is a module in its own right, and spectral is a
 302   subdirectory of the nofib module. The path argument to checkout must always start with a
 303   module name. There's no equivalent form of this command using <tt>update</tt>.</p>
 304 </ul>
 305
 306 <h2>Reporting Bugs in the CVS sources</h2>
 307
 308 <p> If you are reporting a bug or infelicity in the CVS version of
 309 GHC, please send your message to </p>
 310
 311 <table align="center">
 312 <tr><td>
 313         <a href="mailto:cvs-ghc@haskell.org">cvs-ghc@haskell.org</a><td></td>
 314 </td></tr>
 315 <tr><td>
 316         <a href="mailto:cvs-hslibs@haskell.org">cvs-hslibs@haskell.org</a>
 317         <td>(for hslibs/ stuff)</td>
 318 </td></tr>
 319 <tr><td>
 320         <a href="mailto:cvs-nofib@haskell.org">cvs-nofib@haskell.org</a>
 321         <td>(for nofib/ stuff)</td>
 322 </td></tr>
 323 </table>
 324
 325 <p>(not to glasgow-haskell-bugs).   Two reasons:</p>
 326
 327 <ul>
 328 <li> Readers of glasgow-haskell-bugs will get less junk mail</li>
 329
 330 <li> I'm a little worried that ghc-bugs readers are beginning to think
 331   "is ghc really this unreliable?"!    The checked-in-last-night version
 332   of GHC just isn't going to be solid.  No one expects it to be.  But
 333   a casual reader might not distinguish.</li>
 334 </ul>
 335
 336 <p>Please don't stop sending bug reports though.  They are really useful.</p>
 337
 338 <hr>
 339
 340 <p>Ok, that'll do for now. If there's anything else you'd like to see
 341 in this file, just let us know. </p>
 342
 343 <table>
 344   <tr>
 345     <td><a HREF="mailto:jlewis@cse.ogi.edu">Jeff Lewis</a> </td>
 346   </tr>
 347   <tr>
 348     <td><a HREF="mailto:simonm@dcs.gla.ac.uk">Simon Marlow</a> </td>
 349   </tr>
 350 </table>
 351 </body>
 352 </html>