1 CVS Cheat Sheet for fptools hackers.
2 ------------------------------------
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.
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
14 http://arch.cs.yale.edu:8080/~bradley/cvs-instructions
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>).
22 The following guidelines should mean we don't step on each other's
23 toes too much. Ok, here's what you do:
25 * Firstly, identify which areas of the source tree you'll be working
26 on. The directory structure looks like this:
29 fptools/hslibs Haskell Libraries
32 fptools/green-card Green Card
33 fptools/nofib Nofib test suite
34 fptools/common-rts GHC/Hugs combined run-time system
36 For each directory, there's a mailing list: fp-cvs-ghc,
37 fp-cvs-hslibs etc. Everyone on the mailing list is sent a message
38 automatically by CVS whenever someone checks in a change, this helps
39 to keep track of what's going on when several people are working on
40 related stuff. Ask the CVS meister to put you on the relevant
43 * Create a .cvsrc file. Mine looks like this:
50 It just gives default flags for some of the CVS commands. For instance,
51 the -P flag to 'checkout' says prune empty directories, which is
52 normally what you want.
54 * Check out your sources. The Approved Way (at least by me) to do
57 $ CVSROOT=/local/fp/src/cvsroot
60 or, if you're using csh or tcsh:
61 $ setenv CVSROOT=/local/fp/src/cvsroot
63 $ cvs checkout fpconfig
65 At this point you have a new directory called 'fptools' which contains
66 the basic stuff for the fptools suite - including the configuration
67 files and literate programming tools.
69 $ mv fptools <directory>
71 You can call the fptools directory whatever you like, CVS won't mind.
74 $ cvs checkout ghc hslibs happy
76 The second command here checks out the relevant modules you want to
77 work on. For a GHC build, for instance, you need at least ghc and
80 * Build the software, if necessary. Unless you're just working on
81 documentation, you'll probably want to build the software in order
82 to test any changes you make. For GHC, instructions can be found
83 in the GHC installation guide, online in info format.
85 * Make changes. Preferably small ones first.
87 * Test them. You can see exactly what changes you've made by using
88 the 'cvs diff' command. For example,
92 lists all the changes (using the 'diff' command) in and below the
93 current directory. In emacs, C-c C-v C-= runs 'cvs diff' on the current
94 buffer and shows you the results.
96 * Before checking in a change, you need to update your source tree:
101 This pulls in any changes that other people have made, and merges them
102 with yours. If there are any conflicts, CVS will tell you, and you'll
103 have to resolve them before you can check your changes in. The
104 documentation describes what to do in the event of a conflict.
106 It's not always necessary to do a full cvs update before checking in
107 a change, since CVS will always tell you if you try to check in a file
108 that someone else has changed. However, you should still update
109 at regular intervals to avoid making changes that don't work in
110 conjuction with changes that someone else made. Keeping an eye on
111 what goes by on the mailing list can help here.
113 * When you're happy that your change isn't going to break anything,
114 check it in. For a one-file change:
116 $ cvs commit <filename>
118 CVS will then pop up an editor for you to enter a "commit message",
119 this is just a short description of what your change does, and will
120 be kept in the history of the file.
122 If you're using emacs, simply load up the file into a buffer and type
123 C-x C-q, and emacs will prompt for a commit message and then check in
126 For a multiple-file change, things are a bit trickier. There are
127 several ways to do this, but this is the way I find easiest.
128 First type the commit message into a temporary file. Then either
130 $ cvs commit -F <commit-message> <file_1> .... <file_n>
132 or, if nothing else has changed in this part of the source tree,
134 $ cvs commit -F <commit-message> <directory>
136 where <directory> is a common parent directory for all your changes,
137 and <commit-message> is the name of the file containing the commit
140 Shortly afterwards, you'll get some mail from the relevant mailing
141 list saying which files changed, and giving the commit message.
142 For a multiple-file change, you should still get only *one* message.
144 * As a general rule: commit changes in small units, preferably
145 addressing one issue or implementing a single feature. Provide a
146 descriptive log message so that the repository records exactly which
147 changes were required to implement a given feature/fix a bug. I've
148 found this *very* useful in the past for finding out when a particular
149 bug was introduced: you can just wind back the CVS tree until
152 * Keep the sources at least *buildable* at any given time. No
153 doubt bugs will creep in, but it's quite easy to ensure that any
154 change made at least leaves the tree in a buildable state. We do
155 nightly builds of GHC to keep an eye on what things work/don't work
156 each day and how we're doing in relation to previous verions. This
157 idea is truely wrecked if the compiler won't build in the first place!
159 Ok, that'll do for now.
161 Simon Marlow <simonm@dcs.gla.ac.uk>