WebSVN – DevTools – Blame – /core_devl/branches/dpurdie_devl/TOOLS/jats_sandbox.pl

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

Subversion Repositories DevTools

(root)/core_devl/branches/dpurdie_devl/TOOLS/jats_sandbox.pl – Rev 4018