Author: Blaine Simpson. [email protected]
$Revision: 1.6 $
The software which is referred to in this document and which is hosted on the admc.com web site, is distributed for free according to the Gnu Public License.
IMPORTANT! Before adding any WSAD projects to CVS, make sure that you have named the directories correctly. See the porting howto at http://admc.com/blaine/howtos. Pay particular attention that the source directories should be named source for Java projects, and JavaSource for Web projects.
BEFORE you check out or commit any project/module, go to Windows / Preferences / Team and make the following settings.
The WSAD/Eclipse Team plugins follow the CVS convention that
$Revision$ in the source file. When you commit
it, and upon all future checkouts and updates, $Revision$ will be replaced
with the appropriate revision number.
In Javadoc comments, keywords can save a lot of work, and increase accuracy and consistency. For your class Javadoc header, instead of typing in your name for Author, the data and revision number, you cut and paste a boilerplate with the appropriate keywords.
The available keywords are listed at http://www.linuxselfhelp.com/gnu/cvs/html_chapter/cvs_17.html#SEC78.
To add a new WSAD project to CVS, you will add a new CVS module. Be aware that you can not just right-click on the PVCS module and do Team/Share.... We have restrictions in place so that you can only upload a project if a CVS Administrator has created and set up the module directory on the CVS server.
I give instructions on how to accomplish these tasks using the command-line interface to CVS. If you use some graphical CVS tool, it is up to you to figure out if and how to accomplish the same CVS operations using your tool.
Make sure to export the env variable CVS_RSH and set it to the value
ssh. This tells CVS to use ssh instead of rsh to
communicate with the CVS server host. Besides encryption (which I don't
think we need), ssh allows us to authenticate in a secure manner without
having to type in a password each time (this is not possible in a secure
manner with rsh).
If you don't enjoy entering your password time after time after time, then set up your ssh keys so that you can ssh into your CVS reposiroty host without supplying a password. If that works, the commands in this section and the My CVS Scripts section should not prompt you for a password.
If you get error messages about ssh and libraries, check if you have a crazy setting for LD_LIBRARY_PATH. In most cases, the only thing you should have in your LD_LIBRARY_PATH is $ORACLE_HOME/lib. (The Iplanet build environment files are known to do nasty things to the LD_LIBRARY_PATH).
If you are going to be using CVS at the command-line, memorize these idioms:
If you are familiar with RCS, be aware that, unlike RCS, CVS switches that take arguments usually require whitespace (i.e., an additional argument) after the switch itself (see the use of the -m switch a few lines down). Exceptions to this rule are the -k and -r switches, which usually work better for CVS without whitespace.
Commands that every developer must know.
Be aware that the CVS commands need to know where the repository root is. This is accomplished in a few different ways. Most cvs commands use a file in the CVS subdirectory of the current directory to find the location. The checkout and Remote commands (like rtag and rlog) will use the same method as above if you have a CVS subdirectory, otherwise you must use the -d switch or the CVSROOT env variable. (Beware that the precedences explained in the CVS documentation are not what I observe in practice). (My CVS scripts (explained in a section below) which do remote CVS commands use the env variable SCRIPT_CVSROOT.)
Tags are completely analogous to PVCS labels.
Do not use
cvs... commit... -r TAGNAME...
to check in file(s) and apply a static (non-floating) tag TAGNAME to the
checked-in version.
That works ok for floating tags (branches), but otherwise, TAGNAME
must be an existing tag, and the data you check in will assume that revision-
i.e. it will not move the tag to a different version.
(Note that HEAD is a floating tag, and the default behavior, if you
give no -r switch, is to make a new revision and apply HEAD to that revision).
If you want to check in something to head and apply a label
to it, then just do that. Check it in to head (with no -r switch), then use
"cvs tag" or "cvs rtag" to apply the desired tag to it.
(Of course, if you want to tag a file in some other branch, then use the
-r switch to commit to that branch, then run a tag command on that branch).
Example checking in a file and a directory branch, and tagging these resources.
cvs commit -m 'fixed a bug' file.txt subdir
cvs tag TAGNAME file.txt subdir
Many of the remote CVS commands take CVS module name(s) as argument(s). Often, we want to apply some command to all of the modules for a specific development project. Most critically, when working with tags, we need a way to specify the target resources more reliably (and easier) than typing in long lists of CVS modules and depended-upon jar files. We use module aliases to achieve this goal. In this section, I use the phrase traditional module to mean the normal CVS modules which have a physical directory branch rooted in the CVS repository directory, as opposed to a module alias.
Note that module aliases are named so because after a module alias is defined, it is used in remote CVS commands exactly as if it were a traditional module, but the contents of a module alias are not necessarily a module or modules. Module aliases often are a short-hand for just one (or more) artifact file(s) (artifact files = normal files under CVS control).
At any time, you can see the list of all the usable module aliases by
catting the file CVSROOT/modules under the CVS repository on the
repository host.
Since it is extremely important for users to understand exactly which resources are encompassed by a given module alias, we use the following naming convention to differentiate between the different types of aliases that we use.
Justification (skip this paragraph unless you want to know how we decided
on these conventions).
The normal convention for CVS is to use all-caps for tag names. Since we
do not want to be confusing tag names with module aliases, we use lower-case
for module aliases.
We use the hypen and dot characters, with specific suffixes, to indicate
the type of module alias.
We do not use slashes because we don't want our aliases to look like paths
(you can often append a path to a module specification, so that would get
really ugly).
Since we do not use dots in traditional module names, we decided to use the
dot-specifier to differentiate an alias for a specific file.
That is intuitive since if you ran a diror ls and saw a node
with a dot, you would assume that it is a file.
Since our traditional modules all contain the hyphen character, we use the
hyphen character for aliases which contain modules.
To differentiate module aliases from traditional module names, we use the
specific suffixes -ali and -all, which can never collide with our
base CVS modules (which are all named x-ear, x-ejb, x-web, x-java and x-jop).
See the Server-side CVS Administration section for instructions on how to add module aliases.
You could definitely do everything using only traditional module names, and skip module aliases altogether. I'll give an example to show why you probably do want to use module aliases.
A common task is to update a tag to the HEAD. Our example is to update the tag 'ATAG' for the EMT application. You need to make sure that every single artifact needed by your appliation build gets updated. If you depend upon coreEJB.jar, for example-- even though coreEJB.jar is not in any of your development modules, you still need to tag it so that the build procedure knows which version to check out when you do your UNIX build (which is why we say that it is depended upon).
Using traditional module names, the update command looks like this
cvs -d /cvs/cvsrepos -q rtag -F -a ATAG aisleCore-ejb catalog-ejb \
core-ejb/bin/coreEJB.jar coreFrameWork-jar corePresentation-jar \
emt-ear emt-ejb emt-jar emt-web ratePlan-ejb storeAccount-ejb emt-jop
Using module aliases, the update command looks like this
cvs -d /cvs/cvsrepos -q rtag -F -a ATAG emt-all
You create a new tag like this.
cvs -d /cvs/cvsrepos -q rtag NEWTAG emt-all
You update a tag like this.
cvs -d /cvs/cvsrepos -q rtag -F -a EXISTINGTAG emt-all
You have to use the -F and -a switches to update tags. See the man page if
you want to know why.
When committing adds of binary files, you must flag them as binary so that the files don't get corrupted when transferring them between different OSes. The -kb option to commit (or to cvs admin) flags a file as binary. Example.
cvs commit -kb -m 'A new jar file' file.jar
You don't have to worry about this from Eclipse or WSAD, since the plugin
sets the flag based on the filename extension.
Many CVS commands that use the -r switch are sticky. I.e., once
you use that command, future CVS commands in that directory (or upon that
file, etc.) will use that tag specification by default. For example, if
you run cvs co -r TAGX modulename, then any future "updates" done
within the checkedout "modulename" branch will apply to tag TAGX.
You need to understand this because when cvs.tag* property(s) are set in env.properties (the UNIX build environment file), the "co" target will checkout with the specified tags, and will therefore set sticky tags.
You can always view the sticky tags for a resource by using the
"cvs... status" command.
As explained elsewhere in this document, you should not attempt to
commit changes using a static (non-floating) tag.
Therefore, if you use the build script to check out your modules and
later wish to commit changes you make to that source, you will need
to clear the stick tag with cvs -q update -A (if you wish to
apply a non-HEAD branch, you'll also have to specify the branch tag).
These scripts reside at /global_tmp/bin on our developer servers at this time. It's likely that these will be moved to a more suitable location at some point (when that happens, I'll update this document).
Some of these scripts use the environmental variable SCRIPT_CVSROOT, so
export this variable and set its value to the location of your CVS
repository, for example :ext:nhqsnpr1:/cvs/cvsrepos.
(I suggest that you set SCRIPT_CVSROOT to avoid any possible conflict
with CVSROOT, but if you know what you are doing you can set CVSROOT
instead).
Change in behavior. These is no longer a default CVSROOT, you must set and export the SCRIPT_CVSROOT (or CVSROOT) env variable.
Read the part in the Traditional VCS client section about ssh.
allmods *-ear *-ejb *-jar *-web [*-jop]
If you give the -r switch, it will also list all files which do not have the tag (this includes files added after you added the tag).
It is usually most convenient to use this command with module aliases, like
nontips -r TAGNAME emt-all
This will list all differences between TAGNAME and the HEAD of all
artifacts used to build EMT.
This is the command to use to see what's been removed between two tags. If you want to see what's been removed between a TAG and the HEAD, then use the nontips script (explained immediately above).
It is usually most convenient to use this command with module aliases, like
rmed WAS_R2B WAS_R2C emt-all
This will list all EMT artifacts removed between WAS_R2B and WAS_R2C.
This section only describes my recommended OS-level Server-side Administration strategy. It does not describe user-level CVS Administration commands such as creating branches. Those items are covered elsewhere in this document. The work covered herein must be performed on the host which houses the repository you want to work with.
Whenever you edit files under the repository root, always use RCS (i.e., co and ci). See the man pages for co and ci at http://linuxcommand.org/man_pages/co1.html and http://linuxcommand.org/man_pages/ci1.html. Remember that RCS switches take trailing space in a manner exactly opposite to that of CVS. Whereas CVS takes a space after switches, like
cvs... commit -m 'blah blah...
RCS does not
ci... -m'blah blah...
Due to time constraints, I am describing only our normal, typical setup.
Any UNIX user in the OS group cvs may read the resources in any CVS module.
For a UNIX user to be able to update (add, remove, modify) resources in a CVS module, some (any) OS group to which they belong must be listed in the file scripts/modulegroup.list under the CVS repository root.
For a UNIX user to be able to perform OS-level CVS Administration (i.e., add new modules, grant and revoke privileges), they must be in the OS group "cvsadm". To perform this work, the user runs the command
sudo.alt su - cvs
All of the OS commands below should be performed as the user cvs.
cd /the/repos
mkdir new-ejb new-web
chown cvs:cvs new-ejb new-web
chmod 0775 new-ejb new-web
chmod g+s new-ejb new-web
(Our version of Solaris can't handle chmod 02775).
scripts/modulegroup.list
according to the comments in that
file (see the description about modulegroup.list above).
Remember to check it back in with ci.
newAccounting.jar -a new-ejb/bin/accounting.jar
newAdding.jar -a new-ejb/bin/newAdding.jar
# Adding newAccounting.jar onto dependencies for the EMT project:
emt-all -a emt-ali storeshared-ali coreEJB.jar newAccounting.jar
The names for aliases for files should contain a dot so users can easily see
that it is an alias for a file and not a module.
The name must make it obvious what CVS module the file comes from, in order
to avoid confusion and future name collisions.
The value of these aliases is a relative path from the repository root
directory.
# Adding alias for application "new".
new-ali -a new-ejb new-web
The name should end with -ali so users can easily see that it is a simple
(non-nested) alias for module(s).
Note that we list only CVS modules, not file aliases nor other aliases,
in -ali aliases.
new-all -a new-ali storeshared-ali coreEJB.jar
The name should end with -all so users can easily see that it is a nesting
alias for all the resources needed for our application.
modules file back in with ci.