NAME

ClearCase::CRDB - base class for ClearCase config-record analysis

SYNOPSIS

my $crdb = ClearCase::CRDB->new(@ARGV);	# @ARGV is a list of DO's
$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 recursive configuration record (aka CR) of a set of derived objects (aka DO's). 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 from "cleartool catcr -recurse DO ..."; 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 native ClearCase::CRDB->store and ClearCase::CRDB->load methods store 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 database this is how you'd do it.

CONSTRUCTOR

Use ClearCase::CRDB->new to construct a CRDB object. Any parameters given will be taken as the set of derived objects to analyze.

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.

• 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 (see) if derived objects are specified.

• catcr

  Invokes cleartool catcr -recurse 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.

• load

  Reads processed config record data from the specified files.

• needs_do

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

• makes_do

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

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

• vars

  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");

• 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 <dsb@boyski.com>

COPYRIGHT

Copyright (c) 2000-2002 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.

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 and install anyway.

Please send bug reports or patches to the address above.

SEE ALSO

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