CVS is the GNU revision control system. Files (e.g. source code modules) under the aegis of CVS are archived in a data bank. All old versions are kept, and may be restored as necessary. However, CVS is not fascist in its control, meaning that for it to work, everybody has to be aware of it and agree to use it.
The "official" version of any software is kept in a repository hidden away by CVS. You can "check out" a copy of the official version for your own use. This, in fact, is what happens in $DEEPHOME/idlpro. That directory has all of the relevant IDL source modules from our CVS IDL repository. To make a new copy of something in the repository, you check it out. If you then edit it, and you want to make the changes available to the rest of the world, you have to "commit" those changes from your checked out module. You can "update" your version to be the same as the most current version in the repository.
In general, you should not directly edit files in $DEEPHOME/idlpro. Use only CVS to update files in that directory, and everything will be kept clean and manageable.
To use the Deepsearch CVS repository, add this line to your .cshrc:
setenv CVSROOT $DEEPHOME/master
If you are going to edit any of the source modules we keep in the CVS repository, you should make yourself a directory where you are going to keep your checked-out copies of the source files. My understanding of CVS is incomplete, so I don't really know the restrictions on the naming of this directory. However, wherever you put this directory, I believe that things will work if you name it "idlpro". For instance, the directory I use for this purpose is "~/idl/idlpro".
You can then check out source modules to edit with the command:
cvs checkout idlpro/filenameSo, for instance, if you decided that you needed to modify tracker to make it stop working, you would check it out with:
cvs checkout idlpro/tracker.pro
Once you've checked out a file, it's now your copy, and you are free to edit that copy as much as you want. However, there are some things to be aware of.
If you checked out a source file a long time ago, it's possible that somebody else changed it since you checked it out. You might want to make sure you have the latest version before you start doing your own edits. To do this, move into your own "idlpro" directory where you have your checked-out copies of whatever source modules, and use the command:
cvs status filenameLook at the "Status" to the right. If it says "Up-to-date," then your version is the same as the reversion in the repository, and you are ready to go. If it says "Needs Patch," then somebody has changed the repository since you last checked out or updated this source file. If it says "Locally Modified," then you've already editied the bastard since you last comitted your changes. IF it says "Needs Merge," then both are true, and you are probably in for a fair amount of work, depending on whether or not you understand CVS better than I.
If your source module Needs Patch, you may update it with the command:
cvs update filenameIf all goes well, the command will return the letter "U" followed by filename. If all doesn't go well, then there are changes which need to be reconciled; a number of things could indicate this, one of which is the letter M followed by filename. If any of this happens, worry and ask for the advice of others, unless you know what you are doing. (Hint: the cvs diff command may be helpful.)
When you've edited the source module, have used it yourself in IDL for some time, have debugged it, and are satisfied that you are ready to inflict your changes upon the rest of the group, you must first commit your changes the repository, and then you must update the version of the file that everybody else uses.
To commit your changes to the repository, go into your own "idlpro" directory where you have your checked-out source files. Issue the command:
cvs commit filenameThis saves it in the repository. It does not necessarily make that the version that everybody else will use.
To update the version which everybody else will use, go into $DEEPHOME/idlpro and issue the command:
cvs update filenameSee the previous section on updating your own copies of the source files for information on the success of this. Note that if the command is not successful, you are left with a corrupted source file in $DEEPHOME/idlpro. This can make abolutely everybody else in the group very sad. You should as soon as possible get a working version back in $DEEPHOME/idlpro using CVS. (More information on this to be added to this documentation file later.)
The way the IDL path is set up, if you have a version of a source file in "~/idlpro" or "~/idl/idlpro", that one will be used rather than the version in "$DEEPHOME/idlpro". This is fine when you are editing your own changes. However, if somebody else finds and fixes a bug in something, it is important that you start using the new version. This is especially true if it the bug is in someting like freduceimage.pro or ftransimages.pro which saves information to the database. If you are running an old version of the software and saving things to the database that have problems, those problems could continue to propogate through the group's work for some time to come.
There are a number of ways to avoid this trouble:
The command cvs log is entertaining because it shows you the comments which people typed to CVS as they committed the previous versions of the source file to the repository. man cvs may or may not further enahnce your understanding of the concept
NEVER, EVER use the commands "cvs commit *" or "cvs update *", unless you really know what you are doing, which you don't. (I certainly don't know what I'm doing well enough to use either of those commands.) "cvs status *", however, is one whose use is encouraged.