This document pertains to setting up the Hank development environment under your home directory. These procedures apply only to those members of the hank development group.
Last Update:
We have set up the Hank development source code under the CVS (revision control) system . Under this system, the main repository for the Hank code exists in a central location with working copies existing in each user's home directory. The reason for this is simplicity. Each user has their own local copy of the entire Hank code and can make changes, experiment, or simply use the code without affecting the other users. This protects other users from accidental file over-writes, deletions, etc... However, this will not protect us from all problems. We must communicate! We are a team! If you make drastic changes to the source, please talk to the other users that may be affected by the change. CVS has the ability to take care of trivial issues, but it will not protect us from all software development problems, so make sure you communicate what you're doing!
We also use autoconf and automake for managing the Makefiles, compilation, and source code directories. If you are unfamiliar with autoconf, or automake, you may want to browse the info pages on these tools.
info autoconfAlternatively, you can also browse the free, online book published by the authors of these valuable tools. The online book is GNU Autoconf, Automake, and Libtool. It's also known as the "The Goat Book".
info automake
# Example Hank .cshrc file
# KEEP THESE TWO LINES FIRST (important for U. of Iowa CS users) !!
source /etc/CSHRC
source /group/yoyo/aliases
# THESE NEXT TWO LINES ARE REQUIRED FOR HANK
setenv CVSROOT /space/hank/CVSRoot
setenv CLASSPATH /usr/pkg/antlr/2.6.1/jar/antlr.jar:"$CLASSPATH"
setenv M4 /usr/divms/bin/m4
alias m4 "$M4"
Another excellent source of information about CVS is through the manpage.
man cvs
You can now also find out much detailed information about CVS through
a free, online book: The CVS Book.
The lastest version of Hank is called hank in the CVS repository (older versions of Hank are referred to as hank-sim). Thus, your first command (executed from your home directory, or any directory owned by you) should be:
cvs checkout hank
That should be all the setup that is required in order to use CVS for this project. However, if you do encounter any error messages, or run across any problems while using CVS to obtain, check in, or update the Hank source code, feel free to get in touch with Pete Willemsen for assistance. Please make sure you've read the tutorial, as well as the man page first!
For more in depth information about cvs, try one of the following links:
- CVShome.org
- CVS Tutorial (Postscript) - a copy of this exists in the lab (somewhere).
- CVS Documentation (Postscript) - a copy of this exists in the lab (somewhere).
- The CVS Book - a free, online book all about CVS. Probably a good strarting point if you're interested in finding out about the full power of CVS.
The CVS executable is cvs, and takes many options that correspond to performing different actions in the CVS system. All work you will probably do will be through the options of the cvs command.
The idea behind cvs is that each user can have their own "working" copy of the source code in their directory. You obtain this copy by "checking out" the source from the main repository. After you make changes to the repository, you "commit" your changes back to the repository. When you hear of changes made to the repository, you "update" your working copy. Finally, when you are done using the source, you "release" your working copy from your directory. This is a very quick overview of how cvs works. In the following pages, the details behind these actions will become more clear, hopefully. I have prefixed areas detailing information that I find important to know with IMPORTANT NOTE.
Cvs also maintains revision numbers for the files under it. That way, we are able to maintain a "history" of changes to the source. If we ever need to go back and undo some set of changes, it will be much easier than if we were not using cvs. Thus, when you the cvs commands you will periodically see revision numbers associated with the files; when you commit changes to a file you will notice that the revision number will increase by 1, for instance.
To obtain a development copy of the source for the Hank project use the CVS command:
cvs checkout hank
The above command will place a directory called hank filled with the entire source code for the Hank project.
IMPORTANT NOTE - When you perform a checkout with cvs it will create a special directory called "CVS" in each of the sub-directories contained in the hank source code tree. This directory and the files contained within it are used to track revision information about your copy of the hank code. It is important that the files in this directory not be deleted or modified. Similarly, it is important that the "CVS" directory not be deleted.
However, if you plan on using Hank only for your personal research and development and either do not need to submit updates or receive updates through the cvs system, you can perform an export command. Note that once you've done the export you cannot use any of the other cvs commands on that copy of the source. Exporting the source removes the ability for you to participate in development.
cvs export [-rRELEASE_NUMBER] hank
Note: if you just want to export the most recent copy, use the following command:
cvs export -rHEAD hank
Every now and then you will need to update your local copy of the Hank code. You will most likely do this after hearing from other development members that a change has been made to certain parts of the code and it would be beneficial to update your copy. To make this update, you first will need to be in the top level directory of your copy of the Hank code. For example, I have my copy of Hank located in my Research directory (your copy of Hank can be anywhere you like).
cd
cd Research/hank
Once in the hank directory, you can update ALL of your code by the following means:
cvs update
which will proceed to parse the hank directory structure updating and merging any files that have changed, or that differ from the repository files. See Merging for more information on what happens when files are merged.
Note that this will update any files that are different! You may not want to make such a change to your copy. In order to update specific files you will need to change directories to the location of the file that you wish to update. You can then update that file by the command:
cvs update <filename>
which will update only the filename you give as an argument.
Futhermore, it is possible to restrict the update to a single directory by the command:
cvs update -l
This does an update in whatever directory you are currently in but does not descend into any subdirectories. The "-l" option can be used with most cvs commands and prevents cvs from being recursive.
Occasionally, new directories will be added to the hank source tree. When you see notice of this and plan to do an update, it will be necessary to use another option of the cvs update command. For instance, if you have heard that there is a new subdirectory in hank/doc/, you can change directories to the doc directory and issue the following command:
cvs update -d
You can also use the update command to remove sticky information. See Sticky Tags and Dates for more information (the man page provides more explanation of sticky tags).
The update command keeps you informed of what it's doing by printing a line for each file, prefaced with one of the characters {U A R M C ?} to indicate the status of the file:
If you have difficulty performing conflict resolution on some files you attempted to update, but received the conflict message, I urge you to read the manual page for cvs.
If you have need to do a "diff" between your working copy of a file and the repository's copy, you can use the "cvs diff" command to do this. Note, however, that the cvs diff command may not do exactly what you think it should do. Whereas all other cvs commands (update, commit, etc...) work on the HEAD of the development tree, the cvs diff command will compare your file with the repository version it came from.
Say you obtained your copy of "our_code.c" when it was at revision 1.2, and since then four changes have been made by other people in the group. Thus, the current revision number of "our_code.c" is at 1.6. You decide to update your copy of "our_code.c" but first you want to see what changes were actually made. When you use cvs diff our_code.c to find the changes, it reports back nothing. The reason for this is that it compares your copy with the revision it came from and thus there really were no differences between your copy and revision 1.2 since they are the same (if you would have made changes to your 1.2 version, these would show up).
To get cvs diff to compare your files with the most recent you should use the following command:
cvs diff -rHEAD <file_name>
The "-rHEAD" option tells cvs to use the head of the development tree to when comparing the two files rather than the version your copy came from.
IMPORTANT NOTE - Supposedly, the cvs diff command DOES NOT alter the working directory, and thus no stick dates should be set. If anyone can contradict this, please tell me and I'll change this document to reflect it. I am going by the manual until I hear otherwise.
In cvs, when you use the "-r", or "-D" option with certain commands, cvs changes its notion of how you want your files. It sets what is called a sticky tag, or sticky revision in one of those "CVS" directories. What basically happens is that the next time you do a cvs update or cvs diff cvs will use the sticky date, or tag, to perform the update, or the diff, thus causing you problems and headaches. "Sticky" options will restrict how 'cvs update' operates until you reset them. The sticky date, or tag would be useful if we were setting up different development branches, or if certain people were working on Hank, version 1.9 while others were working on the new ultra-modern release Hank, version 3.0, for instance.
To get around this sticky problem, you may first want to view the files where sticky tags are actually set. To do this, perform the command:
cvs status <file_name>
As with most cvs commands, if you do not specify a file, cvs will recursively do a status report on ALL files. This is ok since the status command does not change your copy of the files at all.
The status command will report to you all sticky tag information for a file, including revision numbers, and whether the file has been modified. This command is useful to see what the potential effect of doing cvs update would be. Here is a sample output (from old hank-sim development work):
corn:[9:32am]% cvs status common_def =================================================================== File: common_def Status: Needs Merge Working revision: 1.8 Fri Mar 28 16:56:26 1997 Repository revision: 1.9 /space/hank/CVSRoot/hank-sim/common_def,v Sticky Tag: (none) Sticky Date: (none) Sticky Options: (none)
If a file has sticky information associated with it, your will notice that the Sticky Tag, or Stick Date will have something denoted next to them other than "(none)". If this is the case, you can use the update command to clear the sticky information. To clear sticky information on a file, use the following command:
cvs update -A <file_name>
Here's an example where I have a sticky date set and I clear it using the update command.
corn:[9:38am]% cvs status simple_4way.flt =================================================================== File: simple_4way.flt Status: Locally Modified Working revision: 1.1 Thu Apr 10 16:06:53 1997 Repository revision: 1.1 /space/hank/CVSRoot/hank-sim/data/flt/simple_4way/simple_4way.flt,v Sticky Tag: (none) Sticky Date: 97.06.20.20.09.41 Sticky Options: (none) corn:[9:38am]% cvs update -A simple_4way.flt M simple_4way.flt corn:[9:38am]% cvs status simple_4way.flt =================================================================== File: simple_4way.flt Status: Locally Modified Working revision: 1.1 Thu Apr 10 16:06:53 1997 Repository revision: 1.1 /space/hank/CVSRoot/hank-sim/data/flt/simple_4way/simple_4way.flt,v Sticky Tag: (none) Sticky Date: (none) Sticky Options: (none)
Sometimes you will need to add a file, or maybe even a whole directory to the Hank directory structure. In order to do this you will need to inform CVS of the change that you made so it can add the file/directory to the repository.
To add a file to the Hank structure you simply create the file, place in it whatever you would like and then proceed to tell CVS about the new file. This is done by the command:
cvs add filename
IMPORTANT NOTE - if the file you plan to add is a binary file (e.g. a multigen model file) you need to use the following "cvs add" command.
cvs add -kb <file_name>
The add command proceeds to add the new file to the your repository structure. However, this will notcommit the changes to the main repository itself. In order to accomplish that you will have to commit the change to the repository (see Committing Changes to the Repository).
To add a directory to the Hank structure you will simply create the directory using mkdir and then tell CVS about the new directory. Unlike with adding a file, you do not need to perform a commit operation!
cvs add directoryname
To commit a change that you have made to a file, you will use the commit option of cvs. When you're satisfied that the changes you made to a file are correct and useful to others, you will commit the changes back to the main repository. Note that cvs commit will test whether an update is needed or not. If an update is needed the cvs commit command will fail and you will need to perform a cvs update. Committing a file is done by the following command:
cvs commit -m "Description of the modification" filename
For instance, if I had just got done modifying the file foo.c by adding a variable to keep track of time, and needed to commit the changes back to the repository, I would type the following:
cvs commit -m "Added variable to keep track of time" foo.c
The -m option requires a string that describes the change that you made to the file. If you leave off the "-m" option an editor window will pop-up prompting you for a note to leave in the log file.
Please be VERY careful when commiting files (especially in the beginning). Since there are several people working on this project, we may have problems if people commit files that do not work well with the rest of the system, or overwrite code that other people expect to be there. Always make sure that the following constraints are met before you commit something back to the repository:
The main moral here is to be considerate and communicate what you are doing with the others in the group!
When you have finished working on the source for sometime, you are preparing to leave, or planning on not working on the source, you can use the cvs release command to do the inverse of the checkout command. Releasing your code will help you determine whether or not all of your changes have been applied to the main repository. If you have files that need to be placed back in the repository, the release command will let you know and will give you the option to abort the release and go back and update those files.
The release command when used with the "-d" option will perform a release and then delete your copy of the source. I urge the use of this command over a command such as "rm -fr hank". To use the release functionality, change directories to one-level above where your copy of the hank code is located. For example, in my directory structure, I've checked the hank code into my Research directory:
cd ~/Research
cvs release -d hank
You may notice that release reports back to you that you have a bunch of binaries, Makefiles, or so_locations files that are not in the repository. These generally can be deleted without harm. The one exception is when you have modified a Makefile. If you know that you have explicitly modified a particular Makefile, you should abort the release and commit the changes to the Makfile.