Hank HOWTO - Local Setup
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:
Development Philosophy
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
Step 1 - Edit Your "Dot" Files
Edit your .cshrc file. A representative .cshrc file is given below. You must set the CVSROOT and CLASSPATH environment variables and add the directories shown below to your path.
# 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"
Regarding LD_LIBRARY*_PATH Environment Variables
If you're using the LD_LIBRARY_PATH, or LD_LIBRARYN32_PATH variables, these are no longer needed to run the current version of Hank. In fact, these variable can produce problems with running the Hank code. If you do not have a need for these variables, it is suggested that you remove them from your .cshrc (or equivalent) file.Accessing the GNU m4 macro processor
Hank requires the GNU m4 macro processor. It is currently located in the directory /usr/divms/bin. You may have problems configuring the system if another version of m4 precedes the GNU version in your search path. You can redefine m4 by placing the following two of commands in your .cshrc file.
setenv M4 /usr/divms/bin/m4
alias m4 "$M4"
Step 2 - Check Hank out of the Repository
The version control software, CVS, will create a copy of Hank in your directory. There is a brief tutorial on CVS later on in this document.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!
Step 3 - Compiling and Running Hank
For compiling and executing Hank, please take a look at the HOWTOs:- Compilation Guide - details how to go about compiling hank.
- Running the Simulator - provides some information on how to execute hank.
Using CVS - A Brief Tutorial
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.
Obtaining Your Copy of the Source Initially - Checking Out
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
Updating Your Copy of the Source
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).
Updating the Working Copy - Merging
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:
- U <file_name> - The file was brought "up to date" with respect to the repository. This is done for any file that exists in the repository but not in your source, and for files that you haven't changed but are not the most recent version available in the repository.
- A <file_name> - The file has been "added" to your private copy of the sources, and will be added to the main source repository when you run "cvs commit" on the file. This is a reminder to you that the file needs to be committed.
- R <file_name> - The file has been "removed" from your private copy of the sources, and will be removed from the main repository when you run "cvs commit" on the file. This is a reminder to you that the file needs to be committed.
- M <file_name> - The file is "modified" in your working directory. 'M' can indicate one of two states for a file you are working on: either there were no modifications to the same file in the repository, so that your file remains as you last saw it; or there were modifications in the repository as well as in your copy, but they were "merged" successfully, without conflict, in your working directory.
- C <file_name> - A "conflict" was detected while trying to merge your changes to <file_name> with changes from the main repository. <file_name> (the copy in your working directory) is now the output of the rcsmerge command on the two versions; an unmodified copy of your file is also in your working directory, with the name '.#<file_name>._version_', where _version_ is the revision that your modified file started from. (Note - the .#* files may be purged automatically after a day or so, so if you need it make sure you copy it to another file)
- ? <file_name> - <file_name> is in your working directory, but does not correspond to anything in the source repository, and is not in the list of files for cvs to ignore (e.g. .o, core, etc...).
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.
Differences Between Files
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.
Sticky Tags and Dates
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.
Getting Around Sticky Tags
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)
Adding a File or a Directory to the Repository
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.
Adding a File
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).
Adding a Directory
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
Committing Changes to the Repository
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.
IMPORTANT NOTE:
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 source compiles and the executable runs correctly
- The changes will not interfere with others' development
The main moral here is to be considerate and communicate what you are doing with the others in the group!
Releasing Your Copy
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.
For More Information
- CVS Manual page - type "man cvs" at the command prompt
- CVS Tutorial (Postscript) - a copy of this exists in the lab (somewhere).
- CVS Documentation (Postscript) - a copy of this exists in the lab (somewhere).
- By all means, if you have any questions pertaining to our setup, using new CVS commands, or using basic CVS functionality, please feel free to send me e-mail.
Last Modified:
Please send comments or questions to The Hank Group
Copyright 1996 - The University of Iowa : Department of Computer Science