PLEASE and CVS Examples

The user can either select from the hyper-list of available commands immediately below (to cut to the chase), or read on for a description of the 'please' utility and E895's TAS3 code repository.

A Brief Introduction

This document presents examples illustrating the use of both the 'please' script and its underlying CVS application. The CVS source-code repository for TAS3, installed in LBNL UNIX user e895cvs's working area, has been set up with the implicit assumption that files in that repository will be accessed via these two tools. (While this has little to do with the source code itself, it is built into the makefiles.)

The steps outlined in this document present a sample exercise of both the 'please' script and a few other useful CVS commands. They by no means present an exhaustive list of the features of CVS. Furthermore, they are not necessarily the final word on the utilization of these utilities, but should provide a nice avenue for the beginner to learn the basics.

Conventions in this document are as follows:
Descriptive comments or directives to the user are typed in standard font.
UNIX command-line input AND 'please'/CVS responses are typed in typewriter font.
Command verbs (to either 'please' or CVS) are typed in UPPER ITALICS.

Syntax for 'please' has been designed to be as friendly as possible; the user must always "say please" (after all, UNIX can sometimes seem such a harsh environment ;-) All commands sent to 'please' have the following format:
please VERB [mod/file name]

If the user simply wants to see available commands, the VERB argument can be omitted. However, all other cases require a VERB. Not all VERBs require a mod/file name argument. Those that do will remind you, if none is given.

Setting It Up...

The Central CVS Repository is located in the directory ~e895cvs/TAS3 as viewed by any LBNL machine running NFS (e.g. sseos.lbl.gov, rncus1.lbl.gov, rncus2.lbl.gov). The "local" user should source the script file called setup_CVS which is found there. This will load some necessary modules and define the environment variable CVSROOT to point to this directory. The user should then copy 'please' from this directory into the directory ABOVE which he/she intends to work on TAS3 (e.g. cp ~e895cvs/TAS3/please ~), and set protections so that it is executable (chmod 554 ~/please).

NOTE:
ALL users who intend to use please or CVS will have to load the CVS and RCS modules (module load cvs ; module load rcs) in their .cshrc initialization files. Although these commands are issued in the setup_CVS script, the "modules" environment (PATH, and the like) is effectively "reset" when the newgrp command is given, reverting to the user's .cshrc-defined values.

Remote Users:

The TAS3 code is available via FTP (username e895, call if you do not know the password) on LBNL UNIX machines (e.g. sseos.lbl.gov, rncus2.lbl.gov). A distribution directory (~e895/TAS3_dist, which is a symbolic link to ~e895cvs/TAS3/dist) holds a complete copy of the contents of the repository (including 'please').

This directory is automatically updated at 2:00am (PDT) every morning by a background job called TAS3_chron (whose scripts are also stored in the distdirectory). While TAS3_chron is updating the dist area, the directories will be made un-readable (to avoid distribution of mixed versions). When this is the case, an additional file (dist.LOCK) will appear in the CVS_TAS3 directory, beside the dist directory, to confirm the temporary lockout status. The time stamp on this file can thus indicate to a would-be user the time the update began. Complete update takes about 15 minutes.

VMS users will not be able to use 'please'. This is an unfortunate oversight. Changing 'please' from csh-driven to perl-driven would fix this, but... these things take time. Furthermore, the makefiles (e.g. tpc.make) assume that they are being called by please. To compensate for this, the user can still use the makefiles if he/she:
1) defines the following logical: define UNIXflavor VMS,
2) locates all necessary include files in the current directory for the compilation of each module.
3) issues the "make" command: mms/descrip='mod'.make (where 'mod' is any valid module name, e.g., tpc, gen)

UNIX users may also want to maintain their version of the code in a "remote repository". 'Please' can set up a repository structure (see Initialize) if the user chooses to do so.

Warning:
Creation of a remote repository is NOT A SUBSTITUTE for maintaining the Central Repository (at LBNL)! It is only a tool for allowing multiple users of ONE institution to maintain consistency. Changes to remote repositories MUST BE PROPAGATED back to the central repository for appropriate distribution to the collaboration.

And now, PLEASE and CVS Commands:

INITIALIZE, LIST, HELP

Starting up your CVS working area

Setup CVS_TAS3 configuration:
source ~e895cvs/TAS3/setup_CVS

Go to the directory ABOVE where you want to create your working directory This example will assume that your working directory branches off your home directory. 'please' will create a subdirectory here, later.
cd ~

Get a copy of 'please':
cp ~e895cvs/TAS3/please .

INITIALIZE (set up) a working directory and/or CVS repository
please initialize
If you do not already have a TAS3 directory, say "y" to the first question
If you are not working with the LBNL CVS repository, say "y" to the second question

NOTE:
If you want to set up a REMOTE repository, then at this point you could execute the command: cvsinit

View the HELP list of available commands
please help
Alternatively, 'please' alone will also bring up the list of commands.

NOTE:
Executing the 'please' script will run the user's .cshrc script when it commences execution. If you have lengthy startup procedures, you may want to ensure that there are proper checks which prevent them from being run twice in the same session (the shell environment is already inherited by the script by default)

To view the LIST of current modules that 'please' supports, issue the command:
please list
This will provide a LIST of module names with brief descriptions *might* look as follows: 
Module		Description
--------	------------------------------------------------
bin		'eosgx' binary linking directory
buildmk		Makefile generation utility (object libraries only)
daqs		I/O routines
eosg		EOS-specific Geant routines
exec		Executive library for buildmk utility
gen		TASGEN routines
musi		MUSIC-related routines
str		String-handling routines
sys		TAS-wide system routines
tpc		TPC analysis routines (hit/cluster/track finder)

CHECKOUT, COMMIT, INSTALL, RELEASE

Modifying existing modules
(use 'tpc' module for example)

NOTE: If you CHECKOUT a module, don't forget to RELEASE it!

Go to the TAS3 directory (assume it branches off ~)
cd ~/TAS3

CHECKOUT a module
please checkout tpc
This will place a CHECKOUT entry in the HISTORY file which contains: time/date, your name, module name, your working directory

Go into the directory created for this module
cd tpc

Edit your file
vi am_tpc.f

COMMIT your changes to the repository
please commit

NOTE:
This will conclude by bringing up your default $EDITOR to enter a descriptive message about what change you are COMMITing The editor will already contain lines which look like:
CVS: ----------------------------------------------------------------------
CVS: Enter Log. Lines beginning with `CVS: ' are removed automatically
CVS:
CVS: Committing in .
CVS:
CVS: Modified Files:
CVS: am_tpc.f
CVS: ----------------------------------------------------------------------
This footer describes the current directory ".", and lists all modified files, in case you forgot what you were doing... As indicated, these lines will not appear in the log, they are only a guide for the user.

Enter a few words about the nature of the change.
(CVS will supply your username and time/date in the log automatically)

NOTE:
If, at this point, you want to abort the COMMIT, then exit the editor WITHOUT SAVING THE FILE, and CVS will prompt you with:
Log message unchanged or not specified
a)bort, c)continue, e)dit, !)reuse this message unchanged for remaining dirs
Action: (continue)
You may then proceed as you see fit.

Now, INSTALL any modified object/binary files into the libraries too
please install

You will receive the following one (or two) prompts.
Install object files/libraries? ([y]/n)
Install binary files? ([y]/n)

You will only get the last prompt if you are in a directory which is known to hold binaries.

This will then copy (UNIX cp) all existing object files, object libraries, and binary files into the LIB/dist libraries. These libraries are NOT actually in the repository, but run parallel to it, providing an avenue for COMPILEing and LINKing.

After COMMITing and INSTALLing changes, then go "up" to the TAS3 directory, and RELEASE the module
cd ~/TAS3
please release tpc

You will be prompted with:
Do you want to delete this module too? (y/[n])
Answer.

NOTE:
For any case in which 'please' asks a question followed by (y/[n]) a carriage return will provide the answer encased in brackets.

You will be prompted (again) with:
You have [0] altered files in this repository.
Are you sure you want to release module `bin':
or...
You have [0] altered files in this repository.
Are you sure you want to release (and delete) module `bin':
Answer.

NOTE:
The [0] altered files DOES NOT mean that your change was not processed. It means that there have been no FURTHER changes to the module SINCE THE LAST COMMIT. (This is good!)

If you had made further (unCOMMITed) changes (or aborted the COMMIT) before releasing, the message would have appeared as:
M am_tpc.f
You have [1] altered files in this repository.
Are you sure you want to release module `bin':

After a successful release, CVS adds another entry into the HISTORY file, indicating that you no longer have possession of an active module

The module is now modified and safely back in the repository.

EXPORT

Obtaining a copy (READ ONLY) of repository files
(use 'tpc' module for example)

Go to the TAS3 directory (assume it branches off ~)
cd ~/TAS3

EXPORT a COPY of a current module
please export tpc

This will create a copy of the current 'tpc' module in the TAS3 area. You may do anything you wish to this directory (e.g. ftp, COMPILE, LINK). DO NOT ATTEMPT to return this copy of the module to the repository. Such an attempt will fail (but will not damage anything).

When you are done working with this module, delete it. (rm -r tpc)

COMPILE, LINK

COMPILEing object libraries and LINKing binaries

Go to the module you are working on.
cd ~/TAS3/tpc

COMPILE the objects
please compile

Now, if you are in a potentially LINKable directory (e.g. bin), then you can also LINK
please link

It's that simple

ADD, REMOVE, REBUILD

ADDing new files to, and REMOVEing existing files from, an existing module, and...
Automatically REBUILDing makefiles (for object libraries)

Go to the module directory
cd ~/TAS3/tpc

Make your new file
vi new_hit_finder.f

ADD it to the repository
please add new_hit_finder.f

You should get a message like:
cvs add: scheduling file `new_hit_finder.f' for addition
cvs add: use 'cvs commit' to add this file permanently

You must then perform a COMMIT (see above) in order to complete the new ADDition

If you want to REMOVE a file, the process is similar. Identify the file, and issue the REMOVE command
please remove old_hit_finder.f

You will be prompted with:
Files must be deleted before removal from CVS Repository.
Delete old_hit_finder.f now? (y/[n])
Answer.
Should you choose 'y', you will see the message:
cvs remove: scheduling old_hit_finder.f for removal
cvs remove: use 'cvs commit' to remove this file permanently

If you have ADDed or REMOVEed source files from a library directory (e.g. tpc, eosg... but NOT bin) then you will need to REBUILD the makefile (i.e. tpc.make)
please rebuild
This copies the current 'tpc.make' into 'tpc.make.bak' and writes a new 'tpc.make'

IMPORTANT:
If you REBUILD the makefile, then reCOMPILE with it to be sure that it COMPILEs properly

IMPORTANT:
If you have ADDed, REMOVEed, or REBUILDed files in a module, you must COMMIT (see above) changes to the repository for them to take effect.

IMPORT

Introducing a new module into the CVS repository
(assume new module name is 'newmod')

IMPORTANT:
This should only be done by user e895cvs (to preserve ownership of repository files), and e895cvs will require read/write permission within the 'newmod' directory

Change directory so that you are INSIDE the new module's directory
cd ~/TAS3/newmod

Issue the IMPORT command
please import

You will be prompted with:
Current directory must be INSIDE the new module.
Is this the new module? (y/[n])
Answer.

You will be prompted with:
Enter the name of the new module:
Answer.
newmod

You should then see something *like*:
Importing files...
N /home/sseos/us1/e895/CVS_TAS3/TAS3/newmod/aaa.f
N /home/sseos/us1/e895/CVS_TAS3/TAS3/newmod/bbb.f
N /home/sseos/us1/e895/CVS_TAS3/TAS3/newmod/ccc.f

No conflicts created by this import

Checking out 'modules' file...
U modules/modules
Committing new module name to CVS library...
cvs commit: Examining modules
cvs commit: Committing modules
Checking in modules;
/home/sseos/us1/e895/CVS_TAS3/CVSROOT/modules,v <-- modules
new revision: 1.3; previous revision: 1.2
done
cvs commit: Executing 'mkmodules /home/sseos/us1/e895/CVS_TAS3/CVSROOT'
Releasing 'modules' file...
New Import is complete.

NOTE: You will have to add this module name to the 'please' script
in order to access it. Please do so, and notify other users.

At this point, you will have to actually edit the 'please' script and enter the name of this new module in a few strategic places. The author apologizes for this inconvenience. Explicit instructions addressing what lines to change appear in the first few lines of 'please'.

cvs HISTORY, LOG, STATUS

Extracting useful accounting information from the CVS Repository

CVS keeps a HISTORY list of activity for each module, which contains entries for each time the repository was modified in any way. This includes CHECKOUTs, COMMITs, RELEASEs, and even more others.

To see which modules are currently checked out, look at the CVS HISTORY file:
cvs history [options]
This will respond with a line *like* the following
O 02/04 09:20 STONE TAS3/* =TPC= ~/TAS3/*
where the fields (and meanings) are: 
O		status (O=checked out, F=returned, M=modified, etc... see 'man cvs')
02/04		date of last activity
09:20		time of last activity
STONE		user who performed this activity
TAS3/*		location within the repository
=TPC=		module name (TPC)
~/TAS3/*	user's working directory

Some handy options are: 
-a		return information for ALL users
-e		return ENTIRE history (all past activity)
-m (mod)	return information for MODULE 'mod'

CVS does not MERELY store the times changes were made, but it also stores a verbal record of the nature of these changes. Each time a change is COMMITed to the repository, the user is prompted to enter a few lines about the nature of his/her changes.
To receive a listing of these LOG entries for any file (or module) in the repository, issue the command:
cvs log [filename]
If no filename is given, CVS will report all LOG entries for all modules and/or files in the current directory. This can get long!

A sample log (for the file: bin.make) *might* look like this:
RCS file: /home/sseos/us1/e895/CVS_TAS3/TAS3/bin/bin.make,v
Working file: bin.make
head: 1.3
branch:
locks: strict
access list:
symbolic names:
comment leader: "# "
keyword substitution: kv
total revisions: 3; selected revisions: 3
description:
----------------------------
revision 1.3
date: 1997/01/30 17:39:00; author: stone; state: Exp; lines: +0 -9
modified makefile to allow parallel linking structure
----------------------------
revision 1.2
date: 1997/01/29 21:39:51; author: stone; state: Exp; lines: +1 -1
modified the names of the include files
----------------------------
revision 1.1
date: 1997/01/29 19:00:55; author: stone; state: Exp;
Modified makefile structure to accomodate CVS repository
=============================================================================

This reports that the current version number (head) is 1.3 . There are three revisions on record (for versions 1.1, 1.2, and 1.3), and the associated comments are clearly seen.

The date, time, and author name is automatically added by CVS, so that when entering comments, all YOU need to do is say what you were doing.

If you only wanted to know the STATUS of the file (version number, whether it is different from the repository), then you could have issued the CVS STATUS command:
cvs status [filename]
This command (like LOG), if no filename is given, will return a report for all modules and/or files in the current directory. This can also get long!

One such report *might* look like this:
===================================================================
File: bin.make Status: Locally Modified
Version: 1.6 Mon Feb 3 14:38:05 1997
RCS Version: 1.6 /home/sseos/us1/e895/CVS_TAS3/TAS3/bin/bin.make,v
Sticky Tag: (none)
Sticky Date: (none)
Sticky Options: (none)

The status Locally Modified implies that the user has made changes to this file which he/she has not yet COMMITed. When the file is in sync with the Repository, its status will be Up-to-date.