NAME

ClearCase::Wrapper - General-purpose wrapper for cleartool

SYNOPSIS

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.

CLEARTOOL ENHANCEMENTS

• EXTENSIONS

  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.

• CI/CHECKIN

  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.

  Implements a new -mkhlink flag. This works in the context of the -revert flag and causes any inbound merge hyperlinks to an unchanged checked-out element to be copied to its predecessor before the unchanged element is unchecked-out.

  Since checkin is such a common operation a special feature 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.

• CO/CHECKOUT

  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.

• DIFF

  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.

• DIFFCR

  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.

• EDIT/VI

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

• LSPRIVATE

  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.

• LSVIEW

  Extended to recognize the general -me flag, which restricts the searched namespace to <username>_*.

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

  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.

• UNCO

  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.

GENERAL FEATURES

• symlink expansion

  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.

• -M flag

  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.

• -P flag

  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.

• -me -tag

  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

CONFIGURABILITY

Various degrees of configurability are supported:

• Global Enhancements and Extensions

  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.

• Personal Preference Setting

  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 with the ClearCase::Wrapper module, to use it. Here's an example:

      % cat ~/.clearcase_profile.pl
      require ClearCase::Argv;
      Argv->dbglevel(1);
      ClearCase::Argv->ipc(2);

  The purpose of the above is to turn on ClearCase::Argv "IPC mode" for all commands. The verbosity (Argv->dbglevel) is only set to demonstrate that the setting works. The require statement is used to ensure that the module is loaded before we attempt to configure it.

• Sitewide ClearCase Comment Defaults

  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.

• CLEARCASE_WRAPPER_NATIVE

  This environment variable may be set to suppress all extensions, causing the wrapper to behave just like an alias to cleartool, though somewhat slower.

DIAGNOSTICS

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.

INSTALLATION

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 AND LICENSE

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.