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!
In order to setup your local CVS system so you properly access the Hank files, you must add an environmental variable. For csh, or tcsh users, you'll need to edit your .cshrc file by adding the following lines:
setenv CVSROOT /space/hank/CVSRoot
setenv LD_LIBRARY_PATH /usr/lib:/usr/lib/libpfdb:/space/USERID/hank-sim/lib/iris4d
setenv LD_LIBRARYN32_PATH /usr/lib32:/usr/lib/libpfdb:/space/USERID/hank-sim/lib/iris4d
setenv LD_LIBRARYN64_PATH /usr/lib64:/usr/lib/libpfdb:/space/USERID/hank-sim/lib/iris4d
setenv HANK_DB_PATH /space/hank/hank-data/Development
Optional:
setenv TXTPATH /space/hank/hank-data/Development/textures
setenv FLTEXTERNPATH /space/hank/hank-data/Development/flt/models
setenv HANK_CFG_DIR /space/USERID/hank-data/cfg
If you are not able to use the setenv command (bash/sh/ksh users), you will most likely need to place the following line in your .profile file:
export CVSROOT=/space/hank/CVSRoot
export LD_LIBRARY_PATH=/usr/lib:/usr/lib/libpfdb:/space/USERID/hank-sim/lib/iris4d
export LD_LIBRARYN32_PATH=/usr/lib32:/usr/lib/libpfdb:/space/USERID/hank-sim/lib/iris4d
export LD_LIBRARYN64_PATH=/usr/lib64:/usr/lib/libpfdb:/space/USERID/hank-sim/lib/iris4d
export HANK_DB_PATH=/space/hank/hank-data/Development
Optional:
export TXTPATH=/space/hank/hank-data/Development/textures
export FLTEXTERNPATH=/space/hank/hank-data/Development/flt/models
export HANK_CFG_DIR=/space/USERID/hank-data/cfg
Note: The last three variables have nothing to do with CVS but are used by the run-time environment, as well as the MultiGen modeler. If you already have a LD_LIBRARY_PATH environmental variable, you will just need to concatenate the string ":/usr/lib/libpfdb" onto the end of your current variable setting
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.
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 you currently need to go to your top level directory and use the CVS command:
cvs checkout hank-sim
The above command will place a directory called hank-sim filled with the entire source code for the Hank project. For the time being it is important to checkout the Hank code in your top level directory since we have Makefiles that assume this. I realize that this is a bad design and should be corrected. It will be fixed, eventually, and after such time, you should then be able to perform a checkout into any directory you wish using the same command as outlined here.
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-sim source code tree. This directory and the files contained within it are used to track revision information about your copy of the hank-sim project. 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-sim
Note: if you just want to export the most recent copy, use the following command:
cvs export -rHEAD hank-sim
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 the top level directory of my account.
cd
cd hank-sim
Once in the hank-sim directory, you can update ALL of your code by the following means:
cvs update
which will proceed to parse the hank-sim directory structure updating and merging any files that have changed, or that differ from the repository files. See Merging
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. If you have heard that there is a new subdirectory in ~/hank-sim/data/flt, you can change directories to the flt 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
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. Also, feel free to contact me (Pete) as I will be glad to help you understand the output of the conflicted merge.
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.
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:
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. 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-sim". To use the release functionality, use the following:
cd ~/
cvs release -d hank-sim
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.