########################################################################
# COPYRIGHT - VIX IP PTY LTD ("VIX"). ALL RIGHTS RESERVED.
#
# Module name   : jats_vcssave_build.pl
# Module type   : JATS Utility
# Compiler(s)   : Perl
# Environment(s): JATS
#
# Description   : BuildTool abstraction utility
#                 Determine the Version control system in use
#                 and invoke required utility
#
# Usage         : See POD below
#
#......................................................................#

require 5.008_002;
use strict;
use warnings;

use Pod::Usage;
use Getopt::Long qw(:config pass_through);
use JatsError qw(:name=ABTSAVE);
use JatsSystem;

#
#   Options
#
my $opt_help = 0;
my $opt_verbose = $ENV{'GBE_VERBOSE'};      # Allow global verbose
my $opt_spec;

#
#   VCS to program conversion
#
my $VERSION = "1.0.0";                      # Update this
my %vcs = (
    'SVN' => 'jats_svnsave_build.pl',
    'CC'  => 'jats_ccsave_build.pl',
    );

################################################################################
#   Mainline
#
#
#   Parse the user options
#   Leave unknown options alone and don't complain
#
my @FULL_ARGV = @ARGV;
Verbose ("Parsing Options");
my $result = GetOptions (
                "help:+"        => \$opt_help,              # flag, multiple use allowed
                "manual:3"      => \$opt_help,              # flag
                "v|verbose:+"   => \$opt_verbose,           # flag, multiple use allowed
                "baselabel=s"   => \$opt_spec,              # String
                );

                #
                #   UPDATE THE DOCUMENTATION AT THE END OF THIS FILE !!!
                #
#
#   Process help and manual options
#   Only if we arn't parsing stuff to other routines
#
$opt_help = 0 if ( $opt_spec );
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 );

ErrorConfig( 'verbose' => $opt_verbose );

#
#   Label must be provided - its how we determine the type of VCS
#
Error ("No baselabel provided") unless ( defined $opt_spec );

#
#   Examine the label and determine the VCS encode method
#   Label MUST be of the form
#       XXX::text
#   Where XXX specifies the Version Control System
#
$opt_spec =~ m~^(.+?)::.+~;
my $protocol = $1;
Error ("Badly formatted label. Does not identify VCS", "Label: $opt_spec" )
    unless ( $protocol );
Verbose3("Protocol: $protocol");

Error ("Unknown VCS in label: $opt_spec")
    unless ( exists $vcs{$protocol});

#
#   Pass control to the required utility
#
exit JatsTool ( $vcs{$protocol}, @FULL_ARGV );

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

=pod

=for htmltoc    SYSUTIL::

=head1 NAME

jats_vcssave_build - Release a Package

=head1 SYNOPSIS

  jats etool jats_vcssave_build [options]

 Options:
    -help[=n]           - brief help message
    -help -help         - Detailed help message
    -man[=n]            - Full documentation
    -verbose[=n]        - Verbose operation
    -baselabel=label    - Label the build view is based on
    Others              - Passed on

=head1 OPTIONS

=over 8

=item B<-help[=n]>

Print a brief help message and exits.

The verbosity of the help text can be controlled by setting the help level to a
number in the range of 1 to 3, or by invoking the option multiple times.

=item B<-man[=n]>

Without a numeric argument this is the same as -help=3. Full help will be
displayed.

With a numeric argument, this option is the same as -help=n.

=item B<-verbose[=n]>

This option will increase the level of verbosity of the utility.

If an argument is provided, then it will be used to set the level, otherwise the
existing level will be incremented. This option may be specified multiple times.

=item B<-baselabel=text>

This option is used to determine the VCS system to use to create the workspace
required for the build.

=back

=head1 DESCRIPTION

This utility is used by the automated build system to place build view under
version control. Multiple version control systems are supported.

This utility is a wrapper that will determine VCS and then invoke
The required VCS-specific utility to do the real work.

The utility will examine the -baselabel option and detect the required Version
Control System.

The baselabel must start with a Version Control Header. This is of the form of:

    XXX::Data

Where XXX identifies the Version Control System. Valid values are:

=over 8

=item   CC

ClearCase

The remainder of the label contains a path and a label.

=item   SVN

SubVersion

The remainder of the label contains a URL without the site-specific protocol
or server.

=back

All other command line options are passed to the tool. Thus the tools must
have a common set of options.

Full documentation is availabe in:

=over 8

=item *

L<ccsave_build|TOOLS::jats_ccsave_build>

=item *

L<svnsave_build|TOOLS::jats_svnsave_build>

=back

=cut