+++ /dev/null
-CVS Cheat Sheet for fptools hackers.
-------------------------------------
-
-At Glasgow, we use CVS (Concurrent Version System) to keep track of
-our sources for various software projects. CVS lets several people
-work on the same software at the same time, allowing changes to be
-checked in incrementally.
-
-The full documentation for CVS is online, in info format (use 'info
-cvs' or run emacs and type C-h i). A good source of tips is the CVS
-FAQ, in /local/doc/gnu/CVS.FAQ. Bradley C. Kuszmaul provides a "to
-the point" introduction to CVS at
-
- http://arch.cs.yale.edu:8080/~bradley/cvs-instructions
-
-This note is supposed to be a set of guidelines for how to use CVS at
-Glasgow, and will probably evolve in time. The main thing to remember
-is that most mistakes can be undone, but if there's anything you're
-not sure about feel free to bug the local CVS meister (namely Me
-<simonm@dcs.gla.ac.uk>).
-
-The following guidelines should mean we don't step on each other's
-toes too much. Ok, here's what you do:
-
-
-Using Remote CVS
-----------------
-
-* (only if using CVS remotely, i.e. not at Glasgow):
-
- To use remote CVS, you need to supply me with a username and
- encrypted password. Once you've done that and the account has been
- set up, you need to do:
-
- cvs -d <username>@solander.dcs.gla.ac.uk:/local/fp/src/cvsroot login
-
- CVS will ask for a password. You only need to enter the password once,
- it will be recorded in .cvspass in your home directory.
-
- setenv CVSROOT :pserver:<username>@solander.dcs.gla.ac.uk:/local/fp/src/cvsroot
-
- The CVSROOT environment variable will be recorded in the checked-out
- tree, so you don't need to set this every time either. Ignore the
- instructions for setting CVSROOT below.
-
-
-Using CVS for the First Time
-----------------------------
-
-* (ok, everybody now...) Firstly, identify which areas of the source
- tree you'll be working on. The directory structure looks like this:
-
- fptools/ghc GHC
- fptools/happy Happy
- fptools/haggis Haggis
- fptools/green-card Green Card
- fptools/nofib Nofib test suite
- fptools/hdirect IDL-to-Haskell compiler
- fptools/common-rts GHC/Hugs combined run-time system
-
- For each directory, there's a mailing list: fp-cvs-ghc,
- fp-cvs-nofib etc. Everyone on the mailing list is sent a message
- automatically by CVS whenever someone checks in a change, this helps
- to keep track of what's going on when several people are working on
- related stuff. Ask the CVS meister to put you on the relevant
- mailing lists.
-
-* Create a .cvsrc file. Mine looks like this:
-
- checkout -P
- release -d
- update -P
- diff -c
-
- It just gives default flags for some of the CVS commands. For instance,
- the -P flag to 'checkout' says prune empty directories, which is
- normally what you want.
-
-
-Checking Out a Source Tree
---------------------------
-
-* Check out your sources. The Approved Way (at least by me) to do
- this is as follows:
-
- $ CVSROOT=/local/fp/src/cvsroot
- $ export CVSROOT
-
- or, if you're using csh or tcsh:
- $ setenv CVSROOT=/local/fp/src/cvsroot
-
- $ cvs checkout fpconfig
-
- At this point you have a new directory called 'fptools' which contains
- the basic stuff for the fptools suite - including the configuration
- files and literate programming tools.
-
- $ mv fptools <directory>
-
- You can call the fptools directory whatever you like, CVS won't mind.
-
- $ cd <directory>
- $ cvs checkout ghc happy
-
- The second command here checks out the relevant modules you want to
- work on. For a GHC build, for instance, you need at least the ghc
- module (in fact you can get away with just that).
-
-
-Committing Your Changes
------------------------
-
-* Build the software, if necessary. Unless you're just working on
- documentation, you'll probably want to build the software in order
- to test any changes you make. For GHC, instructions can be found
- in the GHC installation guide, online in info format.
-
-* Make changes. Preferably small ones first.
-
-* Test them. You can see exactly what changes you've made by using
- the 'cvs diff' command. For example,
-
- $ cvs diff
-
- lists all the changes (using the 'diff' command) in and below the
- current directory. In emacs, C-c C-v C-= runs 'cvs diff' on the current
- buffer and shows you the results.
-
-* Before checking in a change, you need to update your source tree:
-
- $ cd fptools
- $ cvs update
-
- This pulls in any changes that other people have made, and merges them
- with yours. If there are any conflicts, CVS will tell you, and you'll
- have to resolve them before you can check your changes in. The
- documentation describes what to do in the event of a conflict.
-
- It's not always necessary to do a full cvs update before checking in
- a change, since CVS will always tell you if you try to check in a file
- that someone else has changed. However, you should still update
- at regular intervals to avoid making changes that don't work in
- conjuction with changes that someone else made. Keeping an eye on
- what goes by on the mailing list can help here.
-
-* When you're happy that your change isn't going to break anything,
- check it in. For a one-file change:
-
- $ cvs commit <filename>
-
- CVS will then pop up an editor for you to enter a "commit message",
- this is just a short description of what your change does, and will
- be kept in the history of the file.
-
- If you're using emacs, simply load up the file into a buffer and type
- C-x C-q, and emacs will prompt for a commit message and then check in
- the file for you.
-
- For a multiple-file change, things are a bit trickier. There are
- several ways to do this, but this is the way I find easiest.
- First type the commit message into a temporary file. Then either
-
- $ cvs commit -F <commit-message> <file_1> .... <file_n>
-
- or, if nothing else has changed in this part of the source tree,
-
- $ cvs commit -F <commit-message> <directory>
-
- where <directory> is a common parent directory for all your changes,
- and <commit-message> is the name of the file containing the commit
- message.
-
- Shortly afterwards, you'll get some mail from the relevant mailing
- list saying which files changed, and giving the commit message.
- For a multiple-file change, you should still get only *one* message.
-
-
-Updating Your Source Tree
--------------------------
-
-It can be tempting to cvs update just part of a source tree to bring
-in some changes that someone else has made, or before committing your
-own changes. This is NOT RECOMMENDED! Quite often changes in one
-part of the tree are dependent on changes in another part of the tree
-(the mk/*.mk files are a good example where problems crop up quite
-often). Having an inconsistent tree is a major cause of headaches.
-
-So, to avoid a lot of hassle, follow this recipe for updating your
-tree:
-
-$ cd fptools
-$ cvs update -Pd 2>&1 | tee log
-
-Look at the log file, and fix any conflicts (denoted by a 'C' in the
-first column). Next for every build tree you have pointing at this
-source tree, you need to update the links in case any new files have
-appeared:
-
-$ cd <build-tree>
-$ lndir <source-tree>
-
-Some files might have been removed, so you need to remove the links
-pointing to these non-existent files:
-
-$ find . -xtype l -exec rm '{}' \;
-
-And finally, re-configure to take into accound any changes in
-mk/config.mk.in.
-
-$ ./configure
-
-To be *really* safe, you should do
-
-$ gmake boot && gmake all
-
-from the top-level, to update the dependencies and build any changed
-files.
-
-
-General Hints
--------------
-
-* As a general rule: commit changes in small units, preferably
- addressing one issue or implementing a single feature. Provide a
- descriptive log message so that the repository records exactly which
- changes were required to implement a given feature/fix a bug. I've
- found this *very* useful in the past for finding out when a particular
- bug was introduced: you can just wind back the CVS tree until
- the bug disappears.
-
-* Keep the sources at least *buildable* at any given time. No
- doubt bugs will creep in, but it's quite easy to ensure that any
- change made at least leaves the tree in a buildable state. We do
- nightly builds of GHC to keep an eye on what things work/don't work
- each day and how we're doing in relation to previous verions. This
- idea is truely wrecked if the compiler won't build in the first place!
-
-* To check out extra bits into an already-checked-out tree, use the
- following procedure. Suppose you have a checked-out fptools tree containing
- just ghc, and you want to add nofib to it:
-
- cd fptools
- cvs checkout nofib
-
- or:
-
- cd fptools
- cvs update -d nofib
-
- (the -d flag tells update to create a new directory). If you just want
- part of the nofib suite, you can do
-
- cd fptools
- cvs checkout nofib/spectral
-
- This works because 'nofib' is a module in its own right, and spectral
- is a subdirectory of the nofib module. The path argument to checkout
- must always start with a module name. There's no equivalent form of
- this command using update.
-
-Ok, that'll do for now. If there's anything else you'd like to see in
-this file, just let me know.
-
-Simon Marlow <simonm@dcs.gla.ac.uk>
-
projects / ghc-hetmet.git / commitdiff