NAME

Profile.pm - site-wide customizations for ct wrapper

VERSION

1.13

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, and -all, which cause the command to operate on (respectively) all eligible elements in the current dir, the current dir recursively, and the current vob. The enhanced commands include checkin/ci, unco, diff, mkelem, and lsprivate. Thus you can check in all your current checkouts with ct ci -all 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

  New -expand flag. This recursively follows all include statements in order to print a complete config spec.

• 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 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.

• 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.

• 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.

• CITREE

  New command. Takes a tree of files from normal Unix file space and puts them under source control in the specified VOB directory. If there are already elements by the same name, it checks them out and back in. Otherwise it runs mkelem operations as needed.

  NOTE: by default, citree makes the target directory an exact replica of the source by removing any files from the target which don't exist in the source. This is not the disaster it might seem since the files are still present in ClearCase, but in any case the -r flag will turn this behavior off.

  This is just a wrapper to the standalone citree program written by Paul Smith (psmith@BayNetworks.com). Run citree with no arguments for full details.

• 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 has the benefit of behaving the same way on NT as well.

• FIND

  Extended to simulate the -fmt option. This is done by sending the results of find to a describe -fmt.

• LSVTREE

  Modified default to always use -a flag.

• LSPRIVATE

  Extended to recognize -dir/-rec/-all (underlying lsprivate always behaves in a -all 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 -profile flag

  The user can associate the view with a ClearCase View Profile. Although, as of CC 3.2 these can only be manipulated on Windows NT, this extension allows them to be used on Unix platforms. In order for this to work, the view-profile storage area must be accessible to the Unix platforms (via NFS or Samba, for instance). The profile text is modified to replace backslashes with forward slashes, correct line-termination characters, and is then instantiated in the config spec. The ct synccs command can be used to resync.

  #=item 4. New -back flag #This is an advanced topic ...

  ## Note: to use the default view-storage feature you must define ## the variable $ViewStgRoot to the appropriate place, typically ## /net/somewhere/viewstore/... or similar.

• 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).

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 $ClearCmd 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

SEE ALSO

cleartool(1), perl(1).