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 -cmnt flag, comments will be stripped from this listing.

  2. New -sources flag

  Prints the files involved in the config spec (the config_spec file itself plus any include files).

  3. New -start flag

  Prints the preferred initial working directory of a view by examining its config spec. If the conventional string ##:Start: dir is present then the value of dir is printed. Otherwise no output is produced. The workon command (see) uses this value if present.

• CI/CHECKIN

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

  Extended to allow symbolic links to be checked in (by simply operating on 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 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 -all to save typing.

• 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. The -new flag causes it to ignore the previous comment.

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

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

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

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

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

  By default, views are placed in a standard path on a standard well-known view server. Of course, the sophisticated user may specify any view-storage location explicitly, taking responsibility for getting the -host/-hpath/-gpath triple right. However, for simplicity a -local flag is also supported which will attempt to place the view in a standard place on the local machine if such a place exists.

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

• SETVIEW

  ClearCase 4.0 for Windows completely removes 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.

• SETCS

  Adds a -clone 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 view dependencies and only flushes the view cache if the compiled_spec is out of date with respect to the config_spec source file or a file it includes. In other words: -sync is to -curr 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.

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

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

  The 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, the wrapper will automatically point CLEARCASE_PROFILE at the 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.

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" file 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,1998,1999,2000 David Boyce (dsb@world.std.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.