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:
29 * (only if using CVS remotely, i.e. not at Glasgow):
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:
35 cvs -d <username>@solander.dcs.gla.ac.uk:/local/fp/src/cvsroot login
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.
40 setenv CVSROOT :pserver:<username>@solander.dcs.gla.ac.uk:/local/fp/src/cvsroot
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.
47 Using CVS for the First Time
48 ----------------------------
50 * (ok, everybody now...) Firstly, identify which areas of the source
51 tree you'll be working on. The directory structure looks like this:
56 fptools/green-card Green Card
57 fptools/nofib Nofib test suite
58 fptools/hdirect IDL-to-Haskell compiler
59 fptools/common-rts GHC/Hugs combined run-time system
61 For each directory, there's a mailing list: fp-cvs-ghc,
62 fp-cvs-nofib 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
68 * Create a .cvsrc file. Mine looks like this:
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.
80 Checking Out a Source Tree
81 --------------------------
83 * Check out your sources. The Approved Way (at least by me) to do
86 $ CVSROOT=/local/fp/src/cvsroot
89 or, if you're using csh or tcsh:
90 $ setenv CVSROOT=/local/fp/src/cvsroot
92 $ cvs checkout fpconfig
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.
98 $ mv fptools <directory>
100 You can call the fptools directory whatever you like, CVS won't mind.
103 $ cvs checkout ghc happy
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 the ghc
107 module (in fact you can get away with just that).
110 Committing Your Changes
111 -----------------------
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.
118 * Make changes. Preferably small ones first.
120 * Test them. You can see exactly what changes you've made by using
121 the 'cvs diff' command. For example,
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.
129 * Before checking in a change, you need to update your source tree:
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.
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.
146 * When you're happy that your change isn't going to break anything,
147 check it in. For a one-file change:
149 $ cvs commit <filename>
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.
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
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
163 $ cvs commit -F <commit-message> <file_1> .... <file_n>
165 or, if nothing else has changed in this part of the source tree,
167 $ cvs commit -F <commit-message> <directory>
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
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.
178 Updating Your Source Tree
179 -------------------------
181 It can be tempting to cvs update just part of a source tree to bring
182 in some changes that someone else has made, or before committing your
183 own changes. This is NOT RECOMMENDED! Quite often changes in one
184 part of the tree are dependent on changes in another part of the tree
185 (the mk/*.mk files are a good example where problems crop up quite
186 often). Having an inconsistent tree is a major cause of headaches.
188 So, to avoid a lot of hassle, follow this recipe for updating your
192 $ cvs update -Pd 2>&1 | tee log
194 Look at the log file, and fix any conflicts (denoted by a 'C' in the
195 first column). Next for every build tree you have pointing at this
196 source tree, you need to update the links in case any new files have
200 $ lndir <source-tree>
202 Some files might have been removed, so you need to remove the links
203 pointing to these non-existent files:
205 $ find . -xtype l -exec rm '{}' \;
207 And finally, re-configure to take into accound any changes in
212 To be *really* safe, you should do
214 $ gmake boot && gmake all
216 from the top-level, to update the dependencies and build any changed
223 * As a general rule: commit changes in small units, preferably
224 addressing one issue or implementing a single feature. Provide a
225 descriptive log message so that the repository records exactly which
226 changes were required to implement a given feature/fix a bug. I've
227 found this *very* useful in the past for finding out when a particular
228 bug was introduced: you can just wind back the CVS tree until
231 * Keep the sources at least *buildable* at any given time. No
232 doubt bugs will creep in, but it's quite easy to ensure that any
233 change made at least leaves the tree in a buildable state. We do
234 nightly builds of GHC to keep an eye on what things work/don't work
235 each day and how we're doing in relation to previous verions. This
236 idea is truely wrecked if the compiler won't build in the first place!
238 * To check out extra bits into an already-checked-out tree, use the
239 following procedure. Suppose you have a checked-out fptools tree containing
240 just ghc, and you want to add nofib to it:
250 (the -d flag tells update to create a new directory). If you just want
251 part of the nofib suite, you can do
254 cvs checkout nofib/spectral
256 This works because 'nofib' is a module in its own right, and spectral
257 is a subdirectory of the nofib module. The path argument to checkout
258 must always start with a module name. There's no equivalent form of
259 this command using update.
261 Ok, that'll do for now. If there's anything else you'd like to see in
262 this file, just let me know.
264 Simon Marlow <simonm@dcs.gla.ac.uk>