NAME

ClearCase::Wrapper - general-purpose wrapper for cleartool

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.

CLEARTOOL ENHANCEMENTS

• CI/CHECKIN

  Extended to handle the -dir/-rec/-all/-avobs flags.

  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 see his/her changes while typing the comment.

  Automatically supplies -nc to checkins if the element list consists of only directories (since directories get a default 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, an unadorned ci cmd is promoted to ci -diff -dir -revert to save typing.

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

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

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

  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.

  Output is relative to the current or specified directory if the -rel/ative flag is used.

  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.

  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.

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 allowd 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 work.

• -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 CC4.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 and 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 XYZ Corporation you should put your enhancement subroutines in a module called ClearCase::Wrapper::XYZ 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 override 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.

  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 XYZ Corporation is a giant international company with many sites using ClearCase, and your site is known as R85G. There could be a ClearCase::Wrapper::XYZ overlay with enhancements that apply anywhere within XYZ and/or a ClearCase::Wrapper::Site::R85G one for your people only. Note that since overlay modules in the Site namespace are not expected to be published on CPAN there's no need for XYZ to appear in its name; that can be implicit.

  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.

  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 strongly recommended that ClearCase::Argv be used to run any cleartool subcommands and its base class Argv be used to run other programs. These modules provide value for 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 overrides 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 (who must be knowledgeable about both ClearCase and Perl) 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.

• 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 "real" 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. Unfortunately, there's no equivalent mechanism for wrapping GUI access to clearcase. For Windows the strategy is similar but requires a "ct.bat" redirector instead of a symlink. See "examples/ct.bat" in the distribution.

To install or update a global enhancement you must re-run "make install". Also, don't forget to check that the contents of lib/ClearCase/Wrapper/clearcase_profile are what you want users to have by default.

COPYRIGHT AND LICENSE

Copyright (c) 1997-2002 David Boyce (dsb@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.