WebSVN – DevTools – Blame – /core_devl/branches/gitBuilder/TOOLS/jats.pl

Rev	Author	Line No.	Line
227	dpurdie	1	`#! perl`
		2	`########################################################################`
		3	`# Copyright (C) 1998-2004 ERG Limited, All rights reserved`
		4	`#`
		5	`# Module name : jats.sh`
		6	`# Module type : Makefile system`
		7	`# Compiler(s) : n/a`
		8	`# Environment(s): jats`
		9	`#`
		10	`# Description:`
		11	`# This is a wrapper script to simplify access to the jats`
		12	`# build system`
		13	`#`
		14	`# Usage: jats build \| make \| install \| help \| ...`
		15	`#`
229	dpurdie	16	`# Package: PACKAGE_TAG`
		17	`# Version: VERSION_TAG`
227	dpurdie	18	`#......................................................................#`
		19
261	dpurdie	20	`require 5.008_002;`
227	dpurdie	21	`use strict;`
		22	`use warnings;`
		23
		24	`use Cwd;`
		25	`use File::Copy;`
		26	`use Getopt::Long qw(:config require_order); # Stop on non-option`
		27	`use Pod::Usage; # For help support`
		28	`use FindBin; # Determine the current directory`
		29	`use lib "$FindBin::Bin/LIB"; # Allow JATS libraries`
		30	`use Config;`
		31	`use Sys::Hostname; # For hostname`
		32
		33	`use JatsError; # Common error reporting`
		34	`use DescPkg; # Package Descriptor processing`
		35	`use JatsSystem; # System call interface`
245	dpurdie	36	`use JatsBuildFiles; # Parse Build Files`
227	dpurdie	37
229	dpurdie	38	`my $GBE_VERSION = "VERSION_TAG"; # Will be re-written when released`
245	dpurdie	39	`my $GBE_NOT_RELEASED = "RELEASE_TAG"; # Will be re-written when released`
227	dpurdie	40	`my $opr_done;`
		41	`my $opt_here = 0;`
		42	`my $BUILD_FILE = "build.pl";`
		43	`my @BUILD_FILE_ALT = qw(auto.pl build_test.pl);`
		44	`my $BUILD_FILE_SET;`
		45	`my $RESULT = 0;`
		46	`my $PSPLIT = ':'; # Win/Unix path splitter`
		47	`my $TIMER = time;`
		48	`my $opt_time = 0;`
		49	`my $opt_help = 0;`
		50	`my $opt_locate = 0;`
		51	`my $opt_locate_file;`
245	dpurdie	52	`my $opt_locate_package;`
227	dpurdie	53	`my $opt_dir;`
		54	`my $opt_java;`
277	dpurdie	55	`my $opt_export_vars = 1;`
227	dpurdie	56	`my $result;`
		57
		58	`#`
		59	`# Grab a copy of ALL the environment variable that will be used`
		60	`# This will simplify the script a great deal`
		61	`#`
		62
279	dpurdie	63	`our $GBE_JATS_VERSION = $ENV{'GBE_JATS_VERSION'} \|\| '';`
227	dpurdie	64	`our $GBE_JATS_SANE = $ENV{'GBE_JATS_SANE'} \|\| 0;`
279	dpurdie	65	`our $GBE_CORE = $ENV{'GBE_CORE'} \|\| '';`
		66	`our $GBE_BIN = $ENV{'GBE_BIN'} \|\| '';`
		67	`our $GBE_CONFIG = $ENV{'GBE_CONFIG'} \|\| '';`
		68	`our $GBE_DPLY = $ENV{'GBE_DPLY'} \|\| '';`
		69	`our $GBE_DPKG = $ENV{'GBE_DPKG'} \|\| '';`
		70	`our $GBE_DPKG_STORE = $ENV{'GBE_DPKG_STORE'} \|\| '';`
		71	`our $GBE_DPKG_LOCAL = $ENV{'GBE_DPKG_LOCAL'} \|\| '';`
		72	`our $GBE_DPKG_CACHE = $ENV{'GBE_DPKG_CACHE'} \|\| '';`
		73	`our $GBE_DPKG_SBOX = $ENV{'GBE_DPKG_SBOX'} \|\| '';`
		74	`our $GBE_SANDBOX = $ENV{'GBE_SANDBOX'} \|\| '';`
		75	`our $GBE_PERL = $ENV{'GBE_PERL'} \|\| '';`
		76	`our $GBE_TOOLS = $ENV{'GBE_TOOLS'} \|\| '';`
		77	`our $GBE_MACHTYPE = $ENV{'GBE_MACHTYPE'} \|\| '';`
273	dpurdie	78	`our $GBE_HOSTMACH = $ENV{'GBE_HOSTMACH'} \|\| $GBE_MACHTYPE;`
279	dpurdie	79	`our $GBE_PLATFORM = $ENV{'GBE_PLATFORM'} \|\| '';`
		80	`our $GBE_BUILDFILTER = $ENV{'GBE_BUILDFILTER'} \|\| '';`
227	dpurdie	81	`our $GBE_DEBUG = $ENV{'GBE_DEBUG'} \|\| 0;`
		82	`our $GBE_VERBOSE = $ENV{'GBE_VERBOSE'} \|\| 0;`
279	dpurdie	83	`our $GBE_DRV = $ENV{'GBE_DRV'} \|\| '';`
		84	`our $GBE_HOSTNAME = $ENV{'GBE_HOSTNAME'} \|\| hostname \|\| '';`
		85	`our $USER = $ENV{'USER'} \|\| '';`
		86	`our $PERL5LIB = $ENV{'PERL5LIB'} \|\| '';`
		87	`our $JAVA_HOME = $ENV{'JAVA_HOME'} \|\| '';`
		88	`our $GBE_ABT = $ENV{'GBE_ABT'} \|\| '';`
227	dpurdie	89	`our $GBE_UNIX = 1;`
		90	`our $CWD;`
		91
		92	`#-------------------------------------------------------------------------------`
		93	`# Clean up some environment variables`
245	dpurdie	94	`# GBE_BUILDFILTER - may be space or comma separated list`
		95	`# GBE_PLATFORM - may be space or comma separated list`
		96	`# GBE_ABT - may be space or comma separated list`
279	dpurdie	97	`# GBE_HOSTNAME - No whitespace`
227	dpurdie	98	`#`
		99	`$GBE_BUILDFILTER = join (' ', split( /[,\s]+/, $GBE_BUILDFILTER));`
		100	`$GBE_PLATFORM = join (' ', split( /[,\s]+/, $GBE_PLATFORM));`
		101	`$GBE_ABT = join (' ', split( /[,\s]+/, $GBE_ABT));`
279	dpurdie	102	`$GBE_HOSTNAME =~ s~\s+~~g;`
227	dpurdie	103
		104	`#-------------------------------------------------------------------------------`
		105	`# Parse the user options`
		106	`# GetOptions has been configured so that it will stop parsing on the first`
		107	`# non-options. This allows the command syntax to the script to have options`
		108	`# that are directed to this script before the command keyword, and command`
		109	`# options to the subcommand to be after the keyword.`
		110	`#`
		111	`$result = GetOptions (`
261	dpurdie	112	`"help\|h:+" => \$opt_help,`
		113	`"manual:3" => \$opt_help,`
		114	`"verbose\|v:+" => \$GBE_VERBOSE,`
		115	`"debug:+" => \$GBE_DEBUG,`
227	dpurdie	116	`"cd\|changedir=s" => \$opt_dir,`
		117	`"locate" => \$opt_locate,`
		118	`"locatefile=s" => \$opt_locate_file,`
245	dpurdie	119	`"locatepkg=s" => \$opt_locate_package,`
227	dpurdie	120	`"here" => \$opt_here,`
		121	`"time" => \$opt_time,`
		122	`"b\|buildfile=s" => \&opts_buildfile,`
245	dpurdie	123	`"java=s" => \$opt_java,`
227	dpurdie	124	`"version=s", => \&opts_version,`
		125	`"platform:s", => sub{ opts_extend( \$GBE_PLATFORM, @_ )},`
		126	`"buildfilter:s" => sub{ opts_extend( \$GBE_BUILDFILTER, @_ )},`
		127	`"abt:s" => sub{ opts_extend( \$GBE_ABT, @_ )},`
277	dpurdie	128	`"exportvars!" => \$opt_export_vars,`
227	dpurdie	129	`);`
		130
		131	`#`
		132	`# Configure the error reporting process now that we have the user options`
		133	`#`
		134	`ErrorConfig( 'name' => 'JATS',`
		135	`'debug' => $GBE_DEBUG,`
		136	`'verbose' => $GBE_VERBOSE );`
		137	`#`
		138	`# Post process some of the options`
		139	`#`
		140	`Error ("Options not parsed. Use -help for help") unless $result;`
263	dpurdie	141	`Verbose3 ('ARGS', @ARGV);`
227	dpurdie	142
		143	`#`
		144	`# Option Helper Routine`
		145	`# Save alternate buildfile. Flag that it has been set`
		146	`#`
		147	`sub opts_buildfile`
		148	`{`
283	dpurdie	149	`my ($junk, $bf) = @_;`
		150	`$BUILD_FILE = $bf;`
227	dpurdie	151	`$BUILD_FILE_SET = 1;`
		152	`Verbose ("Use alternate buildfile: $BUILD_FILE");`
283	dpurdie	153	`return;`
227	dpurdie	154	`}`
		155
		156	`#`
		157	`# Options Helper Routine`
		158	`# Collect a space/comma delimited list and replace/append to string`
		159	`# Allows the string to be reset`
		160	`# Use of a +" will append to existing value`
		161	`#`
		162	`# arg1 - Ref to string to store data`
		163	`# arg2 - Option name`
		164	`# arg3 - Option value`
		165	`#`
		166	`sub opts_extend`
		167	`{`
		168	`my( $ref, $name, $value) = @_;`
		169	`if ( $value )`
		170	`{`
		171	`$value =~ s/,/ /g;`
		172	`$value = ${$ref} . ' ' . $value`
		173	`if ( $value =~ s/\+/ /g );`
		174	`$value =~ s/^\s+//;`
		175	`$value =~ s/\s+/ /;`
		176	`}`
		177	`${$ref} = $value;`
283	dpurdie	178	`return;`
227	dpurdie	179	`}`
		180
		181	`#`
		182	`# Options Helper routine`
		183	`# Collect --version=version, then stop processing of the command line`
		184	`# This will simulate a '--'`
		185	`#`
		186	`sub opts_version`
		187	`{`
283	dpurdie	188	`my ($junk, $vn) = @_;`
		189	`$GBE_JATS_VERSION = $vn;`
		190	`die("!FINISH\n");`
227	dpurdie	191	`}`
		192
		193	`################################################################################`
		194	`#`
		195	`# Ensure that essential environment variables are present and that they`
		196	`# do not contain spaces.`
		197	`#`
		198	`ReportError('Set env-var GBE_PERL (typically "/usr/bin/perl")') unless ( $GBE_PERL );`
229	dpurdie	199	`ReportError('Set env-var GBE_DPKG (typically "/devl/dpkg_archive")') unless ( $GBE_DPKG );`
		200	`ReportError('Set env-var GBE_CORE (typically "/devl/dpkg_archive/PACKAGE_TAG/VERSION_TAG")') unless ( $GBE_CORE );`
279	dpurdie	201	`ReportError('Hostname cannot be determined') unless ( $GBE_HOSTNAME );`
227	dpurdie	202
229	dpurdie	203	`################################################################################`
		204	`#`
		205	`# Warn if using a version of perl that is newer than expected`
		206	`# The 'require' does a lower limit test`
		207	`#`
283	dpurdie	208	`if ( ! $GBE_JATS_SANE )`
		209	`{`
		210	`Warning ("Perl Version may not be compatible",`
		211	`"Jats has been tested with: 5.8.8",`
		212	`"This version is: $]",`
		213	`) if ( $] > 5.010000 );`
227	dpurdie	214
283	dpurdie	215	`Warning ("The PDK, as used by some deployed packages does not work with this version of perl.",`
		216	`"ERG only has a licence for PDK V5 and this only works with Perl 5.6 and 5.8",`
		217	`"This version is: $]",`
		218	`) if ( $] > 5.009000 );`
		219	`}`
229	dpurdie	220
		221	`#`
		222	`# Warn if this is not an active state release`
		223	`#`
		224	`# Would be nice, but I can't figure out how to do it - yet`
		225	`# The following does not work on all platforms`
		226	`#`
		227	`#unless ( $ActivePerl::VERSION )`
		228	`#{`
		229	`# Warning ("Perl does not appear to be an ActiveState Release", "Jats may not function as expected");`
		230	`#}`
		231	`#else`
		232	`#{`
		233	`# Verbose ("ActiveState Version: $ActivePerl::VERSION");`
		234	`#}`
		235
227	dpurdie	236	`################################################################################`
229	dpurdie	237	`#`
245	dpurdie	238	`# Warn if this version of JATS is not correctly versioned`
229	dpurdie	239	`# Users should be using correctly versioned copies of JATS. These come`
		240	`# from dpkg_archive.`
		241	`#`
231	dpurdie	242	`Warning ("* Unofficial version of JATS *")`
243	dpurdie	243	`if ( ! $GBE_JATS_SANE && $GBE_NOT_RELEASED );`
229	dpurdie	244
		245	`################################################################################`
227	dpurdie	246	`# If running with cygwin then warn if the CYGWIN environment variable`
		247	`# contains "tty". tty mode causes some strange behaviour such as:`
		248	`# 1) Non flushing of perl scripts under some conditions (eg:create_dpkg)`
		249	`#`
		250	`if ( $ENV{'CYGWIN'} && $ENV{'CYGWIN'} =~ m/tty/ )`
		251	`{`
		252	`Warning ("The CYGWIN variable contains \"tty\".",`
		253	`"This can cause strange behaviour with interactive scripts");`
		254	`}`
		255
		256	`#`
		257	`# Remove CDPATH - this breaks things when cygwin is running`
		258	`# even if we are not running under cygwin perl`
		259	`#`
		260	`delete $ENV{'CDPATH'};`
		261
		262
		263	`################################################################################`
		264	`# Sanitize GBE_CORE and others for internal Perl use`
		265	`# It may contain \ to be added to PATH but within perl is needs /`
		266	`#`
		267	`$PERL5LIB =~ tr~\\/~/~s;`
		268
		269	`TestDirectoryConfig( 'GBE_CORE' );`
		270	`TestDirectoryConfig( 'GBE_BIN' );`
		271	`TestDirectoryConfig( 'GBE_PERL' );`
		272	`TestDirectoryConfig( 'GBE_DPLY' );`
		273	`TestDirectoryConfig( 'GBE_DPKG' );`
		274	`TestDirectoryConfig( 'GBE_DPKG_CACHE' );`
		275	`TestDirectoryConfig( 'GBE_DPKG_LOCAL' );`
		276	`TestDirectoryConfig( 'GBE_DPKG_STORE' );`
		277	`TestDirectoryConfig( 'GBE_DPKG_SBOX' );`
		278	`TestDirectoryConfig( 'GBE_SANDBOX' );`
		279
		280	`################################################################################`
		281	`# Setup the Machine Type`
		282	`#`
		283	`# GBE_MACHTYPE is used to determine the BIN directory from which JATS will`
		284	`# pull local binary executables from. The directory must exist.`
		285	`#`
		286	`# We need GBE_MACHTYPE to be correctly defined by the user`
		287	`# This is machine specific and should be done in jats.sh/jats.bat`
		288	`#`
		289	`unless ( $GBE_MACHTYPE )`
		290	`{`
		291	`$GBE_MACHTYPE = 'win32' if ( $^O eq "cygwin" );`
		292	`$GBE_MACHTYPE = 'win32' if ( $^O eq "MSWin32" );`
		293	`$GBE_MACHTYPE = 'win32' if ( $^O eq "win95" );`
		294	`Verbose ("Setting GBE_MACHTYPE: $GBE_MACHTYPE") ;`
		295	`}`
		296
		297	`ReportError ('Set env-var GBE_MACHTYPE (typically "win32")') unless ( $GBE_MACHTYPE );`
		298	`ErrorDoExit();`
		299
		300	`if ( $GBE_MACHTYPE eq 'win32' )`
		301	`{`
		302	`$PSPLIT = ';';`
		303	`$GBE_UNIX = 0;`
		304	`}`
		305
		306	`################################################################################`
		307	`# Windows: If the user is running JATS from within the development view`
		308	`# then they may not provide a drive letter in the full name of GBE_CORE`
		309	`# For correct operation GBE_CORE needs to be able to run programs and`
		310	`# scripts from any other drive`
		311	`#`
		312	`# If GBE_CORE does not have a driver letter - then add one`
		313	`# Note: Use the CWD before any CD operations`
		314	`#`
		315	`if ( $GBE_MACHTYPE eq 'win32' && $GBE_CORE !~ m/^\w\:/ )`
		316	`{`
		317	`my $cwd = getcwd();`
		318	`$GBE_CORE = substr( $cwd, 0, 2 ) . '/' . $GBE_CORE;`
		319	`$GBE_CORE =~ s~//~/~g;`
		320	`Verbose2 ("Setting GBE_CORE drive: $GBE_CORE");`
		321	`}`
		322
		323	`################################################################################`
		324	`# Attempt to run JATS from a local cache`
		325	`# This mechanism allows JATS to be a link to a desired version on a network`
		326	`# drive, but to have the version transferred locally if required`
		327	`#`
229	dpurdie	328	`# The transfer/check is only done on the first invocation of jats. If jats uses`
245	dpurdie	329	`# jats to perform functions, then it will not be performed.`
229	dpurdie	330	`#`
245	dpurdie	331	`# If we want to run an alternate version of JATS, then don't attempt to`
229	dpurdie	332	`# cache the initial version of JATS.`
		333	`#`
227	dpurdie	334	`if ( $ENV{GBE_CACHE_JATS} && ! $GBE_JATS_SANE && ! $GBE_JATS_VERSION)`
		335	`{`
		336	`my $state = "Not Cached: Not running from dpkg_archive";`
		337	`#`
		338	`# Must have the DPKG_ARCHIVE cache`
229	dpurdie	339	`# Must be running from DPKG_ARCHIVE - prevent messing with local copies`
227	dpurdie	340	`#`
		341	`if ( $GBE_DPKG_CACHE )`
		342	`{`
229	dpurdie	343	`#`
		344	`# JATS must be running from an archive, otherwise we assume that its`
		345	`# a local copy. Detected by:`
		346	`# GBE_NOT_RELEASED being set`
		347	`# Lack of descpkg file`
		348	`#`
		349	`if ( ! $GBE_NOT_RELEASED && -f "$GBE_CORE/descpkg" )`
227	dpurdie	350	`{`
229	dpurdie	351	`my ($archive, $package) = LocateJatsVersion( $GBE_VERSION );`
		352	`if ( $archive )`
		353	`{`
		354	`Verbose ("Update cached version of JATS: $GBE_VERSION");`
		355	`#`
		356	`# Attempt to cache the package`
		357	`# Need enough JATS environment to run the cache_dpkg utility`
		358	`#`
283	dpurdie	359	`{`
		360	`local %ENV = %ENV;`
227	dpurdie	361
283	dpurdie	362	`$ENV{GBE_TOOLS} = "$GBE_CORE/TOOLS";`
		363	`$ENV{PERL5LIB} = "$GBE_CORE/TOOLS/LIB" ;`
		364	`$ENV{GBE_BIN} = "$GBE_CORE/BIN.$GBE_MACHTYPE";`
		365	`$ENV{GBE_VERBOSE} = $GBE_VERBOSE;`
227	dpurdie	366
283	dpurdie	367	`etool ( 'cache_dpkg.pl', $package );`
		368	`}`
227	dpurdie	369
229	dpurdie	370	`my $tgt = "$GBE_DPKG_CACHE/$package";`
		371	`if ( -d $tgt )`
		372	`{`
		373	`Verbose ("Using cached version of JATS: $GBE_VERSION");`
		374	`$GBE_CORE = $tgt;`
		375	`$state = "Cached";`
		376	`}`
		377	`else`
		378	`{`
		379	`$state = "Not Cached: Copy Failure";`
		380	`}`
227	dpurdie	381	`}`
		382	`else`
		383	`{`
229	dpurdie	384	`$state = "Not Cached: Not found in archives";`
227	dpurdie	385	`}`
		386	`}`
		387	`}`
		388	`else`
		389	`{`
		390	`$state = "Not Cached: No GBE_DPKG_CACHE";`
		391	`}`
		392
		393	`#`
		394	`# Flag JATS having been cached on the machine`
		395	`#`
		396	`$ENV{GBE_CACHE_JATS} = $state;`
		397	`}`
		398
		399
		400	`################################################################################`
		401	`# Establish a relationship between GBE_BIN, GBE_TOOLS and GBE_CONFIG`
		402	`# unless the user has already provided one.`
		403	`#`
		404	`# Only NEED GBE_CORE - the others will be derived`
		405	`#`
		406	`unless ( $GBE_BIN )`
		407	`{`
		408	`$GBE_BIN = "$GBE_CORE/BIN.$GBE_MACHTYPE";`
		409	`Verbose2 ("Setting GBE_BIN: $GBE_BIN");`
		410	`}`
		411	`ReportError ('GBE_MACHTYPE is not valid.',`
		412	`'There must be a corresponding BIN directory in GBE_CORE',`
		413	`"GBE_BIN : $GBE_BIN",`
		414	`"GBE_MACHTYPE: $GBE_MACHTYPE"`
		415	`) unless ( -d $GBE_BIN );`
		416
		417	`ReportError ('Machine specific binary directory does not appear to setup',`
		418	`'After JATS is installed the PostInstall script must be run',`
		419	`"GBE_BIN : $GBE_BIN"`
		420	`) unless ( -x $GBE_BIN . '/sh' \|\| -x $GBE_BIN . '/sh.exe' );`
		421
		422	`unless ( $GBE_TOOLS )`
		423	`{`
		424	`$GBE_TOOLS = "$GBE_CORE/TOOLS";`
		425	`Verbose2 ("Setting GBE_TOOLS: $GBE_TOOLS");`
		426	`}`
		427
		428	`unless ( $GBE_CONFIG )`
		429	`{`
		430	`$GBE_CONFIG = "$GBE_CORE/CFG";`
		431	`Verbose2 ("Setting GBE_CONFIG: $GBE_CONFIG");`
		432	`}`
		433
		434	`#`
		435	`# Extend the PERL5 with our own Module Repository`
		436	`#`
		437	`$PERL5LIB = join( $PSPLIT, split( $PSPLIT, $PERL5LIB), "$GBE_CORE/TOOLS/LIB" );`
		438
		439
		440	`################################################################################`
		441	`# Sanity Test`
		442	`# The ABT environment requires several parameters to specify the location`
		443	`# of the Release/Deployment Managers`
		444	`#`
		445	`# GBE_DM_LOCATION will be set GBE_RM_LOCATION, if not set`
		446	`#`
		447	`# Only perform the test:`
		448	`# - On the first invocation of JATS, not nested invocations`
		449	`# - Based on the EnvVar, not the user option. This will allow a user`
		450	`# to invoke ABT without the need for these values to be present`
		451	`#`
		452	`if ( ! $GBE_JATS_SANE && $ENV{GBE_RM_LOCATION} && ! $ENV{GBE_DM_LOCATION} )`
		453	`{`
		454	`$ENV{GBE_DM_LOCATION} = $ENV{GBE_RM_LOCATION};`
		455	`}`
		456
		457	`if ( ! $GBE_JATS_SANE && $ENV{GBE_ABT} )`
		458	`{`
		459	`foreach my $var ( qw(GBE_DM_LOCATION GBE_DM_USERNAME GBE_DM_PASSWORD GBE_RM_URL))`
		460	`{`
		461	`Warning("Deployment Manager EnvVar may need to be defined: $var") unless ( $ENV{$var} );`
		462	`}`
		463
		464	`foreach my $var ( qw(GBE_RM_LOCATION GBE_RM_USERNAME GBE_RM_PASSWORD GBE_DM_URL))`
		465	`{`
		466	`ReportError("Release Manager EnvVar needs to be defined: $var") unless ( $ENV{$var} );`
		467	`}`
		468	`}`
		469
		470	`################################################################################`
		471	`#`
		472	`# Change to the required root directory`
		473	`# The user may specify a start directory( -c )`
		474	`#`
		475	`change_dir ( $opt_dir );`
245	dpurdie	476
		477
		478	`################################################################################`
		479	`# Locate the root of the build - if required`
		480	`# This is used by the autobuild tools to:`
		481	`# 1) Locate the build.pl file for JATS based builds`
		482	`# The name of the target package can be provided to resolve`
		483	`# cases of multiple build files.`
		484	`#`
		485	`# 2) Locate the <ProjectName>depends.xml file for ANT based builds`
		486	`# The name of the buildfile will be specified`
		487	`# There must be only one file of this name in the tree`
		488	`#`
		489	`# Note: If only one build file is found, then it will be used`
		490	`# It will not be sanity tested. This is intentional`
		491	`# for backward compatability.`
		492	`#`
		493	`if ( $opt_locate \|\| $opt_locate_file \|\| $opt_locate_package )`
227	dpurdie	494	`{`
245	dpurdie	495	`#`
		496	`# Allow the user to specify the name of the build file`
		497	`# This will be used in ANT builds as the name changes`
		498	`# but it can be predetermined`
		499	`#`
227	dpurdie	500	`$opt_locate_file = $BUILD_FILE unless ( $opt_locate_file );`
		501
245	dpurdie	502	`#`
		503	`# Create a Build File Scanner object`
		504	`# This will be used to locate a suitable build file`
		505	`#`
227	dpurdie	506	`Verbose ("Autolocate the build file: $opt_locate_file");`
		507
245	dpurdie	508	`my $bscanner = BuildFileScanner ( '.', $opt_locate_file );`
		509	`my $count = $bscanner->locate();`
		510
		511	`Error ("Autolocate. Build file not found: $opt_locate_file" )`
		512	`if ( $count <= 0 );`
		513
227	dpurdie	514	`#`
245	dpurdie	515	`# If multiple build files have been found`
		516	`# If $opt_locate_package is set then we can attempt to resolve the package`
227	dpurdie	517	`#`
245	dpurdie	518	`# Scan the buildfiles and determine the names of the packages that will`
		519	`# be built. This can be used to generate nice error messages`
		520	`if ( $count > 1 )`
		521	`{`
		522	`$bscanner->scan();`
		523	`$count = $bscanner->match( $opt_locate_package );`
		524	`#DebugDumpData ("Bscan", \$bscanner );`
227	dpurdie	525
245	dpurdie	526	`my $errmess;`
		527	`unless ( $opt_locate_package ) {`
		528	`$errmess = "Use -locatepkg=pkg to resolve required package";`
		529
		530	`} elsif ( $count <= 0 ) {`
		531	`$errmess = "None found that build package: $opt_locate_package";`
		532
		533	`} elsif ( $count > 1 ) {`
		534	`$errmess = "Multiple build files build the required package: $opt_locate_package";`
		535	`}`
		536
		537	`#`
		538	`# Pretty error display`
		539	`# Display build directory and the package name (mangled)`
		540	`#`
		541	`if ( $errmess )`
		542	`{`
		543	`Error ("Autolocate. Multiple build files found.",`
		544	`$errmess,`
		545	`"Build files found in:", $bscanner->formatData() );`
		546	`}`
		547	`}`
		548
227	dpurdie	549	`#`
245	dpurdie	550	`# Extract the required build file directory`
227	dpurdie	551	`#`
245	dpurdie	552	`my $dir = $bscanner->getMatchDir() \|\| '';`
		553	`Verbose ("Autolocate. Found $count build files: $dir");`
227	dpurdie	554
		555	`#`
		556	`# Select the one true build directory`
		557	`#`
245	dpurdie	558	`change_dir ( $dir );`
227	dpurdie	559
		560	`#`
		561	`# Kill location scan as we have already located the build file`
		562	`#`
		563	`$opt_here = 1;`
		564	`}`
		565
		566	`################################################################################`
		567	`# Version redirection`
		568	`# JATS allows the version of JATS to be used to be specified`
		569	`# This mechanism operates on the assumption that the required version is`
		570	`# present in dpkg_archive. If a specific version is required then the bulk`
		571	`# of this script is bypassed and the arguments passed directly to the required`
		572	`# target`
		573	`#`
		574	`if ( $GBE_JATS_VERSION && $GBE_JATS_VERSION eq $GBE_VERSION )`
		575	`{`
		576	`Message("Using current JATS version: $GBE_JATS_VERSION" );`
		577	`$GBE_JATS_VERSION = undef;`
		578	`}`
		579
		580	`if ( $GBE_JATS_VERSION )`
		581	`{`
		582	`#`
		583	`# Report any errors detected`
		584	`#`
		585	`ErrorDoExit();`
		586	`Message("Using JATS version: $GBE_JATS_VERSION");`
		587
		588	`#`
245	dpurdie	589	`# If we have a cache available, then attempt to transfer the required`
		590	`# version into the cache. If we don't have a cache, then don't even try.`
229	dpurdie	591	`#`
245	dpurdie	592	`if ( $GBE_DPKG_CACHE )`
		593	`{`
		594	`#`
		595	`# Attempt to locate the desired version in one of the well known`
		596	`# package archives. This will give us its package name.`
		597	`#`
		598	`my ($archive, $package) = LocateJatsVersion ($GBE_JATS_VERSION);`
		599	`Error("Cannot find JATS version: $GBE_JATS_VERSION") unless $archive;`
229	dpurdie	600
245	dpurdie	601	`#`
		602	`# Do NOT propagate GBE_JATS_VERSION in the environment`
		603	`# This will only cause problem in recursion`
		604	`#`
		605	`delete $ENV{GBE_JATS_VERSION};`
227	dpurdie	606
245	dpurdie	607	`#`
		608	`# Attempt to cache the package`
		609	`# Need enough JATS environment to run the utility`
		610	`#`
283	dpurdie	611	`{`
		612	`local %ENV = %ENV;`
227	dpurdie	613
283	dpurdie	614	`$ENV{PERL5LIB} = $PERL5LIB;`
		615	`$ENV{GBE_BIN} = $GBE_BIN;`
		616	`$ENV{GBE_VERBOSE} = $GBE_VERBOSE;`
		617	`$ENV{GBE_TOOLS} = $GBE_TOOLS;`
227	dpurdie	618
283	dpurdie	619	`etool ( 'cache_dpkg.pl', $package );`
		620	`}`
245	dpurdie	621	`}`
227	dpurdie	622
		623	`#`
229	dpurdie	624	`# Locate the version of JATS to be run (again)`
227	dpurdie	625	`# It should be in the cache, but it may not be`
		626	`#`
245	dpurdie	627	`my ($archive, $package) = LocateJatsVersion ($GBE_JATS_VERSION);`
229	dpurdie	628	`Error("Cannot find JATS version: $GBE_JATS_VERSION") unless $archive;`
		629
		630	`$GBE_CORE = "$archive/$package";`
227	dpurdie	631	`Verbose2 ("Using alternate version: $GBE_CORE");`
		632
		633	`#`
		634	`# Run the specified version of JATS`
		635	`# Force the required version of GBE_CORE and invoke the wrapper script`
		636	`#`
		637	`$ENV{GBE_CORE} = $GBE_CORE;`
		638
		639	`Verbose("Use ARGV: @ARGV");`
		640	`$RESULT = System ($GBE_PERL, "$GBE_CORE/TOOLS/jats.pl", @ARGV );`
		641	`do_exit();`
		642	`}`
		643
		644	`################################################################################`
		645	`# Determine the current directory`
		646	# Note: Don't use `pwd`. This sucks for so many reasons including
		647	`# the fact that it may not be available until this wrapper`
		648	`# script has done it job.`
		649	`#`
		650	`$CWD = getcwd();`
		651	`Verbose ("Current Working Directory: $CWD");`
		652	`Warning ("Current working directory contains spaces") if ( $CWD =~ m/\s/ );`
		653
		654
		655	`################################################################################`
		656	`# Setup drive`
		657	`# This is only required under windows`
		658	`# Purpose is unclear, but under windows it is required, so lets create one`
		659	`# if its not present`
		660	`#`
		661	`unless ( $GBE_UNIX )`
		662	`{`
		663	`unless ( $GBE_DRV )`
		664	`{`
		665	`($GBE_DRV = $CWD ) =~ s~[^:]*$~~;`
		666	`$GBE_DRV = "c:" if ( $GBE_DRV !~ m/:/ );`
		667	`Verbose2( "Setting GBE_DRV: $GBE_DRV" );`
		668	`}`
		669	`}`
		670
		671	`################################################################################`
		672	`# Sanity test the main archive variable`
		673	`# This MUST address one archive`
		674	`#`
		675
		676	`Error ("GBE_DPKG must not be a path list: $GBE_DPKG")`
		677	`if ( $GBE_DPKG =~ /$PSPLIT/ );`
		678	`Error ("GBE_DPKG is not a directory : $GBE_DPKG")`
		679	`unless( -d $GBE_DPKG );`
		680
		681	`################################################################################`
		682	`# Sanity test the cache`
		683	`#`
		684	`Error ("GBE_DPKG_CACHE is not a directory : $GBE_DPKG_CACHE")`
		685	`if ( $GBE_DPKG_CACHE && ! -d $GBE_DPKG_CACHE );`
		686
		687	`################################################################################`
		688	`# Sanity test the global store`
		689	`#`
		690	`Error ("GBE_DPKG_STORE is not a directory : $GBE_DPKG_STORE")`
		691	`if ( $GBE_DPKG_STORE && ! -d $GBE_DPKG_STORE );`
		692
		693	`Error ("GBE_DPLY is not a directory : $GBE_DPLY")`
		694	`if ( $GBE_DPLY && ! -d $GBE_DPLY );`
		695
		696	`########################################################################`
		697	`#`
		698	`# Locate a local_dpkg_archive directory, by searching from the CWD`
		699	`# to the root of the file system`
		700	`#`
		701	`unless ( $GBE_DPKG_LOCAL )`
		702	`{`
283	dpurdie	703	`($GBE_DPKG_LOCAL) = scan_for_dir ('local_dpkg_archive');`
227	dpurdie	704	`}`
		705	`else`
		706	`{`
		707	`Error ("GBE_DPKG_LOCAL is not a directory : $GBE_DPKG_LOCAL")`
		708	`unless( -d $GBE_DPKG_LOCAL );`
		709	`}`
		710
		711	`########################################################################`
		712	`#`
		713	`# Locate a sandbox_dpkg_archive directory by searching from the CWD`
		714	`# to the root of the file system`
		715	`#`
241	dpurdie	716	`# sandbox_dpkg_archive is a dpkg_archive for packages that are being`
		717	`# co-developed. Package Versions within the sandbox are ignored`
227	dpurdie	718	`#`
241	dpurdie	719
		720	`#`
		721	`# Ensure that the user does not set $GBE_SANDBOX or $GBE_DPKG_SBOX`
		722	`# $GBE_JATS_SANE will be set for multiple invocations, thus it is cleared`
		723	`# for the first one (unless the user messes with it).`
		724	`#`
		725	`unless ( $GBE_JATS_SANE )`
227	dpurdie	726	`{`
241	dpurdie	727	`Error ("GBE_SANDBOX must not be set by the user") if ( $GBE_SANDBOX );`
		728	`Error ("GBE_DPKG_SBOX must not be set by the user") if ( $GBE_DPKG_SBOX );`
		729
		730	`#`
		731	`# The ABT does not use the sandbox`
		732	`# It will never be found and will be ignored`
		733	`#`
		734	`unless ( $GBE_ABT )`
		735	`{`
277	dpurdie	736	`($GBE_DPKG_SBOX,$GBE_SANDBOX) = scan_for_dir ('sandbox_dpkg_archive');`
227	dpurdie	737	`}`
		738	`}`
		739
		740	`########################################################################`
		741	`#`
		742	`# Ensure that the user has been set`
		743	`# Under windows USER may not be set, but USERNAME may be`
299	dpurdie	744	`# As a last resort, use getlogin data`
227	dpurdie	745	`#`
		746	`$USER = $ENV{ 'USERNAME' } \|\| '' unless ( $USER );`
		747	`$USER = $ENV{ 'LOGNAME' } \|\| '' unless ( $USER );`
299	dpurdie	748	`$USER = getlogin() \|\| '' unless ( $USER );`
301	dpurdie	749	`ReportError ('Cannot determine USER name, via USER, USERNAME, LOGNAME or getlogin')`
		750	`unless ( $USER );`
299	dpurdie	751	`#Debug ("User: ", $USER, $ENV{ 'USERNAME'}, $ENV{ 'LOGNAME' }, getlogin() );`
		752
227	dpurdie	753	`################################################################################`
		754	`# Sanitize the PATH variable`
		755	`# Some of the Win32 binary tools used by JATS cannot handle lower case Path`
		756	`# Force an upper case PATH`
		757	`#`
		758	`my $PATH = '';`
		759	`$PATH .= delete( $ENV{ 'Path' } ) if (exists $ENV{ 'Path' });`
		760	`$PATH .= delete( $ENV{ 'path' } ) if (exists $ENV{ 'path' });`
		761	`$PATH .= delete( $ENV{ 'PATH' } ) if (exists $ENV{ 'PATH' });`
277	dpurdie	762	`$ENV{'PATH'} = $PATH;`
227	dpurdie	763
		764	`#`
		765	`# Windows now defines ComSpec. This is only a problem when programs are`
		766	`# started up without the use of cmd.exe - like the JATS internal sh.exe`
		767	`# Correct by deleting the environment variable and forcing it to be uppercase`
		768	`#`
		769	`my $COMSPEC = '';`
		770	`$COMSPEC = delete( $ENV{'COMSPEC'} ) if ( exists $ENV{'COMSPEC'} );`
		771
		772	`################################################################################`
		773	`# There is some really ugly interaction between Cygwin, ActiveState Perl 5.8.2`
		774	`# and xmake. Even if none of the cygwin bits are used within JATS the fact that`
		775	`# Cygwin is in the path causes problems.`
		776	`#`
		777	`# Problems seen:`
		778	`# 1) "jats build" xmake fails with a segment fault. Possibly when`
		779	`# displaying an error message`
		780	`# 2) Warnings and messages generated from within Perl don't always appear`
		781	`# In particular. The output from a Message() within a PLATFORM/xxx file`
		782	`# does not get displayed.`
		783	`#`
		784	`# Solution:`
		785	`# Remove cygwin from the PATH`
		786	`#`
		787	`$PATH =~ s~c:\\cygwin[^;]*;~~ig;`
		788
		789	`################################################################################`
297	dpurdie	790	`# Setup the default JAVA_HOME`
		791	`# User should specify 1.4, 1.5,1.6 ....`
		792	`#`
		793	`$JAVA_HOME = get_java_home ($opt_java)`
		794	`if ( $opt_java );`
		795	`PathPrepend ("$JAVA_HOME/bin")`
		796	`if ( -d $JAVA_HOME );`
		797
		798
		799	`################################################################################`
227	dpurdie	800	`# Ensure that the PATH contains the PERL executable`
		801	`# Need to true path to the PERL executable so that the user has access to some`
		802	`# of the perl utility programs such as pod2html`
		803	`#`
299	dpurdie	804	`PathPrepend ($Config{'binexp'});`
227	dpurdie	805
		806	`################################################################################`
		807	`# There is more ugliness if GBE_BIN is not in the users path`
		808	`# I suspect that it something within xmake (under win32) and that it needs`
		809	`# to be able to find sh within the path - even though its fully pathed`
		810	`#`
		811	`# Add GBE_BIN to the start of the path to assist in searching`
		812	`# Also ensure that we pickup our version of utilities instead of random`
		813	`# versions.`
		814	`#`
297	dpurdie	815	`PathPrepend ($GBE_BIN);`
227	dpurdie	816
		817	`################################################################################`
		818	`# Clean PATH`
		819	`# Remove duplicates`
		820	`# Remove empty elements`
		821	`# Clean path endings`
245	dpurdie	822	`# Place non-existent paths at the end. They will be seen, but not scanned`
227	dpurdie	823	`#`
		824	`{`
		825	`my @new_path;`
		826	`my @non_exist;`
		827	`my %seen;`
		828	`foreach ( split $PSPLIT, $PATH )`
		829	`{`
		830	`s~[/\\]+$~~; # Remove trailing / or \`
		831	`my $name = ( $GBE_UNIX ) ? $_ : lc ($_); # Windows is case insensitive`
		832	`next unless ( $_ ); # Remove empty elements`
		833	`next if ( /^\.+$/ ); # Remove . and ..`
		834	`next if ( exists $seen{$name} ); # Remove duplicates`
		835	`if ( -d $_ ) {`
		836	`push @new_path, $_; # Exists`
		837	`} else {`
245	dpurdie	838	`push @non_exist, $_; # Place non existent paths at the end`
227	dpurdie	839	`}`
		840	`$seen{$name} = 1;`
		841	`}`
		842	`$PATH = join( $PSPLIT, @new_path, @non_exist );`
		843	`}`
		844
		845	`################################################################################`
		846	`# Windows: Ensure that cmd.exe is in the users PATH`
		847	`# If cmd.exe cannot be found then the 'system' command will not work`
		848	`#`
		849	`unless ( $GBE_UNIX )`
		850	`{`
		851	`my $cmd_found;`
		852	`foreach ( split $PSPLIT, $PATH )`
		853	`{`
		854	`my $file = $_ . "/cmd.exe";`
		855	`Verbose2 ("Look for: $file");`
		856	`if ( -x $file )`
		857	`{`
		858	`$cmd_found = 1;`
		859	`Verbose ("Found: $file");`
		860	`last;`
		861	`}`
		862	`}`
		863
		864	`Warning( "Users PATH does not contain \"cmd.exe\"",`
		865	`"System commands may not work" ) unless $cmd_found;`
		866	`}`
		867
		868	`################################################################################`
		869	`# Sanitize the Microsoft Visual Studio environment variables LIB and INCLUDE.`
		870	`# If these have a trailing \ then the generated makefiles`
		871	`# will fail. This is impossible to detect and fix within make so do it here`
		872	`#`
		873	`# Note: JATS no longer allows these environment variables through to the`
		874	`# makefiles.`
		875	`#`
		876	`unless ( $GBE_UNIX )`
		877	`{`
		878	`for my $var qw ( LIB INCLUDE )`
		879	`{`
		880	`my $evar = $ENV{$var};`
		881	`if ( $evar )`
		882	`{`
		883	`$evar =~ s~\\;~;~g; # Remove trailing \ from components \; -> ;`
		884	`$evar =~ s~\\$~~; # Remove trailing \`
		885	`$evar =~ s~;$~~; # Remove trailing ;`
		886	`$evar =~ s~;;~;~g; # Remove empty items ;;`
		887	`$ENV{$var} = $evar;`
		888	`}`
		889	`}`
		890	`}`
		891
		892	`################################################################################`
297	dpurdie	893	`# Update the environment variables used by JATS, unless requested otherwise.`
227	dpurdie	894	`#`
277	dpurdie	895	`# If JATS is being used to startup build daemons, then we don't want to`
		896	`# export many of the calculated values into the environment. In particular`
		897	`# GBE_CORE, GBE_BIN, GBE_CONFIG and GBE_TOOLS must not be exported as it will`
		898	`# prevent the daemon from picking up the 'current' version of JATS`
		899	`#`
		900	`#`
287	dpurdie	901
277	dpurdie	902	`if ( $opt_export_vars )`
		903	`{`
		904	`$ENV{'PATH'} = $PATH;`
		905	`$ENV{'GBE_VERSION'} = $GBE_VERSION;`
		906	`$ENV{'GBE_CORE'} = $GBE_CORE;`
		907	`$ENV{'GBE_BIN'} = $GBE_BIN;`
		908	`$ENV{'GBE_CONFIG'} = $GBE_CONFIG;`
		909	`$ENV{'GBE_DPLY'} = $GBE_DPLY;`
		910	`$ENV{'GBE_DPKG'} = $GBE_DPKG;`
		911	`$ENV{'JATS_HOME'} = $GBE_DPKG;`
		912	`$ENV{'GBE_DPKG_CACHE'} = $GBE_DPKG_CACHE;`
		913	`$ENV{'GBE_DPKG_STORE'} = $GBE_DPKG_STORE;`
		914	`$ENV{'GBE_DPKG_LOCAL'} = $GBE_DPKG_LOCAL;`
		915	`$ENV{'GBE_SANDBOX'} = $GBE_SANDBOX;`
		916	`$ENV{'GBE_DPKG_SBOX'} = $GBE_DPKG_SBOX;`
		917	`$ENV{'GBE_PERL'} = $GBE_PERL;`
		918	`$ENV{'GBE_TOOLS'} = $GBE_TOOLS;`
		919	`$ENV{'GBE_MACHTYPE'} = $GBE_MACHTYPE;`
		920	`$ENV{'GBE_HOSTMACH'} = $GBE_HOSTMACH;`
		921	`$ENV{'GBE_PLATFORM'} = $GBE_PLATFORM;`
		922	`$ENV{'GBE_DRV'} = $GBE_DRV;`
		923	`$ENV{'PERL5LIB'} = $PERL5LIB;`
		924	`$ENV{'JAVA_HOME'} = $JAVA_HOME if ($JAVA_HOME);`
		925	`$ENV{'GBE_JATS_SANE'} = 1;`
		926	`}`
287	dpurdie	927	`else`
		928	`{`
		929	`#`
		930	`# Delete, from the environment, values that are related to selecting`
		931	`# the version of JATS being used`
		932	`#`
		933	`foreach ( qw( GBE_VERSION GBE_CORE GBE_BIN GBE_CONFIG GBE_TOOLS GBE_DRV PERL5LIB GBE_DPKG_SBOX GBE_SANDBOX GBE_PLATFORM GBE_JATS_SANE ) )`
		934	`{`
		935	`delete $ENV{$_};`
		936	`}`
		937	`}`
277	dpurdie	938
		939	`#`
		940	`# The following don't affect the operation of the build daemons selecting`
		941	`# the current version of JATS. Some need to be passed through anyway`
		942	`#`
227	dpurdie	943	`$ENV{'GBE_BUILDFILTER'} = $GBE_BUILDFILTER;`
277	dpurdie	944	`$ENV{'GBE_ABT'} = $GBE_ABT if ($GBE_ABT);`
227	dpurdie	945	`$ENV{'GBE_DEBUG'} = $GBE_DEBUG;`
		946	`$ENV{'GBE_VERBOSE'} = $GBE_VERBOSE;`
		947	`$ENV{'GBE_UNIX'} = $GBE_UNIX;`
		948	`$ENV{'USER'} = $USER;`
277	dpurdie	949	`$ENV{'COMSPEC'} = $COMSPEC;`
279	dpurdie	950	`$ENV{'GBE_HOSTNAME'} = $GBE_HOSTNAME;`
227	dpurdie	951
		952	`#-------------------------------------------------------------------------------`
297	dpurdie	953	`# Function : PathPrepend`
		954	`#`
		955	`# Description : Prepend stuff to the PATH`
		956	`#`
		957	`# Inputs : Items to prepend`
		958	`#`
		959	`# Returns : Nothing`
		960	`# Modifies $PATH`
		961	`#`
		962	`sub PathPrepend`
		963	`{`
299	dpurdie	964	`foreach my $el ( @_ )`
297	dpurdie	965	`{`
299	dpurdie	966	`# Must NOT change the original argument, just a copy of it.`
		967	`# Don't use $_ as this messes up too`
		968	`my $item = $el;`
297	dpurdie	969	`$item =~ s~/~\\~g unless ( $GBE_UNIX );`
		970	`$PATH = $item . $PSPLIT . $PATH;`
		971	`}`
		972	`}`
		973
		974	`#-------------------------------------------------------------------------------`
229	dpurdie	975	`# Function : LocateJatsVersion`
		976	`#`
245	dpurdie	977	`# Description : Scan archives looking for a specified version of JATS`
229	dpurdie	978	`# Complicated by the name change from core_devl to jats`
245	dpurdie	979	`# that occurred circa version 2.71.7.`
229	dpurdie	980	`# The required version may be in either of the packages`
		981	`#`
		982	`# Inputs : $version - Version to locate`
		983	`#`
		984	`# Returns : undef - if not found`
		985	`# Array of:`
		986	`# Repository`
		987	`# package/version`
		988	`#`
		989	`sub LocateJatsVersion`
		990	`{`
		991	`my ($version) = @_;`
		992	`my $package;`
		993	`my $path;`
		994
		995	`foreach my $archive qw ( GBE_DPKG_LOCAL GBE_DPKG_CACHE GBE_DPKG GBE_DPKG_STORE )`
		996	`{`
		997	`no strict 'refs';`
		998	`$path = ${$archive};`
		999	`use strict 'refs';`
		1000	`next unless ( $path );`
		1001
		1002	`foreach my $package qw( jats core_devl )`
		1003	`{`
		1004	`Verbose2( "ExamineDir: $path/$package/$version" );`
		1005	`if ( -d "$path/$package/$version" )`
		1006	`{`
283	dpurdie	1007	`return $path, "$package/$version";`
229	dpurdie	1008	`}`
		1009	`}`
		1010	`}`
283	dpurdie	1011	`return;`
229	dpurdie	1012	`}`
		1013
		1014
		1015	`#-------------------------------------------------------------------------------`
227	dpurdie	1016	`# Function : TestDirectoryConfig`
		1017	`#`
		1018	`# Description : Sanity test a user configurable directory or file`
		1019	`# Must not contain spaces`
		1020	`# Must not be a network drive ie: //computer`
		1021	`#`
		1022	`# Inputs :`
		1023	`#`
		1024	`# Returns :`
		1025	`#`
		1026	`sub TestDirectoryConfig`
		1027	`{`
		1028	`my ($dir) = @_;`
		1029
		1030	`no strict 'refs';`
		1031	`my $val = ${$dir};`
		1032
		1033	`if ( $val )`
		1034	`{`
		1035	`#`
		1036	`# Cleanup the path`
		1037	`#`
		1038	`$val =~ tr~\\/~/~s;`
		1039	`$val =~ s~/+$~~;`
255	dpurdie	1040	`$val = '' if ( $val eq '-' \|\| $val eq 'none' );`
227	dpurdie	1041	`${$dir} = $val;`
		1042
		1043	`ReportError("$dir path cannot contain spaces: $val") if ( $val =~ m/\s/ );`
		1044	`ReportError("$dir path cannot be a computer name: $val") if ( $val =~ m~^//~ );`
		1045	`}`
		1046	`use strict 'refs';`
283	dpurdie	1047	`return;`
227	dpurdie	1048	`}`
		1049
		1050	`#-------------------------------------------------------------------------------`
		1051	`# Function : change_dir`
		1052	`#`
		1053	`# Description : change directory to the specified directory`
		1054	`#`
		1055	`# Inputs : $1 - Target directory`
		1056	`#`
		1057	`# Returns :`
		1058	`#`
		1059	`sub change_dir`
		1060	`{`
		1061	`my ($dir) = @_;`
		1062
		1063	`if ( $dir && $dir !~ m/^\.$/ )`
		1064	`{`
		1065	`Verbose ("Changing to JATS build directory: $dir");`
		1066	`chdir $dir \|\| Error ("Bad change directory: $dir");`
		1067	`}`
		1068
		1069	`#`
		1070	`# Reset the CWD`
		1071	# Note: Don't use `pwd`. This sucks for so many reasons including
		1072	`# the fact that it may not be available until this wrapper`
		1073	`# script has done it job.`
		1074	`#`
		1075	`$CWD = getcwd();`
		1076	`$CWD =~tr~\\/~/~s;`
		1077	`Warning ("Current working directory contains spaces") if ( $CWD =~ m/\s/ );`
283	dpurdie	1078	`return;`
227	dpurdie	1079	`}`
		1080
		1081	`#-------------------------------------------------------------------------------`
277	dpurdie	1082	`# Function : scan_for_dir`
		1083	`#`
		1084	`# Description : Scan from the current directory up to the root`
		1085	`# of the current file system looking for a named`
		1086	`# directory`
		1087	`#`
		1088	`# Inputs : $target - Directory to locate`
		1089	`#`
		1090	`# Returns : full_path - Path of dir`
		1091	`# full_dir - Containng dir`
		1092	`#`
		1093
		1094	`sub scan_for_dir`
		1095	`{`
		1096	`my ($target) = @_;`
		1097	`Verbose2 ("Scan for $target");`
		1098
		1099	`my $test_dir = $CWD;`
		1100	`{`
		1101	`do`
		1102	`{`
		1103	`#`
		1104	`# Stop at /home to prevent unix automounter spitting`
		1105	`# lots of error messages`
		1106	`#`
		1107	`last if ( $test_dir =~ m~/home$~ );`
		1108	`Verbose2 ("Testing: $test_dir");`
		1109
		1110	`my $test_path = $test_dir . '/' . $target;`
		1111	`if ( -d $test_path )`
		1112	`{`
		1113	`Verbose ("Found $target: $test_path");`
		1114	`return $test_path, $test_dir;`
		1115	`}`
		1116	`#`
		1117	`# Remove one directory`
		1118	`# Terminate the loop when no more can be removed`
		1119	`#`
		1120	`} while ( $test_dir =~ s~[/][^/]*$~~ );`
		1121	`}`
		1122	`return '','';`
		1123	`}`
		1124
		1125	`#-------------------------------------------------------------------------------`
227	dpurdie	1126	`# Function : get_java_home`
		1127	`#`
		1128	`# Description : Convert user java option into a full path,or die`
		1129	`#`
		1130	`# Inputs : User option`
		1131	`#`
		1132	`# Returns : Full path`
		1133	`#`
		1134	`sub get_java_home`
		1135	`{`
		1136	`my ($java) = @_;`
		1137	`my $jv = "JAVA_HOME_$java";`
		1138	`$jv =~ s~\.~_~g;`
		1139
		1140	`unless ( exists($ENV{$jv}) )`
		1141	`{`
		1142	`Error ("Unknown JAVA version: $java",`
		1143	`"Looking for EnvVar: $jv",`
		1144	`"Example Usage: -java=1.5");`
		1145	`}`
		1146	`my $rv = $ENV{$jv};`
		1147	`unless ( -d $rv )`
		1148	`{`
		1149	`Error ("Java home path not found: $jv",`
		1150	`"Looking for: $rv" );`
		1151	`}`
		1152	`return $rv;`
		1153	`}`
		1154
		1155	`#-------------------------------------------------------------------------------`
		1156	`# Function : get_version`
		1157	`#`
		1158	`# Description : Return the version of JATS being run`
		1159	`# JATS should be run from a "package"`
		1160	`# The package should have a descpkg file`
		1161	`# Use this file`
		1162	`#`
		1163	`# Inputs :`
		1164	`#`
		1165	`# Returns : A string`
		1166	`#`
		1167	`sub get_version`
		1168	`{`
229	dpurdie	1169	`#`
		1170	`# The version number is embedded into this script by the release process`
		1171	`# The text [V]ERSION_TAG will be replaced by the real version number`
245	dpurdie	1172	`# If this has not occurred then we know that the release is not official`
229	dpurdie	1173	`# Need to be a little bit careful about the tag name`
		1174	`#`
		1175	`return ("Unreleased Version. Version tag has not been set")`
		1176	`if ( $GBE_NOT_RELEASED );`
		1177
227	dpurdie	1178	`return "$GBE_VERSION [ Internal. Not an installed package ]"`
		1179	`if ( ! -f "$GBE_CORE/descpkg" );`
		1180
		1181	`my $rec;`
		1182	`return $rec->{'VERSION_FULL'}`
		1183	`if ($rec = ReadDescpkg ( "$GBE_CORE/descpkg" ) );`
		1184
		1185	`return "ERROR";`
		1186	`}`
		1187
		1188	`#-------------------------------------------------------------------------------`
		1189	`# Function : print_version`
		1190	`#`
		1191	`# Description :`
		1192	`#`
		1193	`# Inputs :`
		1194	`#`
		1195	`# Returns :`
		1196	`#`
		1197	`sub print_version`
		1198	`{`
		1199	`#`
		1200	`# Allow user to specify verboseness as an argument`
		1201	`#`
		1202	`foreach ( @_ )`
		1203	`{`
		1204	`$GBE_VERBOSE++ if ( m/^-v/ );`
		1205	`}`
		1206
		1207	`Message get_version();`
		1208	`Message "Internal: $GBE_VERSION" if ($GBE_VERBOSE);`
		1209	`$opr_done = 1;`
283	dpurdie	1210	`return;`
227	dpurdie	1211	`}`
		1212
		1213
		1214	`#-------------------------------------------------------------------------------`
		1215	`#`
		1216	`# Give the user a clue`
		1217	`#`
		1218	`sub help`
		1219	`{`
		1220	`my ($level) = @_;`
		1221	`$level = $opt_help unless ( $level );`
		1222
		1223	`pod2usage(-verbose => 0, -message => "Version: ". get_version()) if ($level == 1 );`
261	dpurdie	1224	`pod2usage(-verbose => $level - 1 );`
227	dpurdie	1225	`}`
		1226
		1227	`#-------------------------------------------------------------------------------`
309	dpurdie	1228	`# Function : find_jats_dir`
227	dpurdie	1229	`#`
309	dpurdie	1230	`# Description : Find a JATS build directory`
		1231	`# Can be supressed with JATS '-here' command line option`
227	dpurdie	1232	`#`
309	dpurdie	1233	`# Inputs : files - Files to look for`
		1234	`# options`
		1235	`# --Ant - Allow Ant files too`
295	dpurdie	1236	`#`
309	dpurdie	1237	`# Returns : Will not return if not found`
		1238	`# Will 'cd' to the build directory`
		1239	`#`
227	dpurdie	1240	`sub find_jats_dir`
		1241	`{`
309	dpurdie	1242	`my $allow_ant;`
		1243	`my @FILES;`
		1244	`my $DIR;`
		1245	`my $check_file;`
		1246
227	dpurdie	1247	`#`
		1248	`# Autodetect suppressed ?`
		1249	`#`
		1250	`return if ( $opt_here );`
		1251
309	dpurdie	1252	`#`
		1253	`# Collect options`
		1254	`# Collect the rest of the arguments`
		1255	`#`
		1256	`foreach ( @_ )`
		1257	`{`
		1258	`if ( m/^--Ant/ ) {`
		1259	`$allow_ant = 1;`
		1260	`}`
		1261	`else {`
		1262	`push @FILES, $_;`
		1263	`}`
		1264	`}`
		1265
227	dpurdie	1266	`push @FILES, @BUILD_FILE_ALT;`
309	dpurdie	1267	`push @FILES, 'build.xml' if ( $allow_ant );`
		1268
		1269	`#`
		1270	`# Parent directories to search`
		1271	`# Child dirs to search`
		1272	`#`
227	dpurdie	1273	`my @SEARCH = qw( . .. ../.. ../../.. );`
309	dpurdie	1274	`my @CHILD = ('', '/jats', '/build', '/build/jats' );`
227	dpurdie	1275
		1276	`#`
		1277	`# Locate the JATS build files`
		1278	`# Allow the user to be in a number of parent directories`
		1279	`#`
309	dpurdie	1280	`scan:`
227	dpurdie	1281	`for my $ROOTDIR (@SEARCH)`
		1282	`{`
309	dpurdie	1283	`for my $SUBDIR (@CHILD)`
227	dpurdie	1284	`{`
309	dpurdie	1285	`$DIR = $ROOTDIR . $SUBDIR;`
227	dpurdie	1286	`next unless -d $DIR;`
		1287
283	dpurdie	1288	`for my $FILE ( @FILES)`
227	dpurdie	1289	`{`
309	dpurdie	1290	`$check_file = $DIR . '/' . $FILE;`
227	dpurdie	1291	`Verbose2 ("Check for: $check_file");`
309	dpurdie	1292	`last scan if ( -f $check_file );`
		1293	`}`
		1294
		1295	`next unless ( $allow_ant );`
		1296	`foreach ( glob($DIR . '/*depends.xml' ) )`
		1297	`{`
		1298	`Verbose2 ("Check for: $_");`
		1299	`if ( m/(.+)depends.xml/ )`
227	dpurdie	1300	`{`
309	dpurdie	1301	`$check_file = "$1.xml";`
		1302	`last scan if ( -f $check_file );`
227	dpurdie	1303	`}`
		1304	`}`
		1305	`}`
309	dpurdie	1306	`$DIR = '';`
227	dpurdie	1307	`}`
309	dpurdie	1308
		1309	`#`
		1310	`# Change to the build directory if one has been found`
		1311	`#`
		1312	`if ( $DIR )`
		1313	`{`
		1314	`Verbose2 ("Found check file: $check_file");`
		1315	`change_dir ( $DIR );`
		1316	`}`
		1317	`else`
		1318	`{`
		1319	`Error ( 'JATS build directory not found.',`
		1320	`"Cannot locate: @FILES",`
		1321	`$allow_ant ? 'or Ant <Package>.xml <Package>depends.xml pair' : undef,`
		1322	`'Use -here option to supress this test'`
		1323	`);`
		1324	`}`
227	dpurdie	1325	`}`
		1326
		1327	`#-------------------------------------------------------------------------------`
		1328	`#`
295	dpurdie	1329	`# Determine the real build file to use`
		1330	`# Will select from a list of known build files.`
227	dpurdie	1331	`#`
295	dpurdie	1332	`sub getBuildFile`
227	dpurdie	1333	`{`
		1334	`my $build_file = $BUILD_FILE;`
		1335	`#`
		1336	`# Use an alternative buildfile - if it exists`
		1337	`# Do not use this file if the user has specified a buildfile`
		1338	`#`
		1339	`unless ( $BUILD_FILE_SET )`
		1340	`{`
		1341	`Verbose ("Search for alternate build file");`
		1342	`foreach my $test_file ( @BUILD_FILE_ALT )`
		1343	`{`
		1344	`Verbose2 ("Search for alternate build file: $test_file");`
		1345	`if ( -f $test_file )`
		1346	`{`
		1347	`$build_file = $test_file;`
		1348	`Message ("=== USING ALTERNATE BUILDFILE: $build_file ===");`
		1349	`last;`
		1350	`}`
		1351	`}`
		1352	`}`
295	dpurdie	1353	`return $build_file;`
		1354	`}`
227	dpurdie	1355
295	dpurdie	1356	`#-------------------------------------------------------------------------------`
		1357	`#`
		1358	`# Kick off the build process`
		1359	`#`
		1360	`sub build`
		1361	`{`
		1362	`my $build_file = $BUILD_FILE;`
		1363	`(my $name = $CWD) =~ s~^.*/~~ ;`
		1364	`$opr_done = 1;`
		1365
		1366	`find_jats_dir($build_file);`
		1367	`Message ("=== Building $name ===");`
		1368	`$build_file = getBuildFile();`
		1369
227	dpurdie	1370	`#`
		1371	`# Jats/make does not handle file systems with spaces in the path names`
		1372	`#`
		1373	`Error('$CWD path cannot contain spaces') if ( $CWD =~ m/\s/ );`
		1374
		1375	`$RESULT = System ($GBE_PERL, $build_file, $CWD, "$GBE_TOOLS/buildlib.pl", "--project", @_ );`
		1376
283	dpurdie	1377	`Message ("=== Build $name NOT complete ===") if ( $RESULT );`
		1378	`Message ("=== Build $name complete ===") unless ( $RESULT );`
227	dpurdie	1379	`return $RESULT`
		1380	`}`
		1381
		1382	`#-------------------------------------------------------------------------------`
		1383	`# Function : bmake_it`
		1384	`#`
		1385	`# Description : Combo build and make operations`
		1386	`#`
		1387	`# Inputs : ... - COMMANDS or Make arguments.`
		1388	`# Key commands are BUILD and INSTALL`
		1389	`#`
		1390	`# Returns : RESULT code`
		1391	`#`
		1392	`sub bmake_it`
		1393	`{`
		1394	`my @make_args = @_;`
		1395	`my $all = 1;`
		1396	`my $msg;`
		1397	`$opr_done = 1;`
		1398
		1399	`if ( $make_args[0] && $make_args[0] eq 'NOTALL' )`
		1400	`{`
		1401	`$all = 0;`
		1402	`shift @make_args;`
		1403	`}`
		1404	`elsif ( $make_args[0] && $make_args[0] eq 'BUILD' )`
		1405	`{`
		1406	`Verbose ("Makeit build") ;`
		1407	`$msg = "Component not built";`
		1408	`build();`
		1409	`shift @make_args;`
		1410	`}`
		1411
		1412	`unless ( $RESULT )`
		1413	`{`
		1414	`push @make_args, '-default=all' if ( $all );`
		1415	`Verbose ("Makeit make @make_args") ;`
		1416
309	dpurdie	1417	`find_jats_dir( 'makefile.pl', 'Makefile.gbe', $BUILD_FILE );`
227	dpurdie	1418	`Error ("No Makefile.gbe file found") unless ( -f 'Makefile.gbe' );`
		1419
		1420	`etool ( 'jmake.pl', @make_args );`
		1421	`$msg = "Component not made";`
		1422	`@make_args = ();`
		1423	`}`
		1424
		1425
		1426	`Verbose ("Makeit Result: $RESULT") ;`
		1427	`Error ( $msg ) if ( $RESULT );`
		1428	`return if ( $RESULT );`
		1429	`}`
		1430
		1431	`#-------------------------------------------------------------------------------`
		1432	`# Function : dev_expand`
		1433	`#`
		1434	`# Description : Expand the users arguments to the "debug/prod" command`
		1435	`# "debug/prod" builds and packages debug stuff`
		1436	`#`
		1437	`# Ignore make options.`
		1438	`#`
		1439	`# Inputs : target`
		1440	`# Argument list`
		1441	`#`
		1442	`# Returns : expanded argument list`
		1443	`#`
		1444	`sub dev_expand`
		1445	`{`
		1446	`my @resultd;`
		1447	`my @resultp;`
		1448	`my @args;`
		1449	`my @opts;`
		1450
		1451	`#`
		1452	`# Remove options from the argument list`
		1453	`#`
		1454	`foreach ( @_ )`
		1455	`{`
		1456	`if ( m~=~ \|\| m~^-~ ) {`
		1457	`push @opts, $_;`
		1458	`} else {`
		1459	`push @args, $_;`
		1460	`}`
		1461	`}`
		1462
		1463	`my $target = shift @args;`
		1464	`my @cmd = $target;`
		1465	`if ( $#args < 0 )`
		1466	`{`
		1467	`push @cmd, "package_$target";`
		1468	`}`
		1469	`else`
		1470	`{`
		1471	`foreach ( @args )`
		1472	`{`
		1473	`push @resultd, $_ . "_$target";`
		1474	`push @resultp, $_ . "_package_$target";`
		1475	`@cmd = ();`
		1476	`}`
		1477	`}`
		1478
		1479	`return (@cmd, @resultd, @resultp, @opts);`
		1480	`}`
		1481
		1482	`#-------------------------------------------------------------------------------`
		1483	`# Function : install_pkg`
		1484	`#`
		1485	`# Description : Install the built package into local_dpkg_archive`
		1486	`# This will make it available for use, without populating the`
		1487	`# global archive`
		1488	`#`
		1489	`# This is done through an external utility to maintain`
		1490	`# consistent interface`
		1491	`#`
		1492	`sub install_pkg`
		1493	`{`
		1494
309	dpurdie	1495	`find_jats_dir($BUILD_FILE, '--Ant');`
227	dpurdie	1496	`etool ( 'create_dpkg.pl', '-archive=local', '-quiet', '-override', @_ );`
		1497	`}`
		1498
		1499	`#-------------------------------------------------------------------------------`
		1500	`# Function : create_dpkg`
		1501	`#`
		1502	`# Description : Install a package into the main dpkg_archive`
		1503	`# This is done through an external utility to maintain`
		1504	`# consistent interface`
		1505	`#`
		1506	`# This function is simply an easy way to access the utility`
		1507
		1508	`sub create_dpkg`
		1509	`{`
309	dpurdie	1510	`find_jats_dir($BUILD_FILE, '--Ant');`
227	dpurdie	1511	`etool ( 'create_dpkg.pl', @_ );`
		1512	`}`
		1513
		1514	`#-------------------------------------------------------------------------------`
		1515	`# Function : etool`
		1516	`#`
		1517	`# Description : Invoke an external tool program written in PERL`
		1518	`#`
		1519	`# Arguments : $1 Name of the program to run`
		1520	`# With optional .pl suffix`
		1521	`# $2+ Program arguments`
		1522	`#`
		1523	`sub etool`
		1524	`{`
		1525	`my $command = shift;`
		1526	`my $cmd;`
		1527	`my @etool_path = ( "$ENV{'GBE_TOOLS'}",`
		1528	`"$ENV{'GBE_TOOLS'}/DEPLOY",`
		1529	`"$ENV{'GBE_TOOLS'}/LOCAL" );`
		1530	`if ( $command )`
		1531	`{`
		1532	`#`
		1533	`# Locate a potential tool`
		1534	`# These will have the user name or a .pl extension`
		1535	`#`
		1536	`ETOOL_SEARCH:`
		1537	`foreach my $ext ( '', '.pl' )`
		1538	`{`
		1539	`foreach my $dir ( @etool_path )`
		1540	`{`
297	dpurdie	1541	`$cmd = "$dir/jats_$command$ext";`
		1542	`last ETOOL_SEARCH if ( -f $cmd );`
		1543
227	dpurdie	1544	`$cmd = "$dir/$command$ext";`
		1545	`last ETOOL_SEARCH if ( -f $cmd );`
		1546	`}`
		1547	`$cmd='';`
		1548	`}`
		1549
		1550	`Error ("Tool not found: $command", "Search path:", @etool_path) unless $cmd;`
		1551	`$RESULT = System ( $GBE_PERL, $cmd, @_ );`
		1552	`}`
		1553	`else`
		1554	`{`
		1555	`#`
		1556	`# Display on the .pl commands`
		1557	`#`
		1558	`display_commands("Available Tools", \@etool_path, ['*.pl'] );`
		1559	`}`
		1560
		1561	`$opr_done = 1;`
		1562	`}`
		1563
		1564	`#-------------------------------------------------------------------------------`
		1565	`# Function : ebin`
		1566	`#`
		1567	`# Description : Invoke an external JATS provided binary`
		1568	`# within the JATS toolset`
		1569	`#`
		1570	`# Arguments : $1 Name of the program to run`
		1571	`# $2+ Program arguments`
		1572	`#`
		1573	`sub ebin`
		1574	`{`
		1575	`my $command = shift;`
		1576	`my $cmd;`
		1577	`my @ebin_path = ( "$GBE_BIN" );`
		1578
		1579	`if ( $command )`
		1580	`{`
		1581	`#`
		1582	`# Locate a potential executable`
		1583	`# This`
		1584	`#`
		1585	`ETOOL_SEARCH:`
		1586	`foreach my $ext ( '', '.exe', '.sh' )`
		1587	`{`
		1588	`foreach my $dir ( @ebin_path )`
		1589	`{`
		1590	`$cmd = "$dir/$command$ext";`
		1591	`last ETOOL_SEARCH if ( -f $cmd );`
		1592	`}`
		1593	`$cmd='';`
		1594	`}`
		1595
		1596	`Error ("Program not found: $command", "Search path:", @ebin_path) unless $cmd;`
		1597	`$RESULT = System ( $cmd, @_ );`
		1598	`}`
		1599	`else`
		1600	`{`
		1601	`#`
		1602	`# Display a list of programs`
		1603	`#`
		1604	`display_commands("Available Programs", \@ebin_path, ['*'] );`
		1605	`}`
		1606
		1607	`$opr_done = 1;`
		1608	`}`
		1609
		1610	`#-------------------------------------------------------------------------------`
		1611	`# Function : eprog`
		1612	`#`
		1613	`# Description : Invoke an external program`
		1614	`# Will detect local .pl files and execute them`
		1615	`# Will detect local .jar files and execute them`
229	dpurdie	1616	`# Will detect local .bat files and execute them`
227	dpurdie	1617	`#`
		1618	`# Arguments : $1 Name of the program to run`
		1619	`# $2+ Program arguments`
		1620	`#`
		1621	`sub eprog`
		1622	`{`
229	dpurdie	1623	`Verbose ("eprog: @_");`
227	dpurdie	1624	`my $name = shift @_;`
		1625	`Error ("eprog. No program specified") unless ( $name );`
		1626
229	dpurdie	1627	`$name .= ".pl" if ( -f "${name}.pl" );`
		1628	`$name .= ".jar" if ( -f "${name}.jar" );`
		1629	`$name .= ".bat" if ( -f "${name}.bat" );`
227	dpurdie	1630
229	dpurdie	1631	`#`
245	dpurdie	1632	`# On Windows programs in the CWD will be found`
		1633	`# Mimic this behaviour on Unix`
229	dpurdie	1634	`#`
		1635	`$name = "./$name" if ( $name !~ m~/~ && -f "./$name");`
		1636
227	dpurdie	1637	`if ( $name =~ m~\.pl$~ ) {`
		1638	`$RESULT = System ( $GBE_PERL, $name, @_ );`
		1639
		1640	`} elsif ( $name =~ m~\.jar$~ ) {`
		1641	`$RESULT = System ( "$JAVA_HOME/bin/java", '-jar', $name, @_);`
		1642
		1643	`} else {`
229	dpurdie	1644	`#`
		1645	`# Ensure .bat files are pathed with \, and not / characters`
		1646	`# The windows command interpreter does not like /`
		1647	`#`
		1648	`$name =~ s~/~\\~g if ( $name =~ m~\.bat$~ );`
		1649
227	dpurdie	1650	`$RESULT = System ( $name, @_ );`
		1651	`}`
		1652
		1653	`$opr_done = 1;`
		1654	`}`
		1655
		1656	`#-------------------------------------------------------------------------------`
		1657	`# Function : display_commands`
		1658	`#`
		1659	`# Description : Display a list of commands from a specified list of dirs`
		1660	`# Internal helper function`
		1661	`#`
		1662	`# Inputs : $title - Display header`
		1663	`# $ref_path - Ref to an array that contains the search path`
		1664	`# $ref_ext - Ref to an array of valid patterns`
		1665	`#`
		1666	`# Returns : Nothing`
		1667	`#`
		1668	`sub display_commands`
		1669	`{`
		1670	`my ( $title, $ref_path, $ref_ext ) = @_;`
		1671
		1672	`#`
		1673	`# Display a list of commands`
		1674	`#`
		1675	`my %list;`
		1676	`foreach ( @$ref_path )`
		1677	`{`
		1678	`foreach my $ext ( @$ref_ext )`
		1679	`{`
		1680	`foreach my $file ( glob( "$_/$ext") )`
		1681	`{`
		1682	`$file =~ s~.*/~~ unless $GBE_VERBOSE;`
		1683	`$list{$file} = 1;`
		1684	`}`
		1685	`}`
		1686	`}`
		1687
		1688	`my $count = 0;`
		1689	`my $limit = $GBE_VERBOSE ? 1 : 3;`
		1690	`print "$title:\n";`
		1691	`foreach ( sort keys %list )`
		1692	`{`
		1693	`printf "%-26s", $_;`
		1694	`print "\n" if ( !( ++$count % $limit) );`
		1695	`}`
		1696	`}`
		1697
		1698	`#-------------------------------------------------------------------------------`
		1699	`# Function : run_ant`
		1700	`#`
		1701	`# Description : Invoke ant`
		1702	`# If the current directory looks like an ERG build system, then`
		1703	`# create and maintain an auto.xml file. Otherwise simply invoke ant`
		1704	`#`
		1705	`# Inputs : $1+ program arguments`
		1706	`#`
		1707	`sub run_ant`
		1708	`{`
		1709	`my $JAVA_HOME = $ENV{JAVA_HOME} \|\| Error ("JAVA_HOME is not defined in the environment");`
		1710	`my $ANT_HOME = $ENV{ANT_HOME} \|\| Error ("ANT_HOME is not defined in the environment" );`
		1711
		1712	`#`
		1713	`# Detect an ERG formatted build`
		1714	`# This will have two files <projectname>.xml and <projectname>depends.xml`
		1715	`# Create the 'auto.xml' file only if its not present`
		1716	`#`
		1717	`my @ant_arg;`
		1718	`my @flist;`
		1719	`my $basename = '';`
235	dpurdie	1720	`my $scanner = '*depends.xml';`
227	dpurdie	1721
		1722	`#`
		1723	`# Use specified build file to resolve multiple names`
		1724	`# Strip any trailing depends.xml to make it user friendly`
		1725	`#`
		1726	`if ( $BUILD_FILE_SET )`
		1727	`{`
		1728	`$basename = $BUILD_FILE;`
		1729	`$basename =~ s~\.xml$~~;`
		1730	`$basename =~ s~depends$~~;`
235	dpurdie	1731	`$scanner = "${basename}depends.xml";`
227	dpurdie	1732	`Verbose ("Using buildfile: $basename");`
		1733	`}`
		1734
235	dpurdie	1735	`my @buildlist = glob($scanner);`
227	dpurdie	1736	`foreach ( @buildlist )`
		1737	`{`
		1738	`if ( m/(.+)depends.xml/ )`
		1739	`{`
		1740	`my $pname = $1;`
		1741	`push @flist, $pname if ( -f "$pname.xml" );`
		1742	`}`
		1743	`}`
		1744
		1745	`if ( $#flist >= 0 )`
		1746	`{`
		1747	`Error ("Multiple depends.xml files found:", @flist,`
297	dpurdie	1748	`"Use 'jats -buildfile=name ant ...' to resolve") if ( $#flist > 0 );`
227	dpurdie	1749
		1750	`my $depend = "$flist[0]depends.xml";`
		1751	`@ant_arg = ('-f', "$flist[0].xml");`
		1752
		1753	`Message ("Ant using projectfiles: $flist[0].xml");`
		1754
		1755	`#`
		1756	`# Check for depends.xml newer than auto.xml.`
		1757	`#`
		1758	`my $auto_timestamp = (stat('auto.xml'))[9] \|\| 0;`
		1759	`my $depend_timestamp = (stat($depend))[9];`
		1760	`if ( $depend_timestamp > $auto_timestamp )`
		1761	`{`
		1762	`Message ("Creating: auto.xml");`
		1763	`copy( $depend, 'auto.xml' );`
		1764	`chmod 0777, 'auto.xml';`
		1765	`}`
		1766	`}`
		1767	`elsif ( $BUILD_FILE_SET )`
		1768	`{`
		1769	`Error ("Specified build file pair not found:", $basename, $basename . "depends.xml");`
		1770	`}`
		1771
		1772	`#`
		1773	`# The ant provided startup scripts don't return an exit code under`
		1774	`# windows. Invoke ant directly`
		1775	`#`
		1776	`launch_ant ( $JAVA_HOME, $ANT_HOME, @ant_arg, @_ );`
		1777	`$opr_done = 1;`
		1778	`}`
		1779
		1780	`#-------------------------------------------------------------------------------`
		1781	`# Function : run_abt`
		1782	`#`
		1783	`# Description : Invoke auto build tool (older form)`
		1784	`# Options for the ABT`
		1785	`# --Java=x.x`
		1786	`# Invoke ANT for the ABT using a specified version of Java`
		1787	`# Do not play with the user environment.`
297	dpurdie	1788	`# Don't stick java path into environment`
227	dpurdie	1789	`#`
		1790	`# Inputs : $1+ program arguments`
		1791	`#`
		1792	`sub run_abt`
		1793	`{`
279	dpurdie	1794	`my $ABT_JAVA = 'JAVA_HOME_1_6'; # Default version for the ABT`
227	dpurdie	1795	`my $JAVA_HOME = $ENV{$ABT_JAVA};`
		1796	`my $ANT_HOME = $ENV{ANT_HOME};`
		1797	`my @abt_arg;`
239	dpurdie	1798	`my $buildfile = 'build.xml';`
227	dpurdie	1799
		1800	`ErrorConfig( 'name' => 'JATS ABT' );`
		1801
		1802	`#`
239	dpurdie	1803	`# Use the user specified buildfile`
		1804	`#`
		1805	`$buildfile = $BUILD_FILE`
		1806	`if ( $BUILD_FILE_SET );`
		1807
		1808	`#`
227	dpurdie	1809	`# Extract known options`
		1810	`#`
		1811	`foreach ( @_ )`
		1812	`{`
		1813	`if ( m/-java=(.*)/ ) {`
		1814	`$JAVA_HOME = get_java_home($1);`
239	dpurdie	1815
		1816	`} elsif ( m/^-buildfile=(.+)/ ) {`
		1817	`$buildfile = $1;`
		1818
227	dpurdie	1819	`} else {`
		1820	`push @abt_arg, $_;`
		1821	`}`
		1822	`}`
		1823
		1824	`Error ("$ABT_JAVA is not defined in the environment") unless $JAVA_HOME;`
		1825	`Error ("ANT_HOME is not defined in the environment" ) unless $ANT_HOME;`
239	dpurdie	1826	`Error ("Ant buildfile not found: $buildfile" ) unless (-f $buildfile);`
227	dpurdie	1827
		1828	`#`
239	dpurdie	1829	`# Insert correct build file arguments`
		1830	`#`
279	dpurdie	1831	`push @abt_arg, '-buildfile', $buildfile;`
		1832
		1833	`#`
		1834	`# Add current directory as java library directory, but only if`
		1835	`# it contains JAR files.`
		1836	`#`
		1837	`push @abt_arg, '-lib', $CWD`
		1838	`if ( glob ('*.jar') );`
239	dpurdie	1839
		1840	`#`
227	dpurdie	1841	`# Use the ant-launcher to invoke ant directly`
		1842	`#`
		1843	`launch_ant ( $JAVA_HOME, $ANT_HOME, @abt_arg );`
		1844	`$opr_done = 1;`
		1845	`}`
		1846
		1847	`#-------------------------------------------------------------------------------`
		1848	`# Function : launch_ant`
		1849	`#`
		1850	`# Description : Start ANT - with sanity checking`
		1851	`#`
		1852	`# Inputs : JAVA_HOME`
		1853	`# ANT_HOME`
		1854	`# @user_args`
		1855	`#`
		1856	`# Returns : Result Code`
		1857	`#`
		1858	`sub launch_ant`
		1859	`{`
		1860	`my ($JAVA_HOME, $ANT_HOME, @user_args ) = @_;`
		1861
		1862	`Error ("Directory not found: $JAVA_HOME") unless ( -d "$JAVA_HOME" );`
		1863	`Error ("Program not found: $JAVA_HOME/bin/java") unless ( -e "$JAVA_HOME/bin/java" \|\| -e "$JAVA_HOME/bin/java.exe" );`
		1864	`Error ("Jar not found: $ANT_HOME/lib/ant-launcher.jar") unless ( -e "$ANT_HOME/lib/ant-launcher.jar" );`
		1865	`Error ("Directory not found: $ANT_HOME") unless ( -d "$ANT_HOME" );`
		1866	`Error ("Directory not found: $ANT_HOME/lib") unless ( -d "$ANT_HOME/lib" );`
		1867
		1868	`#`
		1869	`# Use the ant-launcher to invoke ant directly`
		1870	`#`
		1871	`$RESULT = System ( "$JAVA_HOME/bin/java",`
		1872	`"-classpath","$ANT_HOME/lib/ant-launcher.jar",`
		1873	`"-Dant.home=$ANT_HOME",`
		1874	`"org.apache.tools.ant.launch.Launcher",`
		1875	`"-lib","$ANT_HOME/lib",`
		1876	`@user_args`
		1877	`);`
		1878
		1879	`return $RESULT;`
		1880	`}`
		1881
		1882
		1883	`#-------------------------------------------------------------------------------`
		1884	`#`
		1885	`# Cleanup the sandbox`
		1886	`# Perform a "make clobber" then a "build clobber"`
		1887	`#`
		1888	`sub clobber`
		1889	`{`
		1890	`Message ("=== Removing ======");`
		1891	`find_jats_dir( $BUILD_FILE );`
295	dpurdie	1892	`my $build_file = getBuildFile();`
		1893
227	dpurdie	1894
		1895	`#`
		1896	`# Run a "make clobber" to clean out "everything"`
		1897	`#`
		1898	`etool ( 'jmake.pl', 'clobber' )`
		1899	`if ( -f "Makefile.gbe" );`
		1900
295	dpurdie	1901	`if ( -f $build_file )`
227	dpurdie	1902	`{`
295	dpurdie	1903	`System ( $GBE_PERL, $build_file, $CWD, "$GBE_TOOLS/buildlib.pl", 'clobber' );`
227	dpurdie	1904	`}`
		1905	`else`
		1906	`{`
		1907	`Error ("Cannot clobber. No buildfile found");`
		1908	`}`
		1909
		1910	`Message ("=== Remove complete ===");`
		1911	`$opr_done = 1;`
		1912	`}`
		1913
		1914	`#-------------------------------------------------------------------------------`
		1915	`#`
		1916	`# Dumpout relevant parts of the environment`
		1917	`#`
		1918	`sub dump_vars`
		1919	`{`
		1920	`$opr_done = 1;`
		1921
		1922	`#`
		1923	`# Allow user to specify verboseness as an argument`
		1924	`#`
		1925	`foreach ( @_ )`
		1926	`{`
		1927	`$GBE_VERBOSE++ if ( m/^-v/ )`
		1928	`}`
		1929
		1930	`# Display an array separated list, one entry per line, with dir sanity check`
		1931	`sub alist`
		1932	`{`
		1933	`my ($text, @var) = @_;`
		1934	`my $sep = "=";`
		1935	`for ( @var )`
		1936	`{`
		1937	`my $valid = ( -d $_ \|\| -f $_ ) ? " " : "*";`
		1938	`printf "%-17s%s%s%s\n", $text, $sep, $valid, $_;`
		1939	`$text = "";`
		1940	`$sep = " ";`
		1941	`}`
		1942	`}`
		1943
		1944	`# Display a ';' or ':' separated list, one entry per line`
		1945	`sub dlist`
		1946	`{`
		1947	`my ($text, $var) = @_;`
		1948	`alist( $text, split $PSPLIT, $var \|\| " " );`
		1949	`}`
		1950
		1951	`# Simple print of name and variable`
		1952	`sub pvar`
		1953	`{`
		1954	`my ($text, $data) = @_;`
		1955	`printf "%-17s= %s\n", $text, $data;`
		1956	`}`
		1957
		1958	`# Print of name and variable of directory with sanity check`
		1959	`sub dvar`
		1960	`{`
		1961	`my ($text, $data) = @_;`
		1962	`my $valid = ( ! $data \|\| -d $data \|\| -f $data ) ? " " : "*";`
		1963	`printf "%-17s=%s%s\n", $text, $valid, $data;`
		1964	`}`
		1965
		1966	`# Display a variable extracted from the environment`
		1967	`sub penv`
		1968	`{`
		1969	`my ($var) = @_;`
		1970	`pvar $var, $ENV{$var} \|\| '';`
		1971	`}`
		1972
		1973	`# Display a variable extracted from the environment with dir sanity check`
		1974	`sub denv`
		1975	`{`
		1976	`my ($var) = @_;`
		1977	`dvar $var, $ENV{$var} \|\| '';`
		1978	`}`
		1979
		1980	`#`
		1981	`# Complete environment dump`
		1982	`#`
		1983	`if ( $GBE_VERBOSE > 1 )`
		1984	`{`
		1985	`Message ("Complete environment dump");`
		1986	`foreach my $var ( sort keys(%ENV) )`
		1987	`{`
		1988	`penv $var;`
		1989	`}`
		1990	`return;`
		1991	`}`
		1992
		1993	`pvar "Version" , get_version();`
		1994	`penv "GBE_SCRIPT";`
		1995	`pvar "GBE_DEBUG" , $GBE_DEBUG;`
		1996	`pvar "GBE_VERBOSE" , $GBE_VERBOSE;`
		1997	`pvar "GBE_MACHTYPE" , $GBE_MACHTYPE;`
273	dpurdie	1998	`pvar "GBE_HOSTMACH" , $GBE_HOSTMACH;`
227	dpurdie	1999	`pvar "GBE_UNIX" , $GBE_UNIX;`
		2000	`pvar "GBE_DRV" , $GBE_DRV;`
		2001	`dvar "GBE_PERL" , $GBE_PERL;`
		2002	`dvar "GBE_CORE" , $GBE_CORE;`
		2003	`dvar "GBE_BIN" , $GBE_BIN;`
		2004	`dvar "GBE_TOOLS" , $GBE_TOOLS;`
		2005	`dvar "GBE_CONFIG" , $GBE_CONFIG;`
		2006	`penv "GBE_CACHE_JATS";`
		2007	`dlist "GBE_SANDBOX" , $GBE_SANDBOX;`
		2008	`dlist "GBE_DPKG_STORE" , $GBE_DPKG_STORE;`
		2009	`dlist "GBE_DPKG" , $GBE_DPKG;`
		2010	`dlist "GBE_DPKG_CACHE" , $GBE_DPKG_CACHE;`
		2011	`dlist "GBE_DPKG_LOCAL" , $GBE_DPKG_LOCAL;`
		2012	`dlist "GBE_DPKG_SBOX" , $GBE_DPKG_SBOX;`
		2013	`dlist "GBE_DPLY" , $GBE_DPLY;`
		2014	`pvar "GBE_PLATFORM" , $GBE_PLATFORM;`
		2015	`pvar "GBE_BUILDFILTER" , $GBE_BUILDFILTER;`
		2016	`pvar "GBE_ABT" , $GBE_ABT;`
		2017
		2018	`denv "GBE_VIEWBASE";`
281	dpurdie	2019	`pvar "GBE_HOSTNAME" , $GBE_HOSTNAME;`
227	dpurdie	2020	`dvar "CWD" , $CWD;`
		2021	`pvar "BUILD_FILE" , $BUILD_FILE;`
		2022
		2023	`penv "COMSPEC";`
		2024	`penv "SHELL";`
		2025	`pvar "USER" , $USER;`
		2026	`dlist "PATH" , $PATH;`
		2027
		2028	`#`
		2029	`# Display variables used by various "known" toolsets`
		2030	`# These do cause grief sometime, so only do it for verbose`
		2031	`#`
		2032	`if ( $GBE_VERBOSE )`
		2033	`{`
		2034	`print "\nPerl Environment\n";`
		2035	`pvar "VERSION" ,$];`
		2036	`penv "PERL5SHELL";`
		2037	`penv "PERL5OPT";`
		2038	`dlist "PERL5LIB" ,$ENV{'PERL5LIB'};`
		2039	`alist "INC" ,@INC;`
		2040
		2041	`print "\nJava Environment\n";`
283	dpurdie	2042	`foreach my $var ( sort grep ( {/^JAVA_HOME/ } keys %ENV) )`
227	dpurdie	2043	`{`
		2044	`denv $var;`
		2045	`}`
		2046	`denv "ANT_HOME";`
		2047	`denv "JATS_HOME";`
		2048	`dlist "CLASSPATH" ,$ENV{'CLASSPATH'};`
		2049	`}`
		2050
		2051	`if ( $GBE_VERBOSE \|\| $GBE_ABT )`
		2052	`{`
		2053	`print "\nRelease Manager Environment\n";`
		2054	`penv "GBE_RM_LOCATION";`
		2055	`penv "GBE_RM_USERNAME";`
		2056	`penv "GBE_RM_PASSWORD";`
		2057	`penv "GBE_RM_URL";`
		2058	`penv "GBE_DM_LOCATION";`
		2059	`penv "GBE_DM_USERNAME";`
		2060	`penv "GBE_DM_PASSWORD";`
		2061	`penv "GBE_DM_URL";`
		2062	`}`
297	dpurdie	2063
		2064	`if ( $GBE_VERBOSE \|\| $ENV{GBE_SVN_URL} )`
		2065	`{`
		2066	`print "\nSubVersion (Experimental)\n";`
		2067	`penv "GBE_SVN_PATH";`
		2068	`penv "GBE_SVN_URL";`
		2069	`penv "GBE_SVN_USERNAME";`
		2070	`penv "GBE_SVN_PASSWORD";`
		2071	`}`
227	dpurdie	2072
		2073	`if ( $GBE_VERBOSE && ! $GBE_UNIX)`
		2074	`{`
		2075	`print "\nWindows Environment\n";`
		2076	`denv "TEMP";`
		2077	`denv "TMP";`
		2078
		2079	`print "\nMicrosoft Studio Variables\n";`
		2080	`denv "PROGRAMFILES";`
		2081	`denv "WINDIR";`
		2082	`denv "MSVCDir";`
		2083
		2084	`print "\nMicroTec Compiler Variables\n";`
		2085	`denv "MRI_68K";`
		2086	`denv "MRI_CF";`
		2087	`denv "VISIONCLICK";`
		2088
		2089	`print "\nPCLint Variables\n";`
		2090	`denv "PCLINT";`
		2091	`penv "LINTPACKAGE";`
		2092	`}`
		2093	`}`
		2094
		2095	`#-------------------------------------------------------------------------------`
		2096	`# Function : do_exit`
		2097	`#`
		2098	`# Description : Common exit point so that time information can be displayed`
		2099	`#`
		2100	`# Inputs : Optional exit code`
		2101	`#`
		2102	`# Returns :`
		2103	`#`
		2104	`sub do_exit`
		2105	`{`
		2106	`my ($ecode) = @_;`
		2107
		2108	`$RESULT = $ecode if ( $ecode );`
		2109
		2110	`#..`
		2111	`# Determine the runtime`
		2112	`#`
		2113	`if ( $opt_time )`
		2114	`{`
		2115	`my ($TIMEU, $TIMES) = times;`
		2116	`$TIMER = time - $TIMER;`
		2117	`my ($m, $s );`
		2118
		2119	`$m = int($TIMER / 60);`
		2120	`$s = $TIMER - ($m * 60);`
		2121
		2122	`Message ( "Times: Real: $m:$s, User: $TIMEU, System: $TIMES");`
		2123	`}`
		2124	`#.`
		2125	`# Make sure that any important exit code is passed to the user`
		2126	`#`
		2127	`Verbose ("ExitCode: $RESULT");`
		2128	`exit $RESULT;`
		2129	`}`
		2130
		2131	`########################################################################`
		2132	`#`
		2133	`# Main body of the script`
		2134	`#`
		2135	`# Process help and manual options`
		2136	`# Done after all the setup to ensure that the PATH is correct`
		2137	`# Done before bombout to give user a chance`
		2138	`#`
		2139	`help() if $opt_help;`
		2140	`ErrorDoExit(); # Exit if any error in setup`
		2141	`ErrorConfig( 'on_exit' => \&do_exit );`
		2142
		2143	`#`
231	dpurdie	2144	`# Reset operational flags.`
		2145	`# May have been used by setup`
		2146	`#`
		2147	`$opr_done = 0;`
		2148	`$RESULT = 0;`
		2149
		2150	`#`
227	dpurdie	2151	`# Process user commands`
		2152	`#`
263	dpurdie	2153	`my $cmd = shift @ARGV \|\| help(1);`
227	dpurdie	2154
263	dpurdie	2155	`help(1) if ( $cmd =~ m/^help$/);`
227	dpurdie	2156	`dump_vars(@ARGV) if ( $cmd =~ m/^var/ );`
		2157	`print_version(@ARGV) if ( $cmd =~ m/^ver/ );`
		2158
		2159	`clobber if ( $cmd =~ m/^clobber$/ );`
		2160	`build (@ARGV) if ( $cmd =~ m/^build$/ );`
		2161
		2162	`bmake_it ('NOTALL', @ARGV) if ( $cmd =~ m/^[x]*make$/ );`
		2163	`bmake_it (@ARGV) if ( $cmd =~ m/^go$/ );`
		2164	`bmake_it (dev_expand('debug', @ARGV) ) if ( $cmd =~ m/^debug$/ );`
		2165	`bmake_it (dev_expand('prod', @ARGV) ) if ( $cmd =~ m/^prod$/ );`
		2166	`bmake_it ("clean", @ARGV) if ( $cmd =~ m/^clean$/ );`
		2167	`bmake_it ("rebuild", @ARGV) if ( $cmd =~ m/^rebuild$/ );`
		2168	`bmake_it ('BUILD', @ARGV) if ( $cmd =~ m/^all$/ );`
		2169	`bmake_it ($cmd, @ARGV ) if ( $cmd =~ m/^run_unit_tests/ );`
		2170
		2171	`install_pkg(@ARGV) if ( $cmd =~ m/^install$/ );`
		2172	`create_dpkg(@ARGV) if ( $cmd =~ m/^create_dpkg$/ );`
		2173
		2174	`ebin (@ARGV) if ( $cmd =~ m/^ebin/ );`
		2175	`etool (@ARGV) if ( $cmd =~ m/^etool/ );`
		2176	`eprog (@ARGV) if ( $cmd =~ m/^eprog$/ );`
		2177	`run_ant (@ARGV) if ( $cmd =~ m/^ant$/ );`
		2178	`run_abt (@ARGV) if ( $cmd =~ m/^abt$/ );`
		2179
299	dpurdie	2180	`etool ('cache_dpkg', @ARGV) if ( $cmd =~ m/^dpkg/ );`
		2181	`etool ('gen_msprojects', @ARGV) if ( $cmd =~ m/^gen_msproject/ );`
		2182	`etool ('jats_ccrelease.pl', @ARGV) if ( $cmd =~ m/^cbuild/ );`
		2183	`etool ('jats_ccrelease.pl', @ARGV) if ( $cmd =~ m/^release/ );`
		2184	`etool ('jats_ccrelease.pl', '-extractfiles' ,@ARGV) if ( $cmd =~ m/^extractf/ );`
		2185	`etool ('jats_ccrelease.pl', '-extract' ,@ARGV) if (!$opr_done && $cmd =~ m/^extract/ );`
		2186	`etool ('jats_label', @ARGV) if ( $cmd =~ m/^label$/ );`
		2187	`etool ('jats_sandbox', @ARGV) if ( $cmd =~ m/^sandbox$/ );`
227	dpurdie	2188
		2189	`etool ($cmd, @ARGV) unless ($opr_done); # Pass to etool if not known`
		2190
		2191	`do_exit();`
		2192	`#.`
		2193
		2194	`#-------------------------------------------------------------------------------`
		2195	`# Documentation`
		2196	`#`
		2197
		2198	`=pod`
		2199
		2200	`=head1 NAME`
		2201
		2202	`jats - JATS utility interface tool`
		2203
		2204	`=head1 SYNOPSIS`
		2205
277	dpurdie	2206	`Usage: jats [opts] command [cmd-options]`
227	dpurdie	2207
		2208	`Where opts:`
261	dpurdie	2209	`-h, -h -h, -man=[n] - Help messages with increasing verbosity`
227	dpurdie	2210	`-cd dir - Change to specified directory`
		2211	`-b file - Use alternate build file`
261	dpurdie	2212	`-verbose[=n] - Verbose operation`
		2213	`-debug[=n] - Enable debug mode of JATS scripts`
227	dpurdie	2214	`-here - Disable JATS auto locate of build.pl`
		2215	`-locate - Locate build.pl file and change to directory`
245	dpurdie	2216	`-locatepkg=pkg - Locate build.pl. Resolve multiple files via pkg`
227	dpurdie	2217	`-locatefile=file - Locate specified file and change to directory`
		2218	`-platform=[name] - Set GBE_PLATFORM to name (=+ to append)`
		2219	`-buildfilter=[xxx] - Set GBE_BUILDFILTER to xxx (=+ to append)`
		2220	`-abt=[xxx] - Set GBE_ABT to xxx (=+ to append)`
		2221	`-java=version - Alters java version used (1.4, 1.5)`
		2222	`-time - Time build and compile times`
		2223	`-version=xxx - Use specified version of JATS`
277	dpurdie	2224	`-[no]exportvars - Export sanitised JATS EnvVars (default)`
227	dpurdie	2225
		2226	`Where command is one of:`
		2227	`build - Rebuild the sandbox and makefiles`
		2228	`make - Make one or more components`
		2229	`ant - Invoke an ant build`
		2230	`abt [-java=xxx] - Invoke the auto build tool`
		2231	`install - Install package into local_dpkg_archive`
		2232	`help - Display help message`
		2233	`vars - Display JATS related environment variables`
		2234
		2235	`create_dpkg - Install a package into main dpkg_archive`
		2236	`label - Labelling functions`
		2237	`release - Build a release from a clearcase label`
		2238	`extract - Extract a release from a clearcase label`
		2239	`dpkg_cache - Maintain a dpkg cache`
		2240	`gen_msproject - Generate MSVC project files`
299	dpurdie	2241	`sandbox - Run Sanbox utility`
		2242
227	dpurdie	2243	`etool name - Run internal tool`
		2244	`eprog name - Run external tool`
		2245	`ebin name - Run JATS binary tool`
		2246
		2247	`Shortcut commands. Composites of basic commands`
		2248	`all [opt] - Same as a "build" and "make all"`
		2249	`go [opt] - Same as a "make all"`
		2250	`debug [tgt] - Same as "make debug package_debug"`
		2251	`prod [tgt] - Same as "make prod package_prod"`
		2252	`clean - Same as "make clean"`
		2253	`clobber - Same as "build clobber"`
		2254	`* - Unknown commands are treated as arguments to etool`
		2255
		2256	`Where [cmd-options] are command specific.`
		2257	`Try "jats command -help" for details`
		2258
		2259	`=head1 OPTIONS`
		2260
		2261	`=over 8`
		2262
		2263	`=item B<-help>`
		2264
		2265	`Print a brief help message and exits.`
		2266
		2267	`=item B<-help -help>`
		2268
		2269	`Print a detailed help message with an explanation for each option.`
		2270
261	dpurdie	2271	`=item B<-man[=n]>`
227	dpurdie	2272
		2273	`Prints the manual page and exits.`
		2274
261	dpurdie	2275	`If a numeric manual level is provide then it will be used to control the`
		2276	`verbosity of help provided. This should be inthe range of 1 to 3.`
		2277
227	dpurdie	2278	`=item B<-b file> B<-buildfile file>`
		2279
		2280	`This option modifies the operation of the "build" command. The command will`
		2281	`use the specified file instead of the normal build.pl file.`
		2282
		2283	`=item B<-cd dir> B<-changedir dir>`
		2284
		2285	`This option will change to specified directory before the command is invoked.`
		2286
261	dpurdie	2287	`=item B<--verbose[=n]>`
227	dpurdie	2288
		2289	`This option will increase the level of verbosity of the JATS command and command`
261	dpurdie	2290	`invoked by the JATS shell.`
227	dpurdie	2291
261	dpurdie	2292	`If an argument is provided, then it will be used to set the level, otherwise the`
		2293	`existing level will be incremented. This option may be specified multiple times.`
227	dpurdie	2294
261	dpurdie	2295	`=item B<-debug[=n]>`
		2296
227	dpurdie	2297	`This option will increase the level of debug output of the JATS command and command`
261	dpurdie	2298	`invoked by the JATS shell.`
227	dpurdie	2299
261	dpurdie	2300	`If an argument is provided, then it will be used to set the level, otherwise the`
		2301	`existing level will be incremented. This option may be specified multiple times.`
		2302
227	dpurdie	2303	`=item B<-here>`
		2304
		2305	`This option will disable the "autolocate" mechanism of the JATS shell script.`
		2306
		2307	`By default JATS will "hunt" for a suitable "build.pl" or "makefile.pl" before`
		2308	`executing a build or a make command. JATS will look in the following directories`
		2309	`for a suitable file. Under some conditions this mechanism is not useful.`
		2310
		2311	`By default JATS will hunt in the following directories: "." "jats" "build/`
		2312	`jats" ".." "../.." and "../../..".`
		2313
		2314	`=item B<-locate>`
		2315
		2316	`This option will cause the JATS wrapper script to locate the build.pl file and`
		2317	`then change to that directory. This allows users to locate the build root of`
		2318	`a project and then issue other JATS commands.`
		2319
		2320	`If the B<-c> option is also specified then searching will start in the specified`
		2321	`directory.`
		2322
		2323	`If an alternate build file is specified with the B<-b> option then that filename`
		2324	`will be used in the location process.`
		2325
		2326	`This option implies a B<-here>. No further scanning will be done.`
		2327
		2328	`Exactly one build file must be located. If more than buildfile is located then`
		2329	`the locations of the build files is displayed and JATS will terminate.`
		2330
245	dpurdie	2331
		2332	`=item B<-locatepkg=packagename>`
		2333
		2334	`This option is similar to the B<-locate> option, but it allows the required`
		2335	`build files to be located by ensuring that the required buildfile builds the`
		2336	`specified package.`
		2337
		2338	`There are two forms in which the B<packagename> can be specified. It can be`
		2339	`specified as a full package name and vesrion, or as a package name and the`
		2340	`project suffix. ie: jats-api.1.0.0000.cr or jats-api.cr`
		2341
227	dpurdie	2342	`=item B<-locatefile=file>`
		2343
		2344	`This option is similar to the B<-locate> option, but it allows the name of the`
		2345	`file to be located to be specified.`
		2346
		2347	`=item B<-platform=[name]>`
		2348
		2349	`This option will set the JATS specific environment variable GBE_PLATFORM to`
		2350	`the specified name. The existing value of GBE_PLATFORM may be extended by`
		2351	`using "=+".`
		2352
		2353	`In practice the GBE_PLATFORM variable is of little use. The same effect can be`
		2354	`achieved directly with make targets or with GBE_BUILDFILTER.`
		2355
		2356	`=item B<-buildfilter=[xxx]>`
		2357
		2358	`This option will set the JATS specific environment variable GBE_BUILDFILTER to`
		2359	`the specified name. The existing value of GBE_BUILDFILTER may be extended by`
		2360	`using "=+".`
		2361
		2362	`This option may be used to limit the initial build, and subsequent "make" to a`
		2363	`limited set of platforms.`
		2364
		2365	`=item B<-abt=[xxx]>`
		2366
		2367	`This option will set the JATS specific environment variable GBE_ABT to`
		2368	`the specified name The existing value of GBE_ABT may be extended by`
		2369	`using "=+"..`
		2370
		2371	`This option is used to pass arguments directly to some tools within the`
		2372	`(ABT) Auto Build Tool framework, or to indicate that the build is being`
		2373	`performed within the ABT framework.`
		2374
		2375	`=item B<-java=version>`
		2376
		2377	`This option will override the default java version used by the ant builds and`
		2378	`passed to the underlying programs. The path to the Java SDK is determined from`
		2379	`the environment using the version string replacing the '.' with '_'`
		2380
		2381	`eg: -java=1.5, will examine the environment for JAVA_HOME_1_5 and will set`
		2382	`JAVA_HOME to that value. It will not setup the users PATH or classpath.`
		2383
		2384	`=item B<-time>`
		2385
		2386	`When this option is enabled the JATS script will report the runtime of the`
		2387	`underlying, invoked, command.`
		2388
		2389	`=item B<-version=xxx>`
		2390
		2391	`When this option is invoked JATS will attempt to use the specified version to`
		2392	`perform all processing. JATS will search the GBE_DPKG_LOCAL, GBE_DPKG_CACHE,`
		2393	`GBE_DPKG, GBE_DPKG_STORE in order to locate the specified version of the package.`
		2394
		2395	`The entire command line will be passed to the JATS wrapper script within that`
		2396	`version. This bypasses the jats.bat or jats.sh startup scripts.`
		2397
277	dpurdie	2398	`JATS will attempt to transfer the target version to the local cache in an`
		2399	`attempt to improve performance.`
227	dpurdie	2400
277	dpurdie	2401	`=item B<-[no]exportvars>`
227	dpurdie	2402
277	dpurdie	2403	`The default operation is to export sanitised and calculated values to the`
		2404	`programs running under JATS. The use of NoExportVars will prevent JATS from`
		2405	`exporting modified EnvVars into the environment. This may be required by`
		2406	`processes, such as the build daemons that need to pick up the current version of`
		2407	`JATS on the fly and not have it fixed when the daemon is started.`
227	dpurdie	2408
		2409	`=back`
		2410
		2411	`=head1 ARGUMENTS`
		2412
		2413	`=head2 Basic Commands`
		2414
		2415	`The following commands are invoked directly by the JATS script to wrap the build`
		2416	`tools in a controlled manner.`
		2417
		2418	`=over 8`
		2419
		2420	`=item B<build>`
		2421
		2422	`Build or rebuild the sandbox and makefiles.`
		2423
		2424	`This command must be used before the component can be "made" and when the`
		2425	`contents of the "buildpl" file change. It is a common mistake to use the "build"`
		2426	`command to much.`
		2427
		2428	`The script will hunt for a suitable build.pl file before running the build and`
		2429	`make subcommands.`
		2430
		2431	`The build process has a large number of options. Use "JATS build help" to`
		2432	`display the complete list.`
		2433
		2434	`=item B<make>`
		2435
		2436	`Make one or more components`
		2437
		2438	`This command will invoke a suitable "make" program on the makefile found in`
		2439	`the current directory. This makefile should have been generated by JATS.`
		2440
		2441	`The make process has a large number of options. Use "JATS make help" to`
		2442	`display the complete list.`
		2443
		2444	`=item B<ant>`
		2445
		2446	`This command will use ANT to build a component. JATS will determine the`
		2447	`build.xml file to use with the following algorithm.`
		2448
		2449	`If the files called <Project>depends.xml and <Project>.xml exist then JATS`
		2450	`will create an 'auto.xml' from the depends file, if one does not already`
		2451	`exist or is older than the depends.xml file and then use the <Project>.xml`
		2452	`file as the ant build file.`
		2453
		2454	`Otherwise ant is invoked and it will expect a build.xml file.`
		2455
		2456	`If multiple <Project>depends.xml and <Project>.xml file pairs are found the`
		2457	`command will fail. This can be resolved through the use of the -buildfile=name`
		2458	`option.`
		2459
		2460	`Ant is invoked with the version of Java specified with the -Java=x.x option.`
		2461
		2462	`=item B<abt>`
		2463
		2464	`This command is used to invoke the Auto Build Tool. It will invoke ANT on the`
		2465	`build.xml file in the current directory in such manner as to not affect the`
239	dpurdie	2466	`environment of the programs running under ANT.`
227	dpurdie	2467
245	dpurdie	2468	`The remained of the command line is passed to the ABT, with the exception of`
239	dpurdie	2469	`the options:`
		2470
		2471	`=over 8`
		2472
		2473	`=item * -java=x.x. This is used to control the version of Java used by the`
227	dpurdie	2474	`ABT. The default is 1.5.`
		2475
239	dpurdie	2476	`=item * -buildfile=name. This is used to provide a different build file to ant.`
		2477	`The default build file is 'build.xml'.`
		2478
		2479	`=back`
		2480
227	dpurdie	2481	`=item B<install>`
		2482
		2483	`This command will install a generated "package" into the local_dpkg_archive`
		2484	`directory. This allows a group of packages to be tested before being published`
		2485	`into the global dpkg_archive.`
		2486
		2487	`NOTE. This command is no longer needed. The "build" process will place a`
		2488	`shortcut in the local_dpkg_archive to a components "pkg" directory. Other`
		2489	`components will utilize this shortcut directly and pickup the package without`
		2490	`the user needing to "install" the package - a step that can be forgotten.`
		2491
		2492	`=item B<help>`
		2493
		2494	`Display the basic help message.`
		2495
		2496	`=item B<vars [-v]>`
		2497
		2498	`This command will display all the JATS related environment variables in a`
		2499	`readable form.`
		2500
		2501	`Additional information will be displayed if an argument of "-v" is provided.`
		2502
		2503	`=back`
		2504
		2505	`=head2 Extended Commands`
		2506
		2507	`The following commands support the build environment. They are supplemental to`
		2508	`the build environment. They are implemented as extensions to the basic JATS`
		2509	`command scripts.`
		2510
		2511	`=over 8`
		2512
		2513	`=item B<create_dpkg>`
		2514
		2515	`This command will install a generated package into main dpkg_archive. This`
		2516	`command should not be used directly by a user as it does not ensure that package`
		2517	`has been created in a repeatable manner - use "jats release".`
		2518
		2519	`=item B<label>`
		2520
		2521	`This command provides a number of useful labelling mechanisms to assist in the`
		2522	`labeling of source code.`
		2523
		2524	`=item B<release>, B<cbuild>`
		2525
		2526	`This command allows a package to be built and released, given a Clearcase label.`
		2527	`This is the desired release mechanism.`
		2528
		2529	`The command has two main uses:`
		2530
		2531	`=over 8`
		2532
		2533	`=item 1`
		2534
		2535	`Build a package for release. The process will ensure that the build is`
		2536	`controlled and repeatable.`
		2537
		2538	`=item 2`
		2539
		2540	`Rebuild a package for test or debugging purposes.`
		2541
		2542	`=back`
		2543
		2544	`=item B<extract>`
		2545
		2546	`This is the same as "release -extract"`
		2547
		2548
		2549	`=item B<dpkg_cache>`
		2550
		2551	`This utility provides a number of commands to maintain the local cache of`
245	dpurdie	2552	`dpkg_archive.`
227	dpurdie	2553
		2554	`=item B<gen_msproject>`
		2555
		2556	`This utility will generate a set of Microsoft Studio (Version 6) project and`
		2557	`workspace files to encapsulate the JATS build. The resultant project allows VS`
		2558	`to be used as an editor, source browser, debugger and build tool. JATS is`
		2559	`still used to perform the build.`
		2560
		2561	`=item B<etool name>`
		2562
		2563	`This command allows any JATS extension program to be run. The programs will by`
		2564	`found in the JATS TOOLS directory.`
		2565
		2566	`=item B<eprog name>`
		2567
		2568	`This command allows any JATS extension program to be run.`
		2569	`If the program end in .pl, then it will be run within a perl interpreter.`
		2570	`If the program end in .jar, then it will be run under a java interpreter.`
		2571
		2572	`=item B<ebin name>`
		2573
		2574	`This command allows any JATS support program to be run. The programs will by`
		2575	`found in the JATS BIN directory for the current platform. This command allows`
		2576	`a user script to access many of the machine independent utilities in a simple`
		2577	`manner.`
		2578
		2579	`Example: "JATS ebin ls" - will provide a "real" ls on all platforms.`
		2580
		2581	`Example: "JATS ebin sh" - will start up the shell used by make.`
		2582
		2583	`=back`
		2584
		2585	`=head2 Command Shortcuts`
		2586
		2587	`The following commands are user shortcuts to the basic commands. The are basic`
		2588	`commands run in sequence.`
		2589
		2590	`=over 8`
		2591
		2592	`=item B<all [make_opts]>`
		2593
		2594	`This command is the same as running the command "build" and "make all".`
		2595	`It will build a component with a single command.`
		2596
		2597	`If "make_opts" is not present then "make all" is used.`
		2598
		2599	`If "make_opts" is present then they are passed to the "make" command. In this`
		2600	`manner is it possible to build a WIN32 component of package with a single`
		2601	`command.`
		2602
		2603	`=item B<go [make_opts]>`
		2604
		2605	`This command is similar to the "all" shortcut, but it does not "build" the`
		2606	`sandbox. It may be used where the sandbox has already been prepared.`
		2607
		2608	`=item B<debug [target]>`
		2609
		2610	`This command is the same as running "make debug package_debug". It will make and`
		2611	`package all the debug components of a sandbox.`
		2612
		2613	`If any additional arguments are provided to the B<dev> command then they will be`
		2614	`treated as make targets and the commands will be expanded to make and package`
		2615	`the specified debug versions of the names platforms. Make options cannot be`
		2616	`passed in this manner.`
		2617
		2618	`Example: "JATS dev GAK" will create and package the debug parts for the`
		2619	`GAK_MOS68K and GAK_MOSCF.`
		2620
		2621	`=item B<prod [target]>`
		2622
		2623	`This command is the same as running "make prod package_prod". It will make and`
		2624	`package all the debug components of a sandbox.`
		2625
		2626	`If any additional arguments are provided to the B<prod> command then they will be`
		2627	`treated as make targets and the commands will be expanded to make and package`
		2628	`the specified debug versions of the names platforms. Make options cannot be`
		2629	`passed in this manner.`
		2630
		2631	`Example: "JATS prod GAK" will create and package the production parts for the`
		2632	`GAK_MOS68K and GAK_MOSCF.`
		2633
		2634	`=item B<clean>`
		2635
		2636	`This is the same as "make clean".`
		2637
		2638	`=item B<clobber>`
		2639
		2640	`This is the same as "build clobber"`
		2641
		2642	`=item B<else>`
		2643
		2644	`Commands that are not known to the JATS wrapper script are passed to etool.`
		2645
		2646	`ie: "JATS xxxx" is is the same as "JATS etool xxxx".`
		2647
		2648	`=back`
		2649
		2650	`=head1 DESCRIPTION`
		2651
		2652	`JATS is a wrapper script. It provides:`
		2653
		2654	`=over 8`
		2655
		2656	`=item *`
		2657
		2658	`A controlled and satirized environment to all the build tools.`
		2659
		2660	`=item *`
		2661
		2662	`The same command interface on all supported machines: Windows, Solaris and`
		2663	`Linux.`
		2664
		2665	`=item *`
		2666
		2667	`Provides a framework for extending the build environment toolset.`
		2668
		2669	`=back`
		2670
		2671	`=head1 Installation of the startup script`
		2672
		2673	`The JATS wrapper script is invoked via a machine specific script. This is B<JATS.`
		2674	`BAT> under Windows and B<JATS.SH> under Unix platforms. The startup script`
		2675	`contains sufficient information to startup the main, and common, JATS`
		2676	`program. The script specifies the environment on the machine and should not`
		2677	`affect the target build environment. It also isolates the JATS version changes`
		2678	`from the user.`
		2679
		2680	`This script is intended to be user configured. It should be copied into the`
		2681	`users path and modified. It is intended that the script will not change from`
		2682	`version to version of JATS.`
		2683
		2684	`=head2 Environment variables`
		2685
255	dpurdie	2686	`Environmant varibales that specify a path may be set to '-', or 'none' in order`
		2687	`to force an undefined path.`
		2688
227	dpurdie	2689	`=over 8`
		2690
		2691	`=item GBE_MACHTYPE`
		2692
		2693	`This specifies the machine that the script is running on. This is fixed within`
		2694	`the startup script.`
		2695
273	dpurdie	2696	`=item GBE_HOSTMACH`
		2697
		2698	`This is a copy of GBE_MACHTYPE.`
		2699	`Unlike GBE_MACHTYPE, this copy is not modified by makefiles.`
		2700
227	dpurdie	2701	`=item GBE_PERL`
		2702
		2703	`This specifies the full path the to B<ActiveState> perl binary.`
		2704
		2705	`=item GBE_CORE`
		2706
		2707	`This specifies the path the to B<JATS> installation.`
		2708
		2709	`=item GBE_CACHE_JATS`
		2710
		2711	`When set to a non zero value will force JATS to transfer a working copy to the`
		2712	`local dpkg_archive. This will speed up the build process because the utilities`
		2713	`will be run from a local drive; not a network drive.`
		2714
		2715	`This will only operate if JATS is run from dpkg_archive.`
		2716
		2717	`=item GBE_DPKG_STORE (optional)`
		2718
		2719	`This is the global read-only archive store. It will only be used to source`
		2720	`packages after all other archive stores have been examined. The GBE_DPKG_STORE`
		2721	`is intended to provide a read-only or remote repository within a global`
		2722	`environment.`
		2723
		2724	`=item GBE_DPKG`
		2725
		2726	`This is the official archive. Some tools will publish packages directly to this`
		2727	`archive.`
		2728
		2729	`=item GBE_DPKG_CACHE (optional)`
		2730
		2731	`This the path to a local package archive cache. This is used to speed access to`
		2732	`main repository. The cache should be on the users local machine and not a network`
		2733	`drive.`
		2734
		2735	`=item GBE_DPKG_LOCAL (optional)`
		2736
		2737	`This the path to a group wide local package archive. This may be used to store`
		2738	`non-official packages that are under test or development.`
		2739
		2740	`=item GBE_DPKG_SBOX (optional)`
		2741
		2742	`This the path to a sandbox specific package archive. This may be used to store`
		2743	`non-official packages that are under test or development within the current sandbox.`
		2744
		2745	`The archive is located by searching from the current directory to the root of`
		2746	`the filesystem for a directory called 'sandbox_dpkg_archive'.`
		2747
		2748	`It is intended that a group of packages that are being developed in the same`
		2749	`sandbox will share the same sandbox_dpkg_archive.`
		2750
		2751	`Jats will ignore the version number when dealing with packages in GBE_DPKG_SBOX.`
		2752	`This is done to simplify the publishing and consuming of packages in the sandbox.`
		2753
		2754	`This should not be set by a user. It will be calculated by JATS and passed to`
245	dpurdie	2755	`JATS tools and utilities.`
227	dpurdie	2756
		2757	`=item GBE_SANDBOX (optional)`
		2758
		2759	`This the path to a sandbox base directory. It is intended that a group of`
		2760	`packages that are being developed in the same sandbox will share the same`
		2761	`sandbox_dpkg_archive.`
		2762
		2763	`This should not be set by a user. It will be calculated by JATS and passed to`
245	dpurdie	2764	`JATS tools and utilities.`
227	dpurdie	2765
		2766	`=item GBE_DPLY (optional)`
		2767
		2768	`This the path to the deployment archive.`
		2769	`This archive is NOT used when searching for packages, but it will be used when`
		2770	`publishing special deployment package. This is not the norm.`
		2771
		2772	`This variable may be set on a per-project basis.`
		2773
		2774	`=item GBE_PLATFORM (deprecated)`
		2775
		2776	`This specifies the names of platforms that will be built and made. This should`
		2777	`be empty. Use B<GBE_BUILDFILTER> to provide better control.`
		2778
		2779	`=item GBE_BUILDFILTER (desirable)`
		2780
		2781	`This is a filter string that specifies which platforms to create makefiles`
		2782	`for. This variable is used to prevent JATS from creating Solaris and Linux`
		2783	`targets on a Windows machine and visa-versa.`
		2784
		2785	`=item GBE_JATS_VERSION (optional)`
		2786
		2787	`Specifies the version of JATS that the user will use. This is the same as`
		2788	`specifying the -version=xx.xx.xx option on the command line, but because it is`
		2789	`in the environment the required version will be used by all invocations of JATS.`
		2790
		2791	`=item GBE_ABT (optional)`
		2792
		2793	`Used by the Auto Build Tool to indicate that the build is being performed by the`
		2794	`ABT. When set the build environment will be modified to suite the ABT. Some`
		2795	`operations may be relaxed.`
		2796
		2797	`=item GBE_VIEWBASE (optional)`
		2798
		2799	`Used by the 'release' utility to provide a user configurable base directory for`
		2800	`the creation of static views.`
		2801
		2802	`=item GBE_RM_LOCATION (optional)`
		2803
		2804	`Used by tools that interface to Release Manager: primarily the (ABT) Auto Build Tools.`
245	dpurdie	2805	`Specifies the location of the Release Manager Database. This is a database url`
227	dpurdie	2806	`of the form jdbc:subprotocol:subname as used by java.sql.DriverManager.getConnection()`
		2807
		2808	`Example: jdbc:oracle:thin:@auperaora03:1521:RELEASEM`
		2809
		2810	`=item GBE_RM_USERNAME (optional)`
		2811
		2812	`Used by tools that interface to Release Manager: primarily the (ABT) Auto Build Tools.`
		2813	`Specifies a USERNAME with access to the Release Manager Database.`
		2814
		2815	`=item GBE_RM_PASSWORD (optional)`
		2816
		2817	`Used by tools that interface to Release Manager: primarily the (ABT) Auto Build Tools.`
		2818	`Specifies a PASSWORD to be used in conjunction with GBE_RM_USERNAME to access`
		2819	`the Release Manager Database.`
		2820
		2821	`=item GBE_RM_URL (optional)`
		2822
		2823	`Used by tools that interface to Release Manager: primarily the (ABT) Auto Build Tools.`
		2824	`Specifies the base URL of RElease Manager`
		2825
		2826	`=item GBE_DM_LOCATION (optional)`
		2827
		2828	`Similar to GBE_RM_LOCATION, but is used to access the Deployment Manager Database.`
		2829	`If GBE_DM_LOCATION is not provided, then GBE_RM_LOCATION will be used.`
		2830
		2831	`=item GBE_DM_USERNAME (optional)`
		2832
		2833	`Similar to GBE_RM_USERNAME, but is used to access the Deployment Manager Database.`
		2834
		2835	`=item GBE_DM_PASSWORD (optional)`
		2836
		2837	`Similar to GBE_RM_PASSWORD, but is used to access the Deployment Manager Database.`
		2838
		2839	`=item GBE_DM_URL (optional)`
		2840
		2841	`Similar to GBE_DM_URL, but is used to access the Deployment Manager Database.`
		2842
297	dpurdie	2843	`=item GBE_SVN_URL (optional)`
		2844
		2845	`Specifies the URL of the Subversion repository that can be used by some JATS`
		2846	`commands. The URL should contain the protocol, the repository host and the path to`
		2847	`the root of the the repository, but not the name of the repository. ie:`
		2848
		2849	`svn://auperaws996vm21`
		2850
		2851	`=item GBE_SVN_PATH (optional)`
		2852
		2853	`If provided this will be used to locate the 'svn' utility used by the SubVersion`
		2854	`suport functions. If not provided, then the utilities assume that 'svn' is in the`
		2855	`users PATH.`
		2856
		2857	`=item GBE_SVN_USERNAME (optional)`
		2858
		2859	`Subversion repository crediantials. If provided it will be used, otherwise the`
		2860	`native svn credential mechanism will be used.`
		2861
		2862	`=item GBE_SVN_PASSWORD (optional)`
		2863
		2864	`Subversion repository crediantials. If provided it will be used, otherwise the`
		2865	`native svn credential mechanism will be used.`
		2866
275	dpurdie	2867	`=item GBE_MAKE_TYPE (internal)`
		2868
		2869	`This EnvVar is set when a Makefile is being procssed by 'make'. The value`
		2870	`indicates the type of the build. It will be either P(Production), D(debug)`
		2871	`or C(Common).`
		2872
		2873	`=item GBE_MAKE_TARGET (internal)`
		2874
		2875	`This EnvVar is set when a Makefile is being procssed by 'make'. The value`
		2876	`is set current target platform name.`
		2877
		2878	`=item GBE_MAKE_CFG (internal)`
		2879
		2880	`This EnvVar is set when a Makefile is being procssed by 'make'. The value`
285	dpurdie	2881	`is set to the path of the parsed makefile.pl data gathered when the makefile`
275	dpurdie	2882	`was created.`
		2883
		2884	`=item GBE_MAKE_CMD (internal)`
		2885
		2886	`This EnvVar is set when a Makefile is being procssed by 'make'. The value`
		2887	`is set current make command being processed.`
		2888
297	dpurdie	2889	`=item GBE_HOSTNAME`
279	dpurdie	2890
		2891	`This EnvVar is the name of the current host. It is available to be used within`
		2892	`scripts that need to stamp build files.`
		2893
227	dpurdie	2894	`=back`
		2895
		2896	`=head1 dpkg_archive`
		2897
		2898	`B<dpkg_archive> is the common package repository. This is on a shared network drive`
		2899	`and as such affects the build speed. JATS supports three mechanisms to supplement`
		2900	`dpkg_archive, as described below. The archive search order is:`
		2901
		2902	`=over`
		2903
		2904	`=item GBE_DPKG_LOCAL (User local store)`
		2905
		2906	`=item GBE_DPKG_CACHE (Machine local cache)`
		2907
		2908	`=item GBE_DPKG (Site repository)`
		2909
		2910	`=item GBE_DPKG_STORE (Global repository)`
		2911
		2912	`=back`
		2913
		2914	`=head2 local dpkg_archive`
		2915
		2916	`JATS supports a package archive that is local to a project or suite of build`
		2917	`sandboxes. This is the archive used by the B<install> command.`
		2918
		2919	`The user does not have to do anything to access this archive. The archive is`
		2920	`located by the JATS wrapper script by scanning up the directory tree for a`
		2921	`directory called "local_dpkg_archive". If it is found then it is used as the`
		2922	`preferred source for locating archives. This allows a component to be tested`
		2923	`with a "local" or "fixed" version of another package, before an official`
		2924	`release is made.`
		2925
		2926	`A local archive may be shared by members of a team by setting the environment`
		2927	`variable B<GBE_DPKG_LOCAL> to the location of a shared drive.`
		2928
		2929	`=head2 dpkg_archive cache`
		2930
		2931	`JATS supports a package caching mechanism to reduce network utilization. If`
		2932	`the user specified B<GBE_DPKG_CACHE> exists then that archive is treated as a`
		2933	`cache archive. The various JATS tools work together to maintain the cache.`
		2934
		2935	`This cache must be setup by the user.`
		2936
		2937	`=head2 dpkg_archive store`
		2938
		2939	`JATS supports a global, read-only, package distribution mechanism. If`
		2940	`the user specified B<GBE_DPKG_STORE> exists then that archive is treated as a`
		2941	`global store. The store archive will be searched after all other archives.`
		2942
		2943	`A global store may be used by members of a global team, in a situation in`
		2944	`which the store is rsync'ed from a central repository.`
		2945
		2946	`=head1 EXAMPLES`
		2947
		2948	`=over 8`
		2949
		2950	`=item JATS build`
		2951
		2952	`This will prime the sandbox ready for "make". The command will locate the`
		2953	`build.pl file and process it. This will locate all the external packages and`
		2954	`generate the required makefiles.`
		2955
		2956	`=item JATS make`
		2957
		2958	`This will run the GNU make program over the makefiles generated by the "build"`
		2959	`command. This may be executed in a subdirectory in order to limit the targets`
		2960	`that are "made".`
		2961
		2962	`B<NOTE:> Do not run "make" without using the JATS wrapper. It will not perform`
		2963	`as expected as the environment will not have been set up correctly.`
		2964
		2965	`=back`
		2966
		2967	`=cut`
		2968

Subversion Repositories DevTools

(root)/core_devl/branches/gitBuilder/TOOLS/jats.pl – Rev 309