WebSVN – DevTools – Diff – /core_devl/branches/gitBuilder/TOOLS/jats_sandbox.pl

 use ToolsetFiles;
 use Pod::Usage;                             # required for help support
 use Getopt::Long qw(:config require_order); # Stop on non-option
 use Digest;
+use JSON;
 my $VERSION = "1.0.0";                      # Update this
 my $SCANDEPTH = 3;                          # Almost a constant
+#
 my $opt_allSandbox;                         # Extend scope to entire sandbox
 my $opt_processUsedBy;                      # Process dependants(consumers) not dependents(children)
 my $opt_keepgoing;                          # Ignore errors
 my $opt_reScan;                             # Rescan for buildfiles
 my $opt_multiBuilders = 0;                  # How handle packages with multiple bulders: 0:Error, 1:Report, 2:Ignore
+my $opt_onlyLevel = 0;                      # Single level processing
+#
 #   Globals - Provided by the JATS environment
+#
 my $USER            = $ENV{'USER'};
 my $GBE_DPKG_CACHE      = $ENV{'GBE_DPKG_CACHE'};
 my $GBE_DPKG            = $ENV{'GBE_DPKG'};
 my $GBE_DPLY            = $ENV{'GBE_DPLY'};
 my $GBE_DPKG_STORE      = $ENV{'GBE_DPKG_STORE'};
 my $GBE_DPKG_REPLICA    = $ENV{'GBE_DPKG_REPLICA'};
+my $GBE_DPKG_ESCROW     = $ENV{'GBE_DPKG_ESCROW'};
+#
 #   Globals
+#
 my @stopped = ();                               # Stopped entries
-my @build_order = ();                           # Build Ordered list of entries
-my %extern_deps;                                # Hash of external dependencies
 my %packages;                                   # Hash of packages
+my @build_order = ();                           # Build Ordered list of packages
+my %extern_deps;                                # Hash of external dependencies
 my $currentPkgTag;                              # Tag of the current package - if any
 my $scanDepth;                                  # Depth for build file scan
 my $maxDname = 0;                               # Pretty display
+#
 #   Known files
+#
+$GBE_DPKG_SBOX = '' unless defined $GBE_DPKG_SBOX;
 my $cacheFile  = $GBE_DPKG_SBOX . '/location_cache';
 my $depthFile  = $GBE_DPKG_SBOX . '/scanDepth';
 my $filterFile = $GBE_DPKG_SBOX . '/buildfilter';
 #-------------------------------------------------------------------------------
 info(@ARGV)                             if ( $cmd =~ m/^info$/ );
 populate(@ARGV)                         if ( $cmd =~ m/^populate$/  );
 buildfilter(@ARGV)                      if ( $cmd =~ m/^buildfilter$/  );
 skipBuild(0, @ARGV)                     if ( $cmd =~ m/^skip$/  );
 skipBuild(1, @ARGV)                     if ( $cmd =~ m/^unskip$/  );
+errorBuild(0, @ARGV)                    if ( $cmd =~ m/^error$/  );
+errorBuild(1, @ARGV)                    if ( $cmd =~ m/^unerror$/  );
 fingerPrintPkg(@ARGV)                   if ( $cmd =~ m/^finger/i );
 testLinks(@ARGV)                        if ( $cmd =~ m/^testlinks/i );
 setScanDepth(@ARGV)                     if ( $cmd =~ m/^scandepth/i );
+writeBuildData(@ARGV)                   if ( $cmd =~ m/^writeBuildData/i );
 Error ("Unknown sandbox command: $cmd");
 exit 1;
+    }
     exit 0;
+}
 #-------------------------------------------------------------------------------
+# Function        : errorBuild
+#
+# Description     : Mark the package as having a build error
+#                   This inofrmation will be used in determining build info
+#
+# Inputs          : Mode -: Error, 1:UnError
+#                   User commaand line
+#
+# Returns         : Nothing
+#
+sub errorBuild
+{
+    my ($mode, @cmd_opts ) = @_;
+    my $machine;
+    Getopt::Long::Configure('pass_through');
+    getOptionsFromArray ( \@cmd_opts,
+                        'machine!' => \$machine,
+                        ) || Error ("Invalid command line" );
+    SubCommandHelp( $opt_help, "Error Build") if ($opt_help );
+    Error ("Command must be executed from within a Sandbox") unless ( $GBE_SANDBOX );
+    #
+    #   Determine Sandbox information
+    #   Populate global variables
+    #
+    calc_sandbox_info(1);
+    #
+    #   Display only
+    #
+    unless( @cmd_opts)
+    {
+        foreach my $pkg (keys %packages)
+        {
+            my $fe = $packages{$pkg};
+            next unless $fe->{buildError};
+            my $errMsg = ' (Build Error)';
+            if ($fe->{buildCurrent}) {
+                $errMsg .= ' (Current Package)';
+            }
+            Message( ' Name: ' . $fe->{dname} . $errMsg );
+        }
+        exit 0;
+    }
+    foreach ( @cmd_opts )
+    {
+        #
+        #   Locate the package
+        #
+        my $pe;
+        if ($currentPkgTag && ($_ eq '.'))
+        {
+            if (exists $packages{$currentPkgTag})
+            {
+                $pe = $packages{$currentPkgTag};
+            }
+        }
+        unless ($pe) {
+            foreach my $pkg (keys %packages)
+            {
+                my $entry = $packages{$pkg};
+                if ($entry->{dname} eq $_ || $entry->{fname} eq $_ )
+                {
+                    $pe = $entry;
+                    last;
+                }
+            }
+        }
+        unless ($pe) {
+            Warning("No package found matching: $_");
+            next;
+        }
+        my $errorFile;
+        if ($machine) {
+            $errorFile = catdir($GBE_SANDBOX, 'sandbox_dpkg_archive', '_error.' . $GBE_MACHTYPE . '.' . $pe->{dname});
+        } else {
+            $errorFile = catdir($GBE_SANDBOX, 'sandbox_dpkg_archive', '_error.'. $pe->{dname});
+        }
+        Verbose("ErrorFile: $errorFile");
+        if ($mode)
+        {
+            unlink $errorFile;
+        }
+        else
+        {
+            TouchFile($errorFile);
+        }
+    }
+    exit 0;
+}
+#-------------------------------------------------------------------------------
 # Function        : info
+#
 # Description     : Display Sandbox information
+#
 # Inputs          : Command line args
     if ($showOrder)
+    {
         Message ("Build Order");
         foreach my $pname ( @stopped ) {
-            Message( "    Level:" . "--"  . " [---] Name: " . $pname . ' (Stopped)');
+            Message( "    Level:" . "--"  . " [----] Name: " . $pname . ' (Stopped)');
+        }
         foreach my $fe ( @build_order )
+        {
             displayHeader($fe, { indent => '    ', testFingerPrint =>  $showFingerPrint, showSimplePath => $showPath });
+    #
     #   Process all packages in the sandbox
+    #
     foreach my $linkFile ( glob "$GBE_DPKG_SBOX/*/*.lnk")
+    {
-        my $pkg = TagFileRead($linkFile);
+        my $pkg = getPackageLink( TagFileRead($linkFile) );
-        $pkg =~ s~\\~/~g;
-        if ($pkg =~ s~^GBE_SANDBOX/~$GBE_SANDBOX/~)
-        {
-                # If the target sandbox is in the 'deploymode' then the package
-                # will not be in the expected location. It will be in a 'build/deploy'
-                # subdir. Remove the pkg/name dir to get to the root of the package
-                my @dirs = File::Spec->splitdir( $pkg );
-                splice(@dirs, -2);
-                my $deployBox = catdir(@dirs, 'build', 'deploy');
-                $pkg = $deployBox if ( -d $deployBox);
-        }
         unless ( -d $pkg )
+        {
             if ($opt_delete)
+            {
                 Message ("Delete: $linkFile");
     exit (0);
+}
 #-------------------------------------------------------------------------------
+# Function        : getPackageLink
+#
+# Description     : Read a package link file and process the data to generate
+#                   the link to the package
+#
+# Inputs          : $linkFile   - File that contains the link
+#
+# Returns         : The resolved link
+#
+sub getPackageLink
+{
+    my ($linkFile) = @_;
+    my $pkg = TagFileRead($linkFile);
+    $pkg =~ s~\\~/~g;
+    if ($pkg =~ s~^GBE_SANDBOX/~$GBE_SANDBOX/~)
+    {
+            # If the target sandbox is in the 'deploymode' then the package
+            # will not be in the expected location. It will be in a 'build/deploy'
+            # subdir. Remove the pkg/name dir to get to the root of the package
+            my @dirs = File::Spec->splitdir( $pkg );
+            splice(@dirs, -2);
+            my $deployBox = catdir(@dirs, 'build', 'deploy');
+            $pkg = $deployBox if ( -d $deployBox);
+    }
+    return $pkg;
+}
+#-------------------------------------------------------------------------------
 # Function        : setScanDepth
+#
 # Description     : Set the depth of the build file scan usd in this sandbox
+#
 # Inputs          : Command line arguments
     #   Look in each package archive directory
+    #
     foreach my $dpkg ( $GBE_DPKG_SBOX,
                        $GBE_DPKG_LOCAL,
                        $GBE_DPKG_CACHE,
+                       $GBE_DPKG_ESCROW,
+                       '--NotEscrow',
                        $GBE_DPKG_REPLICA,
                        $GBE_DPKG,
                        $GBE_DPLY,
                        $GBE_DPKG_STORE )
+    {
         next unless ( $dpkg );
-        if ( -d "$dpkg/$name/$ver" )
+        if ( $dpkg eq '--NotEscrow' )
+        {
+            last if ($GBE_DPKG_ESCROW);
-            return 1;
+            next;
+        }
+    }
    return 0;
+}
 #                   Skip the make process if a package with a matching signature
 #                   can be found. ie: We have a pre-built version
+#
 # Inputs          : $fe     - Package Entry
+#
+# Returns         : Two items
-# Returns         : True - Prebuilt package found
+#                   Found       - True - Prebuilt package found
-#                   False - Prebuild package not found
+#                               - False - Prebuild package not found
+#                   Signature   - Package Signature
+#                                 Undef if not found
+#
 sub locatePreBuiltPackage
+{
     my ($fe) = @_;
+    #
     #   Get the package signature
-    #   This is held in the packages interface directory
+    #
-    my $ifaceDir = getpkgInterface($fe);
+    my $pkgSig = getPackageSignature($fe);
-    return 0 unless $ifaceDir;
-    my $sigFile = catdir($ifaceDir, 'Package.sig');
-    return 0 unless -f $sigFile;
+    return (0, undef) unless $pkgSig;
-    my $pkgSig = TagFileRead($sigFile);
+    #
     #   Look in each package archive directory
+    #
     foreach my $dpkg ( $GBE_DPKG_SBOX,
+    {
         my $pkgDir = catdir( $dpkg, $fe->{mname}, $pkgSig);
         if (-d $pkgDir )
+        {
             Debug("Prebuilt Package found: $pkgSig");
-            return 1;
+            return (1, $pkgSig);
+        }
+    }
-    return 0;
+    return (0, $pkgSig);
+}
+#-------------------------------------------------------------------------------
+# Function        : getPackageSignature
+#
+# Description     : Determine if we have calculated the package signature
+#
+# Inputs          : $fe     - Package Entry
+#
+# Returns         : Package signature
+#                   undef if not found
+#
+sub getPackageSignature
+{
+    my ($fe) = @_;
+    #
+    #   Get the package signature
+    #   This is held in the packages interface directory
+    #
+    my $ifaceDir = getpkgInterface($fe);
+    return 0 unless $ifaceDir;
+    my $sigFile = catdir($ifaceDir, 'Package.sig');
+    return 0 unless -f $sigFile;
+    return TagFileRead($sigFile);
+}
 #-------------------------------------------------------------------------------
 # Function        : getpkgInterface
+#
 #                   Operation will be modified by
 #                       $opt_toPackage
 #                       $opt_fromPackage
 #                       @opt_justPackage
 #                       @opt_ignorePackage
+#                       $opt_onlyLevel
+#
 # Inputs          : quiet       undef - noisy
 #                               1 - quiet
+#
 # Returns         : Will exit if not in a sandbox
                 Warning("Package marked for skip: $fe->{dname}, $fe->{dir}") unless $quiet;
                 $scan_add = 0;
                 $fe->{buildSkip} = 1;
+            }
+            #
+            #   Test for a build error marker
+            #
+            my $errorFile = catdir($GBE_SANDBOX, 'sandbox_dpkg_archive', '_error.'. $fe->{dname});
+            my $errorMachFile = catdir($GBE_SANDBOX, 'sandbox_dpkg_archive', '_error.' . $GBE_MACHTYPE . '.' . $fe->{dname});
+            if ( -f $errorFile || -f $errorMachFile )
+            {
+                Warning("Package marked as error: $fe->{dname}, $fe->{dir}") unless $quiet;
+                $fe->{buildError} = 1;
+            }
+            #
+            #   Select one level
+            #
+            if ($opt_onlyLevel && $opt_onlyLevel != $level) {
+                $scan_add = 0;
+            }
             $fe->{level} = $level;
             $fe->{buildActive} = $scan_add;
             $packages{$build} = $fe;
             push (@build_order, $fe);
             delete $depends{$build};
             push @{$packages{$itag}{usedBy}}, $fe->{tag};
+        }
+    }
+    #
+    #   Now have a full dependency list AND full usage list
+    #   Locate packages that have a buildError and mark the consumers
+    #   as have a dependency on an package in error
+    #
+    foreach my $fe ( @build_order )
+    {
+        if ($fe->{buildError} && exists($fe->{'usedBy'}))
+        {
+            foreach my $entry (@{$fe->{'usedBy'}}) {
+                push @{$packages{$entry}{buildExclude}}, $fe->{tag};
+            }
+        }
+    }
+    #
     #   If the CWD is within a package then limit the build to that package and
     #   its dependents, unless user specifies entire sandbox.
+    #
     if ($currentPkgTag && ! $opt_allSandbox )
+    {
 #   DebugDumpData ("Order", \@build_order);
 #   DebugDumpData("External Depends", \%extern_deps );
+}
 #-------------------------------------------------------------------------------
+# Function        : writeBuildData
+#
+# Description     :
+#
+# Inputs          : Command line arguments
+#
+# Returns         :
+#
+sub writeBuildData
+{
+    my (@cmd_opts ) = @_;
+    my $opt_outfile;
+    Getopt::Long::Configure('pass_through');
+    getOptionsFromArray ( \@cmd_opts,
+                           'outfile=s'  => \$opt_outfile,
+                          ) || Error ("Invalid command line" );
+    SubCommandHelp( $opt_help, 'Write Build Data') if ($opt_help  );
+    #
+    #   Calculate sandbox info
+    #   All data written will be based on this information
+    #
+    calc_sandbox_info(1);
+    calc_signature_info();
+    #
+    #   Generate build data
+    #   Consists of a few sections
+    #       BuildPlan   - Package names to be built, in order
+    #                     In practice only the first can be built
+    #                     the others can be used as an indication of builds to be performed
+    #
+    #
+    my %BuildData;
+    my @BuildPlan = ();
+    my @BuildEntry;
+    foreach my $fe ( @build_order ) {
+        next if $fe->{buildError};
+        next if $fe->{buildExclude};
+        next if $fe->{buildSkip};
+        next unless $fe->{buildActive};
+        next if $fe->{si} eq 1;
+        push @BuildPlan, $fe->{fname};
+        push @BuildEntry, $fe;
+    }
+    push @{$BuildData{BuildPlan}}, @BuildPlan;
+    #
+    #   Add information on the first item
+    #   This is the package that will be built so we need more information
+    #
+    my $BuildPkg = $BuildEntry[0];
+    my $pkgData;
+    if ($BuildPkg)
+    {
+        $pkgData->{fname} = $BuildPkg->{fname};
+        $pkgData->{dname} = $BuildPkg->{dname};
+        $pkgData->{dir} = $BuildPkg->{dir};
+        $pkgData->{name} = $BuildPkg->{name};
+        $pkgData->{version} = $BuildPkg->{version};
+        $pkgData->{prj} = $BuildPkg->{prj};
+        $pkgData->{signature} = $BuildPkg->{signature};
+    }
+    $BuildData{BuildPkgData} = $pkgData;
+    $BuildData{BuildPkg} = $BuildPkg->{fname};
+#DebugDumpData("data", $BuildPkg);
+    print( to_json( \%BuildData, { ascii => 1, pretty => 1 }) . "\n");
+#    DebugDumpData("BuildData",\%BuildData);
+    #
+    #   All done
+    #
+    exit(0);
+}
+#-------------------------------------------------------------------------------
+# Function        : calc_signature_info
+#
+# Description     : Calculate signature information for all packages in the sandbox
+#                   Used to create build system information
+#
+# Inputs          : Nothing
+#
+# Returns         : Updates global data structures
+#                   The %packages item {si} will be set to one of:
+#                       1 - Have a prebuild package
+#                       2 - Have generated a signature, but do not have a prebuilt package
+#                       3 - Error generating the signature
+#                       4 - Excluded - Dependent package has no signature
+#                       5 - Excluded - Packages skipped or not active
+#
+sub calc_signature_info
+{
+    foreach my $fe ( @build_order )
+    {
+        next if (exists $fe->{si});
+        if ( !$fe->{buildActive} || $fe->{buildSkip} ) {
+            $fe->{si} = 5;
+            next;
+        }
+        #
+        #   If this package has a signature file then we don't need to re-create it
+        #
+        my $result = 0;
+        my ($preBuilt, $haveSignature) = locatePreBuiltPackage($fe);
+        unless ($haveSignature) {
+            my $dir = $fe->{dir};
+            $result = JatsCmd( "-cd=$dir", 'build', 'signature');
+            }
+        unless ($result) {
+            #
+            #   Signature generated OK
+            #
+            ($preBuilt, $haveSignature) = locatePreBuiltPackage($fe);
+            if ($preBuilt) {
+                $fe->{si} = 1;
+                $fe->{signature} = $haveSignature;
+            } elsif ($haveSignature) {
+                $fe->{si} = 2;
+                $fe->{signature} = $haveSignature;
+            } else {
+                $result = 1;
+            }
+        }
+        #
+        #   Error creating the signature
+        #   Mark this package and all those that depend on it
+        #
+        if ($result) {
+            $fe->{si} = 3;
+            if ( exists($fe->{'usedBy'}))
+            {
+                foreach my $entry (@{$fe->{'usedBy'}}) {
+                    my $pe = $packages{$entry};
+                    $pe->{si} = 4;
+                }
+            }
+        }
+    }
+}
+#-------------------------------------------------------------------------------
 # Function        : calc_rootFingerPrint
+#
 # Description     : Calculate a finger print of all the directories in the
 #                   sandbox root.
+#
         my $active = displayHeader($fe, { showPath => 1 });
         if ($active) {
+            #
             #   Determine build success tag file
-            #   If the tag file exists, then see if any files in the files in the package source are more
+            #   If the tag file exists, then see if any files in the package source are more
             #   recent than the tag file
+            #
             my $mustBuild = 1;
             my $sigMatch = 0;
             my $tagFile = getPkgFingerPrintFile($fe);
         'entireSandBox!'    => \$opt_allSandbox,
         'users!'            => \$opt_processUsedBy,
         'keepgoing!'        => \$opt_keepgoing,
         'rescan!'           => \$opt_reScan,
         'multiBuilders:s'   => $parseMulti,
+        'onlylevel:i'       => \$opt_onlyLevel,
         );
+    #
     #   Merge in the user options
+    #
 #                       showPath        => Bool
 #                       showSimplePath  => Bool
 #                       testFingerPrint => Bool
+#
 # Returns         : True if this entry is to be fully process
 #                   False if its being skipped
+#
+#                   The entry may be have a buildError or a buildExclude
+#                   and still be active
+#
 sub displayHeader
+{
     my $fe = shift @_;
     if ($fe->{buildActive} || $fe->{buildSkip})
 #-------------------------------------------------------------------------------
 # Function        : addBuildInfo
+#
 # Description     : Add some build info status
 #                   It will have a .sig file if its been sucessfully built
+#
+#                   StatusFlags
+#                   Position 1: S - Build Skipped, s - Build Suppressed
+#                   Position 2: Blank - Not processed  , - = NoBuild, B - Built * - Current package
+#                   Position 3: P - Prebuilt, L - Local, M - Both local and prebuilt
+#                   Position 4: G - Good Fingerprint, b - Bad Fingerprint
+#
 # Inputs          : $fe     - Package info
+#
-# Returns         : True - sig file present
+# Returns         : StatusFlags
+#                   StatusText
+#
 sub addBuildInfo
+{
     my ($fe, $args) = @_;
     my $txt = '';
-    my $statusB = ' ';
-    my $statusF = ' ';
     my $statusS = ' ';
+    my $statusB = ' ';
     my $statusP = ' ';
+    my $statusF = ' ';
     unless ($fe->{buildActive}) {
         $txt .= ($fe->{buildSkip}) ? ' (Build Skipped)' : ' (Build Suppressed)';
         $statusS = ($fe->{buildSkip}) ? 'S' : 's';
+    }
+    if ($fe->{buildError} || $fe->{buildExclude} ) {
+        $txt .= ($fe->{buildError})   ? ' (Build Error)' : '';
+        $txt .= ($fe->{buildExclude}) ? ' (Build Excluded)' : '';
+        $statusS = ($fe->{buildError}) ? 'E' : 'e';
+    }
     if ($fe->{buildCurrent})
+    {
         $statusB = '*';
         $txt .= ' (Current Package)';
+    }
-    my $sigFile = getPkgFingerPrintFile($fe);
+    my $fpFile = getPkgFingerPrintFile($fe);
-    if (-f $sigFile)
+    if (-f $fpFile)
+    {
-        my $nobFile = $sigFile;
+        my $nobFile = $fpFile;
         $nobFile =~ s~ffp$~nob~;
         if (-f $nobFile) {
             $txt .= ' [NoBuild]';
             $statusB = '-';
         } else {
             $txt .= ' [Built]';
             $statusB = 'B';
+        }
+    }
-        if ($args->{testFingerPrint})
+    if ($args->{testFingerPrint})
+    {
+        if ( TagFileMatch($fpFile, genPkgFingerPrint($fe, 'Test')) )
+        {
-            if ( TagFileMatch($sigFile, genPkgFingerPrint($fe, 'Test')) )
-            {
-                $txt .= ' [GoodFinger]';
+            $txt .= ' [GoodFinger]';
-                $statusF = 'G';
+            $statusF = 'G';
-            } else {
+        } else {
-                $txt .= ' [BadFinger]';
+            $txt .= ' [BadFinger]';
-                $statusF = 'b';
+            $statusF = 'b';
-            }
+        }
+    }
-    my $preBuilt = locatePreBuiltPackage($fe);
+    my ($preBuilt, $haveSignature) = locatePreBuiltPackage($fe);
+    if ($haveSignature) {
+        $txt .= ' [SigCalc]';
+        $statusP = 's';
+    }
     if ($preBuilt) {
         $txt .= ' [PreBuilt]';
         $statusP = 'P';
     }
+    my $plink = catdir( $GBE_DPKG_SBOX, $fe->{name}, 'sandbox.' . $fe->{prj} . '.lnk' );
+    my $linkTarget = getPackageLink ($plink);
+    Verbose ("Sandbox link: $plink -> $linkTarget");
+    if (-d $linkTarget) {
+        $txt .= ' [Local]';
+        if ($preBuilt) {
+            $statusP = 'M';
+        } else {
+            $statusP = 'L';
+        }
+    }
     return "$statusS$statusB$statusP$statusF", $txt ;
+}
 #-------------------------------------------------------------------------------
 # Function        : opts_add2List
+#
     -help[=n]                  - Display help with specified detail
     -help -help                - Detailed help message
     -man                       - Full documentation
  Options for recursion control:
+    -onlyLevel=number          - Limit building to one level
     -toPackage=name            - Stop building after package
     -fromPackage=name          - Start building from package
     -justPackage=name[,name]   - Build named packages
     -ignorePackage=name[,name] - Do not build named packages
     -entireSandbox             - Process the entire sandbox
     populate            - Populate the sandbox with packages
     delete              - Delete the sandbox
     info [[-v]-v]       - Sandbox information. -v: Be more verbose
     buildfilter         - Modify and display sandbox buildfilter
     [un]skip            - Mark a package to be skipped during the build
+    [un]error           - Mark a package as having build errors
     fingerprint         - Various fingerprint operations
     testlinks           - Test / Delete broken package symlinks
     scandepth           - Set/Display the build file scan depth
     cmd                 - Do commands in all sandbox components
     all                 - Do 'build', if required, then a make in all components
     build               - Force 'build and make' in all sandbox components
     make                - Do 'make' in all sandbox components
     clean               - Do 'make clean' in all sandbox components
     clobber             - Do 'build clobber' is all sandbox components
     cache               - Cache external dependent packages
+    writeBuildData      - Write out build data
  Use the command
     jats sandbox 'command' -h
  for command specific help
 =item B<-man>
 Prints the manual page and exits. This is the same a -help=3
+=item B<-onlyLevel=number>
+This option is available in all commands that process multiple packages.
+Package processing will be limited to the specified level.
+This can be used to perform a multi-machine build. Level-1 builds are performed
+on all machines and the results merged into the common package store, then Level-2 builds
+are performed on all machines.
+Level-1 packages have no dependencies.
+Level-2 packages only have dependancies on Level-1 packages
+Level-N packages only have dependancies on packages below Level N-1
 =item B<-toPackage=name>
 This option is available in all commands that process multiple packages.
 Package processing will stop at the named package.
 Remaining lines are joined together to form a buildfilter
 =back
+=for comment ==================================================================
 =head1 Create Sandbox
 =head2 NAME
 Create Sandbox
 The create command simply places a known directory in the current directory.
 This directory is used by the sandboxing process. It may be manually deleted, or
 deleted with the 'delete' command.
+=for comment ==================================================================
 =head1 Populate Sandbox
 =head2 NAME
 Populate a Sandbox
 jats sandbox populate [command options] [packageName packageVersion]
  Common Options:
     -help[=n], -man            - Command specific help, [n=1,2,3]
+    -onlyLevel=number          - Limit building to one level
     -toPackage=name            - Stop building after package
     -fromPackage=name          - Start building from package
     -justPackage=name[,name]   - Build named packages
     -ignorePackage=name[,name] - Do not build named packages
     -entireSandbox             - Process the entire sandbox
 packages that are required to build the packages in the sandbox. It will not
 examine the dependents of these packages.
 =back
+=for comment ==================================================================
 =head1 Delete Sandbox
 =head2 NAME
 Delete a sandbox
 be executed anywhere within the sandbox.
 Once the sandbox has been deleted, the user must remove the components within the
 sandbox.
+=for comment ==================================================================
 =head1 Sandbox Information
 =head2 NAME
 Display Sandbox Information
 jats sandbox info [command options]
  Common Options:
     -help[=n], -man            - Command specific help, [n=1,2,3]
+    -onlyLevel=number          - Limit building to one level
     -toPackage=name            - Stop building after package
     -fromPackage=name          - Start building from package
     -justPackage=name[,name]   - Build named packages
     -ignorePackage=name[,name] - Do not build named packages
     -entireSandbox             - Process the entire sandbox
 This should be considered a debug option. Undocumented internal information will
 be displayed.
 =back
+=for comment ==================================================================
 =head1 Buildfilter
 =head2 NAME
 Display and Modify Sandbox buildfilter
     jats sandbox buildfilter COBRA +PPC_603E
  or jats sandbox buildfilter COBRA PPC_603E
 will set the buildfilter to be COBRA and PPC_603E
+=for comment ==================================================================
 =head1 Skip Build
 =head2 NAME
 Mark a package to be skipped during the build
     jats sandbox skip package1
 will mark package1 to be skipped during the following builds.
+=for comment ==================================================================
+=head1 Error Build
+=head2 NAME
+Mark a package as having a build error
+=head2 SYNOPSIS
+jats sandbox [un]error [command options] [PackageName]+
+ Command Options
+    -help[=n]               - Command specific help, [n=1,2,3]
+    -man                    - Same as -help=3
+    -[no]machine            - Skip on on this type of machine
+=head2 ARGUMENTS
+Arguments to the 'error' command are the names of packages to be marked.
+If no packages are named then the command will display all packages that are marked as errored.
+If the named package is '.', then the current package will be marked.
+=head2 OPTIONS
+The 'error' command takes the following options:
+=over 8
+=item -[no]machine
+This option will flag that the package will be skipped only on this type of build machine.
+=back
+=head2 DESCRIPTION
+The 'error' command markes the named packages to as having build errors. These packages, and packages that
+they consume them will be excluded from any build consideration.
+=head2 EXAMPLES
+The command
+    jats sandbox error package1
+will mark package1 as having a build error.
+=for comment ==================================================================
 =head1 Sandbox Finger Print
 =head2 NAME
 Various fingerprint operations
     jats sandbox fingerprint -generate
 will regenerate the fingerprint of the current package. Useful after trivial edits to
 enable the sandbox builder to bypass the package and not to rebuild it and all of its dependents.
+=for comment ==================================================================
 =head1 Command all
 =head2 NAME
 Build packages in the sandbox
 jats sandbox all [command options] [arguments]
  Common Options:
     -help[=n], -man            - Command specific help, [n=1,2,3]
+    -onlyLevel=number          - Limit building to one level
     -toPackage=name            - Stop building after package
     -fromPackage=name          - Start building from package
     -justPackage=name[,name]   - Build named packages
     -ignorePackage=name[,name] - Do not build named packages
     -entireSandbox             - Process the entire sandbox
 Resume a failed build.
 =back
+=for comment ==================================================================
 =head1 Command build
 =head2 NAME
 Build packages in the sandbox
 jats sandbox build [command options] [arguments]
  Common Options:
     -help[=n], -man            - Command specific help, [n=1,2,3]
+    -onlyLevel=number          - Limit building to one level
     -toPackage=name            - Stop building after package
     -fromPackage=name          - Start building from package
     -justPackage=name[,name]   - Build named packages
     -ignorePackage=name[,name] - Do not build named packages
     -entireSandbox             - Process the entire sandbox
 Any arguments are passed to the 'make' phase of the process.
 In practice, the 'sandbox all' command is quicker.
+=for comment ==================================================================
 =head1 Clean
 =head2 NAME
 Clean all sandbox components
 jats sandbox clean|clobber [command options]
  Common Options:
     -help[=n], -man            - Command specific help, [n=1,2,3]
+    -onlyLevel=number          - Limit building to one level
     -toPackage=name            - Stop building after package
     -fromPackage=name          - Start building from package
     -justPackage=name[,name]   - Build named packages
     -ignorePackage=name[,name] - Do not build named packages
     -entireSandbox             - Process the entire sandbox
 sandbox.
 The 'clobber' command will perform a 'jats clobber' in all components in the
 sandbox.
+=for comment ==================================================================
 =head1 make
 =head2 NAME
 Make packages in the sandbox
 jats sandbox make [command options] [arguments]
  Common Options:
     -help[=n], -man            - Command specific help, [n=1,2,3]
+    -onlyLevel=number          - Limit building to one level
     -toPackage=name            - Stop building after package
     -fromPackage=name          - Start building from package
     -justPackage=name[,name]   - Build named packages
     -ignorePackage=name[,name] - Do not build named packages
     -entireSandbox             - Process the entire sandbox
 The 'make' command will perform a 'make' operation in each of the packages
 within the sandbox, in the correct build order.
 Any arguments are passed to the 'make'.
+=for comment ==================================================================
 =head1 cmd
 =head2 NAME
 Process each package with a specified command.
 jats sandbox cmd [command options] [arguments]
  Common Options:
     -help[=n], -man            - Command specific help, [n=1,2,3]
+    -onlyLevel=number          - Limit building to one level
     -toPackage=name            - Stop building after package
     -fromPackage=name          - Start building from package
     -justPackage=name[,name]   - Build named packages
     -ignorePackage=name[,name] - Do not build named packages
     -entireSandbox             - Process the entire sandbox
 external to the sandbox, although all version information in the build.pl
 files will be updated.
     jats sandbox cmd upddep -rtagid=12345
+=for comment ==================================================================
 =head1 Cache
 =head2 NAME
 Cache dependent packages
 This command allows the simple creation of a small development environment that
 is not tied to the larger Development Environment. It may then be used in a
 disconnected mode to perform development.
+=for comment ==================================================================
 =head1 Sandbox Test Links
 =head2 NAME
 Test and delete sandbox link files
     jats sandbox testlinks
 will test the symbolic links in the sandbox metadata.
+=for comment ==================================================================
 =head1 Sandbox Scan Depth
 =head2 NAME
 Set and Display the build file scanner depth
     jats sandbox scandepth 5
 will set future build file scan to a maximum of 5 directories below the root of the sandbox.
+=for comment ==================================================================
+=head1 Write Build Data
+=head2 NAME
+Write out build system data
+=head2 SYNOPSIS
+jats sandbox writeBuildData [options]
+ Command Options
+    -help[=n]               - Command specific help, [n=1,2,3]
+    -man                    - Same as -help=3
+    -outfile=path           - Specify the location of the output file
+=head2 ARGUMENTS
+This command does not take any arguments
+=head2 OPTIONS
+The 'writeBuildData' command takes the following options:
+=over 8
+=item -outfile=path
+This option will control the location of the generated file. The path includes the name of the output file.
+The directory in which the file is to be created must exist. The file itself will be deleted and
+recreated. Ideally it should not be present at the beginning of the command.
+=back
+=head2 DESCRIPTION
+The writeBuildData command is used by the automated build system to extract information from
+the sandbox. Data is written to a JSON file.
+=head2 EXAMPLES
+The command
+    jats sandbox writeBuildData -outpath=data.json
+will write a json formatted file that contains data for the build system.
 =cut

Subversion Repositories DevTools

(root)/core_devl/branches/gitBuilder/TOOLS/jats_sandbox.pl – Rev 7312 → 7319