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`
227	dpurdie	57
		58	`#`
		59	`# Globals - Provided by the JATS environment`
		60	`#`
		61	`my $USER = $ENV{'USER'};`
		62	`my $UNIX = $ENV{'GBE_UNIX'};`
		63	`my $HOME = $ENV{'HOME'};`
		64	`my $GBE_SANDBOX = $ENV{'GBE_SANDBOX'};`
		65	`my $GBE_DPKG_SBOX= $ENV{'GBE_DPKG_SBOX'};`
325	dpurdie	66	`my $GBE_MACHTYPE = $ENV{'GBE_MACHTYPE'};`
227	dpurdie	67
335	dpurdie	68	`my $GBE_DPKG_LOCAL = $ENV{'GBE_DPKG_LOCAL'};`
		69	`my $GBE_DPKG_CACHE = $ENV{'GBE_DPKG_CACHE'};`
		70	`my $GBE_DPKG = $ENV{'GBE_DPKG'};`
		71	`my $GBE_DPLY = $ENV{'GBE_DPLY'};`
		72	`my $GBE_DPKG_STORE = $ENV{'GBE_DPKG_STORE'};`
		73
227	dpurdie	74	`#`
		75	`# Globals`
		76	`#`
		77	`my @build_order = (); # Build Ordered list of entries`
255	dpurdie	78	`my %extern_deps; # Hash of external dependencies`
227	dpurdie	79	`my %packages; # Hash of packages`
		80
		81
		82	`#-------------------------------------------------------------------------------`
		83	`# Function : Mainline Entry Point`
		84	`#`
		85	`# Description :`
		86	`#`
		87	`# Inputs :`
		88	`#`
		89	`my $result = GetOptions (`
299	dpurdie	90	`"help\|h:+" => \$opt_help,`
		91	`"manual:3" => \$opt_help,`
337	dpurdie	92	`"verbose:+" => \$opt_verbose, # flag, multiple use allowed`
227	dpurdie	93	`);`
		94
		95	`#`
		96	`# UPDATE THE DOCUMENTATION AT THE END OF THIS FILE !!!`
		97	`#`
		98
		99	`#`
		100	`# Process help and manual options`
		101	`#`
		102	`pod2usage(-verbose => 0, -message => "Version: $VERSION") if ($opt_help == 1 \|\| ! $result);`
		103	`pod2usage(-verbose => 1) if ($opt_help == 2 );`
299	dpurdie	104	`pod2usage(-verbose => 2) if ($opt_help > 2 );`
227	dpurdie	105
		106	`#`
		107	`# Configure the error reporting process now that we have the user options`
		108	`#`
		109	`ErrorConfig( 'name' => 'SANDBOX',`
		110	`'verbose' => $opt_verbose );`
		111
		112	`#`
359	dpurdie	113	`# Reconfigure the options parser to allow subcommands to parse options`
227	dpurdie	114	`#`
359	dpurdie	115	`Getopt::Long::Configure('permute');`
227	dpurdie	116
		117	`#`
359	dpurdie	118	`# Determine Sandbox type. Exact or local`
		119	`#`
		120	`$opt_exact = (-f $GBE_SANDBOX . '/sandbox_dpkg_archive/.exact' )`
		121	`if ( $GBE_SANDBOX );`
		122
		123	`#`
227	dpurdie	124	`# Parse the user command and decide what to do`
		125	`#`
359	dpurdie	126	`# Remove user command from the command line. This will leave command options`
		127	`# in @ARGV so that they can be parsed by the subcommand.`
227	dpurdie	128	`#`
		129	`my $cmd = shift @ARGV \|\| "";`
		130	`help(1) if ( $cmd =~ m/^help$/ \|\| $cmd eq "" );`
359	dpurdie	131	`buildcmd($cmd, @ARGV ) if ( $cmd =~ m/(^all$)\|(^build$)/ );`
		132	`cache(@ARGV) if ( $cmd =~ m/^cache$/ );`
		133	`clean($cmd, @ARGV) if ( $cmd =~ m/(^clobber$)\|(^clean$)/ );`
		134	`cmd('make', $cmd, @ARGV ) if ( $cmd =~ m/(^make$)/ );`
		135	`cmd('cmd', @ARGV) if ( $cmd =~ m/^cmd$/ );`
		136	`create_sandbox() if ( $cmd =~ m/^create$/ );`
299	dpurdie	137	`delete_sandbox() if ( $cmd =~ m/^delete$/ );`
227	dpurdie	138	`info(@ARGV) if ( $cmd =~ m/^info$/ );`
359	dpurdie	139	`populate(@ARGV) if ( $cmd =~ m/^populate$/ );`
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	`{`
		213	`Error ("Sandbox directory not completly 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	`{`
359	dpurdie	234	`GetOptions (`
		235	`"help:+" => \$opt_help,`
		236	`"manual:3" => \$opt_help,`
		237	`"verbose:+" => \$opt_verbose,`
		238	`) \|\| Error ("Invalid command line" );`
227	dpurdie	239
359	dpurdie	240	`SubCommandHelp( $opt_help, "Sandbox Information") if ($opt_help \|\| $#ARGV >=0 );`
361	dpurdie	241
227	dpurdie	242	`#`
		243	`# Determine Sandbox information`
		244	`# Populate global variables`
		245	`#`
		246	`calc_sandbox_info();`
		247
		248	`#`
		249	`# Display information`
		250	`#`
359	dpurdie	251	`Message ("Type : " . ($opt_exact ? 'Exact' : 'Development') );`
		252	`Message ("Base : $GBE_SANDBOX");`
227	dpurdie	253	`Message ("Archive: $GBE_DPKG_SBOX");`
		254
		255	`Message ("Build Order");`
		256	`foreach my $fe ( @build_order )`
		257	`{`
359	dpurdie	258	`Message( " Level:" . $fe->{level} . " Name: " . $fe->{dname} );`
227	dpurdie	259	`Message( DisplayPath (" Path: $fe->{dir}" )) if $opt_verbose;`
		260
		261	`if ( $opt_verbose )`
		262	`{`
359	dpurdie	263	`foreach my $idep ( sort values %{$fe->{'ideps'}} )`
227	dpurdie	264	`{`
359	dpurdie	265	`Message (" I:$idep");`
227	dpurdie	266	`}`
		267
359	dpurdie	268	`foreach my $edep ( sort keys %{$fe->{'edeps'}} )`
227	dpurdie	269	`{`
359	dpurdie	270	`my ($ppn,$ppv) = split( $; , $edep);`
		271	`Message (" E:$ppn $ppv");`
227	dpurdie	272	`}`
361	dpurdie	273
227	dpurdie	274	`}`
		275	`}`
		276
359	dpurdie	277	`#`
		278	`# External dependencies flags`
		279	`# * - Package does not exist in dpkg_archive`
		280	`# + - Multiple versions of this package are used`
		281
255	dpurdie	282	`Message("External Dependencies");`
227	dpurdie	283	`foreach my $de ( sort keys %extern_deps )`
		284	`{`
		285	`my @vlist = keys %{$extern_deps{$de}};`
335	dpurdie	286	`my $flag = $#vlist ? '+' : '';`
359	dpurdie	287	`foreach my $pve ( @vlist )`
227	dpurdie	288	`{`
359	dpurdie	289	`my ($pn,$pv) = split( $; , $pve );`
		290	`my $exists = check_package_existance($pn,$pv ) ? '' : '*';`
335	dpurdie	291	`my $flags = sprintf ("%4.4s", $flag . $exists);`
359	dpurdie	292	`Message ("${flags}${pn} ${pv}");`
227	dpurdie	293	`if ( $opt_verbose )`
		294	`{`
359	dpurdie	295	`foreach my $pkg ( @{$extern_deps{$de}{$pve}} )`
227	dpurdie	296	`{`
359	dpurdie	297	`my $ppn = join ('.', split( $; , $pkg));`
		298	`Message (" U:$ppn");`
227	dpurdie	299	`}`
		300	`}`
359	dpurdie	301
227	dpurdie	302	`}`
		303	`}`
		304
		305	`if ( $opt_verbose > 2 )`
		306	`{`
		307	`DebugDumpData( "extern_deps", \%extern_deps);`
		308	`DebugDumpData( "build_order", \@build_order);`
		309	`DebugDumpData( "packages", \%packages);`
		310	`}`
		311	`exit (0);`
		312	`}`
		313
		314	`#-------------------------------------------------------------------------------`
335	dpurdie	315	`# Function : check_package_existance`
		316	`#`
		317	`# Description : Determine if a given package-version exists`
		318	`#`
		319	`# Inputs : $name - Package Name`
		320	`# $ver - Package Version`
		321	`#`
		322	`# Returns : true - Package exists`
		323	`#`
		324	`sub check_package_existance`
		325	`{`
		326	`my ($name, $ver) = @_;`
		327	`#`
		328	`# Look in each package archive directory`
		329	`#`
		330	`foreach my $dpkg ( $GBE_DPKG_SBOX,`
		331	`$GBE_DPKG_LOCAL,`
		332	`$GBE_DPKG_CACHE,`
		333	`$GBE_DPKG,`
		334	`$GBE_DPLY,`
		335	`$GBE_DPKG_STORE )`
		336	`{`
		337	`next unless ( $dpkg );`
		338	`if ( -d "$dpkg/$name/$ver" )`
		339	`{`
		340	`return 1;`
		341	`}`
		342	`}`
		343	`return 0;`
		344	`}`
		345
		346
		347	`#-------------------------------------------------------------------------------`
227	dpurdie	348	`# Function : calc_sandbox_info`
		349	`#`
		350	`# Description : Examine the sandbox and determine all the important`
		351	`# information`
		352	`#`
		353	`# Inputs : None`
		354	`#`
		355	`# Returns : Will exit if not in a sandbox`
		356	`# Populates global variables`
		357	`# @build_order - build ordered array of build entries`
		358	`#`
		359	`sub calc_sandbox_info`
		360	`{`
		361	`#`
		362	`# Start from the root of the sandbox`
		363	`#`
		364	`Error ("Command must be executed from within a Sandbox") unless ( $GBE_SANDBOX );`
		365	`chdir ($GBE_SANDBOX) \|\| Error ("Cannot chdir to $GBE_SANDBOX");`
		366
		367	`#`
		368	`# Locate all packages within the sandbox`
		369	`# These will be top-level directories - one per package`
		370	`#`
		371	`my @dirlist;`
		372	`my @build_list;`
255	dpurdie	373	`foreach my $pname ( glob("*") )`
227	dpurdie	374	`{`
255	dpurdie	375	`next if ( $pname =~ m~^\.~ );`
		376	`next if ( $pname =~ m~dpkg_archive$~ );`
297	dpurdie	377	`next if ( $pname =~ m~^CVS$~ );`
255	dpurdie	378	`next unless ( -d $pname );`
		379	`Verbose ("Package discovered: $pname");`
275	dpurdie	380
325	dpurdie	381	`if ( -f "$pname/stop" \|\| -f "$pname/stop.$GBE_MACHTYPE" )`
275	dpurdie	382	`{`
		383	`Warning("Package contains stop file: $pname");`
		384	`next;`
		385	`}`
		386
255	dpurdie	387	`push @dirlist, $pname;`
227	dpurdie	388
		389	`#`
		390	`# Locate the build files in each package`
245	dpurdie	391	`# Scan the build files and extract dependancy information`
227	dpurdie	392	`#`
359	dpurdie	393	`my $bscanner = BuildFileScanner( $pname, 'build.pl',`
		394	`'--LocateAll',`
		395	`$opt_exact ? '--ScanExactDependencies' : '--ScanDependencies' );`
245	dpurdie	396	`$bscanner->scan();`
		397	`my @blist = $bscanner->getInfo();`
255	dpurdie	398	`Warning ("Package does not have build files: $pname") unless ( @blist );`
		399	`Warning ("Package has multiple build files: $pname") if ( $#blist > 0 );`
245	dpurdie	400	`push @build_list, @blist;`
227	dpurdie	401	`}`
		402
		403	`#`
		404	`# Process each build file and extract`
		405	`# Name of the Package`
		406	`# Dependency list`
		407	`# Build up a hash of dependence information`
		408	`#`
		409
		410	`my %depends;`
299	dpurdie	411	`my %multi;`
245	dpurdie	412	`foreach my $be ( @build_list )`
227	dpurdie	413	`{`
245	dpurdie	414	`Verbose( DisplayPath ("Build file: " . $be->{dir} . " Name: " . $be->{file} ));`
359	dpurdie	415
		416	`#`
		417	`# Sandbox vs Exact processing`
		418	`# Set a suitable display name`
		419	`# Set a suitable tag`
		420	`#`
		421	`$be->{dname} = $opt_exact ? $be->{full} : $be->{mname};`
		422	`$be->{tag} = $opt_exact ? $be->{fullTag} : $be->{package};`
		423
245	dpurdie	424	`# DebugDumpData ("be", $be );`
227	dpurdie	425
		426	`#`
299	dpurdie	427	`# Catch multiple builds for the same package`
		428	`# Report later - when we have all`
		429	`#`
359	dpurdie	430	`next unless ( $be->{dname} );`
		431	`push @{$multi{$be->{dname}}},$be->{dir};`
299	dpurdie	432
		433	`#`
227	dpurdie	434	`# Add into dependency struct`
		435	`#`
359	dpurdie	436	`$depends{$be->{tag}}{entry} = $be;`
		437	`$depends{$be->{tag}}{depends} = $be->{depends};`
227	dpurdie	438	`}`
		439
359	dpurdie	440	`foreach my $dname ( sort keys %multi )`
299	dpurdie	441	`{`
359	dpurdie	442	`ReportError ("Mutiple builders for : $dname", @{$multi{$dname}} )`
		443	`if ( scalar @{$multi{$dname}} > 1 );`
299	dpurdie	444	`}`
		445	`ErrorDoExit();`
		446
245	dpurdie	447	`#DebugDumpData ("depends", \%depends );`
		448
227	dpurdie	449	`#`
		450	`# Determine the build order`
		451	`#`
		452	`@build_order = ();`
		453	`my $more = 1;`
		454	`my $level = 0;`
		455
		456	`#`
255	dpurdie	457	`# Remove any dependencies to 'external' packages`
227	dpurdie	458	`# These will not be met internally and can be regarded as constant`
		459	`#`
		460	`foreach my $key ( keys %depends )`
		461	`{`
		462	`foreach my $build ( keys( %{$depends{$key}{depends}} ))`
		463	`{`
		464	`unless (exists $depends{$build})`
		465	`{`
359	dpurdie	466	`push @{$extern_deps{$build} {$depends{$key}{depends}{$build}} }, $key;`
		467
		468	`$depends{$key}{entry}{'edeps'}{$depends{$key}{depends}{$build}} = 1;`
227	dpurdie	469	`delete ($depends{$key}{depends}{$build}) ;`
		470	`Verbose2( "Not in set: $build");`
		471	`}`
		472	`else`
		473	`{`
359	dpurdie	474	`$depends{$key}{entry}{'ideps'}{$build} = $depends{$build}{entry}{dname};`
227	dpurdie	475	`}`
		476	`}`
		477	`}`
359	dpurdie	478
		479	`#DebugDumpData ("depends", \%depends );`
		480	`#DebugDumpData ("External Depends", \%extern_deps );`
		481
361	dpurdie	482
359	dpurdie	483	`#`
		484	`# Determine package build order`
		485	`# Scan the list of packages in the build set and determine`
		486	`# those with no dependencies. These can be built.`
		487	`# Remove those packages as dependents from all packages`
		488	`# Repeat.`
		489	`#`
227	dpurdie	490	`while ( $more )`
		491	`{`
		492	`$more = 0;`
		493	`$level++;`
		494	`my @build;`
		495
		496	`#`
		497	`# Locate packages with no dependencies`
		498	`#`
		499	`foreach my $key ( keys %depends )`
		500	`{`
		501	`next if ( keys( %{$depends{$key}{depends}} ) );`
		502	`push @build, $key;`
		503	`}`
		504
		505	`foreach my $build ( @build )`
		506	`{`
		507	`$more = 1;`
		508	`my $fe = $depends{$build}{entry};`
		509	`$fe->{level} = $level;`
		510	`$packages{$build} = $fe;`
		511	`push @build_order, $fe;`
		512	`delete $depends{$build};`
		513	`delete $fe->{depends}; # remove now its not needed`
		514	`}`
		515
		516	`foreach my $key ( keys %depends )`
		517	`{`
		518	`foreach my $build ( @build )`
		519	`{`
		520	`delete $depends{$key}{depends}{$build};`
		521	`}`
		522	`}`
		523	`}`
		524
		525	`#`
		526	`# Just to be sure to be sure`
		527	`#`
245	dpurdie	528	`if ( keys %depends )`
		529	`{`
		530	`#DebugDumpData ("depends", \%depends );`
		531	`Error( "Internal algorithm error: Bad dependancy walk",`
		532	`"Possible circular dependency");`
		533	`}`
227	dpurdie	534
359	dpurdie	535	`# DebugDumpData ("Order", \@build_order);`
		536	`# DebugDumpData("External Depends", \%extern_deps );`
227	dpurdie	537	`}`
		538
		539	`#-------------------------------------------------------------------------------`
		540	`# Function : cmd`
		541	`#`
		542	`# Description : Execute a command in all the sandboxes`
		543	`# Locate the base of the sandbox`
		544	`# Locate all packages in the sandbox`
		545	`# Locate all build files in each sandbox`
		546	`# Determine build order`
		547	`# Issue commands for each sandbox in order`
		548	`#`
255	dpurdie	549	`# Inputs : Arguments passed to jats build`
227	dpurdie	550	`#`
		551	`# Returns : Will exit`
		552	`#`
		553	`sub cmd`
		554	`{`
359	dpurdie	555	`my ($hcmd, @cmds ) = @_;`
		556
		557	`Getopt::Long::Configure('pass_through');`
		558	`GetOptions (`
		559	`"help:+" => \$opt_help,`
		560	`"manual:3" => \$opt_help,`
		561	`) \|\| Error ("Invalid command line" );`
		562
		563	`SubCommandHelp( $opt_help, $hcmd) if ($opt_help );`
		564
227	dpurdie	565	`#`
		566	`# Determine Sandbox information`
		567	`# Populate global variables`
		568	`#`
		569	`calc_sandbox_info();`
		570	`foreach my $fe ( @build_order )`
		571	`{`
		572	`my $dir = $fe->{dir};`
359	dpurdie	573	`Message( "Level:" . $fe->{level} . " Name: " . $fe->{dname} ,`
227	dpurdie	574	`DisplayPath (" Path: $fe->{dir}" ));`
		575
263	dpurdie	576	`my $result = JatsCmd( "-cd=$dir", @cmds);`
255	dpurdie	577	`Error ("Cmd failure") if ( $result );`
227	dpurdie	578	`}`
		579
		580	`exit 0;`
		581	`}`
		582
		583	`#-------------------------------------------------------------------------------`
331	dpurdie	584	`# Function : buildcmd`
		585	`#`
		586	`# Description : Build the entire sandbox`
		587	`# The all and the build are similar.`
		588	`# Its not really useful to do a build without a make`
		589	`# so we don't try`
		590	`#`
		591	`# Inputs : Arguments passed to jats make`
		592	`#`
		593	`#`
		594	`# Returns : Will exit`
		595	`#`
		596
		597	`sub buildcmd`
		598	`{`
337	dpurdie	599	`my ($cmd, @cmd_opts) = @_;`
331	dpurdie	600	`my @build_opts;`
337	dpurdie	601	`my @make_opts;`
331	dpurdie	602
		603	`#`
359	dpurdie	604	`# Extract and options`
		605	`#`
		606	`Getopt::Long::Configure('pass_through');`
		607	`GetOptions (`
		608	`"help:+" => \$opt_help,`
		609	`"manual:3" => \$opt_help,`
		610	`) \|\| Error ("Invalid command line" );`
		611
		612	`SubCommandHelp( $opt_help, "Command $cmd") if ($opt_help );`
361	dpurdie	613
359	dpurdie	614	`#`
331	dpurdie	615	`# Insert default options`
		616	`#`
		617	`push @build_opts, '-noforce' if ( $cmd eq 'all' );`
		618	`push @build_opts, '-force' if ( $cmd ne 'all' );`
		619
337	dpurdie	620	`#`
		621	`# Attempt to split the options into build and make options`
		622	`# Only handle the often used options to build.`
		623	`#`
		624	`foreach ( @cmd_opts )`
		625	`{`
		626	`if ( m/^-cache/ \|\| m/^-package/ \|\| m/^-forcebuildpkg/ \|\| m/-expert/) {`
		627	`push @build_opts, $_;`
		628	`} else {`
		629	`push @make_opts, $_;`
		630	`}`
		631	`}`
		632
331	dpurdie	633	`push @make_opts, 'all' unless ( @make_opts );`
		634
		635	`#`
		636	`# Determine Sandbox information`
		637	`# Populate global variables`
		638	`#`
		639	`calc_sandbox_info();`
		640	`foreach my $fe ( @build_order )`
		641	`{`
		642	`my $dir = $fe->{dir};`
359	dpurdie	643	`Message( "Level:" . $fe->{level} . " Name: " . $fe->{dname} ,`
331	dpurdie	644	`DisplayPath (" Path: $fe->{dir}" ));`
		645
		646	`JatsCmd( "-cd=$dir", 'build', @build_opts) && Error ("Build Cmd failure") if ( $result );`
		647	`JatsCmd( "-cd=$dir", 'make', @make_opts) && Error ("Make Cmd failure") if ( $result );`
		648	`}`
		649
		650	`exit 0;`
		651	`}`
		652
		653
		654	`#-------------------------------------------------------------------------------`
273	dpurdie	655	`# Function : clean`
		656	`#`
		657	`# Description : Execute a command in all the sandboxes`
		658	`# Locate the base of the sandbox`
		659	`# Locate all packages in the sandbox`
		660	`# Locate all build files in each sandbox`
		661	`# Determine build order`
		662	`# Issue commands for each sandbox in order`
		663	`#`
		664	`# Inputs : Arguments passed to jats build`
		665	`#`
		666	`# Returns : Will exit`
		667	`#`
		668	`sub clean`
		669	`{`
		670	`my ($mode, @cmds ) = @_;`
359	dpurdie	671
273	dpurdie	672	`#`
359	dpurdie	673	`# Extract and options`
		674	`#`
		675	`Getopt::Long::Configure('pass_through');`
		676	`GetOptions (`
		677	`"help:+" => \$opt_help,`
		678	`"manual:3" => \$opt_help,`
		679	`) \|\| Error ("Invalid command line" );`
		680
		681	`SubCommandHelp( $opt_help, "Clean") if ($opt_help );`
		682
		683	`#`
273	dpurdie	684	`# Determine Sandbox information`
		685	`# Populate global variables`
		686	`#`
		687	`calc_sandbox_info();`
		688
		689	`my @cmd = $mode eq 'clobber' ? ('clobber') : ('make', 'clean' );`
		690
		691	`#`
		692	`# Clobber and clean need to be done in the reverse order`
		693	`#`
		694	`foreach my $fe ( reverse @build_order )`
		695	`{`
		696	`my $dir = $fe->{dir};`
359	dpurdie	697	`Message( "Level:" . $fe->{level} . " Name: " . $fe->{dname} ,`
273	dpurdie	698	`DisplayPath (" Path: $fe->{dir}" ));`
		699
		700	`my $result = JatsCmd( "-cd=$dir", @cmd, @cmds);`
		701	`Error ("Cmd failure") if ( $result );`
		702	`}`
		703
		704	`exit 0;`
		705	`}`
		706
		707
		708	`#-------------------------------------------------------------------------------`
337	dpurdie	709	`# Function : cache`
		710	`#`
		711	`# Description : Cache external packages into the sandbox`
		712	`#`
		713	`# Inputs : @opts - User options`
		714	`#`
		715	`# Returns : Nothing`
		716	`#`
		717	`sub cache`
		718	`{`
		719	`my (@opts) = @_;`
		720
359	dpurdie	721	`GetOptions (`
		722	`"help:+" => \$opt_help,`
		723	`"manual:3" => \$opt_help,`
		724	`) \|\| Error ("Invalid command line" );`
		725
		726	`SubCommandHelp( $opt_help, "Cache") if ($opt_help \|\| $#ARGV >= 0 );`
		727
337	dpurdie	728	`#`
		729	`# Determine Sandbox information`
		730	`# Populate global variables`
		731	`#`
		732	`Message("Cache External Dependencies");`
		733	`calc_sandbox_info();`
		734
		735	`#`
		736	`# Walk the list of external depenedencies and cache each one`
		737	`#`
		738	`foreach my $de ( sort keys %extern_deps )`
		739	`{`
		740	`my @vlist = keys %{$extern_deps{$de}};`
359	dpurdie	741	`foreach my $pve ( @vlist )`
337	dpurdie	742	`{`
359	dpurdie	743	`my ($pn,$pv) = split( $; , $pve );`
		744	`Message ("Cache ${pn} ${pv}");`
		745	`JatsTool ('cache_dpkg', "${pn}/${pv}" );`
337	dpurdie	746	`}`
		747	`}`
361	dpurdie	748
337	dpurdie	749	`exit 0;`
361	dpurdie	750
337	dpurdie	751	`}`
		752
359	dpurdie	753	`#-------------------------------------------------------------------------------`
		754	`# Function : populate`
		755	`#`
		756	`# Description : Populate the sandbox with package versions`
		757	`#`
		758	`#`
		759	`# Inputs : commands - Array of command line arguments`
		760	`# Mode-0:`
		761	`#`
		762	`# pkg_name pkg_version - Import files for named package`
		763	`# options:`
		764	`# -recurse - Import dependent packages too`
		765	`# -missing - Import dependencies not in dpkg_archive`
		766	`# -test - Show what would be done`
		767	`# -extractfiles - Extract file, no view`
		768	`#`
		769	`#`
		770	`#`
		771	`#`
		772	`# Returns : Does not return`
		773	`#`
		774	`use JatsRmApi;`
		775	`use DBI;`
337	dpurdie	776
359	dpurdie	777	`#`
		778	`# Data Base Interface`
		779	`#`
		780	`my $RM_DB;`
		781	`my $PopLevel = 0;`
		782	`my %PopPackage;`
		783	`my @StrayPackages;`
		784	`my @PopBase;`
		785
		786	`sub populate`
		787	`{`
		788	`my $opt_missing = 0;`
		789	`my $opt_recurse = 0;`
		790	`my $opt_test = 0;`
		791	`my $opt_extractfiles;`
		792	`my @opt_extract = qw(-extract);`
		793	`my @opt_fnames;`
		794
		795	`Getopt::Long::Configure('pass_through');`
		796	`GetOptions (`
		797	`"help:+" => \$opt_help,`
		798	`"manual:3" => \$opt_help,`
		799	`"missing" => \$opt_missing,`
		800	`"test" => \$opt_test,`
		801	`"recurse:100" => \$opt_recurse,`
		802	`) \|\| Error ("Invalid command line" );`
		803
		804	`SubCommandHelp( $opt_help, "Populate Sandbox") if ($opt_help );`
		805
		806	`#`
		807	`# Extract options for the jats extract utility`
		808	`#`
		809	`foreach ( @ARGV )`
		810	`{`
		811	`if ( m~^-~ ) {`
		812	`push ( @opt_extract, $_);`
		813	`} else {`
		814	`push ( @opt_fnames, $_);`
		815	`}`
		816	`}`
		817
		818	`#`
		819	`# Allow exactly zero or two 'bare' arguments`
		820	`# Create an array of package-versions to be processed.`
		821	`#`
		822	`if ( $#opt_fnames >= 0 )`
		823	`{`
		824	`Error ("Populate: Must speicfy both a package name and version")`
		825	`if ( $#opt_fnames != 1 );`
		826	`push @PopBase, join( $;, @opt_fnames );`
		827	`}`
		828	`elsif ( $opt_missing )`
		829	`{`
		830	`#`
		831	`# User has not provided a package name to extract`
		832	`# Assume that the user will want missing dependencies`
		833	`#`
		834	`# Determine packages that are not present`
		835	`#`
		836	`calc_sandbox_info();`
		837
		838	`#`
		839	`# Scan for missing dependencies`
		840	`#`
		841	`foreach my $de ( sort keys %extern_deps )`
		842	`{`
		843	`my @vlist = keys %{$extern_deps{$de}};`
		844	`foreach my $pve ( @vlist )`
		845	`{`
		846	`my ($pn,$pv) = split( $; , $pve );`
		847	`unless (check_package_existance( $pn, $pv ))`
		848	`{`
		849	`push @PopBase, join( $;, $pn , $pv );`
		850	`}`
		851	`}`
		852	`}`
		853	`}`
		854	`else`
		855	`{`
		856	`Error ("No command or option specified. See help for command usage");`
		857	`}`
		858
		859	`#`
		860	`# Process the list of package-versions`
		861	`# These are top level packages. Get details from Release Manager`
		862	`#`
		863	`#DebugDumpData("Data", \@PopBase );`
		864	`$PopLevel = 0;`
		865	`foreach my $entry ( @PopBase )`
		866	`{`
		867	`my ($pname, $pver ) = split( $; , $entry);`
		868
		869	`my $pv_id = getPkgDetailsByName($pname, $pver);`
		870	`Error ("populate: $pname, $pver not found in Release Manager" )`
		871	`unless ( $pv_id );`
		872	`getPkgDetailsByPV_ID($pv_id);`
		873	`}`
		874	`#`
		875	`# If recursing then process packages that have yet to`
		876	`# be processed. At the start there will be the initial user specified`
		877	`# packages on the list. Place a marker at the end so that we can`
		878	`# determine how far we are recursing down the dependency tree.`
		879	`#`
		880	`if ( $opt_recurse )`
		881	`{`
		882	`my $marker = join($; , '_NEXT_LEVEL_', 0, 0 );`
		883	`push @StrayPackages, $marker;`
		884	`$PopLevel++;`
		885
		886	`while ( $#StrayPackages >= 0 )`
		887	`{`
		888	`my ($name, $ver, $pv_id) = split($;, shift @StrayPackages);`
		889
		890	`#`
		891	`# Marker.`
		892	`# Increment the level of recursion`
		893	`# Detect end conditions`
		894	`#`
		895	`if ( $name eq '_NEXT_LEVEL_' )`
		896	`{`
		897	`last unless ($#StrayPackages >= 0 );`
		898	`$PopLevel++;`
		899	`last if ( $PopLevel > $opt_recurse );`
		900	`push @StrayPackages, $marker;`
		901	`next;`
		902	`}`
		903
		904	`next if ( exists $PopPackage{$name}{$ver}{done} );`
		905	`getPkgDetailsByPV_ID ( $pv_id );`
		906	`#print "Stray: $pv_id, $name, $ver\n";`
		907	`}`
		908	`}`
		909	`#DebugDumpData("Data", \%PopPackage );`
		910
		911	`#`
		912	`# Determine packages that need to be extracted`
		913	`# Not ordered in any way. Could order by level if we wanted`
		914	`#`
		915	`foreach my $pname ( sort keys %PopPackage )`
		916	`{`
		917	`foreach my $pver ( sort keys %{$PopPackage{$pname}} )`
		918	`{`
		919	`#`
		920	`# Create a nice view name for the extraction`
		921	`# Will also be used to test for package existance`
		922	`#`
		923	`my $vname = "$pname $pver";`
		924	`$vname =~ s~ ~_~g;`
		925	`$vname =~ s~__~~g;`
		926
		927	`if ( -d "$GBE_SANDBOX/$vname" )`
		928	`{`
		929	`Warning("Package already in sandbox: $pname, $pver");`
		930	`next;`
		931	`}`
		932
		933	`#`
		934	`# If scanning for missing packages, then examine archives`
		935	`# for the packages existence. Don't do this on level-0 packages`
		936	`# These have been user specified.`
		937	`#`
		938	`if ( $opt_missing && $PopPackage{$pname}{$pver}{level} )`
		939	`{`
		940	`my $found = check_package_existance( $pname, $pver );`
		941	`if ( $found )`
		942	`{`
		943	`Verbose ("Package found in archive - skipped: $pname, $pver");`
		944	`next;`
		945	`}`
		946	`}`
		947
		948	`#`
		949	`# Generate commands to extract the package`
		950	`#`
		951	`my $vcstag = $PopPackage{$pname}{$pver}{vcstag};`
		952	`my @cmd = qw(jats_vcsrelease);`
		953	`push @cmd, "-view=$vname", "-label=$vcstag", @opt_extract;`
		954	`if ( $opt_test )`
		955	`{`
		956	`Message "jats " . QuoteCommand (@cmd );`
		957	`}`
		958	`else`
		959	`{`
		960	`Message "Extracting: $pname $pver";`
		961	`my $rv = JatsCmd (@cmd);`
		962	`Error ("Package version not extracted")`
		963	`if ( $rv );`
		964	`}`
		965	`}`
		966	`}`
		967
		968	`#`
		969	`# This command does not return`
		970	`#`
		971	`exit (0);`
		972	`}`
		973
337	dpurdie	974	`#-------------------------------------------------------------------------------`
359	dpurdie	975	`# Function : getPkgDetailsByName`
		976	`#`
		977	`# Description : Determine the PVID for a given package name and version`
		978	`#`
		979	`# Inputs : $pname - Package name`
		980	`# $pver - Package Version`
		981	`#`
361	dpurdie	982	`# Returns :`
359	dpurdie	983	`#`
		984
		985	`sub getPkgDetailsByName`
		986	`{`
		987	`my ($pname, $pver) = @_;`
		988	`my $pv_id;`
		989	`my (@row);`
		990
		991	`connectRM(\$RM_DB) unless ($RM_DB);`
		992
		993	`# First get details for a given package version`
		994
		995	`my $m_sqlstr = "SELECT pv.PV_ID, pkg.PKG_NAME, pv.PKG_VERSION" .`
		996	`" FROM RELEASE_MANAGER.PACKAGE_VERSIONS pv, RELEASE_MANAGER.PACKAGES pkg" .`
		997	`" WHERE pkg.PKG_NAME = \'$pname\' AND pv.PKG_VERSION = \'$pver\' AND pv.PKG_ID = pkg.PKG_ID";`
		998	`my $sth = $RM_DB->prepare($m_sqlstr);`
		999	`if ( defined($sth) )`
		1000	`{`
		1001	`if ( $sth->execute( ) )`
		1002	`{`
		1003	`if ( $sth->rows )`
		1004	`{`
		1005	`while ( @row = $sth->fetchrow_array )`
		1006	`{`
		1007	`$pv_id = $row[0];`
		1008	`my $name = $row[1];`
		1009	`my $ver = $row[2];`
		1010	`Verbose( "getPkgDetailsByName :PV_ID= $pv_id");`
		1011	`}`
		1012	`}`
		1013	`$sth->finish();`
		1014	`}`
		1015	`}`
		1016	`else`
		1017	`{`
		1018	`Error("Prepare failure" );`
		1019	`}`
		1020	`return $pv_id;`
		1021	`}`
		1022
		1023	`#-------------------------------------------------------------------------------`
		1024	`# Function : getPkgDetailsByPV_ID`
		1025	`#`
		1026	`# Description : Populate the Packages structure given a PV_ID`
		1027	`# Called for each package in the SBOM`
		1028	`#`
		1029	`# Inputs : PV_ID - Package Unique Identifier`
		1030	`#`
		1031	`# Returns : Populates Package`
		1032	`#`
		1033	`sub getPkgDetailsByPV_ID`
		1034	`{`
		1035	`my ($PV_ID) = @_;`
		1036	`my $foundDetails = 0;`
		1037	`my (@row);`
		1038
		1039	`connectRM(\$RM_DB) unless ($RM_DB);`
		1040
		1041	`# First get details from pv_id`
		1042
		1043	`my $m_sqlstr = "SELECT pv.PV_ID, pkg.PKG_NAME, pv.PKG_VERSION, release_manager.PK_RMAPI.return_vcs_tag($PV_ID)" .`
		1044	`" FROM RELEASE_MANAGER.PACKAGE_VERSIONS pv, RELEASE_MANAGER.PACKAGES pkg " .`
		1045	`" WHERE pv.PV_ID = \'$PV_ID\' AND pv.PKG_ID = pkg.PKG_ID";`
		1046
		1047	`my $sth = $RM_DB->prepare($m_sqlstr);`
		1048	`if ( defined($sth) )`
		1049	`{`
		1050	`if ( $sth->execute( ) )`
		1051	`{`
		1052	`if ( $sth->rows )`
		1053	`{`
		1054	`while ( @row = $sth->fetchrow_array )`
		1055	`{`
		1056	`my $pv_id = $row[0];`
		1057	`my $name = $row[1];`
		1058	`my $ver = $row[2];`
		1059	`my $vcstag = $row[3] \|\| '';`
		1060
		1061	`$vcstag =~ tr~\\/~/~;`
		1062	`Verbose ("getPkgDetailsByPV_ID: $PV_ID, $name, $ver, $vcstag");`
		1063
		1064	`$PopPackage{$name}{$ver}{pvid} = $PV_ID;`
		1065	`$PopPackage{$name}{$ver}{done} = 1;`
		1066	`$PopPackage{$name}{$ver}{vcstag} = $vcstag;`
		1067	`$PopPackage{$name}{$ver}{level} = $PopLevel;`
		1068	`getDependsByPV_ID( $pv_id, $name, $ver );`
		1069	`}`
		1070	`}`
		1071	`else`
		1072	`{`
		1073	`Warning ("No Package details for: PVID: $PV_ID");`
		1074	`}`
		1075	`$sth->finish();`
		1076	`}`
		1077	`else`
		1078	`{`
		1079	`Error("getPkgDetailsByPV_ID: Execute failure", $m_sqlstr );`
		1080	`}`
		1081	`}`
		1082	`else`
		1083	`{`
		1084	`Error("Prepare failure" );`
		1085	`}`
		1086	`}`
		1087
		1088	`#-------------------------------------------------------------------------------`
		1089	`# Function : getDependsByPV_ID`
		1090	`#`
		1091	`# Description : Extract the dependancies for a given package version`
		1092	`#`
		1093	`# Inputs : $pvid`
		1094	`#`
		1095	`# Returns :`
		1096	`#`
		1097	`sub getDependsByPV_ID`
		1098	`{`
		1099	`my ($pv_id, $pname, $pver) = @_;`
		1100
		1101	`connectRM(\$RM_DB) unless ($RM_DB);`
		1102
		1103	`#`
		1104	`# Now extract the package dependacies`
		1105	`#`
		1106	`my $m_sqlstr = "SELECT pkg.PKG_NAME, pv.PKG_VERSION, pd.DPV_ID" .`
		1107	`" FROM RELEASE_MANAGER.PACKAGE_DEPENDENCIES pd, RELEASE_MANAGER.PACKAGE_VERSIONS pv, RELEASE_MANAGER.PACKAGES pkg" .`
		1108	`" WHERE pd.PV_ID = \'$pv_id\' AND pd.DPV_ID = pv.PV_ID AND pv.PKG_ID = pkg.PKG_ID";`
		1109	`my $sth = $RM_DB->prepare($m_sqlstr);`
		1110	`if ( defined($sth) )`
		1111	`{`
		1112	`if ( $sth->execute( ) )`
		1113	`{`
		1114	`if ( $sth->rows )`
		1115	`{`
		1116	`while ( my @row = $sth->fetchrow_array )`
		1117	`{`
		1118	`my $name = $row[0];`
		1119	`my $ver = $row[1];`
		1120
		1121	`Verbose2( " Depends: $name, $ver");`
		1122	`unless ( exists $PopPackage{$name} && exists $PopPackage{$name}{$ver} && exists $PopPackage{$name}{$ver}{done} )`
		1123	`{`
		1124	`push @StrayPackages, join($;, $name, $ver, $row[2] );`
		1125	`}`
		1126	`}`
		1127	`}`
		1128	`$sth->finish();`
		1129	`}`
		1130	`}`
		1131	`else`
		1132	`{`
		1133	`Error("GetDepends:Prepare failure" );`
		1134	`}`
		1135	`}`
		1136
		1137	`#-------------------------------------------------------------------------------`
		1138	`# Function : SubCommandHelp`
		1139	`#`
		1140	`# Description : Provide help on a subcommand`
		1141	`#`
		1142	`# Inputs : $help_level - Help Level 1,2,3`
		1143	`# $topic - Topic Name`
		1144	`#`
		1145	`# Returns : This function does not return`
		1146	`#`
		1147	`sub SubCommandHelp`
		1148	`{`
		1149	`my ($help_level, $topic) = @_;`
		1150	`my @sections;`
		1151	`#`
		1152	`# Spell out the section we want to display`
		1153	`#`
		1154	`# Note:`
		1155	`# Due to bug in pod2usage can't use 'head1' by itself`
		1156	`# Each one needs a subsection.`
		1157	`#`
		1158	`push @sections, qw( NAME SYNOPSIS ) ;`
		1159	`push @sections, qw( ARGUMENTS OPTIONS ) if ( $help_level > 1 );`
		1160	`push @sections, qw( DESCRIPTION EXAMPLES ) if ( $help_level > 2 );`
		1161
		1162	`#`
		1163	`# Extract section from the POD`
		1164	`#`
		1165	`pod2usage({-verbose => 99,`
		1166	`-noperldoc => 1,`
		1167	`-sections => $topic . '/' . join('\|', @sections) } );`
		1168	`}`
		1169
		1170	`#-------------------------------------------------------------------------------`
227	dpurdie	1171	`# Documentation`
359	dpurdie	1172	`# NOTE`
227	dpurdie	1173	`#`
359	dpurdie	1174	`# Each subcommand MUST have`
		1175	`# head1 section as used by the subcommand`
		1176	`# This should be empty, as the contents will NOT be displayed`
		1177	`# head2 sections called`
		1178	`# NAME SYNOPSIS ARGUMENTS OPTIONS DESCRIPTION EXAMPLES`
		1179	`#`
		1180	`#=head1 xxxxxx`
		1181	`#=head2 NAME`
		1182	`#=head2 SYNOPSIS`
		1183	`#=head2 ARGUMENTS`
		1184	`#=head2 OPTIONS`
		1185	`#=head2 DESCRIPTION`
		1186	`#=head2 EXAMPLES`
		1187	`#`
227	dpurdie	1188
		1189	`=pod`
		1190
		1191	`=head1 NAME`
		1192
		1193	`jats_sandbox - Build in a Development Sandbox`
		1194
		1195	`=head1 SYNOPSIS`
		1196
361	dpurdie	1197	`jats sandbox [options] command [command options]`
227	dpurdie	1198
		1199	`Options:`
299	dpurdie	1200	`-help[=n] - Display help with specified detail`
227	dpurdie	1201	`-help -help - Detailed help message`
		1202	`-man - Full documentation`
		1203
		1204	`Commands:`
		1205	`help - Same as -help`
		1206	`create - Create a sandbox in the current directory`
359	dpurdie	1207	`populate - Populate the sandbox with packages`
299	dpurdie	1208	`delete - Delete the sandbox`
255	dpurdie	1209	`info [[-v]-v] - Sandbox information. -v: Be more verbose`
227	dpurdie	1210	`cmd - Do commands in all sandbox components`
331	dpurdie	1211	`all - Do 'build', if required, then a make in all sandbox components`
		1212	`build - Force 'build and make' in all sandbox components`
275	dpurdie	1213	`make - Do 'make' in all sandbox components`
273	dpurdie	1214	`clean - Do 'make clean' in all sandbox components`
		1215	`clobber - Do 'build clobber' is all sandbox components`
337	dpurdie	1216	`cache - Cache external dependent packages`
227	dpurdie	1217
359	dpurdie	1218	`Use the command`
		1219	`jats sandbox 'command' -h`
		1220	`for command specific help`
361	dpurdie	1221
227	dpurdie	1222	`=head1 OPTIONS`
		1223
		1224	`=over 8`
		1225
299	dpurdie	1226	`=item B<-help[=n]>`
227	dpurdie	1227
		1228	`Print a brief help message and exits.`
299	dpurdie	1229	`There are three levels of help`
227	dpurdie	1230
299	dpurdie	1231	`=over 8`
		1232
361	dpurdie	1233	`=item 1`
299	dpurdie	1234
361	dpurdie	1235	`Brief synopsis`
299	dpurdie	1236
361	dpurdie	1237	`=item 2`
299	dpurdie	1238
361	dpurdie	1239	`Synopsis and option summary`
		1240
		1241	`=item 3`
		1242
		1243	`Detailed help in man format`
		1244
299	dpurdie	1245	`=back 8`
		1246
227	dpurdie	1247	`=item B<-help -help>`
		1248
		1249	`Print a detailed help message with an explanation for each option.`
		1250
		1251	`=item B<-man>`
		1252
299	dpurdie	1253	`Prints the manual page and exits. This is the same a -help=3`
227	dpurdie	1254
279	dpurdie	1255	`=back`
		1256
227	dpurdie	1257	`=head1 DESCRIPTION`
		1258
299	dpurdie	1259	`This program is the primary tool for the maintenance of Development Sandboxes.`
		1260
227	dpurdie	1261	`More documentation will follow.`
		1262
279	dpurdie	1263	`=head2 SANDBOX DIRECTORY`
		1264
299	dpurdie	1265	`The sandbox directory is marked as being a sandbox through the use of the`
		1266	`'sandbox create' command. This will create a suitable structure within the`
279	dpurdie	1267	`current directory.`
		1268
		1269	`Several JATS commands operate differently within a sandbox. The 'extract' and`
		1270	`'release' commands will create static viwes within the sandbox and not the`
		1271	`normal directory. The 'sandbox' sub commands can only be used within a sandbox.`
		1272
		1273	`The sandbox directory contains sub directories, each should contain a single`
359	dpurdie	1274	`package. Sub directories may be created with the 'jats extract' command or with the`
		1275	`'jats sandbox populate' command.`
279	dpurdie	1276
		1277	`Note: Symbolic links are not supported. They cannot work as he sandbox mechanism`
		1278	`requires that all the packages be conatined within a sub directory tree so`
		1279	`that the root of the sandbox can be located by a simple scan of the directory`
		1280	`tree.`
		1281
325	dpurdie	1282	`If a package subdirectory contains a file called 'stop' or 'stop.`
		1283	`<GBE_MACHTYPE>', then that package will not be considered as a part of the`
		1284	`build-set. A 'stop' file will prevent consideration all build platforms. The 'stop.`
		1285	`<GBE_MACHTYPE>' will only prevent consideration if being built on a GBE_MACHTYPE`
		1286	`type of computer.`
279	dpurdie	1287
359	dpurdie	1288	`=head1 Create Sandbox`
299	dpurdie	1289
359	dpurdie	1290	`=head2 NAME`
299	dpurdie	1291
359	dpurdie	1292	`Create Sandbox`
		1293
		1294	`=head2 SYNOPSIS`
		1295
		1296	`jats sandbox [options] create [command options]`
		1297
		1298	`Options:`
		1299	`-help[=n] - Help message, [n=1,2,3]`
		1300	`-man - Full documentation [-help=3]`
		1301	`-verbose[=n] - Verbose command operation`
		1302
		1303	`Command Options`
		1304	`-help[=n] - Command specific help, [n=1,2,3]`
		1305	`-verbose[=n] - Verbose operation`
		1306	`-exact - Create sandbox to reproduce exact versions`
		1307
		1308	`=head2 OPTIONS`
		1309
		1310	`The 'create' command takes the following options:`
		1311
		1312	`=over 8`
		1313
		1314	`=item -exact`
		1315
		1316	`When this option is specified the sandbox is marked for exact processing of`
		1317	`package versions. In this mode the version numbers of the packages in the`
		1318	`sandbox are significant. This is ideal for recreating a package-version.`
		1319
		1320	`The default is for in-exact processing, in which the version numbers of packages`
		1321	`within the sandbox are not significant. The is ideal for development.`
		1322
		1323	`=back`
		1324
		1325	`=head2 DESCRIPTION`
		1326
299	dpurdie	1327	`The 'create' command will create a sandbox in the users current directory. It is`
		1328	`not possible to create a sandbox within a sandbox.`
		1329
		1330	`A sandbox can be created in a directory that contains files and subdirectories.`
		1331
		1332	`The create command simply places a known directory in the current directory.`
359	dpurdie	1333	`This directory is used by the sandboxing process. It may be manually deleted, or`
299	dpurdie	1334	`deleted with the 'delete' command.`
		1335
359	dpurdie	1336	`=head1 Populate Sandbox`
		1337
		1338	`=head2 NAME`
		1339
		1340	`Populate a Sandbox`
		1341
		1342	`=head2 SYNOPSIS`
		1343
		1344	`jats sandbox [options] populate [command options] [packageName packageVersion]`
		1345
		1346	`Options:`
		1347	`-help[=n] - Help message, [n=1,2,3]`
		1348	`-man - Full documentation [-help=3]`
		1349	`-verbose[=n] - Verbose command operation`
		1350
		1351	`Command Options`
		1352	`-help[=n] - Command specific help, [n=1,2,3]`
		1353	`-recurse[=n] - Locate dependencies within packages`
		1354	`-missing - Locate missing packages`
		1355	`-test - Do not extract packages`
		1356	`-<Other> - Pass options to jats extract`
		1357
		1358	`=head2 ARGUMENTS`
		1359
		1360	`The 'populate' command can take a package name and version as arguments. It will`
		1361	`then populate the sandbox with this package. See 'DESCRIPTION' for details.`
		1362
		1363	`=head2 OPTIONS`
		1364
		1365	`The 'populate' command takes the following options:`
		1366
		1367	`=over 4`
		1368
		1369	`=item -recurse[=N]`
		1370
		1371	`This option will modify the operation of the command such that dependencies`
		1372	`of named packages can also be extracted into the sandbox.`
		1373
		1374	`The default operation is to only extract named packages. If the option is`
		1375	`specified then all dependent packages are processed. An optional numeric argument`
		1376	`can be specified to limit the depth of the recursion.`
		1377
		1378	`=item -missing`
		1379
		1380	`This option will modify the operation of the dependency recursion scanning such`
		1381	`that dependent packages that exist in a package archive will not be extracted.`
		1382
		1383	`Use of this option allows a sandbox to be populated with packages that are`
		1384	`required by packages in the sandbox, but are not available in a package archive.`
		1385
		1386	`=item -test`
		1387
		1388	`This option will prevent the command from performing the extraction. It will`
		1389	`simply display the JATS commands that can be used to perform the extraction.`
		1390
		1391	`=item -<Other>`
		1392
		1393	`Options not understood by the 'populate' sub command will be passed through`
		1394	`the package extraction program. Useful options include:`
		1395
363	dpurdie	1396	`=over 4`
359	dpurdie	1397
361	dpurdie	1398	`=item *`
359	dpurdie	1399
361	dpurdie	1400	`-extractfiles`
359	dpurdie	1401
361	dpurdie	1402	`=item *`
		1403
		1404	`-branch=<branch name>`
		1405
359	dpurdie	1406	`=back`
		1407
		1408	`=back`
		1409
		1410	`=head2 DESCRIPTION`
		1411
		1412	`The 'populate' command can be used to assist in populating the sandbox. It has`
		1413	`two modes of operation.`
		1414
363	dpurdie	1415	`=over 4`
359	dpurdie	1416
361	dpurdie	1417	`=item 1`
359	dpurdie	1418
361	dpurdie	1419	`Named Package`
		1420
363	dpurdie	1421	`If the user specifies both a package name and a package version then the command`
359	dpurdie	1422	`will populate the sandbox with that package and optionally its dependencies.`
		1423
361	dpurdie	1424	`=item 2`
359	dpurdie	1425
361	dpurdie	1426	`Determine missing dependencies`
		1427
359	dpurdie	1428	`If the user does not specify a package name and version, but does specify`
		1429	`the '-missing' option, then the command will examine the current sandbox and`
		1430	`determine missing dependent packages. It will then populate the sandbox with`
		1431	`these packages and optionally there dependencies.`
		1432
		1433	`=back`
		1434
		1435	`=head2 EXAMPLES`
		1436
		1437	`=over 4`
		1438
361	dpurdie	1439	`=item *`
359	dpurdie	1440
361	dpurdie	1441	`jats sandbox populate package1 version1`
		1442
359	dpurdie	1443	`This command will populate the sandbox with version1 of package1, if it does not`
		1444	`already exist in the sandbox.`
		1445
361	dpurdie	1446	`=item *`
359	dpurdie	1447
361	dpurdie	1448	`jats sandbox populate package1 version1 -recurse -missing`
		1449
359	dpurdie	1450	`This command will populate the sandbox with version1 of package1, if it does not`
		1451	`already exist in the sandbox, together will all the packages dependencies that`
		1452	`are not available in a package archive.`
		1453
361	dpurdie	1454	`=item *`
359	dpurdie	1455
361	dpurdie	1456	`jats sandbox populate -recurse -missing`
		1457
359	dpurdie	1458	`This command will examine the current sandbox and populate the sandbox with`
		1459	`packages that are required to build the packages in the sandbox and the`
		1460	`dependencies of these packages, provide the dependent package is not in a`
		1461	`package archive.`
		1462
361	dpurdie	1463	`=item *`
359	dpurdie	1464
361	dpurdie	1465	`jats sandbox populate`
		1466
359	dpurdie	1467	`This command will examine the current sandbox and populate the sandbox with`
		1468	`packages that are required to build the packages in the sandbox. It will not`
		1469	`examine the dependents of these packages.`
		1470
		1471	`=back`
		1472
		1473	`=head1 Delete Sandbox`
		1474
		1475	`=head2 NAME`
		1476
		1477	`Deleta a sandbox`
		1478
		1479	`=head2 SYNOPSIS`
		1480
		1481	`jats sandbox [options] delete`
		1482
		1483	`Options:`
		1484	`-help[=n] - Help message, [n=1,2,3]`
		1485	`-man - Full documentation [-help=3]`
		1486	`-verbose[=n] - Verbose command operation`
		1487
		1488	`=head2 DESCRIPTION`
		1489
299	dpurdie	1490	`The 'delete' command will delete the sandbox's marker directory. The command may`
		1491	`be executed anywhere within the sandbox.`
		1492
359	dpurdie	1493	`Once the sandbox has been deleted, the user must remove the components within the`
299	dpurdie	1494	`sandbox.`
		1495
359	dpurdie	1496	`=head1 Sandbox Information`
299	dpurdie	1497
359	dpurdie	1498	`=head2 NAME`
		1499
		1500	`Display Sandbox Information`
		1501
		1502	`=head2 SYNOPSIS`
		1503
		1504	`jats sandbox [options] info [command options]`
		1505
		1506	`Options:`
		1507	`-help[=n] - Help message, [n=1,2,3]`
		1508	`-man - Full documentation [-help=3]`
		1509	`-verbose[=n] - Verbose command operation`
		1510
		1511	`Command Options`
		1512	`-help[=n] - Command specific help, [n=1,2,3]`
		1513	`-verbose[=n] - Display more information`
361	dpurdie	1514
359	dpurdie	1515	`=head2 OPTIONS`
		1516
		1517	`=over`
		1518
		1519	`=item B<-verbose[=n]>`
		1520
		1521	`This options will increase the verbosity of the information being displayed.`
		1522	`Values 1 and 2 are described in the detailed 'DESCRIPTION'. Other values are`
		1523	`reserved for diagnostic use.`
		1524
		1525	`=back`
		1526
		1527	`=head2 DESCRIPTION`
		1528
299	dpurdie	1529	`The 'info' command will display information about the build order and the`
359	dpurdie	1530	`dependencies of packages that it finds within the sandbox.`
299	dpurdie	1531
359	dpurdie	1532	`The command works within various levels of verbosity:`
299	dpurdie	1533
		1534	`=over 8`
		1535
361	dpurdie	1536	`=item *`
299	dpurdie	1537
361	dpurdie	1538	`No Verbosity`
		1539
299	dpurdie	1540	`The basic command will display the build order and the external`
335	dpurdie	1541	`dependencies. External dependencies may be prefixed with one of the`
		1542	`following indicators:`
299	dpurdie	1543
335	dpurdie	1544	`=over 8`
		1545
361	dpurdie	1546	`=item '+' Multiple versions of this package are being used by sandboxed components.`
335	dpurdie	1547
361	dpurdie	1548	`=item '*' The package cannot be found in any of the package archives.`
335	dpurdie	1549
		1550	`=back`
		1551
361	dpurdie	1552	`=item *`
299	dpurdie	1553
361	dpurdie	1554	`Verbosity of 1`
		1555
359	dpurdie	1556	`This level of verbosity will display the build order and detailed information`
299	dpurdie	1557	`on the dependencies. The dependencies will be prefixed with:`
		1558
		1559	`=over 8`
		1560
361	dpurdie	1561	`=item E Dependent Package is external to the sandbox`
299	dpurdie	1562
361	dpurdie	1563	`=item I Dependent Package is internal to the sandbox`
299	dpurdie	1564
		1565	`=back`
		1566
335	dpurdie	1567	`External dependencies may be prefixed with one of the indicators described for`
		1568	`no-verbosity. Additionally the internal consumer of the external package is also`
		1569	`shown. These are prefixed with a 'U'.`
299	dpurdie	1570
361	dpurdie	1571	`=item *`
299	dpurdie	1572
361	dpurdie	1573	`Verbosity of 2`
		1574
359	dpurdie	1575	`Reserved for future use`
299	dpurdie	1576
361	dpurdie	1577	`=item *`
299	dpurdie	1578
361	dpurdie	1579	`Verbosity over 2`
		1580
359	dpurdie	1581	`This should be considered a debug option. Undocumented internal information will`
299	dpurdie	1582	`be displayed.`
		1583
		1584	`=back`
		1585
359	dpurdie	1586	`=head1 Command all`
331	dpurdie	1587
359	dpurdie	1588	`=head2 NAME`
		1589
		1590	`Build packages in the sandbox`
		1591
		1592	`=head2 SYNOPSIS`
		1593
		1594	`jats sandbox [options] all [command options] [arguments]`
		1595
		1596	`Options:`
		1597	`-help[=n] - Help message, [n=1,2,3]`
		1598	`-man - Full documentation [-help=3]`
		1599	`-verbose[=n] - Verbose command operation`
		1600
		1601	`Command Options`
		1602	`-help[=n] - Command specific help, [n=1,2,3]`
		1603
		1604	`=head2 ARGUMENTS`
		1605
		1606	`Arguments are passed to the 'make' phase of the process.`
		1607
		1608	`=head2 OPTIONS`
		1609
		1610	`The are command specific options.`
		1611
		1612	`=head2 DESCRIPTION`
		1613
331	dpurdie	1614	`The 'all' command will perform build, if the build files are out of date,`
		1615	`followed by a make in each of the packages within the sandbox, in the correct`
		1616	`build order.`
		1617
		1618	`Any arguments are passed to the 'make' phase of the process.`
		1619
		1620	`This command may be used to:`
		1621
		1622	`=over 8`
		1623
361	dpurdie	1624	`=item *`
331	dpurdie	1625
361	dpurdie	1626	`Pickup any build file changes.`
331	dpurdie	1627
361	dpurdie	1628	`=item *`
		1629
		1630	`Resume a failed build.`
		1631
331	dpurdie	1632	`=back`
		1633
359	dpurdie	1634	`=head1 Command build`
331	dpurdie	1635
359	dpurdie	1636	`=head2 NAME`
		1637
		1638	`Build packages in the sandbox`
		1639
		1640	`=head2 SYNOPSIS`
		1641
		1642	`jats sandbox [options] build [command options] [arguments]`
		1643
		1644	`Options:`
		1645	`-help[=n] - Help message, [n=1,2,3]`
		1646	`-man - Full documentation [-help=3]`
		1647	`-verbose[=n] - Verbose command operation`
		1648
		1649	`Command Options`
		1650	`-help[=n] - Command specific help, [n=1,2,3]`
		1651
		1652	`=head2 ARGUMENTS`
		1653
		1654	`Arguments are passed to the 'make' phase of the process.`
		1655
		1656	`=head2 OPTIONS`
		1657
		1658	`The are no command specific options.`
		1659
		1660	`=head2 DESCRIPTION`
		1661
331	dpurdie	1662	`The 'build' command will force a build followed by a make in each of the packages`
		1663	`within the sandbox, in the correct build order.`
		1664
		1665	`Any arguments are passed to the 'make' phase of the process.`
		1666
		1667	`In practice, the 'sandbox all' command is quicker.`
		1668
359	dpurdie	1669	`=head1 Clean`
331	dpurdie	1670
359	dpurdie	1671	`=head2 NAME`
		1672
		1673	`Clean all sandbox components`
		1674
		1675	`=head2 SYNOPSIS`
		1676
		1677	`jats sandbox [options] clean\|clobber [command options]`
		1678
		1679	`Options:`
		1680	`-help[=n] - Help message, [n=1,2,3]`
		1681	`-man - Full documentation [-help=3]`
		1682	`-verbose[=n] - Verbose command operation`
		1683
		1684	`Command Options`
		1685	`-help[=n] - Command specific help, [n=1,2,3]`
		1686
		1687	`=head2 ARGUMENTS`
		1688
		1689	`None`
		1690
		1691	`=head2 OPTIONS`
		1692
		1693	`No command specific options`
		1694
		1695	`=head2 DESCRIPTION`
		1696
		1697	`The 'clean' command will perform a 'jats make clean' in all components in the`
		1698	`sandbox.`
		1699
		1700	`The 'clobber' command will perform a 'jats clobber' in all components in the`
		1701	`sandbox.`
		1702
		1703	`=head1 make`
		1704
		1705	`=head2 NAME`
		1706
		1707	`Make packages in the sandbox`
		1708
		1709	`=head2 SYNOPSIS`
		1710
		1711	`jats sandbox [options] make [command options] [arguments]`
		1712
		1713	`Options:`
		1714	`-help[=n] - Help message, [n=1,2,3]`
		1715	`-man - Full documentation [-help=3]`
		1716	`-verbose[=n] - Verbose command operation`
		1717
		1718	`Command Options`
		1719	`-help[=n] - Command specific help, [n=1,2,3]`
		1720
		1721	`=head2 ARGUMENTS`
		1722
		1723	`Arguments are passed to the 'make' phase of the process.`
		1724
		1725	`=head2 OPTIONS`
		1726
		1727	`The are no command specific options.`
		1728
		1729	`=head2 DESCRIPTION`
		1730
331	dpurdie	1731	`The 'make' command will perform a 'make' operation in each of the packages`
		1732	`within the sandbox, in the correct build order.`
		1733
		1734	`Any arguments are passed to the 'make'.`
		1735
359	dpurdie	1736	`=head1 cmd`
331	dpurdie	1737
359	dpurdie	1738	`=head2 NAME`
		1739
		1740	`Process each package with a specified command.`
		1741
		1742	`=head2 SYNOPSIS`
		1743
		1744	`jats sandbox [options] cmd [command options] [arguments]`
		1745
		1746	`Options:`
		1747	`-help[=n] - Help message, [n=1,2,3]`
		1748	`-man - Full documentation [-help=3]`
		1749	`-verbose[=n] - Verbose command operation`
		1750
		1751	`Command Options`
		1752	`-help[=n] - Command specific help, [n=1,2,3]`
		1753
		1754	`=head2 ARGUMENTS`
		1755
		1756	`Arguments are passed to a JATS command.`
		1757
		1758	`=head2 OPTIONS`
		1759
		1760	`The are no command specific options.`
		1761
		1762	`=head2 DESCRIPTION`
		1763
331	dpurdie	1764	`The 'cmd' command will pass all of its arguments to JATS in the build directory`
		1765	`of each of the packages within the sandbox, in the package build order.`
		1766
359	dpurdie	1767	`=head1 Cache`
331	dpurdie	1768
359	dpurdie	1769	`=head2 NAME`
331	dpurdie	1770
359	dpurdie	1771	`Cache dependent packages`
331	dpurdie	1772
359	dpurdie	1773	`jats sandbox [options] cache [command options]`
331	dpurdie	1774
359	dpurdie	1775	`Options:`
		1776	`-help[=n] - Help message, [n=1,2,3]`
		1777	`-man - Full documentation [-help=3]`
		1778	`-verbose[=n] - Verbose command operation`
337	dpurdie	1779
359	dpurdie	1780	`Command Options`
		1781	`-help[=n] - Command specific help, [n=1,2,3]`
337	dpurdie	1782
359	dpurdie	1783	`=head2 ARGUMENTS`
		1784
		1785	`The are no command specific arguments.`
		1786
		1787	`=head2 OPTIONS`
		1788
		1789	`The are no command specific options.`
		1790
		1791	`=head2 DESCRIPTION`
		1792
		1793	`The 'cache' command will cache all external dependent packages into the users`
		1794	`dpkg_archive_cache as defined through the EnvVar GBE_DPKG_CACHE. The result is`
		1795	`similar to the command 'jats sandbox build -cache', without the overhead of`
		1796	`building the sandbox components.`
		1797
		1798	`This command allows the simple creation of a small development environment that`
		1799	`is not tied to the larger Development Environment. It may then be used in a`
337	dpurdie	1800	`disconnected mode to perform development.`
		1801
227	dpurdie	1802	`=cut`
		1803

Subversion Repositories DevTools

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