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;

use Sys::Hostname;                          # For hostname

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';

#

#   Globals

#

my $MACHINENAME;

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

$MACHINENAME = hostname;

Error ("Machine Name not determined")

    unless ( $MACHINENAME );

chomp( $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 a package name and version can be found - then use it

    #       - Insert branch name if required

    #       - Use full user path if all else fails

    #

    if ( $svn_label->Type )

    {

        $opt_viewname = $svn_label->Package;

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

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 || $opt_extract_files );

#

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

}

#

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

        }

    }

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

        $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;

    #

    #   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;

}

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

# 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