From 8b935dd5c2679476b47543c48b5a65ec11b6ba24 Mon Sep 17 00:00:00 2001 From: simonm Date: Tue, 7 Apr 1998 11:22:41 +0000 Subject: [PATCH] [project @ 1998-04-07 11:22:41 by simonm] remove old CVS Cheat Sheet. New one is in docs/cvs-cheat-sheet.html. --- CVS-CHEAT-SHEET | 265 ------------------------------------------------------- 1 file changed, 265 deletions(-) delete mode 100644 CVS-CHEAT-SHEET diff --git a/CVS-CHEAT-SHEET b/CVS-CHEAT-SHEET deleted file mode 100644 index 42b47dd..0000000 --- a/CVS-CHEAT-SHEET +++ /dev/null @@ -1,265 +0,0 @@ -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 -). - -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 @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:@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 - - You can call the fptools directory whatever you like, CVS won't mind. - - $ cd - $ 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 - - 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 .... - - or, if nothing else has changed in this part of the source tree, - - $ cvs commit -F - - where is a common parent directory for all your changes, - and 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 -$ lndir - -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 - -- 1.7.10.4