CONTENTS
OVERVIEW
How do I normally talk to CVS?
How do I set things up initially?
How do I add or remove files to/from an existing module?
Using CVS from machines with no AFS
----- First Time Installation (for the no-AFS case)
----- Normal Usage (for the no-AFS case)
gmake targets
I feel really brave! I want to add a module to the CVS repository!
CVS in general lets you work as a team, modifying common files without interfering with each other's work. The model is that there is a storage of all source files, along with their "history" (who changed what, when, and why). This is called a "repository". IN ADDITION, EACH DEVELOPER has a "working directory" (a hierarchy, actually). This could be a directory on the local machine, or on AFS, where you do work. What is important to remember is that the WORKING DIRECTORY IS NOT ~/g ANYMORE. Each person has his/her own set of directories in which they compile, make changes, and run things. We generally WILL NOT work all in one place like we are used to. [actually, this is the CVS way of viewing things; AUTON things will look slightly different, but don't worry about this right now]
How do I normally talk to CVS?
After things are set up, you basically have two CVS operations:
1) get the stuff that's in the repository onto your working directory. This means that whatever changes were made by other people to the common code-base (ah, software engineering terms) are incorporated into your local directory. This is done ONLY when you issue the right command (the point being that if somebody else made a change -- for good or bad -- you won't see it until you get the stuff to your working directory). This is usually done by typing "cvs update" when you're in the right directory.
2) put the stuff from your working directory into the repository. So from now on if anybody else gets stuff from the repository, they'll see your new stuff. Again, this only happens when you issue the right command. It is "cvs commit".
CVS commands generally work on the directory level (and recursively, on subdirectories). That is, you're either in "h/fastmix" and do "cvs update", or in "h/" and do "cvs update fastmix". You can do a "cvs update filename" if you want to to work on just one file (although this doesn't usually make sense for C source).
I suggest keeping these bookmarks handy for CVS reference:
http://www.loria.fr/~molli/cvs/cvs-FAQ/cvsfaq0.html
http://www.loria.fr/~molli/cvs-index.html
There are a lot of fun ways to exploit this model (eg, person #1's changes and person #2's changes collide. CVS will try to "merge" both changes, leaving it up to the human to edit the harder bits).
How do I set things up initially?
For you to use the AUTON lab CVS, here is what you should do:
0) Create the "g" symlink, if you haven't done so already:
ln -s /afs/cs/project/learn/group ~/g
1) Obtain Kerberos tickets. If you're on a CS-facilitized machine you should have them already. If you're on one of the non-facilitized lab machines type "klog" and then your Kerberos password.
2)
setenv CVSROOT ~/g/cvsroot
(better put that in your .login). If you're using bash the command
would be:
export CVSROOT=~/g/cvsroot
and you'll want it in your .bash_login.
3) decide on a working directory. It will have a similar structure to the ~/g directory, but it will be "yours". It can reside on AFS or local disk. In the following example I assume you chose the name "h" and that you're positioned in the directory under which you want "h" to be created.
*** you do not need to mkdir h by yourself!!! ***
*** ***
*** this example will checkout the module "kmeans". ***
*** substitute with your favorite ~g/ directory ***
4) do "~/g/localdir h"
4.5) NOTE: if this step fails for some reason, and you later retry it, you will have to manually remove the h directory first. The script does not remove it and does not put anything in it if it's already there, fearing it might overwrite something you care about.
5) do "cd h"
6) do "./localize-dirlib kmeans"
7) do "cd kmeans"
8) do "gmake"
well, you get the idea. ~/g/localdir should be run ONCE PER USER (or, maybe once per machine per user -- you can actually have many working directories, if you advocate schizophrenia). At this point you can "update" and "commit" as you please from the "kmeans" directory. I guess we'll all need an adjusting period to see what is a good frequency for this.
For each module you want to work on, run "localize-dirlib module" from your h directory. Note that the Makefile is smart enough to do this for you for the modules that your modules depends on (as listed in the "siblings" line of the Makefile).
If you get an error message, it might very well be the case that your favorite directory is not in CVS yet. Email dpelleg@cs and we'll get it fixed.
How do I add or remove files to/from an existing module?
To add files, do a "cvs add [file...]". You'll get a message saying that the files are scheduled for adding and will be at the next "cvs commit". So, do a "cvs commit" if you're in a hurry to see them incorporated into the module (or else wait till the next commit).
"cvs remove" is the inverse of this (and works similarly). You'll have to remove (or hide) the file in your working directory first. Note that CVS can undo removes.
Using CVS from machines with no AFS
First Time Installation (for the no-AFS case)
make sure the following are installed on your machine:
ssh
cvs
1) Copy the contents of gmake-magic on your OFFICE machine to some directory /home/user/delme on your HOME machine. By "copy" I mean getting the bits across without using CVS. You can use scp, HTTP, anonymous ftp (or regular ftp, and change your password afterwards), sneaker-net, whatever.
2)
setenv CVS_RSH /home/user/delme/tunnel_afs
or, for bash:
export CVS_RSH=/home/user/delme/tunnel_afs
3)
setenv CVSROOT :ext:@OFFICE:/afs/cs/project/learn/group/cvsroot
or, for bash:
export CVSROOT=:ext:@OFFICE:/afs/cs/project/learn/group/cvsroot
Note OFFICE stands for the name of your office machine, and that you should have valid AFS tickets on that machine whenever you perform CVS operations. An easy way to achieve this is to login to that machine, and leave that session open. The CVS operations will "attach" themselves to the token used in that session, so you will have access to the CVS files (which are on AFS). Example:
setenv CVSROOT :ext:@gs999.auton.cs.cmu.edu:/afs/cs/project/learn/group/cvsroot
Note that for now OFFICE should be a Linux machine (there's a binary somewhere in there, and I only bothered to compile it for Linux). Let me know if this causes a problem as it can be easily fixed. The "home" machine, on the other hand, doesn't need to be Linux.
4) (at your home machine do) delme/localdir h
[well, this looks very much like the "normal" way things work already]
5) If all went fine, you have a directory h/ and h/gmake-magic that were just checked out from CVS. You can cd to h/, do "./localize-dirlib foo", and "gmake localize" in h/foo.
6) Now you can safely remove delme/.
Normal Usage (for the no-AFS case)
(better put this in your .login)
setenv CVS_RSH /home/user/h/gmake-magic/tunnel_afs
setenv CVSROOT :ext:@OFFICE:/afs/cs/project/learn/group/cvsroot
Alternatively, if you're using bash the commands would be:
export CVS_RSH=/home/user/h/gmake-magic/tunnel_afs
export CVSROOT=:ext:@OFFICE:/afs/cs/project/learn/group/cvsroot
and you'll want them in your .bash_login.
That's about it --- all cvs commands should work the normal way.
One last tip. You may want to check out ssh-agent. If you set it up right, you don't have to type in your password every single time, which ought to be a relief. In fact, I don't even know if the above procedure works unless you use ssh-agent. I'll come up with instruction how to do that if people ask.
Some gmake targets to help with CVS stuff:
"gmake status"
This will list the CVS files in the local directory that are
out of whack with the repository (due to changes in either one).
"gmake status-all"
This will do the same for *all* directories under h/ (or whatever your
local equivalent it). You still should activate it from a work directory
(eg, in h/kmeans). It will not work when invoked in h/ (as won't any other
gmake command).
"gmake cleansibs"
This helps to ensure re-compilation after a big fat cvs update.
I feel really brave! I want to add a module to the CVS repository!
Just use the CVS "import" command. We'll work through an example in which we put the module "cpuhog" into the CVS repository. Note: normally other people will do this for you so you probably don't need to read this. We assume that the files are in ~/g/cpuhog (although it will be similar if they're elsewhere).
> cd ~/g/cpuhog
> cvs -n import cpuhog AUTON INITIAL
This doesn't do the work yet --- just acts "as if".
The reason for not actually putting stuff in yet is because not everything is fit to CVS. In general, if a file can be easily generated from other files, or if it's a binary file, or if it's rarely modified, there is a good chance it shouldn't be in CVS. In particular, we're trying to avoid placing the following stuff in CVS: machine-specific binaries, PS/dvi files compiled from TeX (assuming the TeX source is in CVS) backup/ directories and temporary files.
The "cvsignore" file is just the default list of things to ignore when inserting things into CVS (I already added to it the architecture-specific prefixes, latex residues, data, backup, and temp). "-I xxx" just adds to that list.
Look at list with I,N,L markings from the "cvs -n" above to see what you want inside is inside and conversely. "N" means this file will be included in the module. "I" means this it will be "ignored". Suppose you're not happy with the file busywait.saved.by.paul.c and you don't want it in CVS. Do:
> cvs -n import -I busywait.saved.by.paul.c cpuhog AUTON INITIAL
you can repeat -I arguments (-I this -I that). Wildcards allowed (escape them!).
Once you're happy with the list, do:
> cvs import -I busywait.saved.by.paul.c cpuhog AUTON INITIAL
This actually puts the stuff in. You will be ask for a short description of the module.
Note, that this procedure does not yet create a working version of the cpuhog directory you can comfortably work in. You'll need to do:
> localize-dirlib cpuhog
in your ~/h directory first. If the original cpuhog you just imported is already in the ~/h directory, move it out of the way first.
In general, "cvs -n xyz" means "do cvs xyz, but Not really -- just tell me what the output would be like".
More info is in the CVS manual (links above).