Subversion Repositories DevTools

Rev

Rev 4688 | Details | Compare with Previous | Last modification | View Log | RSS feed

Rev Author Line No. Line
227 dpurdie 1 
########################################################################
263 dpurdie 2 
# Copyright (C) 2008 ERG Limited, All rights reserved
227 dpurdie 3 
#
263 dpurdie 4 
# Module name   : jats_sandbox.pl
5 
# Module type   : JATS Utility
6 
# Compiler(s)   : Perl
7 
# Environment(s): JATS
227 dpurdie 8 
#
9 
# Description   : A script to build a collection of packages in the
10 
#                 same sandbox. This script will:
11 
#
12 
#                   Determine the packages in the sandbox
13 
#                   Determine the build order of the packages
14 
#                   Build the packages in the correct order
15 
#                   Make the packages in the correct order
16 
#
17 
#                 The script will allow for:
18 
#                   The creation of a sandbox
19 
#                   The addition of packages to the sandbox
20 
#                   Removal of packages from the sandbox
21 
#
22 
#
23 
#                 Command syntax (basic)
24 
#                   jats sandbox <command> (options | actions)@
25 
#
26 
#                 Commands include:
27 
#                   create              - Create a sandbox
28 
#                   delete              - Delete a sandbox
337 dpurdie 29 
#                   info                - Show sandbox info
227 dpurdie 30 
#
31 
#                   build               - Build all packages in the sandbox
32 
#                   make                - make all packages in the sandbox
33 
#
34 
#......................................................................#
35 
 
263 dpurdie 36 
require 5.008_002;
227 dpurdie 37 
use strict;
38 
use warnings;
39 
use JatsError;
40 
use JatsSystem;
41 
use FileUtils;
245 dpurdie 42 
use JatsBuildFiles;
227 dpurdie 43 
use JatsVersionUtils;
4197 dpurdie 44 
use ArrayHashUtils;
227 dpurdie 45 
 
46 
 
47 
use Pod::Usage;                             # required for help support
48 
use Getopt::Long qw(:config require_order); # Stop on non-option
49 
my $VERSION = "1.0.0";                      # Update this
50 
 
51 
#
52 
#   Options
53 
#
54 
my $opt_debug   = $ENV{'GBE_DEBUG'};        # Allow global debug
55 
my $opt_verbose = $ENV{'GBE_VERBOSE'};      # Allow global verbose
359 dpurdie 56 
my $opt_help = 0;                           # Help level
57 
my $opt_exact = 0;                          # Exact (escrow) build
1329 dpurdie 58 
my $opt_toPackage;                          # Control recursion
59 
my $opt_fromPackage;                        # Control recursion
60 
my @opt_justPackage;                        # Control recursion
61 
my @opt_ignorePackage;                      # Control recursion
227 dpurdie 62 
 
63 
#
64 
#   Globals - Provided by the JATS environment
65 
#
4688 dpurdie 66 
my $USER            = $ENV{'USER'};
67 
my $UNIX            = $ENV{'GBE_UNIX'};
68 
my $HOME            = $ENV{'HOME'};
69 
my $GBE_SANDBOX     = $ENV{'GBE_SANDBOX'};
70 
my $GBE_DPKG_SBOX   = $ENV{'GBE_DPKG_SBOX'};
71 
my $GBE_MACHTYPE    = $ENV{'GBE_MACHTYPE'};
3559 dpurdie 72 
my $GBE_BUILDFILTER = $ENV{'GBE_BUILDFILTER'};
335 dpurdie 73 
 
4688 dpurdie 74 
my $GBE_DPKG_LOCAL      = $ENV{'GBE_DPKG_LOCAL'};
75 
my $GBE_DPKG_CACHE      = $ENV{'GBE_DPKG_CACHE'};
76 
my $GBE_DPKG            = $ENV{'GBE_DPKG'};
77 
my $GBE_DPLY            = $ENV{'GBE_DPLY'};
78 
my $GBE_DPKG_STORE      = $ENV{'GBE_DPKG_STORE'};
79 
my $GBE_DPKG_REPLICA    = $ENV{'GBE_DPKG_REPLICA'};
80 
 
227 dpurdie 81 
#
82 
#   Globals
83 
#
1329 dpurdie 84 
my @stopped = ();                         # Stopped entries
227 dpurdie 85 
my @build_order = ();                     # Build Ordered list of entries
255 dpurdie 86 
my %extern_deps;                          # Hash of external dependencies
227 dpurdie 87 
my %packages;                             # Hash of packages
88 
 
89 
 
90 
#-------------------------------------------------------------------------------
91 
# Function        : Mainline Entry Point
92 
#
93 
# Description     :
94 
#
95 
# Inputs          :
96 
#
97 
 
98 
#
99 
#   Process help and manual options
100 
#
1329 dpurdie 101 
my $result = getOptionsFromArray ( \@ARGV );
227 dpurdie 102 
pod2usage(-verbose => 0, -message => "Version: $VERSION")  if ($opt_help == 1  || ! $result);
103 
pod2usage(-verbose => 1)  if ($opt_help == 2 );
299 dpurdie 104 
pod2usage(-verbose => 2)  if ($opt_help > 2 );
227 dpurdie 105 
 
106 
#
107 
#   Configure the error reporting process now that we have the user options
108 
#
109 
ErrorConfig( 'name'    => 'SANDBOX',
110 
             'verbose' => $opt_verbose );
111 
 
112 
#
359 dpurdie 113 
#   Reconfigure the options parser to allow subcommands to parse options
227 dpurdie 114 
#
359 dpurdie 115 
Getopt::Long::Configure('permute');
227 dpurdie 116 
 
117 
#
359 dpurdie 118 
#   Determine Sandbox type. Exact or local
119 
#
120 
$opt_exact = (-f  $GBE_SANDBOX . '/sandbox_dpkg_archive/.exact' )
121 
    if ( $GBE_SANDBOX );
122 
 
123 
#
227 dpurdie 124 
#   Parse the user command and decide what to do
125 
#
359 dpurdie 126 
#   Remove user command from the command line. This will leave command options
127 
#   in @ARGV so that they can be parsed by the subcommand.
227 dpurdie 128 
#
129 
my $cmd = shift @ARGV || "";
130 
help(1)                                 if ( $cmd =~ m/^help$/ || $cmd eq "" );
359 dpurdie 131 
buildcmd($cmd, @ARGV )                  if ( $cmd =~ m/(^all$)|(^build$)/  );
132 
cache(@ARGV)                            if ( $cmd =~ m/^cache$/  );
133 
clean($cmd, @ARGV)                      if ( $cmd =~ m/(^clobber$)|(^clean$)/  );
134 
cmd('make', $cmd, @ARGV )               if ( $cmd =~ m/(^make$)/  );
135 
cmd('cmd', @ARGV)                       if ( $cmd =~ m/^cmd$/ );
136 
create_sandbox()                        if ( $cmd =~ m/^create$/ );
299 dpurdie 137 
delete_sandbox()                        if ( $cmd =~ m/^delete$/ );
227 dpurdie 138 
info(@ARGV)                             if ( $cmd =~ m/^info$/ );
359 dpurdie 139 
populate(@ARGV)                         if ( $cmd =~ m/^populate$/  );
4197 dpurdie 140 
buildfilter(@ARGV)                      if ( $cmd =~ m/^buildfilter$/  );
227 dpurdie 141 
 
142 
Error ("Unknown sandbox command: $cmd");
143 
exit 1;
144 
 
145 
 
146 
#-------------------------------------------------------------------------------
147 
#
148 
#   Give the user a clue
149 
#
150 
sub help
151 
{
152 
    my ($level) = @_;
153 
    $level = $opt_help unless ( $level );
154 
 
155 
    pod2usage(-verbose => 0, -message => "Version: ". $VERSION)  if ($level == 1 );
156 
    pod2usage(-verbose => $level -1 );
157 
}
158 
 
159 
#-------------------------------------------------------------------------------
160 
# Function        : create_sandbox
161 
#
162 
# Description     : create a sandbox in the current current directory
163 
#
164 
# Inputs          : None
165 
#
166 
#
167 
sub create_sandbox
168 
{
359 dpurdie 169 
    GetOptions (
170 
                "help:+"        => \$opt_help,
171 
                "manual:3"      => \$opt_help,
172 
                "exact"         => \$opt_exact,
173 
                ) || Error ("Invalid command line" );
174 
 
175 
    SubCommandHelp( $opt_help, "Create Sandbox") if ($opt_help || $#ARGV >= 0 );
176 
 
227 dpurdie 177 
    Error ("Cannot create a sandbox within a sandbox",
178 
           "Sandbox base is: $GBE_SANDBOX" ) if ( $GBE_SANDBOX );
359 dpurdie 179 
 
227 dpurdie 180 
    mkdir ('sandbox_dpkg_archive') || Error ("Cannot create the directory: sandbox_dpkg_archive") ;
359 dpurdie 181 
 
182 
    TouchFile( 'sandbox_dpkg_archive/.exact', 'Sandbox marker file')
183 
        if ($opt_exact);
184 
 
185 
    Message ('Sandbox created' . ($opt_exact ? ' - With exact version number processing' : ''));
227 dpurdie 186 
    exit  0;
187 
}
188 
 
189 
#-------------------------------------------------------------------------------
299 dpurdie 190 
# Function        : delete_sandbox
191 
#
192 
# Description     : Delete a sandbox
193 
#                   Its up to the user the delete the components in the sandbox
194 
#
195 
# Inputs          : None
196 
#
361 dpurdie 197 
# Returns         :
299 dpurdie 198 
#
199 
sub delete_sandbox
200 
{
359 dpurdie 201 
    GetOptions (
202 
                "help:+"        => \$opt_help,
203 
                "manual:3"      => \$opt_help,
204 
                ) || Error ("Invalid command line" );
205 
 
206 
    SubCommandHelp( $opt_help, "Delete Sandbox") if ($opt_help || $#ARGV >= 0 );
207 
 
299 dpurdie 208 
    unless ( $GBE_SANDBOX )
209 
    {
210 
        Warning("No sandbox found to delete");
211 
    }
212 
    else
213 
    {
365 dpurdie 214 
        Error ("Sandbox directory not completely removed")
361 dpurdie 215 
            if RmDirTree( "$GBE_SANDBOX/sandbox_dpkg_archive" );
299 dpurdie 216 
 
217 
        Message("Sandbox information deleted",
218 
                "Sandbox components must be manually deleted");
219 
    }
220 
    exit 0;
221 
}
222 
 
223 
#-------------------------------------------------------------------------------
227 dpurdie 224 
# Function        : info
225 
#
226 
# Description     : Display Sandbox information
227 
#
228 
# Inputs          : Command line args
229 
#                   -v  - Be more verbose
230 
#
231 
# Returns         : Will exit
232 
#
233 
sub info
234 
{
1329 dpurdie 235 
    my (@cmd_opts ) = @_;
236 
    my $show = 0;
227 dpurdie 237 
 
1329 dpurdie 238 
    Getopt::Long::Configure('pass_through');
239 
    getOptionsFromArray ( \@cmd_opts,
240 
                           'verbose:+'  => \$show,
241 
                        ) || Error ("Invalid command line" );
242 
    SubCommandHelp( $opt_help, "Sandbox Information") if ($opt_help || $#cmd_opts >=0 );
361 dpurdie 243 
 
227 dpurdie 244 
    #
245 
    #   Determine Sandbox information
246 
    #   Populate global variables
247 
    #
1329 dpurdie 248 
    calc_sandbox_info(1);
227 dpurdie 249 
 
250 
    #
251 
    #   Display information
252 
    #
3559 dpurdie 253 
    Message ("Type       : " . ($opt_exact ? 'Exact' : 'Development') );
254 
    Message ("Base       : $GBE_SANDBOX");
255 
    Message ("Archive    : $GBE_DPKG_SBOX");
256 
    Message ("BuildFilter: $GBE_BUILDFILTER" . ( (-f $GBE_SANDBOX . '/buildfilter')  ? ' - Local to sandbox' : ''));
227 dpurdie 257 
 
1329 dpurdie 258 
 
227 dpurdie 259 
    Message ("Build Order");
1329 dpurdie 260 
    foreach my $pname ( @stopped )
261 
    {
262 
        Message( "    Level:" . "-"  . " Name: " . $pname . ' (Stopped)');
263 
    }
227 dpurdie 264 
    foreach my $fe ( @build_order )
265 
    {
1329 dpurdie 266 
        Message( "    Level:" . $fe->{level} . " Name: " . $fe->{dname} . ($fe->{buildActive} ? '' : ' (Build Suppressed)'));
267 
        Message( DisplayPath ("        Path: $fe->{dir}" )) if $show;
227 dpurdie 268 
 
1329 dpurdie 269 
        if ( $show )
227 dpurdie 270 
        {
359 dpurdie 271 
            foreach my $idep ( sort values %{$fe->{'ideps'}} )
227 dpurdie 272 
            {
359 dpurdie 273 
                Message ("        I:$idep");
227 dpurdie 274 
            }
275 
 
359 dpurdie 276 
            foreach my $edep ( sort keys %{$fe->{'edeps'}} )
227 dpurdie 277 
            {
359 dpurdie 278 
                my ($ppn,$ppv) = split( $; , $edep);
279 
                Message ("        E:$ppn $ppv");
227 dpurdie 280 
            }
361 dpurdie 281 
 
227 dpurdie 282 
        }
283 
    }
284 
 
359 dpurdie 285 
    #
286 
    #   External dependencies flags
287 
    #       * - Package does not exist in dpkg_archive
288 
    #       + - Multiple versions of this package are used
289 
 
255 dpurdie 290 
    Message("External Dependencies");
227 dpurdie 291 
    foreach my $de ( sort keys %extern_deps )
292 
    {
293 
        my @vlist = keys %{$extern_deps{$de}};
335 dpurdie 294 
        my $flag = $#vlist ? '+' : '';
359 dpurdie 295 
        foreach my $pve ( @vlist )
227 dpurdie 296 
        {
359 dpurdie 297 
            my ($pn,$pv) = split( $; , $pve );
298 
            my $exists = check_package_existance($pn,$pv  ) ? '' : '*';
335 dpurdie 299 
            my $flags = sprintf ("%4.4s", $flag . $exists);
359 dpurdie 300 
            Message ("${flags}${pn} ${pv}");
1329 dpurdie 301 
            if ( $show )
227 dpurdie 302 
            {
359 dpurdie 303 
                foreach my $pkg ( @{$extern_deps{$de}{$pve}} )
227 dpurdie 304 
                {
359 dpurdie 305 
                    my $ppn = join ('.', split( $; , $pkg));
306 
                    Message ("        U:$ppn");
227 dpurdie 307 
                }
308 
            }
359 dpurdie 309 
 
227 dpurdie 310 
        }
311 
    }
312 
 
1329 dpurdie 313 
    if ( $show > 2 || $opt_verbose > 2 )
227 dpurdie 314 
    {
315 
        DebugDumpData( "extern_deps", \%extern_deps);
316 
        DebugDumpData( "build_order", \@build_order);
317 
        DebugDumpData( "packages", \%packages);
318 
    }
319 
    exit (0);
320 
}
321 
 
322 
#-------------------------------------------------------------------------------
335 dpurdie 323 
# Function        : check_package_existance
324 
#
325 
# Description     : Determine if a given package-version exists
326 
#
327 
# Inputs          : $name           - Package Name
328 
#                   $ver            - Package Version
329 
#
330 
# Returns         : true            - Package exists
331 
#
332 
sub check_package_existance
333 
{
334 
    my ($name, $ver) = @_;
335 
    #
336 
    #   Look in each package archive directory
337 
    #
338 
    foreach my $dpkg ( $GBE_DPKG_SBOX,
339 
                       $GBE_DPKG_LOCAL,
340 
                       $GBE_DPKG_CACHE,
4688 dpurdie 341 
                       $GBE_DPKG_REPLICA,
335 dpurdie 342 
                       $GBE_DPKG,
343 
                       $GBE_DPLY,
344 
                       $GBE_DPKG_STORE )
345 
    {
346 
        next unless ( $dpkg );
347 
        if ( -d "$dpkg/$name/$ver" )
348 
        {
349 
            return 1;
350 
        }
351 
    }
352 
   return 0;
353 
}
354 
 
355 
 
356 
#-------------------------------------------------------------------------------
227 dpurdie 357 
# Function        : calc_sandbox_info
358 
#
359 
# Description     : Examine the sandbox and determine all the important
360 
#                   information
361 
#
1329 dpurdie 362 
#                   Operation will be modified by
363 
#                       $opt_toPackage
364 
#                       $opt_fromPackage
365 
#                       @opt_justPackage
366 
#                       @opt_ignorePackage
227 dpurdie 367 
#
1329 dpurdie 368 
# Inputs          : info                - True: Just for info
369 
#                                               Keep supressed packages
370 
#
227 dpurdie 371 
# Returns         : Will exit if not in a sandbox
372 
#                   Populates global variables
373 
#                       @build_order - build ordered array of build entries
374 
#
375 
sub calc_sandbox_info
376 
{
1329 dpurdie 377 
    my ($info) = @_;
378 
 
227 dpurdie 379 
    #
380 
    #   Start from the root of the sandbox
381 
    #
382 
    Error ("Command must be executed from within a Sandbox") unless ( $GBE_SANDBOX );
383 
    chdir ($GBE_SANDBOX) || Error ("Cannot chdir to $GBE_SANDBOX");
384 
 
385 
    #
386 
    #   Locate all packages within the sandbox
387 
    #   These will be top-level directories - one per package
388 
    #
389 
    my @dirlist;
390 
    my @build_list;
255 dpurdie 391 
    foreach my $pname ( glob("*") )
227 dpurdie 392 
    {
255 dpurdie 393 
        next if ( $pname =~ m~^\.~ );
394 
        next if ( $pname =~ m~dpkg_archive$~ );
297 dpurdie 395 
        next if ( $pname =~ m~^CVS$~ );
255 dpurdie 396 
        next unless ( -d $pname );
397 
        Verbose ("Package discovered: $pname");
275 dpurdie 398 
 
325 dpurdie 399 
        if ( -f "$pname/stop" || -f "$pname/stop.$GBE_MACHTYPE" )
275 dpurdie 400 
        {
1329 dpurdie 401 
            push @stopped, $pname;
275 dpurdie 402 
            Warning("Package contains stop file: $pname");
403 
            next;
404 
        }
405 
 
255 dpurdie 406 
        push @dirlist, $pname;
227 dpurdie 407 
 
408 
        #
409 
        #   Locate the build files in each package
245 dpurdie 410 
        #   Scan the build files and extract dependancy information
227 dpurdie 411 
        #
359 dpurdie 412 
        my $bscanner = BuildFileScanner( $pname, 'build.pl',
413 
                                                 '--LocateAll',
414 
                                                 $opt_exact ? '--ScanExactDependencies' : '--ScanDependencies' );
245 dpurdie 415 
        $bscanner->scan();
416 
        my @blist = $bscanner->getInfo();
255 dpurdie 417 
        Warning ("Package does not have build files: $pname") unless ( @blist );
418 
        Warning ("Package has multiple build files: $pname") if ( $#blist > 0 );
245 dpurdie 419 
        push @build_list, @blist;
227 dpurdie 420 
    }
421 
 
422 
    #
423 
    #   Process each build file and extract
424 
    #       Name of the Package
425 
    #       Dependency list
426 
    #   Build up a hash of dependence information
427 
    #
428 
 
429 
    my %depends;
299 dpurdie 430 
    my %multi;
245 dpurdie 431 
    foreach my $be ( @build_list )
227 dpurdie 432 
    {
245 dpurdie 433 
        Verbose( DisplayPath ("Build file: " . $be->{dir} . " Name: " . $be->{file} ));
359 dpurdie 434 
        #
435 
        #   Sandbox vs Exact processing
436 
        #       Set a suitable display name
437 
        #       Set a suitable tag
438 
        #
439 
        $be->{dname} = $opt_exact ? $be->{full}    : $be->{mname};
440 
        $be->{tag}   = $opt_exact ? $be->{fullTag} : $be->{package};
4184 dpurdie 441 
        $be->{fname} = join ('_', $be->{name}, $be->{version});
359 dpurdie 442 
 
245 dpurdie 443 
#        DebugDumpData ("be", $be );
227 dpurdie 444 
 
445 
        #
299 dpurdie 446 
        #   Catch multiple builds for the same package
447 
        #   Report later - when we have all
448 
        #
359 dpurdie 449 
        next unless ( $be->{dname} );
450 
        push @{$multi{$be->{dname}}},$be->{dir};
299 dpurdie 451 
 
452 
        #
227 dpurdie 453 
        #   Add into dependency struct
454 
        #
1329 dpurdie 455 
        $depends{$be->{tag}} = $be;
227 dpurdie 456 
    }
457 
 
359 dpurdie 458 
    foreach my $dname ( sort keys %multi )
299 dpurdie 459 
    {
365 dpurdie 460 
        ReportError ("Multiple builders for : $dname", @{$multi{$dname}} )
359 dpurdie 461 
            if ( scalar @{$multi{$dname}} > 1 );
299 dpurdie 462 
    }
463 
    ErrorDoExit();
464 
 
245 dpurdie 465 
#DebugDumpData ("depends", \%depends );
466 
 
227 dpurdie 467 
    #
468 
    #   Determine the build order
469 
    #
470 
    @build_order = ();
471 
    my $more = 1;
472 
    my $level = 0;
473 
 
474 
    #
255 dpurdie 475 
    #   Remove any dependencies to 'external' packages
227 dpurdie 476 
    #   These will not be met internally and can be regarded as constant
477 
    #
1329 dpurdie 478 
    #   Split 'depends' into internal (ideps) and external (edeps)
479 
    #       edeps : External Dependencies
480 
    #               Key:        Name;Version
481 
    #               Value:      'tag' - index into packages
482 
    #       ideps : Internal Dependencies
483 
    #               Key:        'tag'   - Index into packages
484 
    #               Value:      'dname' - Display Name
485 
    #
227 dpurdie 486 
    foreach my $key ( keys %depends )
487 
    {
488 
        foreach my $build ( keys( %{$depends{$key}{depends}} ))
489 
        {
490 
            unless (exists $depends{$build})
491 
            {
1329 dpurdie 492 
                $depends{$key}{'edeps'}{$depends{$key}{depends}{$build}} = $build;
227 dpurdie 493 
                delete ($depends{$key}{depends}{$build}) ;
494 
                Verbose2( "Not in set: $build");
495 
            }
496 
            else
497 
            {
1329 dpurdie 498 
                $depends{$key}{'ideps'}{$build} = $depends{$build}{dname};
227 dpurdie 499 
            }
500 
        }
501 
    }
359 dpurdie 502 
 
503 
#DebugDumpData ("depends", \%depends );
504 
 
361 dpurdie 505 
 
359 dpurdie 506 
    #
507 
    #   Determine package build order
508 
    #       Scan the list of packages in the build set and determine
509 
    #       those with no dependencies. These can be built.
510 
    #       Remove those packages as dependents from all packages
511 
    #       Repeat.
512 
    #
1329 dpurdie 513 
    my %found    = map { $_ => 1 } @opt_ignorePackage;
514 
    my %notFound = map { $_ => 1 } @opt_justPackage;
515 
    my $scan_start = 0;
516 
    my $scan_stop = 0;
517 
    my $scan_active = ($opt_fromPackage) ? 0 : 1;
518 
    $scan_active = 0 if ( !$opt_fromPackage && !$opt_fromPackage && !@opt_ignorePackage && @opt_justPackage );
519 
 
227 dpurdie 520 
    while ( $more )
521 
    {
522 
        $more = 0;
523 
        $level++;
524 
        my @build;
525 
 
526 
        #
527 
        #   Locate packages with no dependencies
528 
        #
529 
        foreach my $key ( keys %depends )
530 
        {
531 
            next if ( keys( %{$depends{$key}{depends}} ) );
532 
            push @build, $key;
533 
        }
534 
 
535 
        foreach my $build ( @build )
536 
        {
537 
            $more = 1;
1329 dpurdie 538 
            my $fe = $depends{$build};
539 
            my $scan_add = $scan_active ? 1 : 0;
540 
 
4184 dpurdie 541 
            if ( $opt_fromPackage && (($fe->{mname} eq $opt_fromPackage) || ($fe->{name} eq $opt_fromPackage) || ($fe->{fname} eq $opt_fromPackage)))
1329 dpurdie 542 
            {
543 
                $scan_add = 1;
544 
                $scan_active = 1;
545 
                $scan_start = 1;
546 
            }
547 
 
4184 dpurdie 548 
            if ( $opt_toPackage && (($fe->{mname} eq $opt_toPackage) || ($fe->{name} eq $opt_toPackage) || ($fe->{fname} eq $opt_toPackage)))
1329 dpurdie 549 
            {
550 
                $scan_add = 0;
551 
                $scan_active = 0;
552 
                $scan_stop = 1;
553 
            }
554 
 
555 
            if ( @opt_justPackage )
556 
            {
557 
                foreach my $pname ( @opt_justPackage )
558 
                {
4184 dpurdie 559 
                    if ( (($fe->{mname} eq $pname) || ($fe->{name} eq $pname) || ($fe->{fname} eq $pname)))
1329 dpurdie 560 
                    {
561 
                        $scan_add = 1;
562 
                        delete $notFound{$pname};
563 
                    }
564 
                }
565 
            }
566 
 
567 
            if ( @opt_ignorePackage )
568 
            {
569 
                foreach my $pname ( @opt_ignorePackage )
570 
                {
4184 dpurdie 571 
                    if ( (($fe->{mname} eq $pname) || ($fe->{name} eq $pname) || ($fe->{fname} eq $pname)))
1329 dpurdie 572 
                    {
573 
                        $scan_add = 0;
574 
                        delete $found{$pname};
575 
                    }
576 
                }
577 
            }
578 
 
227 dpurdie 579 
            $fe->{level} = $level;
1329 dpurdie 580 
            $fe->{buildActive} = $scan_add;
227 dpurdie 581 
            $packages{$build} = $fe;
1329 dpurdie 582 
            push (@build_order, $fe) if ( $scan_add || $info );
227 dpurdie 583 
            delete $depends{$build};
584 
            delete $fe->{depends};                          # remove now its not needed
585 
        }
586 
 
587 
        foreach my $key ( keys %depends )
588 
        {
589 
            foreach my $build ( @build )
590 
            {
591 
                delete $depends{$key}{depends}{$build};
592 
            }
593 
        }
594 
    }
595 
 
596 
    #
1329 dpurdie 597 
    #   Detect bad user specifications
598 
    #
599 
    ReportError ("Specified FromPackage not found: $opt_fromPackage") if ( $opt_fromPackage && !$scan_start );
600 
    ReportError ("Specified ToPackage not found: $opt_toPackage") if ( $opt_toPackage && !$scan_stop );
601 
    ReportError ("Specified ExactPackages not found: ", keys( %notFound) ) if ( %notFound );
602 
    ReportError ("Specified IgnorePackages not found: ", keys( %found) ) if ( %found );
603 
    ErrorDoExit();
604 
 
605 
    #
606 
    #   Calculate the external dependencies
607 
    #       Only process packages that are a part of the build
608 
    #
609 
    #   extern_deps structure
610 
    #       Hash key: 'tag'   - Index into packages
611 
    #          Value: Hash of:
612 
    #                 Key  : Name;Version
613 
    #                 Value: Array of: 'tags' (Index into packages)
614 
    #                                   of packages that use the external
615 
    #                                   component.
616 
    {
617 
        Verbose ("Calculate external dependencies");
618 
        %extern_deps = ();
619 
 
620 
        foreach my $key ( keys %packages )
621 
        {
622 
                next unless ( $packages{$key}{buildActive} );
623 
                next unless ( $packages{$key}{'edeps'} );
624 
                foreach ( keys %{$packages{$key}{'edeps'}} )
625 
                {
626 
                    push @{$extern_deps{$packages{$key}{'edeps'}{$_}} {$_} }, $key;
627 
                }
628 
        }
629 
    }
630 
 
631 
    #
227 dpurdie 632 
    #   Just to be sure to be sure
633 
    #
245 dpurdie 634 
    if ( keys %depends )
635 
    {
636 
        #DebugDumpData ("depends", \%depends );
637 
        Error( "Internal algorithm error: Bad dependancy walk",
638 
               "Possible circular dependency");
639 
    }
227 dpurdie 640 
 
1329 dpurdie 641 
#   DebugDumpData("Packages", \%packages);
359 dpurdie 642 
#   DebugDumpData ("Order", \@build_order);
643 
#   DebugDumpData("External Depends", \%extern_deps );
227 dpurdie 644 
}
645 
 
646 
#-------------------------------------------------------------------------------
647 
# Function        : cmd
648 
#
649 
# Description     : Execute a command in all the sandboxes
650 
#                       Locate the base of the sandbox
651 
#                       Locate all packages in the sandbox
652 
#                       Locate all build files in each sandbox
653 
#                       Determine build order
654 
#                       Issue commands for each sandbox in order
655 
#
255 dpurdie 656 
# Inputs          : Arguments passed to jats build
227 dpurdie 657 
#
658 
# Returns         : Will exit
659 
#
660 
sub cmd
661 
{
1329 dpurdie 662 
    my ($hcmd, @cmd_opts ) = @_;
2054 dpurdie 663 
    my $opt_keepgoing;
359 dpurdie 664 
 
665 
    Getopt::Long::Configure('pass_through');
2054 dpurdie 666 
    getOptionsFromArray ( \@cmd_opts,
667 
                           'keepgoing!'  => \$opt_keepgoing,
668 
                        ) || Error ("Invalid command line" );
359 dpurdie 669 
    SubCommandHelp( $opt_help, $hcmd) if ($opt_help  );
670 
 
227 dpurdie 671 
    #
672 
    #   Determine Sandbox information
673 
    #   Populate global variables
674 
    #
675 
    calc_sandbox_info();
676 
    foreach my $fe ( @build_order )
677 
    {
678 
        my $dir = $fe->{dir};
359 dpurdie 679 
        Message( "Level:" . $fe->{level} . " Name: " . $fe->{dname} ,
227 dpurdie 680 
                  DisplayPath ("        Path: $fe->{dir}" ));
681 
 
1329 dpurdie 682 
        my $result = JatsCmd( "-cd=$dir", @cmd_opts);
2054 dpurdie 683 
        if ( $result ) {
684 
            if ( $opt_keepgoing ) {
685 
                Warning ("Cmd failure");
686 
            } else {
687 
                Error   ("Cmd failure");
688 
            }
689 
        }
227 dpurdie 690 
    }
691 
 
692 
    exit 0;
693 
}
694 
 
695 
#-------------------------------------------------------------------------------
331 dpurdie 696 
# Function        : buildcmd
697 
#
698 
# Description     : Build the entire sandbox
699 
#                   The all and the build are similar.
700 
#                   Its not really useful to do a build without a make
701 
#                   so we don't try
702 
#
703 
# Inputs          : Arguments passed to jats make
704 
#
705 
#
706 
# Returns         : Will exit
707 
#
708 
 
709 
sub buildcmd
710 
{
337 dpurdie 711 
    my ($cmd, @cmd_opts) = @_;
331 dpurdie 712 
    my @build_opts;
337 dpurdie 713 
    my @make_opts;
331 dpurdie 714 
 
715 
    #
359 dpurdie 716 
    #   Extract and options
717 
    #
718 
    Getopt::Long::Configure('pass_through');
1329 dpurdie 719 
    getOptionsFromArray ( \@cmd_opts ) || Error ("Invalid command line" );
359 dpurdie 720 
    SubCommandHelp( $opt_help, "Command $cmd") if ($opt_help );
361 dpurdie 721 
 
359 dpurdie 722 
    #
331 dpurdie 723 
    #   Insert default options
724 
    #
725 
    push @build_opts, '-noforce' if ( $cmd eq 'all' );
726 
    push @build_opts, '-force' if ( $cmd ne 'all' );
727 
 
337 dpurdie 728 
    #
729 
    #   Attempt to split the options into build and make options
730 
    #   Only handle the often used options to build.
731 
    #
732 
    foreach  ( @cmd_opts )
733 
    {
734 
        if ( m/^-cache/ || m/^-package/ || m/^-forcebuildpkg/ || m/-expert/) {
735 
            push @build_opts, $_;
736 
        } else {
737 
            push @make_opts, $_;
738 
        }
739 
    }
740 
 
331 dpurdie 741 
    push @make_opts, 'all'  unless ( @make_opts  );
742 
 
743 
    #
744 
    #   Determine Sandbox information
745 
    #   Populate global variables
746 
    #
747 
    calc_sandbox_info();
748 
    foreach my $fe ( @build_order )
749 
    {
750 
        my $dir = $fe->{dir};
359 dpurdie 751 
        Message( "Level:" . $fe->{level} . " Name: " . $fe->{dname} ,
331 dpurdie 752 
                  DisplayPath ("        Path: $fe->{dir}" ));
753 
 
754 
        JatsCmd( "-cd=$dir", 'build', @build_opts) && Error ("Build Cmd failure") if ( $result );
755 
        JatsCmd( "-cd=$dir", 'make',  @make_opts)  && Error ("Make Cmd failure")  if ( $result );
756 
    }
757 
 
758 
    exit 0;
759 
}
760 
 
761 
 
762 
#-------------------------------------------------------------------------------
273 dpurdie 763 
# Function        : clean
764 
#
765 
# Description     : Execute a command in all the sandboxes
766 
#                       Locate the base of the sandbox
767 
#                       Locate all packages in the sandbox
768 
#                       Locate all build files in each sandbox
769 
#                       Determine build order
770 
#                       Issue commands for each sandbox in order
771 
#
772 
# Inputs          : Arguments passed to jats build
773 
#
774 
# Returns         : Will exit
775 
#
776 
sub clean
777 
{
1329 dpurdie 778 
    my ($mode, @cmd_opts ) = @_;
359 dpurdie 779 
 
273 dpurdie 780 
    #
359 dpurdie 781 
    #   Extract and options
782 
    #
783 
    Getopt::Long::Configure('pass_through');
1329 dpurdie 784 
    getOptionsFromArray ( \@cmd_opts ) || Error ("Invalid command line" );
359 dpurdie 785 
    SubCommandHelp( $opt_help, "Clean") if ($opt_help );
786 
 
787 
    #
273 dpurdie 788 
    #   Determine Sandbox information
789 
    #   Populate global variables
790 
    #
791 
    calc_sandbox_info();
792 
 
793 
    my @cmd = $mode eq 'clobber' ? ('clobber') : ('make', 'clean' );
794 
 
795 
    #
796 
    #   Clobber and clean need to be done in the reverse order
797 
    #
798 
    foreach my $fe ( reverse @build_order )
799 
    {
800 
        my $dir = $fe->{dir};
359 dpurdie 801 
        Message( "Level:" . $fe->{level} . " Name: " . $fe->{dname} ,
273 dpurdie 802 
                  DisplayPath ("        Path: $fe->{dir}" ));
803 
 
1329 dpurdie 804 
        my $result = JatsCmd( "-cd=$dir", @cmd, @cmd_opts);
273 dpurdie 805 
        Error ("Cmd failure") if ( $result );
806 
    }
807 
 
808 
    exit 0;
809 
}
810 
 
811 
 
812 
#-------------------------------------------------------------------------------
337 dpurdie 813 
# Function        : cache
814 
#
815 
# Description     : Cache external packages into the sandbox
816 
#
817 
# Inputs          : @opts                   - User options
818 
#
819 
# Returns         : Nothing
820 
#
821 
sub cache
822 
{
1329 dpurdie 823 
    my (@cmd_opts) = @_;
337 dpurdie 824 
 
1329 dpurdie 825 
    getOptionsFromArray ( \@cmd_opts ) || Error ("Invalid command line" );
826 
    SubCommandHelp( $opt_help, "Cache") if ($opt_help || $#cmd_opts >= 0 );
359 dpurdie 827 
 
337 dpurdie 828 
    #
829 
    #   Determine Sandbox information
830 
    #   Populate global variables
831 
    #
832 
    Message("Cache External Dependencies");
833 
    calc_sandbox_info();
834 
 
835 
    #
1329 dpurdie 836 
    #   Walk the list of external dependencies and cache each one
337 dpurdie 837 
    #
838 
    foreach my $de ( sort keys %extern_deps )
839 
    {
840 
        my @vlist = keys %{$extern_deps{$de}};
359 dpurdie 841 
        foreach my $pve ( @vlist )
337 dpurdie 842 
        {
359 dpurdie 843 
            my ($pn,$pv) = split( $; , $pve );
844 
            Message ("Cache ${pn} ${pv}");
845 
            JatsTool ('cache_dpkg', "${pn}/${pv}" );
337 dpurdie 846 
        }
847 
    }
361 dpurdie 848 
 
337 dpurdie 849 
    exit 0;
361 dpurdie 850 
 
337 dpurdie 851 
}
852 
 
359 dpurdie 853 
#-------------------------------------------------------------------------------
854 
# Function        : populate
855 
#
856 
# Description     : Populate the sandbox with package versions
857 
#
858 
#
859 
# Inputs          : commands            - Array of command line arguments
860 
#                   Mode-0:
861 
#
862 
#                       pkg_name pkg_version        - Import files for named package
863 
#                       options:
864 
#                           -recurse                - Import dependent packages too
865 
#                           -missing                - Import dependencies not in dpkg_archive
866 
#                           -test                   - Show what would be done
867 
#                           -extractfiles           - Extract file, no view
868 
#
869 
#
870 
#
871 
#
872 
# Returns         : Does not return
873 
#
874 
use JatsRmApi;
875 
use DBI;
337 dpurdie 876 
 
359 dpurdie 877 
#
878 
#   Data Base Interface
879 
#
880 
my $RM_DB;
881 
my $PopLevel = 0;
882 
my %PopPackage;
883 
my @StrayPackages;
884 
my @PopBase;
885 
 
886 
sub populate
887 
{
1329 dpurdie 888 
    my (@cmd_opts ) = @_;
359 dpurdie 889 
    my $opt_missing = 0;
890 
    my $opt_recurse = 0;
891 
    my $opt_test = 0;
1329 dpurdie 892 
    my $opt_show = 0;
359 dpurdie 893 
    my $opt_extractfiles;
894 
    my @opt_extract = qw(-extract);
895 
    my @opt_fnames;
1329 dpurdie 896 
    my @opt_exclude;
897 
    my $opt_all;
359 dpurdie 898 
 
1329 dpurdie 899 
 
359 dpurdie 900 
    Getopt::Long::Configure('pass_through');
1329 dpurdie 901 
    getOptionsFromArray ( \@cmd_opts,
902 
                "all"               => \$opt_all,
903 
                "missing"           => \$opt_missing,
904 
                "test"              => \$opt_test,
905 
                "show"              => \$opt_show,
906 
                "recurse:100"       => \$opt_recurse,
907 
                'excludePackage:s'  => sub{ opts_add2List( \@opt_exclude, @_ )},
359 dpurdie 908 
                ) || Error ("Invalid command line" );
909 
 
910 
    SubCommandHelp( $opt_help, "Populate Sandbox") if ($opt_help );
911 
 
912 
    #
1329 dpurdie 913 
    #   Sanity tests
914 
    #
915 
    Error ("Populate: -missing and -all options are mutually exclusive")
916 
        if ( $opt_missing && $opt_all );
917 
 
918 
    #
359 dpurdie 919 
    #   Extract options for the jats extract utility
920 
    #
1329 dpurdie 921 
    foreach ( @cmd_opts )
359 dpurdie 922 
    {
923 
        if ( m~^-~ ) {
924 
            push ( @opt_extract, $_);
925 
        } else {
926 
            push ( @opt_fnames, $_);
927 
        }
928 
    }
929 
 
930 
    #
931 
    #   Allow exactly zero or two 'bare' arguments
932 
    #   Create an array of package-versions to be processed.
933 
    #
934 
    if ( $#opt_fnames >= 0 )
935 
    {
365 dpurdie 936 
        Error ("Populate: Must specify both a package name and version")
359 dpurdie 937 
            if ( $#opt_fnames != 1 );
938 
        push @PopBase, join( $;, @opt_fnames );
939 
    }
1329 dpurdie 940 
    elsif ( $opt_missing || $opt_all )
359 dpurdie 941 
    {
942 
        #
943 
        #   User has not provided a package name to extract
1329 dpurdie 944 
        #   Assume that the user will want all or missing dependencies
359 dpurdie 945 
        #
946 
        #   Determine packages that are not present
947 
        #
948 
        calc_sandbox_info();
949 
 
950 
        #
951 
        # Scan for missing dependencies
952 
        #
953 
        foreach my $de ( sort keys %extern_deps )
954 
        {
955 
            my @vlist = keys %{$extern_deps{$de}};
956 
            foreach my $pve ( @vlist )
957 
            {
958 
                my ($pn,$pv) = split( $; , $pve );
1329 dpurdie 959 
                unless ($opt_missing && check_package_existance( $pn, $pv ))
359 dpurdie 960 
                {
961 
                    push @PopBase, join( $;, $pn , $pv );
962 
                }
963 
            }
964 
        }
965 
    }
966 
    else
967 
    {
968 
        Error ("No command or option specified. See help for command usage");
969 
    }
970 
 
971 
    #
972 
    #   Process the list of package-versions
973 
    #   These are top level packages. Get details from Release Manager
974 
    #
975 
    #DebugDumpData("Data", \@PopBase );
976 
    $PopLevel = 0;
977 
    foreach my $entry ( @PopBase )
978 
    {
979 
        my ($pname, $pver ) = split( $; , $entry);
980 
 
981 
        my $pv_id = getPkgDetailsByName($pname, $pver);
982 
        Error ("populate: $pname, $pver not found in Release Manager" )
983 
            unless ( $pv_id );
984 
        getPkgDetailsByPV_ID($pv_id);
985 
    }
986 
    #
987 
    #   If recursing then process packages that have yet to
988 
    #   be processed. At the start there will be the initial user specified
989 
    #   packages on the list. Place a marker at the end so that we can
990 
    #   determine how far we are recursing down the dependency tree.
991 
    #
1329 dpurdie 992 
    $opt_recurse = ($opt_all ? 100 : $opt_recurse);
359 dpurdie 993 
    if ( $opt_recurse )
994 
    {
995 
        my $marker = join($; , '_NEXT_LEVEL_', 0, 0 );
996 
        push @StrayPackages, $marker;
997 
        $PopLevel++;
998 
 
999 
        while ( $#StrayPackages >= 0 )
1000 
        {
1001 
            my ($name, $ver, $pv_id) = split($;, shift @StrayPackages);
1002 
 
1003 
            #
1004 
            #   Marker.
1005 
            #   Increment the level of recursion
1006 
            #   Detect end conditions
1007 
            #
1008 
            if ( $name eq '_NEXT_LEVEL_' )
1009 
            {
1010 
                last unless ($#StrayPackages >= 0 );
1011 
                $PopLevel++;
1012 
                last if ( $PopLevel > $opt_recurse );
1013 
                push @StrayPackages, $marker;
1014 
                next;
1015 
            }
1016 
 
1017 
            next if ( exists $PopPackage{$name}{$ver}{done} );
1018 
            getPkgDetailsByPV_ID ( $pv_id );
1019 
            #print "Stray: $pv_id, $name, $ver\n";
1020 
        }
1021 
    }
1022 
    #DebugDumpData("Data", \%PopPackage );
1023 
 
1024 
    #
1025 
    #   Determine packages that need to be extracted
1329 dpurdie 1026 
    #   Sort alphabetically - case insensitive
359 dpurdie 1027 
    #
1329 dpurdie 1028 
    foreach my $pname ( sort {lc($a) cmp lc($b)} keys %PopPackage )
359 dpurdie 1029 
    {
1329 dpurdie 1030 
        pkgscan:
359 dpurdie 1031 
        foreach my $pver ( sort keys %{$PopPackage{$pname}} )
1032 
        {
1033 
            #
1034 
            #   Create a nice view name for the extraction
365 dpurdie 1035 
            #   Will also be used to test for package existence
359 dpurdie 1036 
            #
1037 
            my $vname = "$pname $pver";
1038 
            $vname =~ s~ ~_~g;
1039 
            $vname =~ s~__~~g;
1040 
 
1041 
            if ( -d "$GBE_SANDBOX/$vname" )
1042 
            {
1043 
                Warning("Package already in sandbox: $pname, $pver");
1044 
                next;
1045 
            }
1046 
 
1047 
            #
1048 
            #   If scanning for missing packages, then examine archives
1049 
            #   for the packages existence. Don't do this on level-0 packages
1050 
            #   These have been user specified.
1051 
            #
1052 
            if ( $opt_missing && $PopPackage{$pname}{$pver}{level}  )
1053 
            {
1054 
                my $found = check_package_existance( $pname, $pver );
1055 
                if ( $found )
1056 
                {
1057 
                    Verbose ("Package found in archive - skipped: $pname, $pver");
1058 
                    next;
1059 
                }
1060 
            }
1061 
 
1062 
            #
1329 dpurdie 1063 
            #   Has the user specifically excluded this package
1064 
            #   Allow three forms
1065 
            #       packageName
1066 
            #       packageName_Version
1067 
            #       packageName.projectName
1068 
            #
1069 
            my $excluded;
1070 
            foreach my $ename ( @opt_exclude )
1071 
            {
1072 
                if ( $ename eq $pname ) {
1073 
                    $excluded = 1;
1074 
                } elsif ($ename eq $pname .'_' . $pver ) {
1075 
                    $excluded = 1;
1076 
                } else {
1077 
                    if ( $pver =~ m~(\.[a-z]{2,4})$~ )
1078 
                    {
1079 
                        $excluded = ($ename eq $pname . $1 );
1080 
                    }
1081 
                }
1082 
 
1083 
                if ( $excluded )
1084 
                {
1085 
                    Message ("Package excluded by user - skipped: $pname, $pver");
1086 
                    next pkgscan;
1087 
                }
1088 
            }
1089 
 
1090 
            #
359 dpurdie 1091 
            #   Generate commands to extract the package
1092 
            #
1093 
            my $vcstag = $PopPackage{$pname}{$pver}{vcstag};
1094 
            my @cmd = qw(jats_vcsrelease);
1095 
            push @cmd, "-view=$vname", "-label=$vcstag", @opt_extract;
1329 dpurdie 1096 
            if ( $opt_show )
359 dpurdie 1097 
            {
1329 dpurdie 1098 
                Message ("$pname $pver");
1099 
            }
1100 
            elsif ( $opt_test )
1101 
            {
359 dpurdie 1102 
                Message "jats " . QuoteCommand (@cmd );
1103 
            }
1104 
            else
1105 
            {
1106 
                Message "Extracting: $pname $pver";
1107 
                my $rv = JatsCmd (@cmd);
1108 
                Error ("Package version not extracted")
1109 
                    if ( $rv );
1110 
            }
1111 
        }
1112 
    }
1113 
 
1114 
    #
1115 
    # This command does not return
1116 
    #
1117 
    exit (0);
1118 
}
1119 
 
337 dpurdie 1120 
#-------------------------------------------------------------------------------
4197 dpurdie 1121 
# Function        : buildfilter
1122 
#
1123 
# Description     : Manipulate the sandbox build filter
1124 
#
1125 
# Inputs          : Optional filter names
1126 
#                       +NAME - will add filter
1127 
#                       -NAME will remove it
1128 
#                       NAME will set it
1129 
#                   No args will just display the build filter
1130 
#
1131 
# Returns         : Does not return
1132 
#
1133 
sub buildfilter
1134 
{
1135 
    my (@cmd_opts ) = @_;
1136 
    my @filter_list;
1137 
    my $first_arg = 1;
1138 
    my $modified;
1139 
 
1140 
    Getopt::Long::Configure('pass_through');
1141 
    getOptionsFromArray ( \@cmd_opts ) || Error ("Invalid command line" );
1142 
 
1143 
    SubCommandHelp( $opt_help, "Buildfilter") if ($opt_help );
1144 
 
1145 
    #
1146 
    #   Set the initial filter list
1147 
    #   This will have been parsed by JATS before we get here
1148 
    #
1149 
    @filter_list = split( /[,\s]+/, join(',', $GBE_BUILDFILTER));
1150 
 
1151 
    #
1152 
    #   Extract options for the jats extract utility
1153 
    #
1154 
    foreach ( @cmd_opts )
1155 
    {
1156 
        if (m~^\+(.*)~)
1157 
        {
1158 
            UniquePush( \@filter_list, $1);
1159 
        }
1160 
        elsif (m~^\-(.*)~)
1161 
        {
1162 
            ArrayDelete( \@filter_list, $1);
1163 
        }
1164 
        else
1165 
        {
1166 
            @filter_list = () if ($first_arg);
1167 
            UniquePush( \@filter_list, $_);
1168 
        }
1169 
        $first_arg = 0;
1170 
        $modified = 1;
1171 
    }
1172 
 
1173 
    #
1174 
    #   Display the results to the user
1175 
    #
1176 
    Message('BuildFilter:', @filter_list);
1177 
 
1178 
    #
1179 
    #   Write out a new file
1180 
    #
1181 
    if ($modified)
1182 
    {
1183 
        FileCreate($GBE_DPKG_SBOX . '/buildfilter', @filter_list);
1184 
    }
1185 
 
1186 
    #
1187 
    # This command does not return
1188 
    #
1189 
    exit (0);
1190 
}
1191 
 
1192 
 
1193 
#-------------------------------------------------------------------------------
359 dpurdie 1194 
# Function        : getPkgDetailsByName
1195 
#
1196 
# Description     : Determine the PVID for a given package name and version
1197 
#
1198 
# Inputs          : $pname          - Package name
1199 
#                   $pver           - Package Version
1200 
#
361 dpurdie 1201 
# Returns         :
359 dpurdie 1202 
#
1203 
 
1204 
sub getPkgDetailsByName
1205 
{
1206 
    my ($pname, $pver) = @_;
1207 
    my $pv_id;
1208 
    my (@row);
1209 
 
1210 
    connectRM(\$RM_DB) unless ($RM_DB);
1211 
 
1212 
    # First get details for a given package version
1213 
 
1214 
    my $m_sqlstr = "SELECT pv.PV_ID, pkg.PKG_NAME, pv.PKG_VERSION" .
1215 
                    " FROM RELEASE_MANAGER.PACKAGE_VERSIONS pv, RELEASE_MANAGER.PACKAGES pkg" .
1216 
                    " WHERE pkg.PKG_NAME = \'$pname\' AND pv.PKG_VERSION = \'$pver\' AND pv.PKG_ID = pkg.PKG_ID";
1217 
    my $sth = $RM_DB->prepare($m_sqlstr);
1218 
    if ( defined($sth) )
1219 
    {
1220 
        if ( $sth->execute( ) )
1221 
        {
1222 
            if ( $sth->rows )
1223 
            {
1224 
                while ( @row = $sth->fetchrow_array )
1225 
                {
1226 
                    $pv_id = $row[0];
1227 
                    my $name = $row[1];
1228 
                    my $ver = $row[2];
1229 
                    Verbose( "getPkgDetailsByName :PV_ID= $pv_id");
1230 
                }
1231 
            }
1232 
            $sth->finish();
1233 
        }
1234 
    }
1235 
    else
1236 
    {
1237 
        Error("Prepare failure" );
1238 
    }
1239 
    return $pv_id;
1240 
}
1241 
 
1242 
#-------------------------------------------------------------------------------
1243 
# Function        : getPkgDetailsByPV_ID
1244 
#
1245 
# Description     : Populate the Packages structure given a PV_ID
1246 
#                   Called for each package in the SBOM
1247 
#
1248 
# Inputs          : PV_ID           - Package Unique Identifier
1249 
#
1250 
# Returns         : Populates Package
1251 
#
1252 
sub getPkgDetailsByPV_ID
1253 
{
1254 
    my ($PV_ID) = @_;
1255 
    my $foundDetails = 0;
1256 
    my (@row);
1257 
 
1258 
    connectRM(\$RM_DB) unless ($RM_DB);
1259 
 
1260 
    # First get details from pv_id
1261 
 
1262 
    my $m_sqlstr = "SELECT pv.PV_ID, pkg.PKG_NAME, pv.PKG_VERSION, release_manager.PK_RMAPI.return_vcs_tag($PV_ID)" .
1263 
                    " FROM RELEASE_MANAGER.PACKAGE_VERSIONS pv, RELEASE_MANAGER.PACKAGES pkg " .
1264 
                    " WHERE pv.PV_ID = \'$PV_ID\' AND pv.PKG_ID = pkg.PKG_ID";
1265 
 
1266 
    my $sth = $RM_DB->prepare($m_sqlstr);
1267 
    if ( defined($sth) )
1268 
    {
1269 
        if ( $sth->execute( ) )
1270 
        {
1271 
            if ( $sth->rows )
1272 
            {
1273 
                while ( @row = $sth->fetchrow_array )
1274 
                {
1275 
                    my $pv_id       = $row[0];
1276 
                    my $name        = $row[1];
1277 
                    my $ver         = $row[2];
1278 
                    my $vcstag      = $row[3] || '';
1279 
 
1280 
                    $vcstag =~ tr~\\/~/~;
1281 
                    Verbose ("getPkgDetailsByPV_ID: $PV_ID, $name, $ver, $vcstag");
1282 
 
1283 
                    $PopPackage{$name}{$ver}{pvid} = $PV_ID;
1284 
                    $PopPackage{$name}{$ver}{done} = 1;
1285 
                    $PopPackage{$name}{$ver}{vcstag} = $vcstag;
1286 
                    $PopPackage{$name}{$ver}{level} = $PopLevel;
1287 
                    getDependsByPV_ID( $pv_id, $name, $ver );
1288 
                }
1289 
            }
1290 
            else
1291 
            {
1292 
                Warning ("No Package details for: PVID: $PV_ID");
1293 
            }
1294 
            $sth->finish();
1295 
        }
1296 
        else
1297 
        {
1298 
            Error("getPkgDetailsByPV_ID: Execute failure", $m_sqlstr );
1299 
        }
1300 
    }
1301 
    else
1302 
    {
1303 
        Error("Prepare failure" );
1304 
    }
1305 
}
1306 
 
1307 
#-------------------------------------------------------------------------------
1308 
# Function        : getDependsByPV_ID
1309 
#
1310 
# Description     : Extract the dependancies for a given package version
1311 
#
1312 
# Inputs          : $pvid
1313 
#
1314 
# Returns         :
1315 
#
1316 
sub getDependsByPV_ID
1317 
{
1318 
    my ($pv_id, $pname, $pver) = @_;
1319 
 
1320 
    connectRM(\$RM_DB) unless ($RM_DB);
1321 
 
1322 
    #
365 dpurdie 1323 
    #   Now extract the package dependencies
359 dpurdie 1324 
    #
1325 
    my $m_sqlstr = "SELECT pkg.PKG_NAME, pv.PKG_VERSION, pd.DPV_ID" .
1326 
                   " FROM RELEASE_MANAGER.PACKAGE_DEPENDENCIES pd, RELEASE_MANAGER.PACKAGE_VERSIONS pv, RELEASE_MANAGER.PACKAGES pkg" .
1327 
                   " WHERE pd.PV_ID = \'$pv_id\' AND pd.DPV_ID = pv.PV_ID AND pv.PKG_ID = pkg.PKG_ID";
1328 
    my $sth = $RM_DB->prepare($m_sqlstr);
1329 
    if ( defined($sth) )
1330 
    {
1331 
        if ( $sth->execute( ) )
1332 
        {
1333 
            if ( $sth->rows )
1334 
            {
1335 
                while ( my @row = $sth->fetchrow_array )
1336 
                {
1337 
                    my $name = $row[0];
1338 
                    my $ver = $row[1];
1339 
 
1340 
                    Verbose2( "       Depends: $name, $ver");
1341 
                    unless ( exists $PopPackage{$name} && exists $PopPackage{$name}{$ver} && exists $PopPackage{$name}{$ver}{done} )
1342 
                    {
1343 
                        push @StrayPackages, join($;, $name, $ver, $row[2] );
1344 
                    }
1345 
                }
1346 
            }
1347 
            $sth->finish();
1348 
        }
1349 
    }
1350 
    else
1351 
    {
1352 
        Error("GetDepends:Prepare failure" );
1353 
    }
1354 
}
1355 
 
1356 
#-------------------------------------------------------------------------------
1329 dpurdie 1357 
# Function        : getOptionsFromArray
1358 
#
1359 
# Description     : Like getOptions, but handles an array
1360 
#                   Provided as the version of Perl used does not have one
1361 
#
1362 
# Inputs          : pArray                  - Ref to array
1363 
#                   ....                    - GetOptions arguments
1364 
#
1365 
# Returns         :
1366 
#
1367 
sub getOptionsFromArray
1368 
{
1369 
    my ($pArray, %args) = @_;
1370 
 
1371 
    #
1372 
    #   Common arguments
1373 
    #
1374 
    my %commonOptions = (
1375 
        'help|h:+'          => \$opt_help,
1376 
        'manual:3'          => \$opt_help,
1377 
        'verbose:+'         => \$opt_verbose,
1378 
        'topackage:s'       => \$opt_toPackage,
1379 
        'frompackage:s'     => \$opt_fromPackage,
1380 
        'justpackage:s'     => sub{ opts_add2List( \@opt_justPackage, @_ )},
1381 
        'ignorepackage:s'   => sub{ opts_add2List( \@opt_ignorePackage, @_ )},
1382 
        );
1383 
 
1384 
    #
1385 
    #   Merge in the user options
1386 
    #
1387 
    @commonOptions{keys %args} = values %args;
1388 
 
1389 
    local ( @ARGV );
1390 
    @ARGV = @$pArray;
1391 
    my $rv = GetOptions ( %commonOptions );
1392 
    @$pArray = @ARGV;
1393 
 
1394 
    ErrorConfig('verbose' => $opt_verbose );
1395 
    return $rv;
1396 
}
1397 
 
1398 
#-------------------------------------------------------------------------------
1399 
# Function        : opts_add2List
1400 
#
1401 
# Description     : Option processing helper
1402 
#                   Add comma separated options to an array
1403 
#                   User can then add items one at a time, or several at once
1404 
#
1405 
# Inputs          : aref        - Ref to an array to extent
1406 
#                   arg2        - Option name
1407 
#                   arg3        - Option value
1408 
#
1409 
# Returns         :
1410 
#
1411 
sub opts_add2List
1412 
{
1413 
    my( $ref, $name, $value) = @_;
1414 
    if ( $value )
1415 
    {
1416 
        foreach ( split(/\s*,\s*/,$value) )
1417 
        {
1418 
            push @{$ref}, $_;
1419 
        }
1420 
    }
1421 
}
1422 
 
1423 
#-------------------------------------------------------------------------------
359 dpurdie 1424 
# Function        : SubCommandHelp
1425 
#
1426 
# Description     : Provide help on a subcommand
1427 
#
1428 
# Inputs          : $help_level             - Help Level 1,2,3
1429 
#                   $topic                  - Topic Name
1430 
#
1431 
# Returns         : This function does not return
1432 
#
1433 
sub SubCommandHelp
1434 
{
1435 
    my ($help_level, $topic) = @_;
1436 
    my @sections;
1437 
    #
1438 
    #   Spell out the section we want to display
1439 
    #
1440 
    #   Note:
1441 
    #   Due to bug in pod2usage can't use 'head1' by itself
1442 
    #   Each one needs a subsection.
1443 
    #
1444 
    push @sections, qw( NAME SYNOPSIS ) ;
1445 
    push @sections, qw( ARGUMENTS OPTIONS )     if ( $help_level > 1 );
1446 
    push @sections, qw( DESCRIPTION EXAMPLES )  if ( $help_level > 2 );
1447 
 
1448 
    #
1449 
    #   Extract section from the POD
1450 
    #
1451 
    pod2usage({-verbose => 99,
1452 
               -noperldoc => 1,
1453 
               -sections => $topic . '/' . join('|', @sections) } );
1454 
}
1455 
 
1456 
#-------------------------------------------------------------------------------
227 dpurdie 1457 
#   Documentation
359 dpurdie 1458 
#   NOTE
227 dpurdie 1459 
#
359 dpurdie 1460 
#   Each subcommand MUST have
1461 
#   head1 section as used by the subcommand
1462 
#       This should be empty, as the contents will NOT be displayed
1463 
#   head2 sections called
1464 
#       NAME SYNOPSIS ARGUMENTS OPTIONS DESCRIPTION EXAMPLES
1465 
#
1466 
#=head1 xxxxxx
1467 
#=head2 NAME
1468 
#=head2 SYNOPSIS
1469 
#=head2 ARGUMENTS
1470 
#=head2 OPTIONS
1471 
#=head2 DESCRIPTION
1472 
#=head2 EXAMPLES
1473 
#
227 dpurdie 1474 
 
1475 
=pod
1476 
 
1477 
=head1 NAME
1478 
 
1479 
jats_sandbox - Build in a Development Sandbox
1480 
 
1481 
=head1 SYNOPSIS
1482 
 
361 dpurdie 1483 
  jats sandbox [options] command [command options]
227 dpurdie 1484 
 
1485 
 Options:
1329 dpurdie 1486 
    -help[=n]                  - Display help with specified detail
1487 
    -help -help                - Detailed help message
1488 
    -man                       - Full documentation
227 dpurdie 1489 
 
1329 dpurdie 1490 
 Options for recursion control:
1491 
    -toPackage=name            - Stop building after package
1492 
    -fromPackage=name          - Start building from package
1493 
    -justPackage=name[,name]   - Build named packages
1494 
    -ignorePackage=name[,name] - Do not build named packages
1495 
 
227 dpurdie 1496 
 Commands:
1497 
    help                - Same as -help
1498 
    create              - Create a sandbox in the current directory
359 dpurdie 1499 
    populate            - Populate the sandbox with packages
299 dpurdie 1500 
    delete              - Delete the sandbox
255 dpurdie 1501 
    info [[-v]-v]       - Sandbox information. -v: Be more verbose
4197 dpurdie 1502 
    buildfilter         - Modify and display sandbox buildfilter
227 dpurdie 1503 
    cmd                 - Do commands in all sandbox components
1329 dpurdie 1504 
    all                 - Do 'build', if required, then a make in all components
331 dpurdie 1505 
    build               - Force 'build and make' in all sandbox components
275 dpurdie 1506 
    make                - Do 'make' in all sandbox components
273 dpurdie 1507 
    clean               - Do 'make clean' in all sandbox components
1508 
    clobber             - Do 'build clobber' is all sandbox components
337 dpurdie 1509 
    cache               - Cache external dependent packages
227 dpurdie 1510 
 
359 dpurdie 1511 
 Use the command
1512 
    jats sandbox 'command' -h
1513 
 for command specific help
361 dpurdie 1514 
 
227 dpurdie 1515 
=head1 OPTIONS
1516 
 
1517 
=over 8
1518 
 
299 dpurdie 1519 
=item B<-help[=n]>
227 dpurdie 1520 
 
1521 
Print a brief help message and exits.
299 dpurdie 1522 
There are three levels of help
227 dpurdie 1523 
 
299 dpurdie 1524 
=over 8
1525 
 
361 dpurdie 1526 
=item   1
299 dpurdie 1527 
 
361 dpurdie 1528 
Brief synopsis
299 dpurdie 1529 
 
361 dpurdie 1530 
=item   2
299 dpurdie 1531 
 
361 dpurdie 1532 
Synopsis and option summary
1533 
 
1534 
=item   3
1535 
 
1536 
Detailed help in man format
1537 
 
299 dpurdie 1538 
=back 8
1539 
 
227 dpurdie 1540 
=item B<-help -help>
1541 
 
1542 
Print a detailed help message with an explanation for each option.
1543 
 
1544 
=item B<-man>
1545 
 
299 dpurdie 1546 
Prints the manual page and exits. This is the same a -help=3
227 dpurdie 1547 
 
1329 dpurdie 1548 
=item B<-toPackage=name>
1549 
 
1550 
This option is available in all commands that process multiple packages.
1551 
Package processing will stop at the named package.
1552 
 
4688 dpurdie 1553 
The package name can be specified in one of three forms:
1329 dpurdie 1554 
 
4184 dpurdie 1555 
=over 8
1556 
 
1557 
=item 1
1558 
 
1559 
Just the package name. ie: MyPackage
1560 
 
1561 
=item 2
1562 
 
1563 
The package name and the project suffix. ie: MyPackage.prj
1564 
 
1565 
=item 3
1566 
 
1567 
The package name and version, joined with an underscore: ie: MyPackage_1.0.0000.prj
1568 
 
1569 
=back 8
1570 
 
1329 dpurdie 1571 
=item B<-fromPackage=name>
1572 
 
1573 
This option is available in all commands that process multiple packages.
1574 
Package processing will start at the named package.
1575 
 
4688 dpurdie 1576 
The package name can be specified in one of the three forms described under the '-toPackage' option.
1329 dpurdie 1577 
 
1578 
=item B<-justPackage=name[,name]>
1579 
 
1580 
This option is available in all commands that process multiple packages. The
1581 
named packages will be processed in the correct build order. Packages that are
1582 
not named will be skipped, unless the package is being processed due to
1583 
being in the 'fromPackage' to 'toPackage' range.
1584 
 
1585 
Multiple packages can be named either by separating names with a comma, or
1586 
with multiple options.
1587 
 
4688 dpurdie 1588 
The package names can be specified as a mix of the three forms described under the '-toPackage' option.
4184 dpurdie 1589 
 
1329 dpurdie 1590 
=item B<-ignorePackage=name[,name]>
1591 
 
1592 
This option is available in all commands that process multiple packages. The
1593 
named packages will not be processed.
1594 
 
1595 
Multiple packages can be named either by separating names with a comma, or
1596 
with multiple options.
1597 
 
1598 
The exclusion of a package takes precedence over its inclusion.
1599 
 
4688 dpurdie 1600 
The package names can be specified as a mix of the three forms described under the '-toPackage' option.
4184 dpurdie 1601 
 
279 dpurdie 1602 
=back
1603 
 
227 dpurdie 1604 
=head1 DESCRIPTION
1605 
 
299 dpurdie 1606 
This program is the primary tool for the maintenance of Development Sandboxes.
1607 
 
227 dpurdie 1608 
More documentation will follow.
1609 
 
279 dpurdie 1610 
=head2 SANDBOX DIRECTORY
1611 
 
299 dpurdie 1612 
The sandbox directory is marked as being a sandbox through the use of the
1613 
'sandbox create' command. This will create a suitable structure within the
279 dpurdie 1614 
current directory.
1615 
 
1616 
Several JATS commands operate differently within a sandbox. The 'extract' and
365 dpurdie 1617 
'release' commands will create static views within the sandbox and not the
279 dpurdie 1618 
normal directory. The 'sandbox' sub commands can only be used within a sandbox.
1619 
 
1620 
The sandbox directory contains sub directories, each should contain a single
359 dpurdie 1621 
package. Sub directories may be created with the 'jats extract' command or with the
1622 
'jats sandbox populate' command.
279 dpurdie 1623 
 
1624 
Note: Symbolic links are not supported. They cannot work as he sandbox mechanism
365 dpurdie 1625 
requires that all the packages be contained within a sub directory tree so
279 dpurdie 1626 
that the root of the sandbox can be located by a simple scan of the directory
1627 
tree.
1628 
 
325 dpurdie 1629 
If a package subdirectory contains a file called 'stop' or 'stop.
1630 
<GBE_MACHTYPE>', then that package will not be considered as a part of the
1631 
build-set. A 'stop' file will prevent consideration all build platforms. The 'stop.
1632 
<GBE_MACHTYPE>' will only prevent consideration if being built on a GBE_MACHTYPE
1633 
type of computer.
279 dpurdie 1634 
 
3559 dpurdie 1635 
If the sandbox contains a file called 'buildfilter', then the contents of the
1636 
file will be read and used a buildfilter. The file is processed by reading each
1637 
line and:
1638 
 
1639 
=over 4
1640 
 
4184 dpurdie 1641 
=item *
3559 dpurdie 1642 
 
4184 dpurdie 1643 
Removing white space at both ends of the line
3559 dpurdie 1644 
 
4184 dpurdie 1645 
=item *
3559 dpurdie 1646 
 
4184 dpurdie 1647 
Removing empty lines
3559 dpurdie 1648 
 
4184 dpurdie 1649 
=item *
1650 
 
1651 
Lines that start with a # are comments and are removed
1652 
 
1653 
=item *
1654 
 
1655 
Remaining lines are joined together to form a buildfilter
1656 
 
3559 dpurdie 1657 
=back
1658 
 
359 dpurdie 1659 
=head1 Create Sandbox
299 dpurdie 1660 
 
359 dpurdie 1661 
=head2 NAME
299 dpurdie 1662 
 
359 dpurdie 1663 
Create Sandbox
1664 
 
1665 
=head2 SYNOPSIS
1666 
 
1329 dpurdie 1667 
jats sandbox create [command options]
359 dpurdie 1668 
 
1669 
 Command Options
1670 
    -help[=n]               - Command specific help, [n=1,2,3]
1671 
    -verbose[=n]            - Verbose operation
1672 
    -exact                  - Create sandbox to reproduce exact versions
1673 
 
1674 
=head2 OPTIONS
1675 
 
1676 
The 'create' command takes the following options:
1677 
 
1678 
=over 8
1679 
 
1680 
=item -exact
1681 
 
1682 
When this option is specified the sandbox is marked for exact processing of
1683 
package versions. In this mode the version numbers of the packages in the
1684 
sandbox are significant. This is ideal for recreating a package-version.
1685 
 
1686 
The default is for in-exact processing, in which the version numbers of packages
1687 
within the sandbox are not significant. The is ideal for development.
1688 
 
1689 
=back
1690 
 
1691 
=head2 DESCRIPTION
1692 
 
299 dpurdie 1693 
The 'create' command will create a sandbox in the users current directory. It is
1694 
not possible to create a sandbox within a sandbox.
1695 
 
1696 
A sandbox can be created in a directory that contains files and subdirectories.
1697 
 
1698 
The create command simply places a known directory in the current directory.
359 dpurdie 1699 
This directory is used by the sandboxing process. It may be manually deleted, or
299 dpurdie 1700 
deleted with the 'delete' command.
1701 
 
359 dpurdie 1702 
=head1 Populate Sandbox
1703 
 
1704 
=head2 NAME
1705 
 
1706 
Populate a Sandbox
1707 
 
1708 
=head2 SYNOPSIS
1709 
 
1329 dpurdie 1710 
jats sandbox populate [command options] [packageName packageVersion]
359 dpurdie 1711 
 
1712 
 Command Options
1329 dpurdie 1713 
    -help[=n]                  - Command specific help, [n=1,2,3]
1714 
    -toPackage=name            - Stop building after package
1715 
    -fromPackage=name          - Start building from package
1716 
    -justPackage=name[,name]   - Build named packages
1717 
    -ignorePackage=name[,name] - Do not build named packages
1718 
    -excludePackage=name[,name]- Do not extract named package
1719 
    -recurse[=n]               - Locate dependencies within packages
1720 
    -all                       - Populate with all dependencies
1721 
    -missing                   - Locate missing packages
1722 
    -show                      - Show packages that would be extracted
1723 
    -test                      - Do not extract packages
1724 
    -<Other>                   - Pass options to jats extract
359 dpurdie 1725 
 
1726 
=head2 ARGUMENTS
1727 
 
1728 
The 'populate' command can take a package name and version as arguments. It will
1729 
then populate the sandbox with this package. See 'DESCRIPTION' for details.
1730 
 
1731 
=head2 OPTIONS
1732 
 
1733 
The 'populate' command takes the following options:
1734 
 
1735 
=over 4
1736 
 
1329 dpurdie 1737 
=item -excludePackage=name[,name]
1738 
 
1739 
This option prevents one, or more, packages from populating the sandbox.
1740 
Packages specified with this option will not be extracted from version control
1741 
and added to the sandbox.
1742 
 
4688 dpurdie 1743 
Packages can be identified in three ways:
1329 dpurdie 1744 
 
1745 
=over 4
1746 
 
1747 
=item 1. Package Name
1748 
 
1749 
All package versions matching the named package will be excluded.
1750 
 
1751 
=item 2. Package Name and Version
1752 
 
1753 
Only the specified version of the named package will be excluded. The
1754 
user specifies the package name and version as a single string separated with
1755 
an underscore. ie: core_devl_2.100.5000.cr
1756 
 
1757 
=item 3. Package Name and Suffix
1758 
 
1759 
All packages matching the named package and project will be excluded. The
1760 
user specifies the package name and project as a single string separated with
1761 
a dot. ie: core_devl.cr
1762 
 
1763 
 
1764 
=back
1765 
 
359 dpurdie 1766 
=item -recurse[=N]
1767 
 
1768 
This option will modify the operation of the command such that dependencies
1769 
of named packages can also be extracted into the sandbox.
1770 
 
1771 
The default operation is to only extract named packages. If the option is
1772 
specified then all dependent packages are processed. An optional numeric argument
1773 
can be specified to limit the depth of the recursion.
1774 
 
1329 dpurdie 1775 
=item -all
1776 
 
1777 
This option will populate the sandbox will all dependencies of packages that are
1778 
currently in the sandbox.
1779 
 
1780 
The global options that control recursion will affect the packages that are
1781 
processed.
1782 
 
1783 
This option cannot be used with the '-missing' option.
1784 
 
359 dpurdie 1785 
=item -missing
1786 
 
1787 
This option will modify the operation of the dependency recursion scanning such
1788 
that dependent packages that exist in a package archive will not be extracted.
1789 
 
1790 
Use of this option allows a sandbox to be populated with packages that are
1791 
required by packages in the sandbox, but are not available in a package archive.
1792 
 
1329 dpurdie 1793 
The global options that control recursion will affect the packages that are
1794 
processed.
1795 
 
1796 
This option cannot be used with the '-all' option.
1797 
 
1798 
=item -show
1799 
 
1800 
This option will prevent the command from performing the extraction. It will
1801 
simply display the names of the packages that would be extracted.
1802 
 
359 dpurdie 1803 
=item -test
1804 
 
1805 
This option will prevent the command from performing the extraction. It will
1806 
simply display the JATS commands that can be used to perform the extraction.
1807 
 
1808 
=item -<Other>
1809 
 
1810 
Options not understood by the 'populate' sub command will be passed through
1811 
the package extraction program. Useful options include:
1812 
 
363 dpurdie 1813 
=over 4
359 dpurdie 1814 
 
361 dpurdie 1815 
=item *
359 dpurdie 1816 
 
361 dpurdie 1817 
-extractfiles
359 dpurdie 1818 
 
361 dpurdie 1819 
=item *
1820 
 
1821 
-branch=<branch name>
1822 
 
359 dpurdie 1823 
=back
1824 
 
1825 
=back
1826 
 
1827 
=head2 DESCRIPTION
1828 
 
1829 
The 'populate' command can be used to assist in populating the sandbox. It has
1830 
two modes of operation.
1831 
 
363 dpurdie 1832 
=over 4
359 dpurdie 1833 
 
361 dpurdie 1834 
=item 1
359 dpurdie 1835 
 
361 dpurdie 1836 
Named Package
1837 
 
363 dpurdie 1838 
If the user specifies both a package name and a package version then the command
359 dpurdie 1839 
will populate the sandbox with that package and optionally its dependencies.
1840 
 
361 dpurdie 1841 
=item 2
359 dpurdie 1842 
 
361 dpurdie 1843 
Determine missing dependencies
1844 
 
359 dpurdie 1845 
If the user does not specify a package name and version, but does specify
1846 
the '-missing' option,  then the command will examine the current sandbox and
1847 
determine missing dependent packages. It will then populate the sandbox with
1848 
these packages and optionally there dependencies.
1849 
 
1850 
=back
1851 
 
1852 
=head2 EXAMPLES
1853 
 
1854 
=over 4
1855 
 
361 dpurdie 1856 
=item *
359 dpurdie 1857 
 
361 dpurdie 1858 
jats sandbox populate package1 version1
1859 
 
359 dpurdie 1860 
This command will populate the sandbox with version1 of package1, if it does not
1861 
already exist in the sandbox.
1862 
 
361 dpurdie 1863 
=item *
359 dpurdie 1864 
 
361 dpurdie 1865 
jats sandbox populate package1 version1 -recurse -missing
1866 
 
359 dpurdie 1867 
This command will populate the sandbox with version1 of package1, if it does not
1868 
already exist in the sandbox, together will all the packages dependencies that
1869 
are not available in a package archive.
1870 
 
361 dpurdie 1871 
=item *
359 dpurdie 1872 
 
361 dpurdie 1873 
jats sandbox populate -recurse -missing
1874 
 
359 dpurdie 1875 
This command will examine the current sandbox and populate the sandbox with
1876 
packages that are required to build the packages in the sandbox and the
1877 
dependencies of these packages, provide the dependent package is not in a
1878 
package archive.
1879 
 
361 dpurdie 1880 
=item *
359 dpurdie 1881 
 
361 dpurdie 1882 
jats sandbox populate
1883 
 
359 dpurdie 1884 
This command will examine the current sandbox and populate the sandbox with
1885 
packages that are required to build the packages in the sandbox. It will not
1886 
examine the dependents of these packages.
1887 
 
1888 
=back
1889 
 
1890 
=head1 Delete Sandbox
1891 
 
1892 
=head2 NAME
1893 
 
4688 dpurdie 1894 
Delete a sandbox
359 dpurdie 1895 
 
1896 
=head2 SYNOPSIS
1897 
 
1898 
jats sandbox [options] delete
1899 
 
1900 
 Options:
1901 
    -help[=n]               - Help message, [n=1,2,3]
1902 
    -man                    - Full documentation [-help=3]
1903 
    -verbose[=n]            - Verbose command operation
1904 
 
1905 
=head2 DESCRIPTION
1906 
 
299 dpurdie 1907 
The 'delete' command will delete the sandbox's marker directory. The command may
1908 
be executed anywhere within the sandbox.
1909 
 
359 dpurdie 1910 
Once the sandbox has been deleted, the user must remove the components within the
299 dpurdie 1911 
sandbox.
1912 
 
359 dpurdie 1913 
=head1 Sandbox Information
299 dpurdie 1914 
 
359 dpurdie 1915 
=head2 NAME
1916 
 
1917 
Display Sandbox Information
1918 
 
1919 
=head2 SYNOPSIS
1920 
 
1329 dpurdie 1921 
jats sandbox info [command options]
359 dpurdie 1922 
 
1923 
 Command Options
1329 dpurdie 1924 
    -help[=n]                  - Command specific help, [n=1,2,3]
1925 
    -verbose[=n]               - Display more information
1926 
    -toPackage=name            - Stop building after package
1927 
    -fromPackage=name          - Start building from package
1928 
    -justPackage=name[,name]   - Build named packages
1929 
    -ignorePackage=name[,name] - Do not build named packages
361 dpurdie 1930 
 
359 dpurdie 1931 
=head2 OPTIONS
1932 
 
1933 
=over
1934 
 
1935 
=item B<-verbose[=n]>
1936 
 
1937 
This options will increase the verbosity of the information being displayed.
1938 
Values 1 and 2 are described in the detailed 'DESCRIPTION'. Other values are
1939 
reserved for diagnostic use.
1940 
 
1941 
=back
1942 
 
1943 
=head2 DESCRIPTION
1944 
 
299 dpurdie 1945 
The 'info' command will display information about the build order and the
359 dpurdie 1946 
dependencies of packages that it finds within the sandbox.
299 dpurdie 1947 
 
359 dpurdie 1948 
The command works within various levels of verbosity:
299 dpurdie 1949 
 
1950 
=over 8
1951 
 
361 dpurdie 1952 
=item *
299 dpurdie 1953 
 
361 dpurdie 1954 
No Verbosity
1955 
 
299 dpurdie 1956 
The basic command will display the build order and the external
335 dpurdie 1957 
dependencies. External dependencies may be prefixed with one of the
1958 
following indicators:
299 dpurdie 1959 
 
335 dpurdie 1960 
=over 8
1961 
 
361 dpurdie 1962 
=item   '+' Multiple versions of this package are being used by sandboxed components.
335 dpurdie 1963 
 
361 dpurdie 1964 
=item   '*' The package cannot be found in any of the package archives.
335 dpurdie 1965 
 
1966 
=back
1967 
 
361 dpurdie 1968 
=item *
299 dpurdie 1969 
 
361 dpurdie 1970 
Verbosity of 1
1971 
 
359 dpurdie 1972 
This level of verbosity will display the build order and detailed information
299 dpurdie 1973 
on the dependencies. The dependencies will be prefixed with:
1974 
 
1975 
=over 8
1976 
 
361 dpurdie 1977 
=item   E Dependent Package is external to the sandbox
299 dpurdie 1978 
 
361 dpurdie 1979 
=item   I Dependent Package is internal to the sandbox
299 dpurdie 1980 
 
1981 
=back
1982 
 
335 dpurdie 1983 
External dependencies may be prefixed with one of the indicators described for
1984 
no-verbosity. Additionally the internal consumer of the external package is also
1985 
shown. These are prefixed with a 'U'.
299 dpurdie 1986 
 
361 dpurdie 1987 
=item *
299 dpurdie 1988 
 
361 dpurdie 1989 
Verbosity of 2
1990 
 
359 dpurdie 1991 
Reserved for future use
299 dpurdie 1992 
 
361 dpurdie 1993 
=item *
299 dpurdie 1994 
 
361 dpurdie 1995 
Verbosity over 2
1996 
 
359 dpurdie 1997 
This should be considered a debug option. Undocumented internal information will
299 dpurdie 1998 
be displayed.
1999 
 
2000 
=back
2001 
 
4197 dpurdie 2002 
=head1 Buildfilter
2003 
 
2004 
=head2 NAME
2005 
 
2006 
Display and Modify Sandbox buildfilter
2007 
 
2008 
=head2 SYNOPSIS
2009 
 
2010 
jats sandbox buildfilter [command options] [TARGETS]+
2011 
 
2012 
 Command Options
2013 
    -help[=n]               - Command specific help, [n=1,2,3]
2014 
    -man                    - Same as -help=3
2015 
 
2016 
 Target Names
2017 
    -TARGET                 - Remove target from the current buildfilter
2018 
    +TARGET                 - Add target to current buildfilter
2019 
    TARGET                  - If first target, then reset buildfilter
2020 
                              and add target, otherwise add target.
2021 
 
2022 
=head2 OPTIONS
2023 
 
2024 
The 'buildfilter' command takes the following options:
2025 
 
2026 
=over 8
2027 
 
2028 
=item -TARGET
2029 
 
2030 
If a target name starts with a '-' and is not an option, then that target will be
2031 
removed from the current buildfilter.
2032 
 
2033 
If the named target is not a part of the current buildfilter then nothing will happen.
2034 
 
2035 
=item +TARGET
2036 
 
2037 
If a target name starts with a '+' then that target will be added to the current buildfilter.
2038 
 
2039 
If the named target is already a part of the current buildfilter then nothing will happen.
2040 
 
2041 
 
2042 
=item TARGET
2043 
 
2044 
If a target name does not start with either a '-' or a '+' then the target will be added to the
2045 
current buildfilter.
2046 
 
2047 
If this is the first named target then the build filter will be set to this one target.
2048 
 
2049 
=back
2050 
 
2051 
=head2 DESCRIPTION
2052 
 
2053 
The 'buildfilter' command will display and optionally modify the build filter used within
2054 
the sandbox.
2055 
 
2056 
=head2 EXAMPLES
2057 
 
2058 
The command
2059 
 
2060 
    jats sandbox buildfilter
2061 
 
2062 
will simply display the current buildfilter.
2063 
 
2064 
The command
2065 
 
2066 
    jats sandbox buildfilter +COBRA +PPC_603E
2067 
 
2068 
will append the build targets COBRA and PPC_603E to the current buildfilter.
2069 
 
2070 
The command
2071 
 
2072 
    jats sandbox buildfilter -COBRA
2073 
 
2074 
will remove the build target COBRA from the current buildfilter.
2075 
 
2076 
The command
2077 
 
2078 
    jats sandbox buildfilter COBRA +PPC_603E
2079 
 or jats sandbox buildfilter COBRA PPC_603E
2080 
 
2081 
will set the buildfilter to be COBRA and PPC_603E
2082 
 
359 dpurdie 2083 
=head1 Command all
331 dpurdie 2084 
 
359 dpurdie 2085 
=head2 NAME
2086 
 
2087 
Build packages in the sandbox
2088 
 
2089 
=head2 SYNOPSIS
2090 
 
1329 dpurdie 2091 
jats sandbox all [command options] [arguments]
359 dpurdie 2092 
 
2093 
 Command Options
1329 dpurdie 2094 
    -help[=n]                  - Command specific help, [n=1,2,3]
2095 
    -toPackage=name            - Stop building after package
2096 
    -fromPackage=name          - Start building from package
2097 
    -justPackage=name[,name]   - Build named packages
2098 
    -ignorePackage=name[,name] - Do not build named packages
359 dpurdie 2099 
 
2100 
=head2 ARGUMENTS
2101 
 
2102 
Arguments are passed to the 'make' phase of the process.
2103 
 
2104 
=head2 OPTIONS
2105 
 
2106 
The are command specific options.
2107 
 
2108 
=head2 DESCRIPTION
2109 
 
331 dpurdie 2110 
The 'all' command will perform build, if the build files are out of date,
2111 
followed by a make in each of the packages within the sandbox, in the correct
2112 
build order.
2113 
 
2114 
Any arguments are passed to the 'make' phase of the process.
2115 
 
2116 
This command may be used to:
2117 
 
2118 
=over 8
2119 
 
361 dpurdie 2120 
=item *
331 dpurdie 2121 
 
361 dpurdie 2122 
Pickup any build file changes.
331 dpurdie 2123 
 
361 dpurdie 2124 
=item *
2125 
 
2126 
Resume a failed build.
2127 
 
331 dpurdie 2128 
=back
2129 
 
359 dpurdie 2130 
=head1 Command build
331 dpurdie 2131 
 
359 dpurdie 2132 
=head2 NAME
2133 
 
2134 
Build packages in the sandbox
2135 
 
2136 
=head2 SYNOPSIS
2137 
 
1329 dpurdie 2138 
jats sandbox build [command options] [arguments]
359 dpurdie 2139 
 
2140 
 Command Options
1329 dpurdie 2141 
    -help[=n]                  - Command specific help, [n=1,2,3]
2142 
    -toPackage=name            - Stop building after package
2143 
    -fromPackage=name          - Start building from package
2144 
    -justPackage=name[,name]   - Build named packages
2145 
    -ignorePackage=name[,name] - Do not build named packages
359 dpurdie 2146 
 
2147 
=head2 ARGUMENTS
2148 
 
2149 
Arguments are passed to the 'make' phase of the process.
2150 
 
2151 
=head2 OPTIONS
2152 
 
2153 
The are no command specific options.
2154 
 
2155 
=head2 DESCRIPTION
2156 
 
331 dpurdie 2157 
The 'build' command will force a build followed by a make in each of the packages
2158 
within the sandbox, in the correct build order.
2159 
 
2160 
Any arguments are passed to the 'make' phase of the process.
2161 
 
2162 
In practice, the 'sandbox all' command is quicker.
2163 
 
359 dpurdie 2164 
=head1 Clean
331 dpurdie 2165 
 
359 dpurdie 2166 
=head2 NAME
2167 
 
2168 
Clean all sandbox components
2169 
 
2170 
=head2 SYNOPSIS
2171 
 
1329 dpurdie 2172 
jats sandbox clean|clobber [command options]
359 dpurdie 2173 
 
2174 
 Command Options
1329 dpurdie 2175 
    -help[=n]                  - Command specific help, [n=1,2,3]
2176 
    -toPackage=name            - Stop building after package
2177 
    -fromPackage=name          - Start building from package
2178 
    -justPackage=name[,name]   - Build named packages
2179 
    -ignorePackage=name[,name] - Do not build named packages
359 dpurdie 2180 
 
2181 
=head2 ARGUMENTS
2182 
 
2183 
None
2184 
 
2185 
=head2 OPTIONS
2186 
 
2187 
No command specific options
2188 
 
2189 
=head2 DESCRIPTION
2190 
 
2191 
The 'clean' command will perform a 'jats make clean' in all components in the
2192 
sandbox.
2193 
 
2194 
The 'clobber' command will perform a 'jats clobber' in all components in the
2195 
sandbox.
2196 
 
2197 
=head1 make
2198 
 
2199 
=head2 NAME
2200 
 
2201 
Make packages in the sandbox
2202 
 
2203 
=head2 SYNOPSIS
2204 
 
1329 dpurdie 2205 
jats sandbox make [command options] [arguments]
359 dpurdie 2206 
 
2207 
 Command Options
1329 dpurdie 2208 
    -help[=n]                  - Command specific help, [n=1,2,3]
2209 
    -toPackage=name            - Stop building after package
2210 
    -fromPackage=name          - Start building from package
2211 
    -justPackage=name[,name]   - Build named packages
2212 
    -ignorePackage=name[,name] - Do not build named packages
359 dpurdie 2213 
 
2214 
=head2 ARGUMENTS
2215 
 
2216 
Arguments are passed to the 'make' phase of the process.
2217 
 
2218 
=head2 OPTIONS
2219 
 
2220 
The are no command specific options.
2221 
 
2222 
=head2 DESCRIPTION
2223 
 
331 dpurdie 2224 
The 'make' command will perform a 'make' operation in each of the packages
2225 
within the sandbox, in the correct build order.
2226 
 
2227 
Any arguments are passed to the 'make'.
2228 
 
359 dpurdie 2229 
=head1 cmd
331 dpurdie 2230 
 
359 dpurdie 2231 
=head2 NAME
2232 
 
2233 
Process each package with a specified command.
2234 
 
2235 
=head2 SYNOPSIS
2236 
 
1329 dpurdie 2237 
jats sandbox cmd [command options] [arguments]
359 dpurdie 2238 
 
2239 
 Command Options
1329 dpurdie 2240 
    -help[=n]                  - Command specific help, [n=1,2,3]
2054 dpurdie 2241 
    -[no]keepgoing             - Ignore errors
1329 dpurdie 2242 
    -toPackage=name            - Stop building after package
2243 
    -fromPackage=name          - Start building from package
2244 
    -justPackage=name[,name]   - Build named packages
2245 
    -ignorePackage=name[,name] - Do not build named packages
359 dpurdie 2246 
 
2247 
=head2 ARGUMENTS
2248 
 
2249 
Arguments are passed to a JATS command.
2250 
 
2251 
=head2 OPTIONS
2252 
 
2054 dpurdie 2253 
=over
359 dpurdie 2254 
 
2054 dpurdie 2255 
=item B<-[no]keepgoing>
2256 
 
2257 
This options controls the behaviour of the command when an error is encountered.
2258 
 
4688 dpurdie 2259 
The default operation is to terminate the command on the package with the
2054 dpurdie 2260 
error. This can be modified so that errors are ignored.
2261 
 
2262 
=back
2263 
 
359 dpurdie 2264 
=head2 DESCRIPTION
2265 
 
331 dpurdie 2266 
The 'cmd' command will pass all of its arguments to JATS in the build directory
2267 
of each of the packages within the sandbox, in the package build order.
2268 
 
4086 dpurdie 2269 
=head2 EXAMPLES
2270 
 
2271 
The following command will update all the Subversion-based packages in the sandbox.
2272 
 
2273 
    jats sandbox cmd eprog svn update
2274 
 
2275 
Note the use of 'eprog' in the command string. This tells JATS to run the external
2276 
(to JATS) program. Without this the command would run the JATS-internal command
2277 
called 'svn' - with different results.
2278 
 
2279 
The following command will update the dependencies in the build.pl files to match
2280 
those of a nominated release. This will only affect the package versions
2281 
external to the sandbox, although all version information in the build.pl
2282 
files will be updated.
2283 
 
2284 
    jats sandbox cmd upddep -rtagid=12345
2285 
 
359 dpurdie 2286 
=head1 Cache
331 dpurdie 2287 
 
359 dpurdie 2288 
=head2 NAME
331 dpurdie 2289 
 
359 dpurdie 2290 
Cache dependent packages
331 dpurdie 2291 
 
359 dpurdie 2292 
jats sandbox [options] cache [command options]
331 dpurdie 2293 
 
359 dpurdie 2294 
 Options:
2295 
    -help[=n]               - Help message, [n=1,2,3]
2296 
    -man                    - Full documentation [-help=3]
2297 
    -verbose[=n]            - Verbose command operation
337 dpurdie 2298 
 
359 dpurdie 2299 
 Command Options
2300 
    -help[=n]               - Command specific help, [n=1,2,3]
337 dpurdie 2301 
 
359 dpurdie 2302 
=head2 ARGUMENTS
2303 
 
2304 
The are no command specific arguments.
2305 
 
2306 
=head2 OPTIONS
2307 
 
2308 
The are no command specific options.
2309 
 
2310 
=head2 DESCRIPTION
2311 
 
2312 
The 'cache' command will cache all external dependent packages into the users
2313 
dpkg_archive_cache as defined through the EnvVar GBE_DPKG_CACHE. The result is
2314 
similar to the command 'jats sandbox build -cache', without the overhead of
2315 
building the sandbox components.
2316 
 
2317 
This command allows the simple creation of a small development environment that
2318 
is not tied to the larger Development Environment. It may then be used in a
337 dpurdie 2319 
disconnected mode to perform development.
2320 
 
227 dpurdie 2321 
=cut
2322