WebSVN – DevTools – Diff – /core_devl/trunk/TOOLS/jats_sandbox.pl

+#
 my $opt_debug   = $ENV{'GBE_DEBUG'};        # Allow global debug
 my $opt_verbose = $ENV{'GBE_VERBOSE'};      # Allow global verbose
 my $opt_help = 0;                           # Help level
 my $opt_exact = 0;                          # Exact (escrow) build
+my $opt_toPackage;                          # Control recursion
+my $opt_fromPackage;                        # Control recursion
+my @opt_justPackage;                        # Control recursion
+my @opt_ignorePackage;                      # Control recursion
+#
 #   Globals - Provided by the JATS environment
+#
 my $USER         = $ENV{'USER'};
 my $GBE_DPKG_STORE = $ENV{'GBE_DPKG_STORE'};
+#
 #   Globals
+#
+my @stopped = ();                         # Stopped entries
 my @build_order = ();                     # Build Ordered list of entries
 my %extern_deps;                          # Hash of external dependencies
 my %packages;                             # Hash of packages
+#
 # Description     :
+#
 # Inputs          :
+#
-my $result = GetOptions (
-                "help|h:+"      => \$opt_help,
-                "manual:3"      => \$opt_help,
-                "verbose:+"     => \$opt_verbose,           # flag, multiple use allowed
-                );
-                #
-                #   UPDATE THE DOCUMENTATION AT THE END OF THIS FILE !!!
-                #
+#
 #   Process help and manual options
+#
+my $result = getOptionsFromArray ( \@ARGV );
 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 );
+#
+#
 # Returns         : Will exit
+#
 sub info
+{
-    GetOptions (
+    my (@cmd_opts ) = @_;
-                "help:+"        => \$opt_help,
+    my $show = 0;
-                "manual:3"      => \$opt_help,
-                "verbose:+"     => \$opt_verbose,
-                ) || Error ("Invalid command line" );
+    Getopt::Long::Configure('pass_through');
+    getOptionsFromArray ( \@cmd_opts,
+                           'verbose:+'  => \$show,
+                        ) || Error ("Invalid command line" );
-    SubCommandHelp( $opt_help, "Sandbox Information") if ($opt_help || $#ARGV >=0 );
+    SubCommandHelp( $opt_help, "Sandbox Information") if ($opt_help || $#cmd_opts >=0 );
+    #
     #   Determine Sandbox information
     #   Populate global variables
+    #
-    calc_sandbox_info();
+    calc_sandbox_info(1);
+    #
     #   Display information
+    #
     Message ("Type   : " . ($opt_exact ? 'Exact' : 'Development') );
     Message ("Base   : $GBE_SANDBOX");
     Message ("Archive: $GBE_DPKG_SBOX");
     Message ("Build Order");
+    foreach my $pname ( @stopped )
+    {
+        Message( "    Level:" . "-"  . " Name: " . $pname . ' (Stopped)');
+    }
     foreach my $fe ( @build_order )
+    {
-        Message( "    Level:" . $fe->{level} . " Name: " . $fe->{dname} );
+        Message( "    Level:" . $fe->{level} . " Name: " . $fe->{dname} . ($fe->{buildActive} ? '' : ' (Build Suppressed)'));
-        Message( DisplayPath ("        Path: $fe->{dir}" )) if $opt_verbose;
+        Message( DisplayPath ("        Path: $fe->{dir}" )) if $show;
-        if ( $opt_verbose )
+        if ( $show )
+        {
             foreach my $idep ( sort values %{$fe->{'ideps'}} )
+            {
                 Message ("        I:$idep");
+            }
+        {
             my ($pn,$pv) = split( $; , $pve );
             my $exists = check_package_existance($pn,$pv  ) ? '' : '*';
             my $flags = sprintf ("%4.4s", $flag . $exists);
             Message ("${flags}${pn} ${pv}");
-            if ( $opt_verbose )
+            if ( $show )
+            {
                 foreach my $pkg ( @{$extern_deps{$de}{$pve}} )
+                {
                     my $ppn = join ('.', split( $; , $pkg));
                     Message ("        U:$ppn");
+            }
+        }
+    }
-    if ( $opt_verbose > 2 )
+    if ( $show > 2 || $opt_verbose > 2 )
+    {
         DebugDumpData( "extern_deps", \%extern_deps);
         DebugDumpData( "build_order", \@build_order);
         DebugDumpData( "packages", \%packages);
+    }
 # Function        : calc_sandbox_info
+#
 # Description     : Examine the sandbox and determine all the important
 #                   information
+#
+#                   Operation will be modified by
-# Inputs          : None
+#                       $opt_toPackage
+#                       $opt_fromPackage
+#                       @opt_justPackage
+#                       @opt_ignorePackage
+#
+# Inputs          : info                - True: Just for info
+#                                               Keep supressed packages
+#
 # Returns         : Will exit if not in a sandbox
 #                   Populates global variables
 #                       @build_order - build ordered array of build entries
+#
 sub calc_sandbox_info
+{
+    my ($info) = @_;
+    #
     #   Start from the root of the sandbox
+    #
     Error ("Command must be executed from within a Sandbox") unless ( $GBE_SANDBOX );
     chdir ($GBE_SANDBOX) || Error ("Cannot chdir to $GBE_SANDBOX");
         next unless ( -d $pname );
         Verbose ("Package discovered: $pname");
         if ( -f "$pname/stop" || -f "$pname/stop.$GBE_MACHTYPE" )
+        {
+            push @stopped, $pname;
             Warning("Package contains stop file: $pname");
             next;
+        }
         push @dirlist, $pname;
     my %depends;
     my %multi;
     foreach my $be ( @build_list )
+    {
         Verbose( DisplayPath ("Build file: " . $be->{dir} . " Name: " . $be->{file} ));
+        #
         #   Sandbox vs Exact processing
         #       Set a suitable display name
         #       Set a suitable tag
+        #
         push @{$multi{$be->{dname}}},$be->{dir};
+        #
         #   Add into dependency struct
+        #
-        $depends{$be->{tag}}{entry} = $be;
+        $depends{$be->{tag}} = $be;
-        $depends{$be->{tag}}{depends} = $be->{depends};
+    }
     foreach my $dname ( sort keys %multi )
+    {
         ReportError ("Multiple builders for : $dname", @{$multi{$dname}} )
+    #
     #   Remove any dependencies to 'external' packages
     #   These will not be met internally and can be regarded as constant
+    #
+    #   Split 'depends' into internal (ideps) and external (edeps)
+    #       edeps : External Dependencies
+    #               Key:        Name;Version
+    #               Value:      'tag' - index into packages
+    #       ideps : Internal Dependencies
+    #               Key:        'tag'   - Index into packages
+    #               Value:      'dname' - Display Name
+    #
     foreach my $key ( keys %depends )
+    {
         foreach my $build ( keys( %{$depends{$key}{depends}} ))
+        {
             unless (exists $depends{$build})
+            {
-                push @{$extern_deps{$build} {$depends{$key}{depends}{$build}} }, $key;
-                $depends{$key}{entry}{'edeps'}{$depends{$key}{depends}{$build}} = 1;
+                $depends{$key}{'edeps'}{$depends{$key}{depends}{$build}} = $build;
                 delete ($depends{$key}{depends}{$build}) ;
                 Verbose2( "Not in set: $build");
+            }
             else
+            {
-                $depends{$key}{entry}{'ideps'}{$build} = $depends{$build}{entry}{dname};
+                $depends{$key}{'ideps'}{$build} = $depends{$build}{dname};
+            }
+        }
+    }
 #DebugDumpData ("depends", \%depends );
-#DebugDumpData ("External Depends", \%extern_deps );
+    #
     #   Determine package build order
     #       Scan the list of packages in the build set and determine
     #       those with no dependencies. These can be built.
     #       Remove those packages as dependents from all packages
     #       Repeat.
+    #
+    my %found    = map { $_ => 1 } @opt_ignorePackage;
+    my %notFound = map { $_ => 1 } @opt_justPackage;
+    my $scan_start = 0;
+    my $scan_stop = 0;
+    my $scan_active = ($opt_fromPackage) ? 0 : 1;
+    $scan_active = 0 if ( !$opt_fromPackage && !$opt_fromPackage && !@opt_ignorePackage && @opt_justPackage );
     while ( $more )
+    {
         $more = 0;
         $level++;
         my @build;
+        }
         foreach my $build ( @build )
+        {
             $more = 1;
-            my $fe = $depends{$build}{entry};
+            my $fe = $depends{$build};
+            my $scan_add = $scan_active ? 1 : 0;
+            if ( $opt_fromPackage && (($fe->{mname} eq $opt_fromPackage) || ($fe->{name} eq $opt_fromPackage)))
+            {
+                $scan_add = 1;
+                $scan_active = 1;
+                $scan_start = 1;
+            }
+            if ( $opt_toPackage && (($fe->{mname} eq $opt_toPackage) || ($fe->{name} eq $opt_toPackage)))
+            {
+                $scan_add = 0;
+                $scan_active = 0;
+                $scan_stop = 1;
+            }
+            if ( @opt_justPackage )
+            {
+                foreach my $pname ( @opt_justPackage )
+                {
+                    if ( (($fe->{mname} eq $pname) || ($fe->{name} eq $pname)))
+                    {
+                        $scan_add = 1;
+                        delete $notFound{$pname};
+                    }
+                }
+            }
+            if ( @opt_ignorePackage )
+            {
+                foreach my $pname ( @opt_ignorePackage )
+                {
+                    if ( (($fe->{mname} eq $pname) || ($fe->{name} eq $pname)))
+                    {
+                        $scan_add = 0;
+                        delete $found{$pname};
+                    }
+                }
+            }
             $fe->{level} = $level;
+            $fe->{buildActive} = $scan_add;
             $packages{$build} = $fe;
-            push @build_order, $fe;
+            push (@build_order, $fe) if ( $scan_add || $info );
             delete $depends{$build};
             delete $fe->{depends};                          # remove now its not needed
+        }
         foreach my $key ( keys %depends )
+            }
+        }
+    }
+    #
+    #   Detect bad user specifications
+    #
+    ReportError ("Specified FromPackage not found: $opt_fromPackage") if ( $opt_fromPackage && !$scan_start );
+    ReportError ("Specified ToPackage not found: $opt_toPackage") if ( $opt_toPackage && !$scan_stop );
+    ReportError ("Specified ExactPackages not found: ", keys( %notFound) ) if ( %notFound );
+    ReportError ("Specified IgnorePackages not found: ", keys( %found) ) if ( %found );
+    ErrorDoExit();
+    #
+    #   Calculate the external dependencies
+    #       Only process packages that are a part of the build
+    #
+    #   extern_deps structure
+    #       Hash key: 'tag'   - Index into packages
+    #          Value: Hash of:
+    #                 Key  : Name;Version
+    #                 Value: Array of: 'tags' (Index into packages)
+    #                                   of packages that use the external
+    #                                   component.
+    {
+        Verbose ("Calculate external dependencies");
+        %extern_deps = ();
+        foreach my $key ( keys %packages )
+        {
+                next unless ( $packages{$key}{buildActive} );
+                next unless ( $packages{$key}{'edeps'} );
+                foreach ( keys %{$packages{$key}{'edeps'}} )
+                {
+                    push @{$extern_deps{$packages{$key}{'edeps'}{$_}} {$_} }, $key;
+                }
+        }
+    }
+    #
     #   Just to be sure to be sure
+    #
     if ( keys %depends )
+    {
         #DebugDumpData ("depends", \%depends );
         Error( "Internal algorithm error: Bad dependancy walk",
                "Possible circular dependency");
+    }
+#   DebugDumpData("Packages", \%packages);
 #   DebugDumpData ("Order", \@build_order);
 #   DebugDumpData("External Depends", \%extern_deps );
+}
 #-------------------------------------------------------------------------------
+#
 # Returns         : Will exit
+#
 sub cmd
+{
-    my ($hcmd, @cmds ) = @_;
+    my ($hcmd, @cmd_opts ) = @_;
     Getopt::Long::Configure('pass_through');
-    GetOptions (
-                "help:+"        => \$opt_help,
-                "manual:3"      => \$opt_help,
-                ) || Error ("Invalid command line" );
+    getOptionsFromArray ( \@cmd_opts ) || Error ("Invalid command line" );
     SubCommandHelp( $opt_help, $hcmd) if ($opt_help  );
+    #
     #   Determine Sandbox information
     #   Populate global variables
+    {
         my $dir = $fe->{dir};
         Message( "Level:" . $fe->{level} . " Name: " . $fe->{dname} ,
                   DisplayPath ("        Path: $fe->{dir}" ));
-        my $result = JatsCmd( "-cd=$dir", @cmds);
+        my $result = JatsCmd( "-cd=$dir", @cmd_opts);
         Error ("Cmd failure") if ( $result );
+    }
     exit 0;
+}
+    #
     #   Extract and options
+    #
     Getopt::Long::Configure('pass_through');
-    GetOptions (
-                "help:+"        => \$opt_help,
-                "manual:3"      => \$opt_help,
-                ) || Error ("Invalid command line" );
+    getOptionsFromArray ( \@cmd_opts ) || Error ("Invalid command line" );
     SubCommandHelp( $opt_help, "Command $cmd") if ($opt_help );
+    #
     #   Insert default options
+    #
+#
 # Returns         : Will exit
+#
 sub clean
+{
-    my ($mode, @cmds ) = @_;
+    my ($mode, @cmd_opts ) = @_;
+    #
     #   Extract and options
+    #
     Getopt::Long::Configure('pass_through');
-    GetOptions (
-                "help:+"        => \$opt_help,
-                "manual:3"      => \$opt_help,
-                ) || Error ("Invalid command line" );
+    getOptionsFromArray ( \@cmd_opts ) || Error ("Invalid command line" );
     SubCommandHelp( $opt_help, "Clean") if ($opt_help );
+    #
     #   Determine Sandbox information
     #   Populate global variables
+    {
         my $dir = $fe->{dir};
         Message( "Level:" . $fe->{level} . " Name: " . $fe->{dname} ,
                   DisplayPath ("        Path: $fe->{dir}" ));
-        my $result = JatsCmd( "-cd=$dir", @cmd, @cmds);
+        my $result = JatsCmd( "-cd=$dir", @cmd, @cmd_opts);
         Error ("Cmd failure") if ( $result );
+    }
     exit 0;
+}
+#
 # Returns         : Nothing
+#
 sub cache
+{
-    my (@opts) = @_;
+    my (@cmd_opts) = @_;
-    GetOptions (
-                "help:+"        => \$opt_help,
-                "manual:3"      => \$opt_help,
-                ) || Error ("Invalid command line" );
+    getOptionsFromArray ( \@cmd_opts ) || Error ("Invalid command line" );
-    SubCommandHelp( $opt_help, "Cache") if ($opt_help || $#ARGV >= 0 );
+    SubCommandHelp( $opt_help, "Cache") if ($opt_help || $#cmd_opts >= 0 );
+    #
     #   Determine Sandbox information
     #   Populate global variables
+    #
     Message("Cache External Dependencies");
     calc_sandbox_info();
+    #
-    #   Walk the list of external despondencies and cache each one
+    #   Walk the list of external dependencies and cache each one
+    #
     foreach my $de ( sort keys %extern_deps )
+    {
         my @vlist = keys %{$extern_deps{$de}};
         foreach my $pve ( @vlist )
 my @StrayPackages;
 my @PopBase;
 sub populate
+{
+    my (@cmd_opts ) = @_;
     my $opt_missing = 0;
     my $opt_recurse = 0;
     my $opt_test = 0;
+    my $opt_show = 0;
     my $opt_extractfiles;
     my @opt_extract = qw(-extract);
     my @opt_fnames;
+    my @opt_exclude;
+    my $opt_all;
     Getopt::Long::Configure('pass_through');
-    GetOptions (
+    getOptionsFromArray ( \@cmd_opts,
-                "help:+"        => \$opt_help,
+                "all"               => \$opt_all,
-                "manual:3"      => \$opt_help,
+                "missing"           => \$opt_missing,
-                "missing"       => \$opt_missing,
+                "test"              => \$opt_test,
-                "test"          => \$opt_test,
+                "show"              => \$opt_show,
-                "recurse:100"   => \$opt_recurse,
+                "recurse:100"       => \$opt_recurse,
+                'excludePackage:s'  => sub{ opts_add2List( \@opt_exclude, @_ )},
                 ) || Error ("Invalid command line" );
     SubCommandHelp( $opt_help, "Populate Sandbox") if ($opt_help );
+    #
+    #   Sanity tests
+    #
+    Error ("Populate: -missing and -all options are mutually exclusive")
+        if ( $opt_missing && $opt_all );
+    #
     #   Extract options for the jats extract utility
+    #
-    foreach ( @ARGV )
+    foreach ( @cmd_opts )
+    {
         if ( m~^-~ ) {
             push ( @opt_extract, $_);
         } else {
             push ( @opt_fnames, $_);
+    {
         Error ("Populate: Must specify both a package name and version")
             if ( $#opt_fnames != 1 );
         push @PopBase, join( $;, @opt_fnames );
+    }
-    elsif ( $opt_missing )
+    elsif ( $opt_missing || $opt_all )
+    {
+        #
         #   User has not provided a package name to extract
-        #   Assume that the user will want missing dependencies
+        #   Assume that the user will want all or missing dependencies
+        #
         #   Determine packages that are not present
+        #
         calc_sandbox_info();
+        {
             my @vlist = keys %{$extern_deps{$de}};
             foreach my $pve ( @vlist )
+            {
                 my ($pn,$pv) = split( $; , $pve );
-                unless (check_package_existance( $pn, $pv ))
+                unless ($opt_missing && check_package_existance( $pn, $pv ))
+                {
                     push @PopBase, join( $;, $pn , $pv );
+                }
+            }
+        }
     #   If recursing then process packages that have yet to
     #   be processed. At the start there will be the initial user specified
     #   packages on the list. Place a marker at the end so that we can
     #   determine how far we are recursing down the dependency tree.
+    #
+    $opt_recurse = ($opt_all ? 100 : $opt_recurse);
     if ( $opt_recurse )
+    {
         my $marker = join($; , '_NEXT_LEVEL_', 0, 0 );
         push @StrayPackages, $marker;
         $PopLevel++;
+    }
     #DebugDumpData("Data", \%PopPackage );
+    #
     #   Determine packages that need to be extracted
-    #   Not ordered in any way. Could order by level if we wanted
+    #   Sort alphabetically - case insensitive
+    #
-    foreach my $pname ( sort keys %PopPackage )
+    foreach my $pname ( sort {lc($a) cmp lc($b)} keys %PopPackage )
+    {
+        pkgscan:
         foreach my $pver ( sort keys %{$PopPackage{$pname}} )
+        {
+            #
             #   Create a nice view name for the extraction
             #   Will also be used to test for package existence
                     next;
+                }
+            }
+            #
+            #   Has the user specifically excluded this package
+            #   Allow three forms
+            #       packageName
+            #       packageName_Version
+            #       packageName.projectName
+            #
+            my $excluded;
+            foreach my $ename ( @opt_exclude )
+            {
+                if ( $ename eq $pname ) {
+                    $excluded = 1;
+                } elsif ($ename eq $pname .'_' . $pver ) {
+                    $excluded = 1;
+                } else {
+                    if ( $pver =~ m~(\.[a-z]{2,4})$~ )
+                    {
+                        $excluded = ($ename eq $pname . $1 );
+                    }
+                }
+                if ( $excluded )
+                {
+                    Message ("Package excluded by user - skipped: $pname, $pver");
+                    next pkgscan;
+                }
+            }
+            #
             #   Generate commands to extract the package
+            #
             my $vcstag = $PopPackage{$pname}{$pver}{vcstag};
             my @cmd = qw(jats_vcsrelease);
             push @cmd, "-view=$vname", "-label=$vcstag", @opt_extract;
+            if ( $opt_show )
+            {
+                Message ("$pname $pver");
+            }
-            if ( $opt_test )
+            elsif ( $opt_test )
+            {
                 Message "jats " . QuoteCommand (@cmd );
+            }
             else
+            {
         Error("GetDepends:Prepare failure" );
+    }
+}
 #-------------------------------------------------------------------------------
+# Function        : getOptionsFromArray
+#
+# Description     : Like getOptions, but handles an array
+#                   Provided as the version of Perl used does not have one
+#
+# Inputs          : pArray                  - Ref to array
+#                   ....                    - GetOptions arguments
+#
+# Returns         :
+#
+sub getOptionsFromArray
+{
+    my ($pArray, %args) = @_;
+    #
+    #   Common arguments
+    #
+    my %commonOptions = (
+        'help|h:+'          => \$opt_help,
+        'manual:3'          => \$opt_help,
+        'verbose:+'         => \$opt_verbose,
+        'topackage:s'       => \$opt_toPackage,
+        'frompackage:s'     => \$opt_fromPackage,
+        'justpackage:s'     => sub{ opts_add2List( \@opt_justPackage, @_ )},
+        'ignorepackage:s'   => sub{ opts_add2List( \@opt_ignorePackage, @_ )},
+        );
+    #
+    #   Merge in the user options
+    #
+    @commonOptions{keys %args} = values %args;
+    local ( @ARGV );
+    @ARGV = @$pArray;
+    my $rv = GetOptions ( %commonOptions );
+    @$pArray = @ARGV;
+    ErrorConfig('verbose' => $opt_verbose );
+    return $rv;
+}
+#-------------------------------------------------------------------------------
+# Function        : opts_add2List
+#
+# Description     : Option processing helper
+#                   Add comma separated options to an array
+#                   User can then add items one at a time, or several at once
+#
+# Inputs          : aref        - Ref to an array to extent
+#                   arg2        - Option name
+#                   arg3        - Option value
+#
+# Returns         :
+#
+sub opts_add2List
+{
+    my( $ref, $name, $value) = @_;
+    if ( $value )
+    {
+        foreach ( split(/\s*,\s*/,$value) )
+        {
+            push @{$ref}, $_;
+        }
+    }
+}
+#-------------------------------------------------------------------------------
 # Function        : SubCommandHelp
+#
 # Description     : Provide help on a subcommand
+#
 # Inputs          : $help_level             - Help Level 1,2,3
 =head1 SYNOPSIS
   jats sandbox [options] command [command options]
  Options:
-    -help[=n]          - Display help with specified detail
+    -help[=n]                  - Display help with specified detail
-    -help -help        - Detailed help message
+    -help -help                - Detailed help message
-    -man               - Full documentation
+    -man                       - Full documentation
+ Options for recursion control:
+    -toPackage=name            - Stop building after package
+    -fromPackage=name          - Start building from package
+    -justPackage=name[,name]   - Build named packages
+    -ignorePackage=name[,name] - Do not build named packages
  Commands:
     help                - Same as -help
     create              - Create a sandbox in the current directory
     populate            - Populate the sandbox with packages
     delete              - Delete the sandbox
     info [[-v]-v]       - Sandbox information. -v: Be more verbose
     cmd                 - Do commands in all sandbox components
-    all                 - Do 'build', if required, then a make in all sandbox components
+    all                 - Do 'build', if required, then a make in all components
     build               - Force 'build and make' in all sandbox components
     make                - Do 'make' in all sandbox components
     clean               - Do 'make clean' in all sandbox components
     clobber             - Do 'build clobber' is all sandbox components
     cache               - Cache external dependent packages
 =item B<-man>
 Prints the manual page and exits. This is the same a -help=3
+=item B<-toPackage=name>
+This option is available in all commands that process multiple packages.
+Package processing will stop at the named package.
+The default operation is to process all packages.
+=item B<-fromPackage=name>
+This option is available in all commands that process multiple packages.
+Package processing will start at the named package.
+The default operation is to process no packages.
+=item B<-justPackage=name[,name]>
+This option is available in all commands that process multiple packages. The
+named packages will be processed in the correct build order. Packages that are
+not named will be skipped, unless the package is being processed due to
+being in the 'fromPackage' to 'toPackage' range.
+Multiple packages can be named either by separating names with a comma, or
+with multiple options.
+=item B<-ignorePackage=name[,name]>
+This option is available in all commands that process multiple packages. The
+named packages will not be processed.
+Multiple packages can be named either by separating names with a comma, or
+with multiple options.
+The exclusion of a package takes precedence over its inclusion.
 =back
 =head1 DESCRIPTION
 This program is the primary tool for the maintenance of Development Sandboxes.
 Create Sandbox
 =head2 SYNOPSIS
-jats sandbox [options] create [command options]
+jats sandbox create [command options]
- Options:
-    -help[=n]               - Help message, [n=1,2,3]
-    -man                    - Full documentation [-help=3]
-    -verbose[=n]            - Verbose command operation
  Command Options
     -help[=n]               - Command specific help, [n=1,2,3]
     -verbose[=n]            - Verbose operation
     -exact                  - Create sandbox to reproduce exact versions
 Populate a Sandbox
 =head2 SYNOPSIS
-jats sandbox [options] populate [command options] [packageName packageVersion]
+jats sandbox populate [command options] [packageName packageVersion]
- Options:
-    -help[=n]               - Help message, [n=1,2,3]
-    -man                    - Full documentation [-help=3]
-    -verbose[=n]            - Verbose command operation
  Command Options
-    -help[=n]               - Command specific help, [n=1,2,3]
+    -help[=n]                  - Command specific help, [n=1,2,3]
+    -toPackage=name            - Stop building after package
+    -fromPackage=name          - Start building from package
+    -justPackage=name[,name]   - Build named packages
+    -ignorePackage=name[,name] - Do not build named packages
+    -excludePackage=name[,name]- Do not extract named package
-    -recurse[=n]            - Locate dependencies within packages
+    -recurse[=n]               - Locate dependencies within packages
+    -all                       - Populate with all dependencies
-    -missing                - Locate missing packages
+    -missing                   - Locate missing packages
+    -show                      - Show packages that would be extracted
-    -test                   - Do not extract packages
+    -test                      - Do not extract packages
-    -<Other>                - Pass options to jats extract
+    -<Other>                   - Pass options to jats extract
 =head2 ARGUMENTS
 The 'populate' command can take a package name and version as arguments. It will
 then populate the sandbox with this package. See 'DESCRIPTION' for details.
 The 'populate' command takes the following options:
 =over 4
+=item -excludePackage=name[,name]
+This option prevents one, or more, packages from populating the sandbox.
+Packages specified with this option will not be extracted from version control
+and added to the sandbox.
+Packages can be itentified in three ways:
+=over 4
+=item 1. Package Name
+All package versions matching the named package will be excluded.
+=item 2. Package Name and Version
+Only the specified version of the named package will be excluded. The
+user specifies the package name and version as a single string separated with
+an underscore. ie: core_devl_2.100.5000.cr
+=item 3. Package Name and Suffix
+All packages matching the named package and project will be excluded. The
+user specifies the package name and project as a single string separated with
+a dot. ie: core_devl.cr
+=back
 =item -recurse[=N]
 This option will modify the operation of the command such that dependencies
 of named packages can also be extracted into the sandbox.
 The default operation is to only extract named packages. If the option is
 specified then all dependent packages are processed. An optional numeric argument
 can be specified to limit the depth of the recursion.
+=item -all
+This option will populate the sandbox will all dependencies of packages that are
+currently in the sandbox.
+The global options that control recursion will affect the packages that are
+processed.
+This option cannot be used with the '-missing' option.
 =item -missing
 This option will modify the operation of the dependency recursion scanning such
 that dependent packages that exist in a package archive will not be extracted.
 Use of this option allows a sandbox to be populated with packages that are
 required by packages in the sandbox, but are not available in a package archive.
+The global options that control recursion will affect the packages that are
+processed.
+This option cannot be used with the '-all' option.
+=item -show
+This option will prevent the command from performing the extraction. It will
+simply display the names of the packages that would be extracted.
 =item -test
 This option will prevent the command from performing the extraction. It will
 simply display the JATS commands that can be used to perform the extraction.
 Display Sandbox Information
 =head2 SYNOPSIS
-jats sandbox [options] info [command options]
+jats sandbox info [command options]
- Options:
-    -help[=n]               - Help message, [n=1,2,3]
-    -man                    - Full documentation [-help=3]
-    -verbose[=n]            - Verbose command operation
  Command Options
-    -help[=n]               - Command specific help, [n=1,2,3]
+    -help[=n]                  - Command specific help, [n=1,2,3]
-    -verbose[=n]            - Display more information
+    -verbose[=n]               - Display more information
+    -toPackage=name            - Stop building after package
+    -fromPackage=name          - Start building from package
+    -justPackage=name[,name]   - Build named packages
+    -ignorePackage=name[,name] - Do not build named packages
 =head2 OPTIONS
 =over
 Build packages in the sandbox
 =head2 SYNOPSIS
-jats sandbox [options] all [command options] [arguments]
+jats sandbox all [command options] [arguments]
- Options:
-    -help[=n]               - Help message, [n=1,2,3]
-    -man                    - Full documentation [-help=3]
-    -verbose[=n]            - Verbose command operation
  Command Options
-    -help[=n]               - Command specific help, [n=1,2,3]
+    -help[=n]                  - Command specific help, [n=1,2,3]
+    -toPackage=name            - Stop building after package
+    -fromPackage=name          - Start building from package
+    -justPackage=name[,name]   - Build named packages
+    -ignorePackage=name[,name] - Do not build named packages
 =head2 ARGUMENTS
 Arguments are passed to the 'make' phase of the process.
 Build packages in the sandbox
 =head2 SYNOPSIS
-jats sandbox [options] build [command options] [arguments]
+jats sandbox build [command options] [arguments]
- Options:
-    -help[=n]               - Help message, [n=1,2,3]
-    -man                    - Full documentation [-help=3]
-    -verbose[=n]            - Verbose command operation
  Command Options
-    -help[=n]               - Command specific help, [n=1,2,3]
+    -help[=n]                  - Command specific help, [n=1,2,3]
+    -toPackage=name            - Stop building after package
+    -fromPackage=name          - Start building from package
+    -justPackage=name[,name]   - Build named packages
+    -ignorePackage=name[,name] - Do not build named packages
 =head2 ARGUMENTS
 Arguments are passed to the 'make' phase of the process.
 Clean all sandbox components
 =head2 SYNOPSIS
-jats sandbox [options] clean|clobber [command options]
+jats sandbox clean|clobber [command options]
- Options:
-    -help[=n]               - Help message, [n=1,2,3]
-    -man                    - Full documentation [-help=3]
-    -verbose[=n]            - Verbose command operation
  Command Options
-    -help[=n]               - Command specific help, [n=1,2,3]
+    -help[=n]                  - Command specific help, [n=1,2,3]
+    -toPackage=name            - Stop building after package
+    -fromPackage=name          - Start building from package
+    -justPackage=name[,name]   - Build named packages
+    -ignorePackage=name[,name] - Do not build named packages
 =head2 ARGUMENTS
 None
 Make packages in the sandbox
 =head2 SYNOPSIS
-jats sandbox [options] make [command options] [arguments]
+jats sandbox make [command options] [arguments]
- Options:
-    -help[=n]               - Help message, [n=1,2,3]
-    -man                    - Full documentation [-help=3]
-    -verbose[=n]            - Verbose command operation
  Command Options
-    -help[=n]               - Command specific help, [n=1,2,3]
+    -help[=n]                  - Command specific help, [n=1,2,3]
+    -toPackage=name            - Stop building after package
+    -fromPackage=name          - Start building from package
+    -justPackage=name[,name]   - Build named packages
+    -ignorePackage=name[,name] - Do not build named packages
 =head2 ARGUMENTS
 Arguments are passed to the 'make' phase of the process.
 Process each package with a specified command.
 =head2 SYNOPSIS
-jats sandbox [options] cmd [command options] [arguments]
+jats sandbox cmd [command options] [arguments]
- Options:
-    -help[=n]               - Help message, [n=1,2,3]
-    -man                    - Full documentation [-help=3]
-    -verbose[=n]            - Verbose command operation
  Command Options
-    -help[=n]               - Command specific help, [n=1,2,3]
+    -help[=n]                  - Command specific help, [n=1,2,3]
+    -toPackage=name            - Stop building after package
+    -fromPackage=name          - Start building from package
+    -justPackage=name[,name]   - Build named packages
+    -ignorePackage=name[,name] - Do not build named packages
 =head2 ARGUMENTS
 Arguments are passed to a JATS command.

Subversion Repositories DevTools

(root)/core_devl/trunk/TOOLS/jats_sandbox.pl – Rev 365 → 1329