NAME

ClearCase::CRDB - Class for ClearCase config-record analysis

SYNOPSIS

my $crdb = ClearCase::CRDB->new(@ARGV);	# Initialize object
$crdb->check;				# Do a CR sanity check
$crdb->catcr;				# Analyze the recursive CR
$crdb->store($filename);			# Dump CR to $filename

DESCRIPTION

A ClearCase::CRDB object represents the (potentially recursive) configuration record (hereafter CR) of a set of derived objects (hereafter DOs). It provides methods for easy extraction of parts of the CR such as the build script, MVFS files used in the creation of a given DO, make macros employed, etc. This is the same data available from ClearCase in raw textual form via cleartool catcr; it's just broken down for easier access and analysis.

An example of what can be done with ClearCase::CRDB is the provided whouses script which, given a particular DO, can show recursively which files it depends on or which files depend on it.

Since recursively deriving a CR database can be a slow process for large build systems and can burden the VOB database, the methods ClearCase::CRDB->store and ClearCase::CRDB->load are provided. These allow the derived CR data to be stored in its processed form to a persistent storage such as a flat file or database and re-loaded from there. For example, this data might be derived once per day as part of a nightly build process and would then be available for use during the day without causing additional VOB load.

The provided ClearCase::CRDB->store and ClearCase::CRDB->load methods save to a flat file in human-readable text format. Different formats may be used by subclassing these two methods. An example subclass ClearCase::CRDB::Storable is provided; this uses the Perl module Storable which is a binary format. If you wanted to store to a relational database this is how you'd do it, using Perl's DBI modules.

CONSTRUCTOR

Use ClearCase::CRDB->new to construct a CRDB object. If @ARGV is passed in, the constructor will automatically parse certain standard flags from @ARGV and use them to initialize the object. See the usage method for details.

INSTANCE METHODS

Following is a brief description of each supported method. Examples are given for all methods that take parameters; if no example is given, usage may be assumed to look like:

my $result = $obj->method;

Also, if the return value is described in plural terms it may be assumed that the method returns a list.

• usage

  Returns a string detailing the internal standard command-line flags parsed by the ->new constructor for use in the script's usage message.

• crdo

  Sets or gets the list of derived objects under consideration, e.g.:

  $obj->crdo(qw(do_1 do_2);	# give the object a list of DO's
  my @dos = $obj->crdo;	# gets the list of DO's

  This method is invoked automatically by the constructor if derived objects are passed to it.

• catcr

  Invokes cleartool catcr on the DO set and breaks the resultant textual data apart into various fields which may then be accessed by the methods below. This method is invoked automatically by the constructor (see) if derived objects are specified.

• check

  Checks the set of derived objects for consistency. For instance, it checks for multiple versions of the same element, or multiple references to the same element under different names, in the set of config records.

• store

  Writes the processed config record data to the specified file (default = stdout).

• load

  Reads processed config record data from the specified files.

• needs

  Takes a list of derived objects, returns the list of prerequisite derived objects (the derived objects on which they depend). For example, if foo.c includes foo.h and compiles to foo.o which then links to the executable foo, the ->needs method when given foo.o would return the list ('foo.c', 'foo.h'). In other words it returns "upstream dependencies" or prerequisite derived objects.

• makes

  Takes a list of derived objects, returns the list of derived objects which use them. This is the reverse of needs. Given the needs example above, the ->makes method when given foo.o would return foo. In other words it returns "downstream dependencies".

• unmentioned

  Takes a list of derived objects, returns the list of prerequisite DOs which were not mentioned in the makefile. Useful for finding makefile bugs.

• iwd

  Each target in a CR has an "initial working directory" or iwd. If passed a DO, this method returns the iwd of that derived object. With no parameters it returns the list of iwds mentioned in the CR.

• files

  Returns the complete set of files mentioned in the CR.

• targets

  Returns the subset of files mentioned in the CR which are targets. Takes one optional boolean parameter, which if true causes sibling derived objects to be returned also.

• terminals

  Returns the subset of targets which are terminal, i.e. those which do not contribute to other derived objects.

• vars

  In a list context, returns the set of make macros used in the build script for the specified DO, e.g.:

  my @list = $obj->vars("path-to-derived-object");

  In scalar context, returns a ref to the hash mapping vars to values:

      my $vhash = $obj->vars("path-to-derived-object");
      for my $var (keys %$vhash) {
  	print "$var=", $vhash->{$var}, "\n";
      }

• val

  Returns the value of the specified make macro as used in the build script for the specified DO:

  my $value = $obj->val("path-to-derived-object", "CC");

• notes

  Returns the set of "build notes" for the specified DO as a list. This is the section of the CR which looks like:

  Target foo built by ...
  Host "host" running ...
  Reference Time ...
  View was ...
  Initial working directory was ...

  E.g.

  my @notes = $obj->notes("path-to-derived-object");

• script

  Returns the build script for the specified DO:

  my $script = $obj->script("path-to-derived-object");

There are also some undocumented methods in the source. This is deliberate; they're experimental.

AUTHOR

David Boyce <dsbperl AT cleartool.com>

COPYRIGHT

Copyright (c) 2000-2005 David Boyce. All rights reserved. This Perl program is free software; you may redistribute and/or modify it under the same terms as Perl itself.

STATUS

This is currently ALPHA code and thus I reserve the right to change the API incompatibly. At some point I'll bump the version suitably and remove this warning, which will constitute an (almost) ironclad promise to leave the interface alone.

PORTING

This module has been at least slightly tested, at various points in its lifecycle, on almost all CC platforms including Solaris 2.6-8, HP-UX 10 and 11, and Windows NT4 and Win2K SP2 using perl 5.004_04 through 5.6.1 and CC4.1 through 5.0. However, I tend to use the latest of everything (CC5.0, Solaris8, Win2KSP2, Perl5.6.1 at this writing) and cannot regression-test with anything earlier. Also, note that I rarely use this on Windows so it may be buggier there.

BUGS

NOTE: A bug in CC 5.0 causes CRDB's "make test" to dump core. This bug is in clearmake, not CRDB, and in any case affects only its test suite. The first CC 5.0 patch contains a fix, so you probably don't want to use CC 5.0 unpatched. If you do, ignore the core dump in the test suite and force the install anyway.

Please send bug reports or patches to the address above.

SEE ALSO

perl(1), ct+config_record(1), clearmake(1) et al