ClearCase::Wrapper - General-purpose wrapper for cleartool
This perl module functions as a wrapper for cleartool, allowing its command-line interface to be extended or modified. It allows defaults to be changed, new flags to be added to existing cleartool commands, or entirely new commands to be synthesized.
A pseudo-command which lists the currently-defined extensions. Use with -long to see which overlay module defines each extension. Note that both extensions and their aliases (e.g. checkin and ci) are shown.
Extended to handle the -dir/-rec/-all/-avobs flags. These are fairly self-explanatory but for the record -dir checks in all checkouts in the current directory, -rec does the same but recursively down from the current directory, -all operates on all checkouts in the current VOB, and -avobs on all checkouts in any VOB.
Extended to allow symbolic links to be checked in (by operating on the target of the link instead).
Extended to implement a -diff flag, which runs a diff -pred command before each checkin so the user can review his/her changes before typing the comment.
Implements a new -revert flag. This causes identical (unchanged) elements to be unchecked-out instead of being checked in.
Since checkin is such a common operation, a special fature is supported
to save typing: an unadorned ci cmd is promoted to ci -dir -me
-diff -revert. In other words typing ct ci will step through each
file checked out by you in the current directory and view,
automatically undoing the checkout if no changes have been made and
showing diffs followed by a checkin-comment prompt otherwise.
Extended to handle the -dir/-rec flags. NOTE: the -all/-avobs flags are disallowed for checkout. Also, directories are not checked out automatically with -dir/-rec.
Extended to handle the -dir/-rec/-all/-avobs flags.
Improved default: if given just one element and no flags, assume -pred.
Extended to implement -n, where n is an integer requesting that the diff take place against the n'th predecessor.
Extended to add the -data flag, which compares the contents of differing elements and removes them from the output if the contents do not differ.
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.
The aggregation flags -dir/-rec/-all/-avo may be used, with the effect being to run the editor on all checked-out files in the named scope. Example: "ct edit -all".
Extended to recognize -dir/-rec/-all/-avobs. Also allows a directory to be specified such that 'ct lsprivate .' restricts output to the cwd. This directory arg may be used in combination with -dir etc.
The -eclipsed flag restricts output to eclipsed elements.
The flag -type d|f is also supported with the usual semantics (see cleartool find).
The flag -visible flag ignores files not currently visible in the view.
Output is relative to the current or specified directory if the -rel/ative flag is used.
The -ext flag sorts the output by extension.
Extended to recognize the general -me flag, which restricts the searched namespace to <username>_*.
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.
By default, only regular (-other) view-private files are considered by -dir|-rec. The -do flag causes derived objects to be made into elements as well.
If -ok is specified, the user will be prompted to continue after the list of eligible files is determined.
When invoked in a view-private directory, mkelem -dir/-rec will
traverse up the directory structure towards the vob root until it finds
a versioned dir to work from. Directories traversed during this walk
are added to the list of new elements.
Extended to accept (and ignore) the standard comment flags for consistency with other cleartool cmds.
Extended to handle the -dir/-rec/-all/-avobs flags.
Extended to operate on ClearCase symbolic links.
Before processing a checkin or checkout command, any symbolic links on the command line are replaced with the file they point to. This allows developers to operate directly on symlinks for ci/co.
As a convenience feature, the -M flag runs all output through your
pager. Of course "ct lsh -M foo" saves only a few keystrokes over
"ct lsh foo | more" but for heavy users of shell history the more
important feature is that it preserves the value of ESC-_ (ksh -o
vi) or !$ (csh). The CLEARCASE_WRAPPER_PAGER EV has the same effect.
This may not work on Windows, though it's possible that a sufficiently modern Perl build and a smarter pager than more.com will do the trick.
The special -P flag will cause ct to pause before finishing.
On Windows this means running the built in pause command. This flag
is useful for plugging ClearCase::Wrapper scripts into the CC GUI.
Introduces a global convenience/standardization feature: the flag -me in the context of a command which takes a -tag view-tag causes "$LOGNAME" to be prefixed to the tag name with an underscore. This relies on the fact that even though -me is a native cleartool flag, at least through CC 7.0 no command which takes -tag also takes -me natively. For example:
% <wrapper-context> mkview -me -tag myview ...
The commands setview, startview, endview, and lsview also take -me, such that the following commands are equivalent:
% <wrapper-context> setview dboyce_myview
% <wrapper-context> setview -me myview
Various degrees of configurability are supported:
To add a global override called 'cleartool xxx', you could just write a subroutine 'xxx', place it after the __END__ token in Wrapper.pm, and re-run 'make install'. However, these changes wcould be lost when a new version of ClearCase::Wrapper is released, and you'd have to take responsibility for merging your changes with mine.
Therefore, the preferred way to make site-wide customizations or
additions is to make an overlay module. ClearCase::Wrapper will
automatically include ('require') all modules in the
ClearCase::Wrapper::* subclass. Thus, if you work for TLA
Corporation you should put your enhancement subroutines in a module
called ClearCase::Wrapper::TLA and they'll automatically become
available.
A sample overlay module is provided in the ./examples subdir. To
make your own you need only take this sample, change all uses of the
word 'MySite' to a string of your choice, replace the sample subroutine
mysite() with your own, and install. It's a good idea to document
your extension in POD format right above the sub and make the
appropriate addition to the "Usage Message Extensions" section. Also,
if the command has an abbreviation (e.g. checkout/co) you should add
that to the "Command Aliases" section. See ClearCase::Wrapper::DSB
for examples.
Two separate namespaces are recognized for overlays:
ClearCase::Wrapper::* and ClearCase::Wrapper::Site::*. The intent
is that if your extension is site-specific it should go in the latter
area, if of general use in the former. These may be combined. For
instance, imagine TLA Corporation is a giant international company with
many sites using ClearCase, and your site is known as R85G. There could
be a ClearCase::Wrapper::TLA overlay with enhancements that apply
anywhere within TLA and/or a ClearCase::Wrapper::Site::R85G for
your people only. Note that since overlay modules in the Site namespace
are not expected to be published on CPAN the naming rules can be less
strict, which is why TLA was left out of the latter module name.
Overlays in the general ClearCase::Wrapper::* namespace are traversed before ClearCase::Wrapper::Site::*. This allows site-specific configuration to override more general code. Within each namespace modules are read in standard ASCII sorted alphabetical order.
All override subroutines are called with @ARGV as their parameter list (and @ARGV is also available directly of course). The function can do whatever it likes but it's recommended that ClearCase::Argv be used to run any cleartool subcommands, and its base class Argv be used to run other programs. These modules help with UNIX/Windows portability and debugging, and aid in parsing flags into different categories where required. See their PODs for full documentation, and see the supplied extensions for lots of examples.
As well as allowing for site-wide enhancements to be made in
Wrapper.pm, a hook is also provided for individual users to set their
own defaults. If the file ~/.clearcase_profile.pl exists it will be
read before launching any of the sitewide enhancements. Note that this
file is passed to the Perl interpreter and thus has access to the full
array of Perl syntax. This mechanism is powerful but the corollary is
that users must be experienced with both ClearCase and Perl, and to
some degree wth the ClearCase::Wrapper module, to use it.
This distribution comes with a file called clearcase_profile which is installed as part of the module. If the user has no clearcase_profile file in his/her home directory and if CLEARCASE_PROFILE isn't already set, CLEARCASE_PROFILE will automatically be pointed at this supplied file. This allows the administrator to set sitewide defaults of checkin/checkout comment handling using the syntax supported by ClearCase natively but without each user needing to maintain their own config file or set their own EV.
This environment variable may be set to suppress all extensions, causing the wrapper to behave just like an alias to cleartool, though somewhat slower.
The flag -/dbg=1 prints all cleartool operations executed by the wrapper to stderr as long as the extension in use was coded with ClearCase::Argv, which is the case for all supplied extensions.
I recommend you install the cleartool.plx file to some global dir (e.g. /usr/local/bin), then symlink it to ct or whatever short name you prefer. For Windows the strategy is similar but requires a "ct.bat" redirector instead of a symlink. See "examples/ct.bat" in the distribution. Unfortunately, there's no equivalent mechanism for wrapping GUI access to clearcase.
To install or update a global enhancement you must run "make pure_all
install" - at least that's what I've found to work. Also, don't forget
to check that the contents of
lib/ClearCase/Wrapper/clearcase_profile are what you want your users
to have by default.
Copyright (c) 1997-2006 David Boyce (dsbperl AT boyski.com). All rights reserved. This Perl program is free software; you may redistribute it and/or modify it under the same terms as Perl itself.