Subversion Repositories DevTools

Rev

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