VCS::PVCS - A Perl interface to the PVCS Version Manager

Copyright (c) 1998  Bill Middleton

This is the VCS::PVCS module, a suite of perl packages which provide
an interface to the Intersolv PVCS Version Control tools, folders,
files, archives, and access-control mechanisms. 

DESCRIPTION

  This module gives the PVCS user/admin a simple (hopefully), 
object-oriented interface to the various components of a PVCS Project, 
including the Project itself, it's folders, archives, and the 
attributes for each of these members, as designated by the project's 
administrator(s).

  You can operate on existing projects and their members, or create 
new projects, folders and archives using the methods defined in
the interface.  Operations on archive objects, in particular, use the
PVCS Command-Line tools, VCS, GET, PUT, VDIFF, and VLOG.  (others
may be supported in the future).

  The preferred method for operating within PVCS is to use Folders,
and the interface provides you with the ability to perform command-line
actions to some or all of a folder's members at once, simplifying the
process of release-tagging and making releases, nightly builds, version
history for metrics, and many other operations on the archives, which
may be performed in an automated fashion using cron or some other
time-scheduling tool.  You can also operate on entire projects at once,
or individually on archive objects by themselves.  Additionally, the
Commands.pm exports all of it's methods for a simple, if slightly more
complicated, interface to the PVCS commands directly (you supply the
file/archive names).

Here's an example:


use VCS::PVCS::Project;
use Cwd;

# Open a project
my $proj = new VCS::PVCS::Project("Existing Project");

# Open all of the "docs" folders and return ref to array
@folders  = $proj->openFolders("docs");

foreach $folder (@folders){
    # Checkout all files in the folder
    $folder->checkout("-l");  # Checkout all archives with lock

    # Populate the attributes object for each file in the folder
    $folder->getAttributes;

    # Get a list of archive object members of the folder and ck for locks
    @members = $folder->members;
    foreach $member (@members){
        $attributes = $member->attributes;  # Get the attributes object
        print $attributes->Workfile," : ",$attributes->Locks,"\n";
    }

    $folder->checkin('-f','-M"Checked in from test"');  # Checkin all archives 

    # Reload the attributes for all files  (with 1 as argument)
    $folder->getAttributes(1);

    foreach $member (@members){
        $attributes = $member->attributes;  # Get the attributes hash
        print $attributes->Workfile," : ",$attributes->Last_trunk_rev,"\n";
    }

    # Add/change/delete some version labels

    # add foobar to the tip
    $folder->addVersionLabel("foobar");

    # Add a version label to an earlier version
    $folder->addVersionLabel("bazbar:1.0");
    
    # Convert a version label to floating
    $folder->transformVersionLabel("foobar");
    
    # delete a version label
    $folder->deleteVersionLabel("foobar");

    # Rename a version label
    $folder->replaceVersionLabel("blahblek","bazbar");

    # Promote all of the 1.0 revisions to the Prodtest group
    $folder->addPromoGroup("Prodtest:1.0");

    # take a diff on all members against the two versions (default)
    foreach $member (@members){
        $member->vdiff("-R1.0 -R1.1");
        print $PVCSOUTPUT;
    }
}



WARNING:

    This is ALPHA SOFTWARE. You should consider the interface methods,
inheritance heirarchy, parameters, and objects to be in a unfinis

:-)

QUICK START GUIDE

  This VCS::PVCS module must make several assumptions about your
PVCS environment.  You must have the following ENVIRONMENT variables
set, in order for things to work "out of the box".

$PVCS_BINDIR - this is where the PVCS binaries all live.  It can
(and should) be hardwired in the VCS/PVCS.pm file before installation.

$ISLVINI - this per-user environment variable is the location of
the .islvrc (islv.ini on WINDOWS) file.  This file should specify
locations for at least the following:

    PVCSPROJ=/path/to/pvcs/projects/master/directory  # Master PVCS dir
    NFSMAP=/path/to/directory/where/nfsmap/is/located  # unix dir for nfsmap

Normally, this file is found in the HOME or C:\WINNT directory under
unix/Win respectively.  If not, you'll have to hardwire it or set
it in the environment.  The example script shows you how to do this.

The other variable which may have to be hand configured is the location
of the MASTER.CFG file, which has information about the default
configuration for PVCS.  When we created our setup here, it was
named MASTER.CFG, and found in $PVCSPROJ.  I've hardcoded this into
the PVCS.pm module. If this convention is non-standard, or not the 
way it works on UNIX-only environments, you'll need to change it, 
and please let me know at wjm@metronet.com ASAP.  Just search PVCS.pm 
for $PVCSMASTERCFG and change it in the locations you find.  You
wont need to change it anywhere else.

Once you've set these, you can install the package, and run the
test scripts.  Note that the test scripts make attempts to configure
themselves automatically and create and use a COMPLETELY SEPARATE
PVCSPROJ directory.  Running the test scripts will, in no way affect
your PVCS installation.

    perl Makefile.PL
    make
    make test
    make install


DOCUMENTATION

  The documentation, except for this file, is embedded POD, and
found in the .pm files themselves.  You can run pod2html against
them to get HTML documentation, and the manpages are created automatically
by the make.

  The documentation can be found also at my web site,

  http://www.metronet.com/~wjm/PVCS

MORE INFORMATION - Mailing List, etc.

While it doesn't actually exist yet, I plan to implement a mailing
list for this module.  For more information and to keep informed 
about new developments with this module suite, you can join the 
a mailing list (pvcs-perl@w5.metronet.com) by sending a subscribe to 
pvcs-perl-request@w5.metronet.com, or drop me a line at 
wjm@metronet.com, and I'll add your name.

IF YOU HAVE PROBLEMS

I'm pretty busy.  You can drop me a line, or send a note to the
mailing list (once it exists..) and I'll try to help when I can.  
Patches are gratefully accepted.

DESIGN

  The components of PVCS, namely PROJECTS, FOLDERS, ARCHIVES,
and ATTRIBUTES, lend nicely to an OO design.  e.g. - Archives
inherit from Attributes, Folders inherit from Archives, and
Projects inherit from both folders and archives.  I've tried to
implement this in this package, so that you can operate on a
given component and rely on the fact that all  of it's subcomponents
will be properly handled.

HOWEVER, and thats a BIG HOWEVER, IMHO, the best and only way
to use PVCS is through folders.  Many of our projects here where
I work have dozens of folders, some mapping to TEST directories,
some mapping to DEVELOPMENT directories (sometimes on the local
disk), and some designated for RELEASE folders as readonly checkouts.
I recommend that you use the folder objects liberally,
and possibly, exclusively, when operating on your PVCS project.

See the test scripts for complete examples of how to use folder
objects, and operate on folder members (archives) in a nice way.

NOTES

  The PVCS crossplatform capability gives rise to some interesting
problems.  Namely, all paths in the config files and paths for documents,
folders, etc, are stored as Windows paths, if the project was created
on windows, or if the project was created on UNIX using an NFSMAP.
(See the PVCS GUI documentation/README for details on the NFSMAP)
Thus, when we find and NFSMAP, we assume that ALL output must be
translated to WINDOWS format when creating new folders, archives,
or doing queries using the SQL components.  


SECURITY

  I like PVCS. I've administered and used ClearCase, PVCS, CVS and
SourceSafe, and PVCS seems to be the best choice for an environment
of developers that aren't all kernel hackers, but are interested
in establishing a sound CM process. It's easy to learn, without
having to take courses, safe (NO DATABASE, YEA!), and relatively
powerful, with triggers, promotion groups, and other features to
help you implement your site policy. 

 On the other hand, I'm not too fond of the PVCS GUI.  On the third hand,
the GUI does keep the user at a (usually) safe distance from the
filesystem, with some security mechanisms (depending on how you
set it up).  This module lets the user get much closer to the filesystem,
and doesn't give a whit (yet) about the access permissions, except to
code in a default parameter for all commands which includes the access 
permissions in (-C MASTER.CFG) if they are defined.  This, of course, 
can be hacked around, and the user can perform any operation on an archive 
that the filesystem will let him/her get away with. Caveat scriptor.

Best regards, and happy CM'ing!

Bill


----
Bill Middleton
wjm@metronet.com