CVS-CHEAT-SHEET

   1 CVS Cheat Sheet for fptools hackers.
   2 ------------------------------------
   3
   4 At Glasgow, we use CVS (Concurrent Version System) to keep track of
   5 our sources for various software projects.  CVS lets several people
   6 work on the same software at the same time, allowing changes to be
   7 checked in incrementally.
   8
   9 The full documentation for CVS is online, in info format (use 'info
  10 cvs' or run emacs and type C-h i).  A good source of tips is the CVS
  11 FAQ, in /local/doc/gnu/CVS.FAQ.  Bradley C. Kuszmaul provides a "to
  12 the point" introduction to CVS at
  13
  14         http://arch.cs.yale.edu:8080/~bradley/cvs-instructions
  15
  16 This note is supposed to be a set of guidelines for how to use CVS at
  17 Glasgow, and will probably evolve in time.  The main thing to remember
  18 is that most mistakes can be undone, but if there's anything you're
  19 not sure about feel free to bug the local CVS meister (namely Me
  20 <simonm@dcs.gla.ac.uk>).
  21
  22 The following guidelines should mean we don't step on each other's
  23 toes too much.  Ok, here's what you do:
  24
  25
  26 Using Remote CVS
  27 ----------------
  28
  29 * (only if using CVS remotely, i.e. not at Glasgow):
  30
  31   To use remote CVS, you need to supply me with a username and
  32   encrypted password.  Once you've done that and the account has been
  33   set up, you need to do:
  34
  35      cvs -d <username>@solander.dcs.gla.ac.uk:/local/fp/src/cvsroot login
  36
  37   CVS will ask for a password.  You only need to enter the password once,
  38   it will be recorded in .cvspass in your home directory.
  39
  40      setenv CVSROOT :pserver:<username>@solander.dcs.gla.ac.uk:/local/fp/src/cvsroot
  41
  42   The CVSROOT environment variable will be recorded in the checked-out
  43   tree, so you don't need to set this every time either.  Ignore the
  44   instructions for setting CVSROOT below.
  45
  46
  47 Using CVS for the First Time
  48 ----------------------------
  49
  50 * (ok, everybody now...) Firstly, identify which areas of the source
  51   tree you'll be working on.  The directory structure looks like this:
  52
  53         fptools/ghc             GHC
  54         fptools/hslibs          Haskell Libraries
  55         fptools/happy           Happy
  56         fptools/haggis          Haggis
  57         fptools/green-card      Green Card
  58         fptools/nofib           Nofib test suite
  59         fptools/common-rts      GHC/Hugs combined run-time system
  60
  61   For each directory, there's a mailing list: fp-cvs-ghc,
  62   fp-cvs-hslibs etc.  Everyone on the mailing list is sent a message
  63   automatically by CVS whenever someone checks in a change, this helps
  64   to keep track of what's going on when several people are working on
  65   related stuff.  Ask the CVS meister to put you on the relevant
  66   mailing lists.
  67
  68 * Create a .cvsrc file.  Mine looks like this:
  69
  70         checkout -P
  71         release -d
  72         update -P
  73         diff -c
  74
  75   It just gives default flags for some of the CVS commands.  For instance,
  76   the -P flag to 'checkout' says prune empty directories, which is
  77   normally what you want.
  78
  79
  80 Checking Out a Source Tree
  81 --------------------------
  82
  83 * Check out your sources.  The Approved Way (at least by me) to do
  84   this is as follows:
  85
  86         $ CVSROOT=/local/fp/src/cvsroot
  87         $ export CVSROOT
  88
  89         or, if you're using csh or tcsh:
  90                 $ setenv CVSROOT=/local/fp/src/cvsroot
  91
  92         $ cvs checkout fpconfig
  93
  94   At this point you have a new directory called 'fptools' which contains
  95   the basic stuff for the fptools suite - including the configuration
  96   files and literate programming tools.
  97
  98         $ mv fptools <directory>
  99
 100   You can call the fptools directory whatever you like, CVS won't mind.
 101
 102         $ cd <directory>
 103         $ cvs checkout ghc hslibs happy
 104
 105   The second command here checks out the relevant modules you want to
 106   work on.  For a GHC build, for instance, you need at least ghc and
 107   hslibs.
 108
 109
 110 Committing Your Changes
 111 -----------------------
 112
 113 * Build the software, if necessary.  Unless you're just working on
 114   documentation, you'll probably want to build the software in order
 115   to test any changes you make.  For GHC, instructions can be found
 116   in the GHC installation guide, online in info format.
 117
 118 * Make changes.  Preferably small ones first.
 119
 120 * Test them.  You can see exactly what changes you've made by using
 121   the 'cvs diff' command.  For example,
 122
 123         $ cvs diff
 124
 125   lists all the changes (using the 'diff' command) in and below the
 126   current directory.  In emacs, C-c C-v C-= runs 'cvs diff' on the current
 127   buffer and shows you the results.
 128
 129 * Before checking in a change, you need to update your source tree:
 130
 131         $ cd fptools
 132         $ cvs update
 133
 134   This pulls in any changes that other people have made, and merges them
 135   with yours.  If there are any conflicts, CVS will tell you, and you'll
 136   have to resolve them before you can check your changes in.  The
 137   documentation describes what to do in the event of a conflict.
 138
 139   It's not always necessary to do a full cvs update before checking in
 140   a change, since CVS will always tell you if you try to check in a file
 141   that someone else has changed.  However, you should still update
 142   at regular intervals to avoid making changes that don't work in
 143   conjuction with changes that someone else made.  Keeping an eye on
 144   what goes by on the mailing list can help here.
 145
 146 * When you're happy that your change isn't going to break anything,
 147   check it in.  For a one-file change:
 148
 149         $ cvs commit <filename>
 150
 151   CVS will then pop up an editor for you to enter a "commit message",
 152   this is just a short description of what your change does, and will
 153   be kept in the history of the file.
 154
 155   If you're using emacs, simply load up the file into a buffer and type
 156   C-x C-q, and emacs will prompt for a commit message and then check in
 157   the file for you.
 158
 159   For a multiple-file change, things are a bit trickier.  There are
 160   several ways to do this, but this is the way I find easiest.
 161   First type the commit message into a temporary file.  Then either
 162
 163         $ cvs commit -F <commit-message> <file_1> .... <file_n>
 164
 165   or, if nothing else has changed in this part of the source tree,
 166
 167         $ cvs commit -F <commit-message> <directory>
 168
 169   where <directory> is a common parent directory for all your changes,
 170   and <commit-message> is the name of the file containing the commit
 171   message.
 172
 173   Shortly afterwards, you'll get some mail from the relevant mailing
 174   list saying which files changed, and giving the commit message.
 175   For a multiple-file change, you should still get only *one* message.
 176
 177
 178 General Hints
 179 -------------
 180
 181 * As a general rule: commit changes in small units, preferably
 182   addressing one issue or implementing a single feature.  Provide a
 183   descriptive log message so that the repository records exactly which
 184   changes were required to implement a given feature/fix a bug.  I've
 185   found this *very* useful in the past for finding out when a particular
 186   bug was introduced: you can just wind back the CVS tree until
 187   the bug disappears.
 188
 189 * Keep the sources at least *buildable* at any given time.  No
 190   doubt bugs will creep in, but it's quite easy to ensure that any
 191   change made at least leaves the tree in a buildable state.  We do
 192   nightly builds of GHC to keep an eye on what things work/don't work
 193   each day and how we're doing in relation to previous verions.  This
 194   idea is truely wrecked if the compiler won't build in the first place!
 195
 196 * To check out extra bits into an already-checked-out tree, use the
 197   following procedure.  Suppose you have a checked-out fptools tree containing
 198   just ghc and hslibs, and you want to add nofib to it:
 199
 200         cd fptools
 201         cvs checkout nofib
 202
 203   or:
 204
 205         cd fptools
 206         cvs update -d nofib
 207
 208   (the -d flag tells update to create a new directory).  If you just want
 209   part of the nofib suite, you can do
 210
 211         cd fptools
 212         cvs checkout nofib/spectral
 213
 214   This works because 'nofib' is a module in its own right, and spectral
 215   is a subdirectory of the nofib module.  The path argument to checkout
 216   must always start with a module name.  There's no equivalent form of
 217   this command using update.
 218
 219 Ok, that'll do for now.  If there's anything else you'd like to see in
 220 this file, just let me know.
 221
 222 Simon Marlow <simonm@dcs.gla.ac.uk>
 223