NAME

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

SYNOPSIS

my $crdb = ClearCase::CRDB->new(@ARGV);	# @ARGV is a list of DO's

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.

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:

$obj->method;

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

• iwd

  Returns the directory marked as "Initial working directory" 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");

AUTHOR

David Boyce <dsb@boyski.com>

COPYRIGHT

Copyright (c) 2000,2001 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 and 5.6.0. However, the code does a require 5.6.0 since I no longer test with anything earlier.

BUGS

Please send bug reports or patches to the address above.

SEE ALSO

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