docs/cvs-cheat-sheet.html

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