Subversion Repositories DevTools

########################################################################
# Copyright (C) 1998-2008 ERG Limited, All rights reserved
#
# Module name   : jats_svnrelease.pl
# Module type   : Jats Utility
# Compiler(s)   : Perl
# Environment(s): Jats
#
# Description   : A script to build a package from a SubVersion
#                 The script will:
#                   Create a workspace
#                   Checkout the files
#                   Locate the build file
#                   Build the packages
#                   Install packages
#                   Remove the view
#
#               The script can do a lot of other things too.
#
# Notes         : A lot of this code is common to jats_ccrelease.pl
#                 Will need to refactor if both are to be used
#
#......................................................................#

require 5.006_001;
use strict;
use warnings;
use JatsError;
use JatsSystem;
use FileUtils;
use JatsBuildFiles;
use ArrayHashUtils;
use JatsSvn;

use Pod::Usage;                             # required for help support
use Getopt::Long;
use File::Find;
use File::Copy;
use File::Path;
use Cwd;

my $VERSION = "1.0.0";                      # Update this

#
#   Options
#
my $opt_debug   = $ENV{'GBE_DEBUG'};        # Allow global debug
my $opt_verbose = $ENV{'GBE_VERBOSE'};      # Allow global verbose
my $opt_help = 0;                           # User help level
my @opt_spec;                               # Labels used as a base for the view
my $opt_dpkg = 1;                           # Transfer built package to dpkg_archive
my $opt_copy = 0;                           # Copy built package to user
my $opt_reuse = 0;                          # Re-user view if it exists
my $opt_viewname;                           # View Name
my $opt_extract;                            # Just create a static view
my $opt_extract_files;                      # Just extract files to user - no view
my $opt_delete = 0;                         # Just delete the view. 2 to force
my @opt_build;                              # build files to use (kludge)
my $opt_test;                               # Test the build process - no copy
my $opt_cache;                              # Cache external packages
my $opt_keep = 0;                           # Keep view if successful
my $opt_beta;                               # Create beta release
my $opt_merge;                              # Merge release
my $opt_path;                               # Path for view spec
my $opt_runtests = 1;                       # Run unit tests after build
my $opt_branch;                             # Create config spec with branch
my $opt_debug_build = 0;                    # Build Debug Only
my $opt_prod_build = 0;                     # Build ion Only
my $opt_view_root = $ENV{'GBE_VIEWBASE'};   # Root of the view
my $opt_prefix = 1;                         # Prefix the view tag with user-name
my $bad_label_name = 0;                     # Badly formed label

#
#   Globals - Provided by the JATS environment
#
my $USER            = $ENV{'USER'};
my $UNIX            = $ENV{'GBE_UNIX'};
my $HOME            = $ENV{'HOME'};
my $GBE_SANDBOX     = $ENV{'GBE_SANDBOX'};
my $GBE_ABT         = $ENV{'GBE_ABT'} || '0';
my $MACHINENAME     = $ENV{'GBE_HOSTNAME'};

#
#   Globals
#
my $VIEWDIR_ROOT = "c:/clearcase";          # Root of all static views (WIN32)
my $VIEWDIR;                                # Absolute path to the view
my $VIEWPATH;                               # Path relative to clearcase
my $user_cwd;
my $error = 0;
my $label_count = 0;                        # Number of labels to create the view
my @label_not_pegged;                       # List of unpegged labels

my $UNIX_VP_ROOT    = 'jats_cbuilder';
my $view_prefix     = "${USER}_";

#-------------------------------------------------------------------------------
# Function        : Mainline Entry Point
#
# Description     :
#
# Inputs          :
#

#
#   Alter some option defaults if we are creating a view within a sandbox
#
if ( $GBE_SANDBOX )
{
   $opt_view_root = $GBE_SANDBOX;
   $opt_prefix = 0;
}

#
#   Parse the user options
#
my $result = GetOptions (
                "help:+"        => \$opt_help,              # flag, multiple use allowed
                "manual:3"      => \$opt_help,              # flag
                "v|verbose:+"     => \$opt_verbose,           # flag, multiple use allowed
                "label=s"       => \@opt_spec,              # Array of build specs
                "view=s"        => \$opt_viewname,          # String
                "dpkg!"         => \$opt_dpkg,              # [no]flag
                "copy!"         => \$opt_copy,              # [no]flag
                "reuse!"        => \$opt_reuse,             # [no]flag
                "extract"       => \$opt_extract,           # flag
                "extractfiles"  => \$opt_extract_files,     # flag
                "delete:+"      => \$opt_delete,            # flag
                "build=s"       => \@opt_build,             # An array of build
                "test!"         => \$opt_test,              # [no]flag
                "cache"         => \$opt_cache,             # flag
                "keep!"         => \$opt_keep,              # [no]flag
                "beta!"         => \$opt_beta,              # [no]flag
                "merge"         => \$opt_merge,             # [no]flag
                "path=s"        => \$opt_path,              # string
                "runtests!"     => \$opt_runtests,          # [no]flag
                "branch=s"      => \$opt_branch,            # String
                "mkbranch=s"    => \$opt_branch,            # String
                "prodOnly"      => \$opt_prod_build,        # flag
                "debugOnly"     => \$opt_debug_build,       # flag
                "root=s"        => \$opt_view_root,         # string
                "prefix!"       => \$opt_prefix,            # flag
                );

                #
                #   UPDATE THE DOCUMENTATION AT THE END OF THIS FILE !!!
                #

#
#   Process help and manual options
#
pod2usage(-verbose => 0, -message => "Version: $VERSION")  if ($opt_help == 1  || ! $result);
pod2usage(-verbose => 1)  if ($opt_help == 2 );
pod2usage(-verbose => 2)  if ($opt_help > 2 );

InitFileUtils();

#
#   Configure the error reporting process now that we have the user options
#
ErrorConfig( 'name'    => 'SVNRELEASE',
             'verbose' => $opt_verbose );

#
#   Validate user options
#   Use either -label or one command line argument
#
Error ("Unexpected command line arguments present.","Cannot mix -label and command line label" )
    if ( $#opt_spec >= 0 && $#ARGV >= 0);

push @opt_spec, @ARGV;

unless(  @opt_spec  )
{
    Error ("Need a view or a label. -help for options") if ( $opt_delete  && ! $opt_viewname );
    Error ("Need a label or config_spec. -help for options") unless $opt_delete;
}

#
#   Convert label with embedded VCS information into a 'normal' form.
#   Form:
#       SVN::<URL>
#
foreach ( @opt_spec )
{
    s~^SVN::~~;
    Error ("Label contains invalid Version Control Identifier: $_")
        if ( m~^(.+)::.+~ );
    Verbose ("Clean URL: $_");
}

#
#   Limit the user to ONE label/tag/
#   Reason: Under Subversion its not possible to 'pinch' files from another
#           package. Don't need to create a workspace with multiple labels
#
#           It was a bad practice under clearcase
#
#
if ( $#opt_spec >= 1 )
{
    Error ("Multiple labels not supported",
           "Use one label to describe a package" );
}

#
#   User has specified both debug and production
#   Then set both to 0 : ie default
#
if ( $opt_debug_build + $opt_prod_build > 1 )
{
    $opt_debug_build = 0;
    $opt_prod_build = 0;
}

#
#   User has requested test mode
#       - Don't copy
#       - Don't packgae
#
if ( $opt_test )
{
    $opt_dpkg = 0;
    $opt_copy = 0;
}

#
#   Determine the machine type
#
Verbose ("Machine Type: UNIX=$UNIX");

Error ("Machine Name not determined")
    unless ( $MACHINENAME );
$user_cwd = getcwd;

Error ("USER name not determined" )
    unless ( $USER );

#
#   Under UNIX, create views in the user home directory
#
unless ( $opt_view_root  )
{
    if ( $UNIX )
    {
        Error ("Unix HOME EnvVar not defined" ) unless ( $HOME );
        Error ("Unix HOME directory not found: $HOME" ) unless (-d $HOME );
        $VIEWDIR_ROOT = "$HOME/$UNIX_VP_ROOT";
        Verbose ("Unix viewpath: $VIEWDIR_ROOT");
        mkdir ( $VIEWDIR_ROOT ) unless (-d $VIEWDIR_ROOT);
    }
}
else
{
    $opt_view_root = Realpath($opt_view_root) || $opt_view_root;
    $VIEWDIR_ROOT = $opt_view_root;
}

Verbose ("Viewpath: $VIEWDIR_ROOT");
Error ("Cannot locate view root directory: $VIEWDIR_ROOT" ) unless (-d $VIEWDIR_ROOT);

#
#   Remove any user name from the front of the view name
#   Simplifies the deletion process as the user can provide
#   the directory name
#
$view_prefix = "" unless ( $opt_prefix );

#
#   Create a class to describe the complete SVN label
#   This will parse the label and create a number of nice elements
#
my $svn_label = NewSessionByUrl ( $opt_spec[0] );

#
#   Setup user specified workspace
#   Include the user name to ensure that the view name is unique-ish
#   Keep the name as short as possible as some compilers display a fixed
#   length filename in error messages and this name is part of the path
#
#   Base the viewname on the view label. This will simplify the creation
#   of multiple views and reduce the risk of unexpected deletion
#
if ( $opt_viewname )
{
    Error ("View Name contains invalid characters" )
        unless ( $opt_viewname =~ m~^[-.:0-9a-zA-Z_]+$~ )
}
else
{
    #
    #   Create a view name based on the provide 'label'
    #
    if ( $svn_label->Type )
    {
        $opt_viewname = $svn_label->Path;
        $opt_viewname .= '_' . ($svn_label->Version || 'trunk');
    }
    else
    {
        $opt_viewname = $svn_label->Path;
        $bad_label_name = 1;
    }

    #
    #   If creating a branch, then insert the branch name
    #   into the workspace name
    #
    $opt_viewname .= '_' . $opt_branch if ( $opt_branch );
    
    #
    #   Create a singe dir name
    #   Remove path sep characters and replace with _
    #
    $opt_viewname =~ tr~\\/:~_~s;

}
$opt_viewname =~ s~^$view_prefix~~ if (defined($opt_viewname) && $view_prefix && $opt_delete );

#
#   Create a clearcase view to be used for the view
#
$VIEWPATH = "$view_prefix$opt_viewname";
$VIEWDIR = "$VIEWDIR_ROOT/$VIEWPATH";
$VIEWDIR =~ tr~\\/~/~s;
Verbose( "Hostname: $MACHINENAME" );
Verbose( "Viewpath: $VIEWPATH" );
Verbose( "Viewdir : $VIEWDIR" );

#
#   If the user has specified a "source path", then we must ensure that it is
#   valid. It will be used to create the WorkSpace
#
#   Ensure that the path is a defined variable. If used prepend a / to simplify
#   concatenation.
#
Verbose("Validate Source Path");
if ( $opt_path )
{
    $opt_path =~ tr~\\/~/~s;
    $opt_path =~ s~/$~~;
    $opt_path =~ s~^/~~;

    Error( "Source Path has drive specifier" ) if ( $opt_path =~ m~^[A-Za-z]\:~ );
    $opt_path = '/'.$opt_path ;
}
else
{
    $opt_path = '';
}

#
#   If the view currently exists then it will be deleted if allowed
#
delete_view()
    unless ( $opt_reuse );

#
#   If the user is simply deleting the view then all has been done
#
exit 0
    if ( $opt_delete );


#
#   Ensure that the label is present within the specified VOB
#
Verbose("Ensure Labels can be found in a Repository");
Verbose ("Testing label: ". $svn_label->Full );
$label_count++;

$svn_label->SvnValidateTarget (
                    'cmd'    => 'SvnRelease',
                    'target' => $svn_label->Full,
                    'require' => 1,
                    );
#
#   Test for a pegged label
#
push @label_not_pegged, $svn_label->Full
    unless ( $svn_label->Peg );

#
#   If we are only extracting files then ...
#
if ( $opt_extract_files )
{
    extract_files_from_view();
    exit (0);
}

#
#   Create a new workspace
#
if (! -d $VIEWDIR || ! $opt_reuse )
{
    Message( "Create the workspace" . ($GBE_SANDBOX ? " in a SANDBOX" : ""));

    my $view_tag = $svn_label->Full;
    #
    #   If a branch is required then copy the source to the
    #   branch and then checkout the branch
    #
    if ( $opt_branch )
    {
        #
        #   Create the name of the branch
        #   Will be based on the current package
        #
        my $branch = $svn_label->BranchName($opt_branch, 'branches' );

        $view_tag = $svn_label->SvnCopy (
                            'old' => $view_tag,
                            'new' => $branch,
                            'comment' => 'Created by Jats SvnRelease branch request',
                            'replace' => 0 );

        $view_tag = $svn_label->Url( $view_tag);
    }

    $svn_label->SvnCo ( $view_tag, $VIEWDIR . $opt_path );
    Error ("Cannot locate the created Workspace")
        unless ( -d $VIEWDIR . $opt_path);

    #
    #   Create a local package archive
    #   May be needed for multipackage builds and it will prevent JATS from
    #   finding any outside the view
    #
    mkdir ( $VIEWDIR . '/local_dpkg_archive')
        unless ($GBE_SANDBOX);
}

#   Place a tag-file in the user-specified source path
#   This will be used by the build-tool to locate the 'source-path' of the
#   view, primarily for determining metrics.
#
#   Calculate where the dynmaic view will be
#   This differ between UNIX/WINDOWS
#
if ( $opt_path && $GBE_ABT)
{
    Message( "Create Build tagfile");
    my $cpath = $VIEWDIR . $opt_path;
    if ( -d $cpath )
    {
        TouchFile ( "$cpath/.jats.packageroot" );
    }
}

#
#   Locate the JATS build files within the populated view
#
chdir ($VIEWDIR) or Error( "Cannot chdir to $VIEWDIR");
Message( "Locating build files");

my $bscanner = BuildFileScanner( $VIEWDIR, 'build.pl', '--LocateAll' );
$bscanner->scan();
my @build_list = $bscanner->getInfo();
foreach my $be ( @build_list )
{
    Message( DisplayPath ("Build file: $be->{dir} Name: $be->{file}"));
}

#
#   If we are extracting the view then we are done
#   Display useful information for the user
#
if ( $opt_extract )
{
    Message  DisplayPath "View in: $VIEWDIR";
    Warning ("No build files found" )   if ( $#build_list < 0 );
    Warning( "Multiple build files found" )if ( $#build_list > 0 );
    Message ("Not all labels are pegged") if ( @label_not_pegged  );
    Message ("All labels are pegged") unless ( @label_not_pegged  );
    Message ("Badly formed label name" ) if ( $bad_label_name );
    Message ("Development Sandbox") if ( $GBE_SANDBOX );

    exit 0;
}

Error ("No build files found")  if ( $#build_list < 0 );

#
#   Determine the list of builds to perform
#   Ensure that the user-requested build files are present
#
#   The user specifies the build file, via the mangled package name
#   This is package_name . project extension (daf_utils.cr)
#
if ( $#opt_build  >= 0)
{
    Verbose( "Check and locate the build files");
    @build_list = ();
    foreach my $bentry ( @opt_build )
    {
        if ($bscanner->match( $bentry) )
        {
            UniquePush (\@build_list, $bscanner->getMatchList() );
            Verbose ("Found: $bentry");
        }
        else
        {
            Error ("Cannot locate requested build files for: $bentry")
        }
    }
}

#
#   Sanity test if we will transfer the generated package to dpkg_archive
#   There are some limits
#       1) Must have built from one label
#       2) That label must be locked
#       3) Only one build file
#       4) The view must not have been reused
#       5) The view has a branch rule
#       6) Cannot release from a sandbox
#
my @elist;
push @elist, "Package built from multiple labels" unless ( $label_count == 1 );
push @elist, "Package built from an unpegged label" if ( @label_not_pegged  );
push @elist, "Package built with multiple build files" if ( scalar @build_list > 1 );
push @elist, "Package from a reused view" if ( $opt_reuse && ! $opt_beta );
push @elist, "Package from a development sandbox" if ( $GBE_SANDBOX );
push @elist, "View contains a branch" if ( $opt_branch );
push @elist, "User has specified build files" if ( $#opt_build > 0 );
push @elist, "Badly formed label name" if ( $bad_label_name );

if ( @elist )
{
    Warning ("Cannot officially release the package.", @elist);
    Error ("Build terminated as it cannot be released") if ($opt_dpkg && ! $opt_beta);
}
Warning ("Beta Release") if $opt_beta;

#
#   Process each of the build files in the specified order
#
foreach my $be (@build_list)
{

    #
    #   We need to change to the build directory
    #   Moreover we need the local name of the build directory.
    #   Windows does not handle a UNC pathname to well (at all)
    #
    my $build_dir = $be->{dir};
    chdir ("$build_dir") or Error( "Cannot chdir to build directory: $build_dir");

    if ( $be->{file} =~ m/^build.pl$/ )
    {
        Message ("Using JATS: $build_dir");
        #
        #   Invoke JATS to build the package and make the package
        #
        my @build_args = qw(--expert --cache);
        push @build_args, '--cache' if $opt_cache;

        my $make_type = 'all';
        $make_type = 'all_prod'  if ( $opt_prod_build );
        $make_type = 'all_debug' if ( $opt_debug_build );


        JatsCmd('build', @build_args)               and Error("Package did not build");
        JatsCmd('make', $make_type, 'NODEPEND=1')   and Error("Package did not make");
        JatsCmd('install');

        if ( $opt_runtests )
        {
            JatsCmd('make', 'run_unit_tests')      and Error("Tests did not run correctly");
        }
    }
    else
    {
        #
        #   Ant build files
        #
        my $pname =  $be->{file};
        Message ("Using ANT: $build_dir, $pname");
        $pname =~ s~depends.xml$~.xml~;
        copy($be->{file}, "auto.xml");
        JatsCmd('-buildfile', $pname, 'ant', 'build')        and Error("Package did not build");
        JatsCmd('-buildfile', $pname, 'ant', 'make_package') and Error("Package did not make_package");
    }
}

#
#   Copy the generated packages
#       1) dpkg_archive
#       2) Users local directory
#
foreach my $be (@build_list)
{
    my $build_dir = $be->{dir};
    chdir ("$build_dir") or Error( "Cannot chdir to build directory: $build_dir");
    if ( $opt_dpkg )
    {
        Message ("Using: $build_dir");
        my @create_opts = "-o";
        push @create_opts ,"-m" if ( $opt_merge );
        JatsCmd('-here', 'create_dpkg', @create_opts, '-pname', $be->{name}, '-pversion', $be->{version}) and $error++;
    }

    if ( $opt_copy )
    {
        Message ("Copy package to $user_cwd");
        copy_directory( 'pkg', $user_cwd, '' );
    }

    #
    #   Test structure of the package
    #   Ensure that it has a descpkg file
    #   Validate the package name and version
    #   More important for ANT projects than JATS as JATS has a sanity test
    #
    if ( $opt_test )
    {
        JatsCmd('-here', 'create_dpkg', '-test', '-pname', $be->{name}, '-pversion', $be->{version}) and $error++;
    }

}
Error ("Package not transferred")
    if ( $error );


#
#   Delete the view
#
if ( ! $opt_reuse && ! $error && ! $opt_keep )
{
    delete_view();
}
else
{
    Message( "View left in: $VIEWDIR" );
}

Message ("End program");
exit 0;

#-------------------------------------------------------------------------------
# Function        : delete_view
#
# Description     : Delete a view
#
# Inputs          : None
#                   $VIEWDIR - path of the view
#
# Returns         :
#
sub delete_view
{
    my $cofound = 0;
    my $uuid;

    #
    #   Simple delete
    #
    if ( $opt_extract_files )
    {
        if ( -d $VIEWDIR )
        {
            Message("Remove extracted files: $VIEWDIR");
            rmtree( $VIEWDIR );
        }
    }
    else
    {
        #
        #   If the view physically exists then attempt to phyically remove it
        #
        if ( -d $VIEWDIR )
        {
            #
            #   Determine if there are any checked out files in the view
            #
            Message("Remove the view: $VIEWDIR");
            Verbose("Look for checked out files");


            SvnRmView ('path'     => $VIEWDIR . $opt_path,
                       'force'    => $opt_delete > 1,
                       'modified' => [ 'local_dpkg_archive' ] );
        }
        Error ("View was not deleted")
            if ( -d $VIEWDIR . $opt_path );
        rmtree( $VIEWDIR ) if $opt_path;
    }

    Error ("View was not deleted")
        if ( -d $VIEWDIR );
}

#-------------------------------------------------------------------------------
# Function        : copy_directory
#
# Description     : Copy a directory tree
#
# Inputs          : Source directory
#                   Target directory
#                   Strip
#
#                   Should be full pathnames
#
# Returns         :
#
my $copy_error;
my $copy_count;
sub copy_directory
{
    our ($src_dir, $dest_dir, $strip) = @_;
    our $slength = length ($strip);

    #
    #   Prevent File::Find from generating warnings
    #
    no warnings 'File::Find';


    #
    #   Helper routine to copy files
    #
    sub copy_file_wanted
    {
        #
        #   Do not copy directories
        #   Just make the directory entry. May result in empty directories
        #
        if ( -d $_ )
        {
            my $tdir = "$dest_dir/" . substr( $File::Find::dir, $slength);
            $tdir .= "/$_";
            File::Path::mkpath( $tdir )
                unless ( -d $tdir);
            return;
        }

        #
        #   When used to copy file from within a clearcase dynamic view the
        #   files may not actually exist. This will generate an error later
        #   so check for existance of file file now.
        #
        return unless ( -e $_ );

        #
        #   Have been chdir'ed to the source directory
        #   when invoked
        #
        my $tdir = "$dest_dir/" . substr( $File::Find::dir, $slength);
        my $tfile = "$tdir/$_";
        my $sfile = "$File::Find::dir/$_";
        Verbose ("Copy: $sfile -> $tfile");

        File::Path::mkpath( $tdir )
            unless ( -d $tdir);

        unlink ( $tfile )
            if ( -f $tfile );

        if( ! File::Copy::copy ( $_ , $tfile ) )
        {
            $copy_error++;
            Message "Error copying $sfile";
        }
        else
        {
            my $perm = (stat $_)[2] & 07777;
            chmod($perm, $tfile);

            $copy_count++;
        }
    }

    #
    #   Locate all files to copy
    #
    $copy_error = 0;
    $copy_count = 0;
    File::Find::find ( \&copy_file_wanted, $src_dir );
    return $copy_error;
}

#-------------------------------------------------------------------------------
# Function        : count_files
#
# Description     : Count files in a workspace
#                   Ignore .svn stuff
#
# Inputs          : Source directory
#
# Returns         :
#
sub count_files
{
    my ($src_dir) = @_;

    #
    #   Prevent File::Find from generating warnings
    #
    no warnings 'File::Find';


    #
    #   Helper routine to copy files
    #
    sub count_file_wanted
    {
        #
        #   Do not count dirs, only files
        #
        return if ( -d $_ );
        $copy_count++;
    }

    #
    #   Locate all files
    #
    $copy_count = 0;
    File::Find::find ( \&count_file_wanted, $src_dir );
}


#-------------------------------------------------------------------------------
# Function        : extract_files_from_view
#
# Description     : This function will
#                       Create a dynamic view
#                       Copy all the files out of the view
#                       Delete the view
#
#                   Its used in the creation of escrow directories
#
# Inputs          : None
#                   All done via globals
#
# Returns         : 
#
sub extract_files_from_view
{
    #
    #   Determine the target directory for the extracted files
    #       Delete the output subdir
    #       Create the config spec in that directory
    #
    Verbose("Extracting files into $VIEWDIR");
    if ( -d $VIEWDIR )
    {
        Verbose "Delete Directory: $VIEWDIR\n";
        rmtree( $VIEWDIR );
    }

    $svn_label->SvnCo ( $svn_label->Full, $VIEWDIR, '--Export' );

    #
    #   Count this files in the view
    #   Done so that its clear when we have a empty workspace
    #
    Verbose ("Examine View contents");
    count_files ( $VIEWDIR );
    Message ("View files in: $VIEWDIR, Files: $copy_count" );

}

#-------------------------------------------------------------------------------


#-------------------------------------------------------------------------------
#   Documentation
#

=pod

=head1 NAME

jats_svnrelease - Build a package given a SubVersion label

=head1 SYNOPSIS

  jats svnrelease [options] [-label=]label

 Options:
    -help              - brief help message
    -help -help        - Detailed help message
    -man               - Full documentation
    -label=xxx         - Subversion label
    -spec=xxx          - Same as -label=xxx
    -path=xxx          - Source Path
    -view=xxx          - Modify the name of the created view
    -build=xxx         - Package Name to build
    -root=xxx          - Root directory for generated view
    -[mk]branch=xxx    - Will create a view with a branch rule
    -extract           - Extract the view and exit
    -extractfiles      - Extract files, without a view
    -cache             - Refresh local dpkg_archive cache
    -delete            - Remove any existing view and exit
    -debugOnly         - Make only the debug version
    -prodOnly          - Make only the production version
    -[no]dpkg          - Transfer package into dpkg_archive
    -[no]copy          - Transfer pkg directory to the current user directory
    -[no]reuse         - Reuse the view
    -[no]test          - Test package build. Implies nocopy and nodpkg
    -[no]keep          - Keep the view after the build
    -[no]beta          - Release a beta package
    -[no]merge         - Merge packages into dpkg_archive
    -[no]runtests      - Run units tests. Default is runtests
    -[no]prefix        - Supress user prefix in view name. Default prefix is USER

=head1 OPTIONS

=over 8

=item B<-help>

Print a brief help message and exits.

=item B<-help -help>

Print a detailed help message with an explanation for each option.

=item B<-man>

Prints the manual page and exits.

=item B<-label> or B<-spec>

The Subversion label to use as the base for the workspace.

Eg: DPG_SWBASE/daf_utils_math/tags/3.2.1@12345

=item B<-view name>

Specified an alternate view name and tag to be used. This option does not provide the
full name of the view.

    The view path will be: "${USER}_${NAME}"

The default "NAME" is the first label specified with the repository and tag removed.

If the user provides a view "name" that is prefixed with their user name
('${USER}_'), then the username will be stripped of for internal processing.
This allows a user to provide a view path when deleting a view.

=item B<-path=xxx>

Specifies the source path to the root of the extracted file tree. This option is
not mandatory and is only used to mnaintain toolset compatability woth other
,similar, tools.

If provided, then the Workspace will be created within the named subdirectory
tree within the base of the view.

=item B<-build=xxx>

This option allows the user to specify the packages to be built and the
order in which the packages are to be built.
This is useful if the extracted view contains multiple build files

This option may be used multiple times.

There are two forms in which the build target can be specified. It can be
specified as a full package name and vesrion, or as a package name and the
project suffix.

By default the program will assume that there is only one build file in the
view and will not build if multiple files are present, unless the package to be
built can be resolved.

The location mechanism operates for both JATS and ANT build files.

Example: -build=jats-api.1.0.0000.cr

This will locate the build file that builds version 1.0.0000.cr of the jats-api
package. The version numbers must match exactly.

Example: -build=jats-api.cr -build=jats-lib.cr

This will located the build files that build the jats_api (cr) package and the
jats-lib (cr) package. The version of the packages will not be considered.

=item B<-root=xxx>

This option allows the location of the generated view to be specified on the
command line. The environment variable GBE_VIEWBASE provides the same feature,
but it will affect all the view created.

The default location is:

=over 8

=item WINDOWS

c:\clearcase

=item Unix

$(HOME)/jats_cbuilder

If the comamnd is invoked within a development sandbox, then the default
location will be the root directory of the development sandbox.

=back

=item B<-branch=xxx or -mkbranch=xxx>

This option will create workspace branch that is tagged with the named branch.
This is intended to facilitate the maintenance of existing packages - the
creation of a patch.

The named branch must NOT exist within the subversion repository. The script will
check for its existence.

The tool will copy the specified source version to the branch and then create a
workspace based on the branch.

=item B<-extract>

With this option the view is created and the left in place. The user may then
access the files within the view. The view should not be used for a
production release.

=item B<-extractfiles>

With this option the utility will create a dynamic view and transfer files from
the view to the user's tararget. The dynamic view is then removed.

This command is intended to simplify the process of creating an escrow.

=item B<-cache>

Forces external packages to be placed in the local dpkg_archive cache.

The normal operation is to copy the packages, only if they do not already exist
in the local cache. This option may be used to ensure that the local copy is
correct and up to date.

=item B<-delete>

Delete the view used by the program, if it exists. This option may be used to
cleanup after an error.

Note: Ensure that no files are open in the view and that the users current
working directory is not in the view as these will prevent the view from being
deleted.

=item B<-debugOnly>

Make only the debug version of the package. The default it to create both the
debug and production version of the package. The type of build may be  further
limited by options within the package.

=item B<-prodOnly>

Make only the production version of the package. The default it to create both the
debug and production version of the package. The type of build may be  further
limited by options within the package.

=item B<-[no]dpkg>

Copy the generated package into dpkg_archive. This is the default mode of
operation.

=item B<-[no]copy>

Copy the built "pkg" directory to the users current directory. The entire
"pkg" subdirectory includes the full package named directory for the package
that has been built.

=item B<-[no]reuse>

This flag allows the view created by the program to be re-used.

=over 8

=item 1. The view is not deleted before being populated.

=item 2. The view will not be populated if it does exist.

=item 3. The view will not be deleted at the end the process.

=back

This option is useful for debugging a build process.

=item B<-[no]test>

Test the building of the package. This option implies "nocopy" and "nodpkg".

=item B<-[no]keep>

Keep the clearcase view after the build. The default option is "nokeep"

This option is different to the "reuse" in that the view will be deleted, if
it exists, before the build, but will be retained at the completion of the
process. The user may then manually extract the created package.

The view may be deleted with the the "delete" option; taking care to ensure that
no files are open in the view and that the users current working directory is
not in the view.

=item B<-[no]beta>

This option overrides many of the package release tests to allow a beta package
to be released.

=item B<-[no]merge>

This option will merge packages being built on multiple machines into
dpkg_archive. By default, if a package already exists in the archive it will be
deleted and replaced. With this option the package will be merged. The merge
process does not over write files found in the archive.

=item B<-[no]runtests>

This option will allow the suppression of the running of the unit tests included
with the component. By default the tests are run. This can be suppressed
without affecting the release process.

=back

=head1 DESCRIPTION

This program is the primary tool for the creation, recreation and release of
packages within the B<ERG> build environment, although the program can perform a
number of very useful operations required during normal development and
maintenance.

This program will build a system containing one or more inter-related build
files using the JATS build tools.

In normal operation the program will:

=over 8

=item Remove Workspace

Remove any existing workspace of the same name. The workspace will not be
removed if it contains checked-out files.

The workspace removal may fail if there are any files B<open> within the view or if
any shell has a subdirectory of the view set as a B<current working directory>.

=item Create the workspace

Create a workspace to contain the files described by the Subversion
label being processed.

=item Populate the workspace

Loads files into the workspace.

I<Note:> If the workspace files are simply being extracted, then this is the end
of the program. The extracted workspace is left in place.

=item Sanity Test

If the build is being used as a release into dpkg_archive then
various tests are performed to ensure the repeatability of the view and the
build. These tests include:

=over 8

=item   * The view must be constructed from one label

=item   * That label must be pegged

=item   * The labelled view must contain exactly one build file

=item   * The view cannot have been re-used.

=back

=item Locate build files

Locate the build file within the view.

It is an error to have multiple build files within the workspace, unless the
B<-build> option is used. By default, only one package will be built.

=item Package the results

Use JATS to build and make the package.

The resultant package may be copied to a numbers of locations. These include

=over 8

=item 1

The master dpkg_archive as an official release. This is the default operation.

=item 2

The users current directory. The package directory from the built package is
copied locally. The "pkg" directory is copied. This is only performed with the
B<-copy> option.

=back

=item Delete the workspace

Delete the workspace and all related files.

The workspace will not be deleted if an error was detected in the build process, or
the "reuse" or "keep" options are present.

=back

=cut