NAME

Profile.pm - site-wide customizations for ct wrapper

VERSION

1.17

SYNOPSIS

This perl module functions as a wrapper for cleartool, allowing the command-line interface of cleartool to be extended or modified. It allows defaults to be changed, new flags to be added to existing cleartool commands, or entirely new cleartool commands to be synthesized.

Unfortunately, there's no equivalent mechanism for wrapping GUI access to clearcase.

SUMMARY

Here's a quick overview of the extensions available via ct which may be of interest to users:

Many cleartool commands have been enhanced to simulate the standard flags -dir, -rec, -all, and -avobs which cause the command to operate on (respectively) all eligible elements in the current dir, the current dir recursively, the current vob, and all vobs. The enhanced commands include checkin/ci, unco, diff, mkelem, and lsprivate. Thus you could check in all checkouts in the current view with ct ci -avobs or see the view-private files in and under the current dir with ct lsprivate -rec. You can convert a tree of view-private data into elements with ct mkelem -rec -ci.

The ct checkin command is also enhanced to take a -diff flag which prints your changes to the screen before prompting for a comment.

A new command ct edit is added. This is the same as ct checkout but execs your favorite editor after checking out. It also takes a -ci flag which will check the file in afterwards.

All commands which take a -tag view-tag option are enhanced to recognize the -me flag. This modifies the effect of -tag by prepending your username to the view name. E.g. -tag foo -me is a shorthand for -tag <username>_foo. Similarly, ct lsview -me will show only views whose names match the pattern <username>_*.

The ct mkview command is enhanced to default the view-storage location to a standard place using a standard naming convention. See SiteProfile.pm.sample for how this is set up. Also, mkview recognizes the -me flag as described above. This means that making a new view can/should be done as ct mkview -tag foo -me.

New pseudo-commands ct edattr and ct edcmnt are added. These make it easy to edit the attributes and comments, respectively, of a particular version.

A new command ct rmpriv is added, which behaves like rm -i `ct lsprivate -rec`, though -dir or -all may be substituted for -rec and -f may be passed to override -i.

Detailed descriptions of all the above may be found below. Summaries are available via the standard -h flag.

DESCRIPTION

CATCS
1. New -expand flag
  Follows all include statements recursively in order to print a complete config spec. The -cmnt flag will strip comments from this listing.
2. New -rdl flag
  Shows 'rdl' options embedded in the config spec.
3. New -sources flag
  Prints the files involved in the config spec (the config_spec file itself plus any include files).
4. New -start flag
  Prints the initial working directory of a view by examining its config spec. If the conventional string ##:Start: dir is present then the value of dir is printed. Otherwise no output is produced.
SETCS
Adds a -sync flag. This is similar to -current except that it analyzes the view dependencies and only flushes the view cache if the compiled_spec is out of date with respect to the config_spec source file or a file it includes.
CI/CHECKIN
Extended to handle the -dir/-rec/-all flags.
Extended to allow symbolic links to be ``checked in'' (by simply checking in the target of the link instead).

Extended to implement a -diff flag, which runs a ct diff -pred command before each checkin so the user can look at his/her changes before typing the comment.

Also, automatically supplies -nc to checkins if the element list consists of only directories (directories get a default comment).

Implements a new -revert flag. This causes identical (unchanged) elements to be unchecked-out instead of being checked in.

Also extended to implement a -iff flag. This reduces the supplied list of elements to those truly checked out. E.g. ct ct -iff *.c will check in only the elements which match *.c and are checked out, without producing a lot of errors for the others.
CO/CHECKOUT
Extension: if element being checked out is a symbolic link, silently replace it with the name of its target, because for some reason ClearCase doesn't do this automatically.
Automatically defaults checkouts to use -nc. This could be done with clearcase_profile as well, of course, but is more centralized here.
EDIT
Convenience command. Same as 'checkout' but execs your favorite editor afterwards. Takes all the same flags as checkout, plus -ci to check the element back in afterwards. When -ci is used in conjunction with -diff the file will be either checked in or un-checked out depending on whether it was modified.
Also, ct edit -dir will not check anything out but will exec the editor on all currently checked-out files.
DIFF
Modified default: if no flags given, assume -pred.
Extended to handle the -dir/-rec/-all flags. Also adds a -c flag to generate a context diff (by simply using the real diff program).
REVIEW
New convenience command: sends a context diff between current and previous versions to the 'pprint' program, which prints it with line numbers appropriate for code reviews. E.g. you could generate a listing of all changes currently checked-out in your view with ct review -all.
ECLIPSE
New command. Eclipses an element by copying a view-private version over it. This is the dynamic-view equivalent of ``hijacking'' a file in a snapshot view. Typically of use if you need temporary write access to a file when the VOB is locked, or it's checked out reserved. Eclipsing elements can lead to dangerous levels of confusion - use with care!
EDATTR
New command, inspired by the edcs cmd. Analogous to edcs, edattr dumps the attributes of the specified elements into a temp file, then execs your favorite editor on it, and adds, removes or modifies the attributes as appropriate after you exit the editor. Attribute types are created and deleted automatically. This is particularly useful on Unix platforms because as of CC 3.2 the Unix GUI doesn't support modification of attributes.
EDCMNT
Similar to edattr. For each version specified, dump the comment into a temp file, allow the user to edit it with his/her favorite editor, then change the version's comment to the results of the edit. The -new flag causes it to ignore the previous comment.
RMPRIV
New convenience command. Conceptually this is just a shorthand for ``rm -i `ct lsp`'', but it also handles convenience features such as the rm-like -f flag plus -dir/-rec/-all. It also has the benefit of behaving the same way on NT, which rm doesn't.
FIND
Extended to simulate the -fmt option. This is done by sending the results of find to a describe -fmt.
GREP
New command. Greps all past revisions of a file for a pattern, so you see which revision introduced a particular function or which introduced a particular bug. Suggested by Seth Alford <setha@plaza.ds.adp.com>.
LS
On Windows, do the user a favor and handle globbing for DOS shell.
LSVTREE
Modified default to always use -a flag.
LSPRIVATE
Extended to recognize -dir/-rec/-all (underlying lsprivate always behaves in a -avobs fashion). Also allows a directory to be specified, such that 'ct lsprivate .' restricts output to cwd.
LSVIEW
Extended to recognize the general -me flag, restricting the search namespace to <username>_*.
MKATTYPE
Modification: if user tries to make a type in the current VOB without explicitly specifying -ordinary or -global, and if said VOB is associated with an admin VOB, then by default create the type as a global type in the admin VOB instead. In effect, this makes -global the default iff a suitable admin VOB exists.
MKBRTYPE,MKLBTYPE
Same as mkattype above.
MKELEM
Extended to handle the -dir/-rec flags, enabling automated mkelems with otherwise the same syntax as original. Directories are also automatically checked out as required in this mode. Note that this automatic directory checkout is only enabled when the candidate list is derived via the -dir/-rec flags. If the -ci flag is present, any directories automatically checked out are checked back in too.
MKVIEW
Extended in the following ways:
1. New -me flag
  Supports the -me flag to prepend $LOGNAME to the view name, separated by an underscore. This enables the convention that all user views be named <username>_<whatever>.
2. Default view-storage location
  Provides a standard default view-storage path which includes the user's name. Thus a user can simply type ``mkview -me -tag foo'' and the view will be created as <username>_foo with the view storage placed in a default location determined by the sysadmin.
3. New -local flag
  By default, views are placed in a standard path on a standard well-known view server. Of course, the sophisticated user may specify any view-storage location explicitly, taking responsibility for getting the -host/-hpath/-gpath triple right. But a -local flag is also supported which will attempt to place the view in the same standard place but on the local machine.
4. New -clone flag
  This allows you to specify another view from which to copy the config spec and other properties. Note that it does not copy view-private files from the old view, just the properties.
SYNCCS
New command: takes an optional view tag via -tag and a view-profile name with -profile, and synchronizes the config spec with the profile. If no tag is passed, operates on the current view spec; if no -profile, re-synchronizes with the current profile.
UNCO
Modified default to always use -rm (this may be controversial but is easily overridden in the user's profile).
Extended to accept (and ignore) the -nc flag for consistency with other cleartool cmds.

Extended to handle the -dir/-rec/-all flags.
SETVIEW/STARTVIEW/ENDVIEW
Extended to support the -me flag (prepends <username>_* to tag).
Also completely implements the setview command on Windows where it's not native. This is done by mapping a drive letter, cd-ing to that drive, and starting a subshell. A -persistent flag is supported which causes the drive to stay mapped when done as well as -drive allowing you to specify a drive letter.
WORKON
New command - similar to setview but sets up any required environment variables as well. Also cd's to the initial working directory within the view. This directory is defined as the output of ct catcs -start (see).

FURTHER CUSTOMIZATION

Working on a profile is actually quite easy if you remember that within it $_ is set to the command name, @ARGV is the complete command line and @_ is a copy of it, $0 is the path to the wrapper, and $CT is the path to the real cleartool program. Also, the hash %Vgra is a reverse lookup such that $ARGV[$Vgra{xyz}] eq "xyz".

With most perl modules, the .pm code itself (the part that gets found via @INC) is static - it's not generally modified except via updates of the module. Meanwhile, users write code to use the module and that code is fluid; they change it as they please. This module is backwards from that since the ct program is policy-free and thus shouldn't need to be changed significantly. Meanwhile, the Profile.pm is intended to be a reflection of the local policies and preferences; the provided Profile.pm is simply a sample of what can be done.

The Profile.pm does not establish a separate namespace; it operates within main::. There did not seem to be any good reason to do so, since the whole point is to operate directly on the namespace provided by the client program ct.

The ct program is normally expected to be used under that name, which means that users running cleartool lsco, for instance, will go around the wrapper. However, it's also designed to allow for complete wrapping if desired. To do so, move $ATRIAHOME/bin/cleartool to $ATRIAHOME/bin/wrapped/cleartool and install ct as $ATRIAHOME/bin/cleartool. You can continue to install/link the wrapper as ct as well - it won't invoke the wrapper twice because it contains code to detect the presence of the moved-aside binary and run it.

As a safety mechanism, the require-ing of the profile is handled within an eval block, so a syntax error or config problem in the profile won't cause it to fail. It will simply print a warning and continue.

AUTHOR

David Boyce, dsb@world.std.com