ClearCase-Wrapper
view release on metacpan or search on metacpan
- Allow "ct mkelem -dir/-rec" to be run in a view-private dir.
It will traverse 'up' towards the vob root looking for a
versioned dir to work from.
- Added -P (pause) flag (see README.GUI for why).
1.01 Fri Jan 25 09:35:11 EST 2002
- *COMPATIBILITY ALERT*
With this release the infrastructure is largely rewritten
to make customizations/extensions easier to write and
maintain. The old Site.pm hack is gone. In its place
are "overlay modules". See the README and the POD in
Wrapper.pm for details, but basically this makes it much
easier to write (and potentially contribute) new features.
*NOTE* If upgrading from a version <1.00, you should manually
uninstall the old version. See README.upgrade for details.
The Makefile.PL has some code to try to warn you about this
situation.
1.02 Sun Jan 27 13:54:17 EST 2002
- Added README.upgrade and some upgrade help in
Makefile.PL view on Meta::CPAN
'Ct', or even just 'c'. This must be set up by hand and may be
done on UNIX via a symbolic link, e.g.:
% cd /opt/local/bin; ln -s cleartool.plx ct
or on Windows by making a tiny ct.bat file containing:
@echo off
perl //UNC/path/to/cleartool.plx %*
*NOTE* There are additional 'overlay' modules available which
*NOTE* extend the functionality of this module.
*NOTE* Consider ClearCase::Wrapper::DSB, ClearCase::Wrapper::MGi, etc.
);
# The regular stuff.
WriteMakefile(
'NAME' => 'ClearCase::Wrapper',
'VERSION_FROM' => 'Wrapper.pm', # finds $VERSION
'EXE_FILES' => [ qw(cleartool.plx cleartool.dbg) ],
--------------
The interesting files in this distribution are cleartool.plx and
Wrapper.pm. The first is the actual cleartool wrapper program; it's
short, generic, and should need no local modification. Wrapper.pm
provides some funky importing infrastructure above the __END__ token;
again, this is boilerplate. All the interesting stuff - the ClearCase
customizations - are made in the AutoLoader area below the __END__.
It is not recommended that you modify either of these files for your
own customizations. Rather, a provision is made for "overlay modules"
which let you overlay your own semantics. A sample overlay module is
provided in the ./examples directory along with its own README.
In theory, as described above, ClearCase::Wrapper per se is just a
framework for making your own enhancements. By that logic it should
be delivered without any customizations. In other words, it should
provide only mechanism and let you provide the policy.
However, I think many of the enhancements I've made are of general
interest and may be a primary reason for installing the module, so
here's what I've done. The ones which are (a) widely applicable and (b)
uncontroversial (e.g. don't change native CC defaults) are provided
directly in ClearCase::Wrapper. The ones of perhaps less general
use have been segregated into the overlay ClearCase::Wrapper::DSB,
which is also available on CPAN. Those which are site-specific and/or
modify CC defaults, or are controversial in any other way, are in a
site-specific overlay which is not released.
THEREFORE: to get the full scope of functionality, with all
published enhancements, you should install BOTH ClearCase::Wrapper
and ClearCase::Wrapper::DSB. At some point there may even be other
overlays available on CPAN; check their docs before installing.
Make your own customizations in ClearCase::Wrapper::YOURNAME or
ClearCase::Wrapper::Site::YOURSITE, depending on whether the
enhancements embody your or your organization's preferences.
Note: older versions of ClearCase::Wrapper, prior to 1.00, had a
different customization strategy involving a Site.pm file. This is
obsolete. If you have a customized Site.pm it should continue to work,
but it would be easy (and much cleaner) to convert it into an overlay
module. The best way to do this is to copy your subroutines out of Site.pm
into the sample overlay module ("MySite"). Rename as appropriate,
test and install, and don't forget to take the obsolete Site.pm
file out of your @INC area manually.
See the POD for further discussion of how to add your own extensions.
The wrapper script also looks for a file called ~/.clearcase_profile.pl
(note same name ClearCase supports except with a .pl suffix) containing
personal customizations. No sample of this is delivered; the syntax is
pure Perl and the idea would be to modify @ARGV before the override
subroutine and/or exec() ever see it. I've never found a need for this
sub Mysub
'PUBLIC' : not an 'op', but expected to be shared with other extensions so
is exported to submodules
sub _Mysub
'PRIVATE': not an 'op', and not expected to be shared with other extensions.
sub MYSUB
'CONST' : So don't do this, instead do this -> use constant MYSUB => ...
Note: these rules apply also to the names of global variables defined
in the overlay modules. So, use initial uppercases...
DEBUGGING
--------
As the sample enhancements all use ClearCase::Argv, they can take
advantage of its debugging infrastructure. In particular you can see
all cleartool commands as executed by exporting ARGV_DBGLEVEL=1 or
passing -/dbg=1 on the command line. See "perldoc ClearCase::Argv" and
"perldoc Argv" for (lots of) details.
require 5.006;
use AutoLoader 'AUTOLOAD';
use B;
use strict;
use warnings;
use vars qw(%Packages %ExtMap $libdir $prog $dieexit $dieexec $diemexec);
# Inherit some symbols from the main package. We will later "donate"
# these to all overlay packages as well.
BEGIN {
*prog = \$::prog;
*dieexit = \$::dieexit;
*dieexec = \$::dieexec;
*diemexec = \$::diemexec;
}
# For some reason this can't be handled the same as $prog above ...
use constant MSWIN => $^O =~ /MSWin|Windows_NT/i ? 1 : 0;
# This is the list of functions we want to export to overlay pkgs.
my @exports = qw(MSWIN GetOptions Assert Burrow Msg Pred ViewTag
AutoCheckedOut AutoNotCheckedOut AutoViewPrivate);
# Hacks for portability with Windows env vars.
BEGIN {
$ENV{LOGNAME} ||= $ENV{USERNAME};
$ENV{HOME} ||= "$ENV{HOMEDRIVE}/$ENV{HOMEPATH}";
}
# Unless the user has their own CLEARCASE_PROFILE, set it to the global one.
my ($dir, $subdir) = @_;
# Not sure how glob() sorts so force a standard order.
my @pms = sort glob("$dir/$subdir/*.pm");
for my $pm (@pms) {
my $dirQuoted = quotemeta($dir);
$pm =~ s%^$dirQuoted/(.*)\.pm$%$1%;
(my $pkg = $pm) =~ s%[/\\]+%::%g;
eval "*${pkg}::exit = \$dieexit";
eval "*${pkg}::exec = \$dieexec";
# In this block we temporarily enter the overlay's package
# just in case the overlay module forgot its package stmt.
# We then require the overlay file and also, if it's
# an autoloaded module (which is recommended), we drag
# in the index file too. This is because we need to
# derive a list of all functions defined in the overlay
# in order to import them to our own namespace.
{
eval qq(package $pkg); # default the pkg correctly
no warnings qw(redefine);
eval {
eval "require $pkg";
warn $@ if $@;
};
next if $@;
my $ix = "auto/$pm/autosplit.ix";
if (-e "$dir/$ix") {
eval { require $ix };
warn $@ if $@;
}
}
# Now the overlay module is read in. We need to examine its
# newly-created symbol table, determine which functions
# it defined, and import them here. The same basic thing is
# done for the base package later.
no strict 'refs';
my %names = %{"${pkg}::"};
for (keys %names) {
# Skip symbols that can't be names of valid cleartool ops.
next if m%^(?:_?[A-Z]|__|[ab]$)%;
my $tglob = "${pkg}::$_";
my $coderef = \&{$tglob};
# Take what survives the above tests and create a hash
# mapping defined functions to the pkg that defines them.
$ExtMap{$_} = $pkg;
# We import the entire typeglob for 'foo' when we
# find an extension func named foo(). This allows usage
# msg extensions (in the form $foo) to come over too.
eval qq(*$_ = *$tglob);
}
# The base module defines a few functions which the
# overlay's code might want to use. Make aliases
# for those in the overlay's symbol table.
for (@exports) {
eval "*${pkg}::$_ = \\&$_";
}
eval "*${pkg}::prog = \\\$prog";
$Packages{$pkg} = $INC{"$pm.pm"};
}
}
for my $subdir (qw(ClearCase/Wrapper ClearCase/Wrapper/Site)) {
for my $dir (@INC) {
return @vps;
}
=head1 CLEARTOOL ENHANCEMENTS
=over 4
=item * EXTENSIONS
A pseudo-command which lists the currently-defined extensions. Use with
B<-long> to see which overlay module defines each extension. Note that
both extensions and their aliases (e.g. I<checkin> and I<ci>) are
shown.
=cut
sub extensions {
my %opt;
GetOptions(\%opt, qw(short long));
my @exts = sort grep !/^_/, keys %ExtMap;
for (@exts) {
=item * 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 I<overlay> module. ClearCase::Wrapper will
automatically include ('require') all modules in the
ClearCase::Wrapper::* subclass. Thus, if you work for C<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 C<./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
C<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:
I<ClearCase::Wrapper::*> and I<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 I<ClearCase::Wrapper::TLA> overlay with enhancements that apply
anywhere within TLA and/or a I<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 C<TLA> was left out of the latter module name.
Overlays in the general I<ClearCase::Wrapper::*> namespace are
traversed before I<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
examples/README view on Meta::CPAN
The ct.bat file is an example of a redirector. If you have a UNIX/SMB
solution such as Samba running you should be able to use this to
execute the exact same script, same copy, on Unix and Windows.
The MySite.tar.gz file is a sample enhancement overlay. To create
your own cleartool enhancements, you should be able to simply
unpack MySite.tar.gz, change all references to 'MySite' (including
the containing directory) to something which makes more sense for
your site. Then add subroutines to the (renamed) MySite.pm file
and go through the standard
perl Makefile.PL
make
make test
make install
sequence and test your additions. Don't forget to put your new module
under source (ClearCase) control.
Alternatively, if you want to develop an enhancement which isn't
site-specific and that you want to release to CPAN, remove the 'Site'
part from the package namespace, add copyright and license information,
and you're away.
The CGC.tar.gz file is similar to MySite, but it's a real site-specific
overlay that I use. Normally the whole point of overlays in the Site::*
namespace is that they're not released but I ship mine for pedagogical
purposes. So please don't install it as is; use it as a reference
for site-specific overlays.
( run in 1.260 second using v1.01-cache-2.11-cpan-d8267643d1d )