/ 
ClearCase-Ct-1.01
/ Profile.pm

NAME

Profile.pm - site-wide customizations for ct wrapper

SYNOPSIS

This is the local profile for the ct program, which functions as a wrapper for cleartool, thus 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 developers:

A number of commands have been enhanced to simulate the standard cleartool flags -dir, -rec, and -all, which cause the command to operate on (respectively) all eligible files 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.

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.

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

All commands which take a view tag with -tag are enhanced to recognize the -me flag. This modifies the effect of -tag by prepending your username automatically 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. Also, mkview recognizes the -me flag. This means that making a new view can/should be done as ct mkview -tag foo -me.

Detailed descriptions of all the above may be found below.

DESCRIPTION

  • CATCS

    Lots of enhancements here, mostly in the area of config-spec parsing for automation:

    1. New -expand flag

    This follows all include statements recursively in order to print a complete config spec.

    2. New -source flag

    Prints the initial working directory of a view by examining its config spec. If the conventional string ##:Source: dir is present then the value of dir is printed. Otherwise the first path found in the second field of the config spec, typically a vob tag, is used. If no explicit paths are present, no output is produced.

    3. New -branch flag

    Prints the name of the first branch selected in the config spec via a line like this:

    C<element * .../I<branch>/LATEST>
    4. New -vobs flag

    Prints a list of all vob tags referenced explicitly within the config spec.

    5. New -project flag

    Prints the name of the first vob tag encountered in the config spec, assuming the vob-naming convention /vobs/name/src or /vobs/name/do (meaning source vobs and derived-object vobs respectively).

    6. New -promote flag

    Prints the name of the backing branch of the current config spec. This is the branch that local work will be merged to.

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

  • 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

    New convenience command. Same as 'checkout' but execs your favorite editor afterwards.

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

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

  • LSCO

    Modified default: if no flags supplied, pass -cview.

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

  • MKELEM

    Extended to handle the -dir/-rec/-all flags, enabling recursive mkelems with otherwise the same syntax as original. To implement this, we put all the directories under version control within the wrapper, then do a mkelem as usual on the files. If the -ci flag is present we then check the directories back in before finishing.

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

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

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.

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