1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
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]">
7 <BODY TEXT="#2C3361" BGCOLOR="#FFFFFF" ALINK="#11BBFF">
9 <H1><B>FP Tools CVS Cheat Sheet</B></H1>
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.
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
22 href="http://arch.cs.yale.edu:8080/~bradley/cvs-instructions">introduction
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>).
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>
43 <h2><b><a name="read-only">Remote Read-only CVS Access</a></b></h2>
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
53 anoncvs@solander.dcs.gla.ac.uk:/cvs
56 <p>and you can then check out a source tree using normal CVS commands.
60 $ cvs checkout fpconfig
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>.
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
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>.
80 <h2><b><a name="read-write">Remote Read-Write CVS Access</a></b></h2>
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
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:
96 cvs -d <username>@solander.dcs.gla.ac.uk:/local/fp/src/cvsroot login
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.
103 setenv CVSROOT :pserver:<username>@solander.dcs.gla.ac.uk:/local/fp/src/cvsroot
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.
111 <h2><b><a name="first">Using CVS for the First Time</a></b></h2>
115 ok, everybody now...) Firstly, identify which areas of the source
116 tree you'll be working on. The directory structure looks like this:
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
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.
140 Create a .cvsrc file. Mine looks like this:
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.
154 <h2><b><a name="checkout">Checking Out a Source Tree</a></b></h2>
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:
163 $ CVSROOT=/local/fp/src/cvsroot
167 or, if you're using csh or tcsh:
170 $ setenv CVSROOT=/local/fp/src/cvsroot
173 The Approved Way (at least by me) to check out a source tree is as
177 $ cvs checkout fpconfig
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.
185 $ mv fptools <directory>
188 You can call the fptools directory whatever you like, CVS won't mind.
191 $ cd <directory>
192 $ cvs checkout ghc happy
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).
201 <h2><b><a name="commit">Committing Your Changes</a></b></h2>
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.
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>
214 <li> Make changes. Preferably small ones first.<p>
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>
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>
227 <li> Before checking in a change, you need to update your source tree:
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.
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>
246 <li> When you're happy that your change isn't going to break anything,
247 check it in. For a one-file change:
250 $ cvs commit <filename>
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.
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
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
266 $ cvs commit -F <commit-message> <file_1> .... <file_n>
269 or, if nothing else has changed in this part of the source tree,
272 $ cvs commit -F <commit-message> <directory>
275 where <directory> is a common parent directory for all your changes,
276 and <commit-message> is the name of the file containing the commit
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.
285 <h2><b><a name="update">Updating Your Source Tree</a></b></h2>
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
295 <p>So, to avoid a lot of hassle, follow this recipe for updating your
300 $ cvs update -Pd 2>&1 | tee log
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:
309 $ cd <build-tree>
310 $ lndir <source-tree>
313 <p>Some files might have been removed, so you need to remove the links
314 pointing to these non-existent files:
317 $ find . -xtype l -exec rm '{}' \;
320 <p>And finally, re-configure to take into accound any changes in
327 <p>To be *really* safe, you should do
330 $ gmake boot && gmake all
333 <p>from the top-level, to update the dependencies and build any changed
337 <h2><b><a name="hints">General Hints</a></b></h2>
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>
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
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:
373 (the -d flag tells update to create a new directory). If you just want
374 part of the nofib suite, you can do
378 cvs checkout nofib/spectral
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>.
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.
390 <p><a href="mailto:simonm@dcs.gla.ac.uk">Simon Marlow</a>