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

• CATCS

  1. New -expand flag

  Follows all include statements recursively in order to print a complete config spec. When used with the -cmnt flag, comments are stripped from this listing.

  2. New -sources flag

  Prints all files involved in the config spec (the config_spec file itself plus any files it includes).

  3. New -start flag

  Prints the preferred initial working directory of a view by examining its config spec. If the conventional string C"<##:Start: dir"> is present then the value of dir is printed. Otherwise no output is produced. The workon command (see) uses this value. E.g., using workon instead of setview with the config spec:

  ##:Start: /vobs_fw/src/java
  element * CHECKEDOUT
  element * /main/LATEST

  would automatically cd to /vobs_fw/src/java within the set view.

  4. New -rdl flag

  Prints the value of the config spec's C"<##:RDL:> attribute.

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

• COMMENT

  For each ClearCase object specified, dump the current comment into a temp file, allow the user to edit it with his/her favorite editor, then change the objects's comment to the results of the edit. This is useful if you mistyped a comment and want to correct it.

  The -new flag causes it to ignore the previous comment.

  See edattr for editor selection rules.

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

• DIFFCS

  New command. Diffcs dumps the config specs of two specified views into temp files and diffs them. If only one view is specified, compares against the current working view's config spec.

• EDATTR

  New command, inspired by the edcs cmd. Edattr dumps the attributes of the specified object 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 and the quoting rules make it difficult to use the command line.

  The environment variables WINEDITOR, VISUAL, and EDITOR are checked in that order for editor names. If none of the above are set, the default editor used is vi on UNIX and notepad on Windows.

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

• GREP

  New command. Greps through past revisions of a file for a pattern, so you can see which revision introduced a particular function or a particular bug. By analogy with lsvtree, grep searches only "interesting" versions unless -all is specified.

  Flags -nnn are accepted where nnn represents the number of versions to go back. Thus grep -1 foo would search only the predecessor.

• LOCK

  New -allow and -deny flags. These work like -nuser but operate incrementally on an existing -nuser list rather than completely replacing it. When -allow or -deny are used, -replace is implied.

  When -iflocked is used, no lock will be created where one didn't previously exist; the -nusers list will only be modified for existing locks.

• LSPRIVATE

  Extended to recognize -dir/-rec/-all/-avobs. Also allows a directory to be specified such that 'ct lsprivate .' restricts output to the cwd, etc. This directory arg may be used in combination with -dir etc. Output in these cases 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.

  The flag -visible flag removes files not currently visible in the view.

  The -ext flag sorts the output by extension.

• LSVIEW

  Extended to recognize the general -me flag, restricting the search namespace to <username>_*.

• LSVTREE

  Modified default to always use -a flag.

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

• MKLABEL

  The new -up flag, when combined with -recurse, also labels the parent directories of the specified pnames all the way up to their vob tags.

• MKBRTYPE,MKLBTYPE

  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.

• 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 -clone flag

  This allows you to specify another view from which to copy the config spec and other properties. Note that it does not copy view-private files from the old view, just the view properties.

• MOUNT

  This is a Windows-only enhancement: on UNIX, mount behaves correctly and we do not mess with its behavior. On Windows, cleartool mount -all gives an error for already-mounted VOBs for some reason; these are now ignored as on UNIX. At the same time, VOB tags containing / are normalized to \ so they'll match the registry, and an extension is made to allow multiple VOB tags to be passed to one mount command.

• RECO/RECHECKOUT

  Redoes a checkout without the database operations by simply copying the contents of the existing checkout's predecessor over the view-private checkout file. The previous contents are moved aside to "<element>.reco".

• SETVIEW

  ClearCase 4.0 for Windows completely removed setview functionality, but this wrapper emulates it by attaching the view to a drive letter and cd-ing to that drive. It supports all the flags setview for CC 3.2.1/Windows supported (-drive, -exec, etc.) and adds a new one: -persistent.

  If the view is already mapped to a drive letter that drive is used. If not, the first available drive working backwards from Z: is used. Without -persistent a drive mapped by setview will be unmapped when the setview process is existed.

  The setview emulation sets CLEARCASE_ROOT for compatibility and adds a new EV CLEARCASE_VIEWDRIVE.

  UNIX setview functionality is left alone.

• SETCS

  Adds a -clone flag which lets you specify another view from which to copy the config spec.

  Adds a -sync flag. This is similar to -current except that it analyzes the CS dependencies and only flushes the view cache if the compiled_spec file is out of date with respect to the config_spec source file or any file it includes. In other words: setcs -sync is to setcs -current as make foo.o is to cc -c foo.c.

  Adds a -expand flag, which "flattens out" the config spec by inlining the contents of any include files.

• WORKON

  New command, similar to setview but provides hooks to cd to a preferred initial working directory within the view and to set up any required environment variables. The initial working directory is defined as the output of ct catcs -start (see).

  If a file called .viewenv.pl exists in the initial working directory, it's read before starting the user's shell. This file uses Perl syntax and must end with a "1;" like any require-d file. Any unrecognized arguments given to workon following the view name will be passed on to .viewenv.pl in @ARGV. Environment variables required for builds within the setview may be set here.

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

• WINKIN

  The -tag flag allows you specify a local file path plus another view; the named DO in the named view will be winked into the current view.

  The -vp flag, when used with -tag, causes the "remote" file to be converted into a DO if required before winkin is attempted. See the winkout extension for details.

• WINKOUT

  The winkout pseudo-cmd takes a set of view-private files as arguments and, using clearaudit, makes them into derived objects. The config records generated are meaningless but the mere fact of being a DO makes a file eligible for forced winkin.

  If the -promote flag is given, the view scrubber will be run on the new DO's. This has the effect of promoting them to the VOB and winking them back into the current view.

  If a meta-DO filename is specified with -meta, this file is created as a DO and caused to reference all the other new DO's, thus defining a DO set and allowing the entire set to be winked in using the meta-DO as a hook. E.g. assuming view-private files X, Y, and Z already exist:

  ct winkout -meta .WINKIN X Y Z

  will make them into derived objects and create a 4th DO ".WINKIN" containing references to the others. A subsequent

  ct winkin -recurse -adirs /view/extended/path/to/.WINKIN

  from a different view will wink all four files into the current view.

  Accepts -dir/-rec/-all/-avobs, a file containing a list of files with -flist, or a literal list of view-private files. When using -dir/-rec/-all/-avobs to derive the file list only the output of lsprivate -other is considered unless -do is used; -do causes existing DO's to be re-converted.

  The "-flist -" flag can be used to read the file list from stdin.

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.

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

CONFIGURATION

Various degrees of configurability are supported:

• Global Enhancements and Extensions

  To add a global override for 'cleartool xxx', simply define a subroutine 'xxx' after the __END__ token in Wrapper.pm or in lib/ClearCase/Wrapper/Site.pm and re-run 'make install'. When doing so it's a good idea to document it 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.

  This override subroutine is called with @ARGV as its parameter list (and @ARGV is also available directly of course). The sub 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 aid in parsing flags into different categories where required. See their PODs for full documentation.

• 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 (but 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 "ct.bat.sample" 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

Copyright (c) 1997-2001 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.