=head1 NAME Configuration -- Configuration for ClearCase::Wrapper::MGi =head1 SYNOPSIS Four methods, to configure different aspects: =over 4 =item C<##:BranchOff: root> in the config spec =item .clearcase_profile.pl =item environment variables =item variables in the configuration modules =back =head1 DESCRIPTION The I<extra> directory contains files which can be used to configure the wrapper for specific needs, either on a site on a user basis. The features described here are not enabled by default. One functionality is highly experimental (the C<FSCBROKER> environment variable): fixing the layout of source containers for elements of text_file and derivate types, in conjunction with the I<BranchOff> mechanism =head2 BranchOff The I<BranchOff> mechanism is one of the two driving forces of this wrapper (the other one being I<incremental type families>). The intention is to make it possible to always branch off, when checking out a version not already on a branch one created oneself; this without ending up cascading 'forever', i.e. until meeting system limits. The setup is simple, and per view. Start your config spec with a meta-comment such as: ##:BranchOff: root The effect will be to interpret C<mkbranch> directives (in the config spec) as injonctions to branch off the root of the version tree for every element (usually C</main/0>). The relation to the predecessor version is not lost: it is reestablished with a C<Merge> hyperlink. As this might result in 'bloated' source containers (in fact a very minor concern, even with certain advantages), an additional, optional setup may be considered: see below. =head3 fixsrccnt, FixSrcCont.pm, FSCbrokerSuDo, FSCbrokerSsh These files implement the experimental feature: I<fix source containers>. The rationale is documented in: L<http://code.google.com/p/clearcase-cpan/wiki/TypeMgr> These files are not installed by C<make install>, and are largely provided as templates for you to configure according to yourown environment. =head4 fixsrccnt This should be installed in a path accessible from every client, possibly in a vob. The path to C<perl> is the only part I changed myself. =head4 FixSrcCont.pm This must be installed as C<ClearCase::FixSrcCont> in a path in C<$INC>. Note that installing the file (e.g. for one user) is not enough to enable its use (e.g. for others). Remember to set there the path to the previous script, unless the default is suitable (unlikely since host local): my $fxsc = '/usr/local/bin/fixsrccnt'; =head4 FSCbrokerSuDo and/or FSCbrokerSsh These two scripts implement alternatives to make it possible to run C<fixsrccnt> as vob owner, for every possible argument (hence potentially multiple vob owner accounts). The C<sudo> alternative is preferred on UNIX, but the C<ssh> one is needed from Windows or Cygwin (note: that the current implementation is restricted to UNIX vob servers!) Install in a path reachable from every client, and setuid to an account trusted by every vob server account in the appropriate way (i.e. using C<sudo>, this may be restricted to using C<fixsrccnt> but in a passwordless way). Adjust the paths to C<perl> and to C<fixsrccnt>. In addition, check the path to C<sudo> for C<FSCbrokerSuDo>, which uses the C<Sudo> CPAN package (which you have to install). For C<FSCbrokerSsh>, the C<$sshhost> must be set. The template also assumes an installation in a vob, hence uses a C<$view>. Otherwise, it uses the same C<Net::SSH::Perl> CPAN package as does C<ForceLock> (see below). To enable the functionality, you must select the variant of the script suitable for your system, and set the environment variable accordingly: FSCBROKER=ClearCase::FSCbrokerSuDo =head2 VobPathConv.pm I<VobPathConv.pm> (and its pod file) does not require any configuration and may be used as such. I may even consider to extract it and publish it as a separate package in its own, albeit modest, right. It offers functions to convert paths from Windows to Unix, using the registry to map the tags in associated regions. It must be installed in the C<@INC> path as C<ClearCase::VobPathConv>. =head2 ForceLock The remaining files are mostly concerned with locking and unlocking label types owned by other people (colleagues, members of the same group, vob owner...). The lack of such an ability is considered a bug in ClearCase, and is the object of an RFE (currently rejected...). It defeats the use of locking in general. The installer must select the solution(s) best adapted to her case, possibly edit a few fields appropriate to her environment, and copy the suitable file by hand to the lib/site_perl directory. Users must pick up these configurations with environment variables, e.g. setting them in their C<~/.clearcase_profile.pl> file I<ForceLockSudo.pm> implements the simplest, safest and most efficient solution, from unix. As its alternatives, dealing with cases in which this superior solution could not be used, it is meant to be installed in the C<@INC> path, under a ClearCase directory, and accessed via an environment variable FORCELOCK=ClearCase::ForceLockSudo This is so its use would not penalize functions which do not require locking. Two other versions are provided for now, one for unix, and one for Windows (and cygwin): FORCELOCK=ClearCase::ForceLockUnix #Unix FORCELOCK=ClearCase::ForceLock #Windows These can be used as examples or a templates. They require some customization. The two latter build upon I<locklbtype>, a standalone script, to be installed suid enabled, owned by an account, which is itself authorized in the configurations of the respective vob owners of all vobs in the local region, to run locking commands. It acts as a switch, allowing to simplify the maintainance of the authorization setup. Two variants are proposed: one using ssh, the other using sudo. Only the most suitable one needs to be installed, as I<locklbtype>. The appropriate setup will have to be performed respectively in the vob owner accounts' I<~/.ssh/authorized_keys> files, or in the host based or system-wide I</etc/sudoers> file. Both variants require a minimal customization. For ssh, one needs to set the name of the host running an sshd daemon Note that one needs to avoid using I<localhost> here, so that different host keys do not overwrite each other in the I<~/.ssh/known_hosts> files. For both, one may also set the name of the log used to save the identity of the unlocking users (for lock events, this is saved in a comment of the locks). The paths to ssh or sudo, cleartool and perl are likely to be satisfying. In order to use this script, we needed to define a pair of functions, for locking and unlocking. The unix version of the I<ClearCase::ForceLock> module, is meant to invoke locklbtype via a system call, therefore using the suid bit mechanism offered by unix shells. The only customization is the path to the locklbtype utility. In a Windows environment, the related module fills the same role, but invokes the suid script on a unix host, via ssh. As perl is found in a vob on my unix environment, I need to customize a view tag in addition to the host name and the path to the script. Ssh is accessed with the Net::SSH::Perl module. It depends on a long list of modules, which I could successfully install on: I<cygwin 1.7 / perl 5.10 / libgmp-devel 4.3.1-1, libssh2, pari-gp 2.3.5> and on I<Windows Vista / Strawberry perl 5.12 / GMP-4.1.2>: Digest-SHA1-2.1 Digest-HMAC-1.01 Class-ErrorHandler-0.01 Convert-ASN1-0.22 Crypt-CBC-2.30 Crypt-DES-2.05 Crypt-Blowfish-2.10 Crypt-DES_EDE3-0.01 Convert-PEM-0.07 Data-Buffer-0.04 Class-Loader-2.03 Convert-ASCII-Armour-1.4 Digest-MD2-2.03 Sort-Versions-1.5 Tie-EncryptedHash-1.24 Digest-BubbleBabble-0.01 String-CRC32-1.4 Math::GMP-2.05 Math::BigInt::GMP-1.24 Math::BigInt-1.89 Net::SSH::Perl-1.34 On cygwin, I had in addition to install: Crypt-DH-0.06 Crypt-DSA-0.14 Crypt-IDEA-1.08 Math-Pari-2.01080604 Crypt-Random-1.25 Crypt-Primes-0.50 Crypt-RSA-1.98 Note that these are just the versions I use, and which work for me. I cannot claim that this list is a minimal requirement. =head2 .clearcase_profile.pl This file is meant to be found in the user home directory. It is common to all possible wrappers derived from ClearCase::Wrapper. It may be symlinked from a shared version, for sitewise configuration. An example of I<.clearcase_profile.pl> sets the ipc mode for all commands apart for setview (unavailable then, assuming the wrapper itself is used from a vob). An other setting for this file is: $ClearCase::Wrapper::MGi::global = 1; This setting drives I<mklbtype> and I<mkbrtype> to create I<global> types (including the metadata types) in vobs having an admin vob. This used to be the default with I<ClearCase::Wrapper::DSB>. Next possible setting: $ClearCase::Wrapper::MGi::lockbl = 1; If this is set, the baseline type is locked in the end of a rollout. Conversely, a next rollout is aborted if the baselin is found unlocked on entry, in order to prevent possible collisions of independent rollouts. This would be the default if locking/unlocking by group members was supported natively by ClearCase, instead of depending on user configuration. Note that one might e.g. add there code such as: umask(002); This ensures that under cleartool (from the wrapper), group members are granted write access e.g. to directory elements being created. The example provided also sets an environment variable (see below). =head2 environment variables Four variables to consider (see earlier for the two first): FORCELOCK FSCBROKER CLEARCASE_TAB_SIZE: affects the annotate format (default: 2) CCMGI_ANNF: annotate format CCMGI_ANNL: length of the prefix in the annotate format (before the actual file contents) The default annotate format is: %Sd %25.-25Vn %-9.9u,|,%Sd %25.-25Vn %-9.9u This means: a short date, a 25 chars right aligned, possibly truncated field for the version specification, a 9 chars left aligned field for the author. The same format is used for elisions as for additions. Its corresponding prefix length is: 49 (10 for the date, 25 for the version, 9 for the id, 2 for space separators, and 3 for the deletion marker--including spaces). This prefix is used to compute the beginning of the text upon which to apply regexps in case of using the C<-grep> option of C<annotate>.