package Torello.Java.Build;

import java.io.File;

import java.util.Arrays;
import java.util.function.Consumer;
import java.util.function.Predicate;
import java.util.stream.Stream;

import Torello.Java.FileNodeException;
import Torello.Java.Q;
import Torello.Java.StrCmpr;
import Torello.Java.UnreachableError;
import Torello.Java.Verbosity;
import Torello.Java.StringParse;    // Needed for JavaDoc {@link's}
import Torello.Java.GSUTIL;         // Needed for JavaDoc {@link's}

import Torello.Java.ReadOnly.ReadOnlyList;
import Torello.Java.ReadOnly.ReadOnlyArrayList;

import Torello.Java.Additional.Ret2;

import Torello.JavaDoc.Upgrade;

// Needed for a javadoc {@link}
import Torello.HTML.Tools.Images.UnrecognizedImageExtException;

import java.io.FileNotFoundException;
import java.io.IOException;

public class Builder
{
    // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
    // A Minor "Optimization" (Hack) - Note that this Field is Package-Visible
    // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
    //
    // This field is set by Stage-5, and then retrieved in Stage-8.  This allows the String[] Array
    // to avoid being re-computed / re-calculated twice.
    //
    // Just stores some GCS-Directories to make the "Make-Public" Command (Stage-8) run a lot
    // faster when a User has provided a sub-set / list of Packages using their Nick-Names.  
    // Essentially the "Old Way" to run Stage-8 was to call "Make-Public" on the entire GCS
    // Directory-Tree for a Project - even when only a small sub-set of files were updated.  Now,
    // when a small sub-set of files are synchronized, only those files are subjected to the 
    // GSUTIL.MP Command.  This shaves off 10 seconds on the Partial-Build's.  GSUTIL is a littl
    // slow.

    String[] stage8GCSDirs = null;




    // ********************************************************************************************
    // ********************************************************************************************
    // ********************************************************************************************
    // ********************************************************************************************
    // Fields - These Directly Copied from class Config.  Unmodified, same name
    // ********************************************************************************************
    // ********************************************************************************************
    // ********************************************************************************************
    // ********************************************************************************************




    /**
     * Used during the JAR-Build (Stage 4).
     * TO BE EXPLAINED AT A LATER DATE.
     * @see Config#HOME_DIR
     */
    public final String HOME_DIR;

    /**
     * This {@code String} contains either the absolute, or the relative, path to the on-disk
     * location of the directory where {@code javadoc} has left its output.
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>Validity-Checking:</B>
     * 
     * <BR />A Directory-Check <I>is not performed</I> by class {@code Config's}
     * {@link Config#validate() validate} method.  Often, when the {@code Builder} instance is
     * constructed, the {@code 'javadoc/'} output directory does not exist as it hasn't yet been
     * created by the Java-Doc Tool yet.
     * 
     * <BR /><BR />{@code 'javadoc'} isn't run / executed until Build-Stage 2.
     * 
     * <EMBED CLASS=defs DATA-F=LOCAL_JAVADOC_DIR>
     * <EMBED CLASS='external-html' DATA-FILE-ID=VALIDITY_NULL>
     * <EMBED CLASS='external-html' DATA-FILE-ID=DIRECT_COPY>
     * @see Config#LOCAL_JAVADOC_DIR
     */
    public final String LOCAL_JAVADOC_DIR;

    /**
     * This is a small name-{@code String} for the Project.
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>Validity-Checking:</B>
     * 
     * <BR />This field's value is checked for validity by a Regular-Expression
     * {@link Config#projectNameValidator validator} - publicly available in class {@link Config}.
     * 
     * <EMBED CLASS=defs DATA-F=PROJECT_NAME>
     * <EMBED CLASS='external-html' DATA-FILE-ID=VALIDITY_NULL>
     * <EMBED CLASS='external-html' DATA-FILE-ID=DIRECT_COPY>
     * @see Config#PROJECT_NAME
     * @see Config#projectNameValidator
     */
    public final String PROJECT_NAME;

    /**
     * The Project must have a "Version Number".  In this project -
     * <B STYLE='color: darkred;'>JavaHTML 1.8</B>, at the writing of this JavaDoc Comment the 
     * "Major Version Number" is {@code '1'}, while the "Minor Version Number" is {@code '8'}.
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>Validity-Checking:</B>
     * 
     * <BR />This number must be a positive integer, and it is checked for validity by class
     * {@code Config's} {@link Config#validate() validate} method.
     * 
     * <EMBED CLASS='external-html' DATA-F=VERSION_MAJOR_NUMBER DATA-FILE-ID=DIRECT_COPY>
     * @see #VERSION_MINOR_NUMBER
     * @see Config#VERSION_MAJOR_NUMBER
     */
    public final byte VERSION_MAJOR_NUMBER;

    /**
     * The Project-Version Minor-Number. 
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>Validity-Checking:</B>
     * 
     * <BR />This number must be a positive integer, and it is checked for validity by class
     * {@code Config's} {@link Config#validate() validate} method.
     * 
     * <EMBED CLASS='external-html' DATA-F=VERSION_MINOR_NUMBER DATA-FILE-ID=DIRECT_COPY>
     * @see #VERSION_MAJOR_NUMBER
     * @see Config#VERSION_MINOR_NUMBER
     */
    public final byte VERSION_MINOR_NUMBER;

    /**
     * This must contain the direct path from the current working directory to the {@code 'javac'}
     * binary-file.  This {@code String}-Configuration names the executable used by Build-Stage 1.
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>Validity-Checking:</B>
     * 
     * <BR />This parameter is not checked for validity, but the Java-Compiler Build-Stage Class,
     * {@link S01_JavaCompiler}, will throw exceptions if this {@code String} doesn't point to a
     * valid binary or executable file.
     * 
     * <EMBED CLASS=defs DATA-F=JAVAC_BIN>
     * <EMBED CLASS='external-html' DATA-FILE-ID=VALIDITY_NULL>
     * <EMBED CLASS='external-html' DATA-FILE-ID=DIRECT_COPY>
     * @see Config#JAVAC_BIN
     * @see S01_JavaCompiler
     */
    public final String JAVAC_BIN;

    /**
     * This must contain the direct path from the current working directory to the
     * {@code 'javadoc'} binary-file.  This {@code String}-Configuration names the executable used
     * by Build-Stage 1.
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>Validity-Checking:</B>
     * 
     * <BR />This parameter is not checked for validity, but the Javadoc Build-Stage Class,
     * {@link S02_JavaDoc}, will throw exceptions if this {@code String} doesn't point to a valid
     * binary or executable file.
     * 
     * <EMBED CLASS=defs DATA-F=JAVADOC_BIN>
     * <EMBED CLASS='external-html' DATA-FILE-ID=VALIDITY_NULL>
     * <EMBED CLASS='external-html' DATA-FILE-ID=DIRECT_COPY>
     * @see Config#JAVADOC_BIN
     * @see S02_JavaDoc
     */
    public final String JAVADOC_BIN;

    /**
     * This Configuration-Field may be used to request that the Build-Tool insert the
     * {@code 'javac'} Command-Line Switch {@code '--release XX'} to the {@code 'javac'} Command
     * Invocation.  The release switch asks that the Java-Compiler generate Java Byte-Code that is
     * that is consistent with the Byte-Code for the JDK-Release {@code 'X'}.
     * 
     * <BR /><BR />If {@code 'X'} were passed {@code '11'}, the Java-Compiler would generate Java
     * Byte-Code that is consistent with the JDK-11 LTS (Released in Year 2018).
     * 
     * <BR /><BR />This parameter is not checked for validity, but the Java-Compiler will generate 
     * error messages (instead of compiling) if the Release-Number isn't valid.  If you are using 
     * JDK-11, and pass {@code '21'} to this Configuration-Field, {@code 'javac'} will obviously
     * complain.
     * 
     * <BR /><BR />The default value for this field is {@code '-1'}.  Any negative number (or zero)
     * assigned to this field will implicitly tell the Stage 1 Builder-Class that using a
     * {@code '--release'} switch is not necessary, and should be left off when compiling
     * {@code '.java'} Files.
     * 
     * <EMBED CLASS=defs DATA-F=JAVA_RELEASE_NUM_SWITCH>
     * <EMBED CLASS='external-html' DATA-FILE-ID=DIRECT_COPY>
     * @see Config#JAVA_RELEASE_NUM_SWITCH
     * @see S01_JavaCompiler
     */
    public final byte JAVA_RELEASE_NUM_SWITCH;

    /**
     * Currently this is an unused Configuration-Field.  It is not checked for validity.
     * When this class is constructed, this field is automatically assigned to the value of the 
     * field {@link Config#JAVADOC_VER}.
     * 
     * @see Config#JAVADOC_VER
     * @see S02_JavaDoc
     */
    public final byte JAVADOC_VER;

    /**
     * Contains {@code FAVICON} Image File-Name, to be used by the Stage 3 Build-Class 
     * {@link S03_Upgrade}.  When this Configuration-Field is non-null, the Upgrade-Stage will copy
     * favicon file into the {@link #LOCAL_JAVADOC_DIR}.
     * 
     * <BR /><BR />This Configuration-Field may be null - <I>which is the default value assigned to
     * {@link Config#FAVICON}</I>.  When it is, no favicon file is copied to the root
     * {@code 'javadoc/'} directory.
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>Validity-Checking:</B>
     * 
     * <BR />This {@code String}-Field, when non-null, is checked whether or not it points to an
     * actual Image-File, that both exists and is accessible on the File-System.  Class
     * {@link Config Config's} {@link Config#validate() validate} method will throw a 
     * {@code FileNotFoundException} if this check fails.
     * 
     * <BR /><BR />If class {@link Torello.HTML.Tools.Images.IF#guessOrThrow(String) IF} is unable
     * to properly guess the Image-Type based on its File-Name, then an
     * {@link UnrecognizedImageExtException} is thrown by the validator method.
     * 
     * <EMBED CLASS=defs DATA-F=FAVICON>
     * <EMBED CLASS='external-html' DATA-FILE-ID=DIRECT_COPY>
     * @see Config#FAVICON
     * @see S03_Upgrade
     */
    public final String FAVICON;

    /**
     * This class specifies the Root Source-Code Directory containing all {@code '.java'}
     * Files, {@code '.class'} Files, and any configurations needed for the build.  The 
     * Stage 4 Builder-Class {@link S04_TarJar} invokes the OS Command {@code 'tar'} around this
     * directory to create a Project Backup-File.
     * 
     * <BR /><BR />The name given the Project Tar-Backup File will just be the {@code String}
     * provided to {@link #PROJECT_NAME}, followed by the {@link #VERSION_MAJOR_NUMBER} and 
     * {@link #VERSION_MINOR_NUMBER}.
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>Validity-Checking:</B>
     * 
     * <BR />This {@code String}-Field may not be null, or {@code NullPointerException} throws.
     * Furthermore the {@code Config} {@link Config#validate() validate} method will ensure that
     * this {@code String} points to a valid and accessible File-System Directory-Name.
     * 
     * <BR /><BR />If this isn't a valid directory, a {@code FileNotFoundException} will throw.
     * Keep in mind that {@code FileNotFoundException} is a Java Checked-Exception which inherits
     * {@code IOException}.
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>Configuration-Field Use:</B>
     * 
     * <BR />This field is very simply used in the Stage 4 Build-Class {@link S04_TarJar} as
     * follows.  The following code snippet was copied on March 4th, 2024:
     * 
     * <BR /><DIV CLASS=SNIP>{@code 
     * // Shell-Constructor Parameters used:
     * // (outputAppendable, commandStrAppendable, standardOutput, errorOutput)
     * 
     * Shell shell = new Shell(SB_TAR, new BiAppendable(SB_TAR, System.out), null, null);
     * 
     * // JavaHTML-1.x.tar.gz
     * CHECK(
     *     shell.COMMAND(
     *         "tar",
     *         new String[] { "-cvzf", builder.TAR_FILE, builder.TAR_SOURCE_DIR }
     * ));
     * }</DIV>
     * 
     * <EMBED CLASS=defs DATA-F=TAR_SOURCE_DIR>
     * <EMBED CLASS='external-html' DATA-FILE-ID=DIRECT_COPY>
     * @see Config#TAR_SOURCE_DIR
     * @see #TAR_FILE
     * @see S04_TarJar
     * @see S06_SyncTarJar
     */
    public final String TAR_SOURCE_DIR;

    /**
     * This parameter is used by all four Build-Stages that involve Google Cloud Server / Platform.
     * This parameter may, indeed, remain null and if or when it is, Build-Stages that pertain to
     * GCS Storage-Buckets will not be performed.  These stages include 5 through 8.
     * 
     * <BR /><BR />This Configuration-Field is not checked for Validity.  If it is non-null, but
     * points to / indicates a Google Storage Bucket that isn't valid or isn't writeable, any and 
     * all GCP Synchronization Stages will throw exceptions and exit.
     * 
     * <BR /><BR />By default, this field is assigned null.
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>Amazon S3 &amp; MSFT Azure Storage:</B>
     * 
     * <BR />There is currently no Build-Implementation that can capably synchronize the Build 
     * Java-Doc or Archive-File output with {@code 'Amazon S3'}.  {@code 'S3'} is simply AWS'
     * implementation of Network Based Storage, just like GCP Storage.
     * 
     * <BR /><BR />The concept is, certainly, on the "To Do" List, but will not be implemented in
     * the immediate future.
     * 
     * <EMBED CLASS=defs DATA-F=GCS_DIR_DEV>
     * <EMBED CLASS='external-html' DATA-FILE-ID=DIRECT_COPY>
     * @see Config#GCS_DIR_DEV
     * @see #GCS_DIR_RELEASE
     * @see Config#GCS_DIR_RELEASE
     * @see S05_SyncJavaDoc
     * @see S06_SyncTarJar
     * @see S07_SyncLogs
     */
    public final String GCS_DIR_DEV;

    /**
     * This Configuration Field is nearly identical in function to {@link #GCS_DIR_DEV}, but 
     * specifies a Storage-Bucket &amp; Directory Location for a "Full Release Version" of the same
     * Project's Documentation-HTML &amp; Jar-Files.
     * 
     * <BR /><BR />This Configuration-Field, by default is assigned null, and may remain null at 
     * the time that a {@code Builder}-Class instance is constructed.  When this configuration is
     * null, it is silently ignored.  If null, the Upgrade Cloud Storage-Bucket Synchronization
     * Stage for the Release-Directory isn't applied, and becomes "unavailable".
     * 
     * <BR /><BR />In this project, <B>Java-HTML</B>, the "Full-Release" Storage-Bucket &amp;
     * Web-Address URL ({@link #GCS_DIR_RELEASE}) is {@code 'javahtml.torello.directory'}.
     * 
     * <BR /><BR />The Developer Storage-Bucket Web-Address ({@link #GCS_DIR_DEV}) is
     * {@code 'developer.torello.directory/JavaHTML/Version'} (followed by the Major &amp; Minor
     * Version Release Numbers).
     * 
     * <BR /><BR />Having two separate output bucket-directories for copying the Java-Doc Output 
     * and Jar-Distribution allows for having a separate URL for daily Project Software
     * Development, and a GCS directory which is updated less frequently for released, CI/CD
     * Distribution.
     * 
     * <EMBED CLASS=defs DATA-F=GCS_DIR_RELEASE>
     * <EMBED CLASS='external-html' DATA-FILE-ID=DIRECT_COPY>
     * @see Config#GCS_DIR_RELEASE
     * @see #GCS_DIR_DEV
     * @see Config#GCS_DIR_DEV
     * @see S05_SyncJavaDoc
     * @see S06_SyncTarJar
     * @see S07_SyncLogs
     */
    public final String GCS_DIR_RELEASE;

    /**
     * When using GCP Storage-Buckets for hosting / serving Web &amp; HTTP Content, Google provides
     * an option to assign "Bucket-Level" or "Object-Level" access permissions.  When an entire
     * Storage-Bucket has been made public, there is no need to make each HTML-File that resides
     * inside the bucket public.  However, if "Object-Level" access permissions have been
     * configured, then each HTML-File also needs to be made public, or Web-Browsers will not be 
     * able to see the HTML-Files.
     * 
     * <BR /><BR />If you have opted for "Bucket-Level" permissions (everything in your bucket is
     * publicly readable), then calling {@link GSUTIL} function
     * {@link GSUTIL#MP(Iterable, String...) Make Public} will actually cause this builder to throw
     * an exception.  Therefore this boolean should be used to inform the builder whether or not
     * the javadoc HTML Files are already public, as per the GCP Storage-Bucket settings.
     * 
     * <BR /><BR />The Storage-Bucket directory to which the "Make Public" operations are precisely
     * the directories listed in {@link #GCS_DIR_DEV} and {@link #GCS_DIR_RELEASE}.  As per the
     * User's selected target-build CLI Option, Java-Doc HTML-Files are copied to only one of these
     * two bucket directories.
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>Assigning this Field:</B>
     * 
     * <BR />This is how the value for this field is computed:
     * 
     * <DIV CLASS=SNIP>{@code
     * this.RUN_MAKE_PUBLIC = this.cli.toReleaseOrDeveloper
     *     ? config.RUN_MAKE_PUBLIC_RELEASE
     *     : config.RUN_MAKE_PUBLIC_DEV;
     * }</DIV>
     * 
     * @see Config#RUN_MAKE_PUBLIC_DEV
     * @see Config#RUN_MAKE_PUBLIC_RELEASE
     * @see #GCS_DIR_DEV
     * @see #GCS_DIR_RELEASE
     */
    public final boolean RUN_MAKE_PUBLIC;

    /**
     * This Project {@code '.tar'} File that is created out of the Project Root Directory can be
     * automatically copied to a safe location in a Storage-Bucket so that Project-Files are 
     * automatically backed up every time they are compiled and documented.
     * 
     * <BR /><BR />This Configuration-Field should contain the name of a valid Google Cloud Storage
     * Bucket Directory-Name.  When this field is non-null, Build-Stage 6 ({@link S06_SyncTarJar})
     * will automatically copy the Project-Backup {@code '.tar'} File to the directory structure
     * indicated by this field.
     * 
     * <BR /><BR />Note, first, that this field may be null.  If it is null, then the Stage 6
     * Synchronization Effort to backup the Project-Files will simply be skipped.
     * 
     * <BR /><BR />Also, note that the file is actually copied to a sub-directory whose name is 
     * created using today's date - the Year, Month &amp; Day - of the running / execution of the 
     * Build Command.
     * 
     * <BR /><BR />This field <I>is not checked for validity</I>.  If a non-null but erroneous
     * Google Cloud Storage-Bucket Directory-Name is provided (or one that exists, but is not 
     * writeable) - then the Tar-Synchronization Build-Stage (Stage 6) will fail and throw an
     * exception.
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>Visibility:</B>
     * 
     * <BR />If this feature is used, it's usually a good idea to make sure that the directory 
     * provided to this field is <B STYLE='color: red;'><I>not publicly visible to
     * <CODE>'AllUsers'</CODE></I></B> - otherwise everybody will be capable of downloading the
     * entirety of your development work.
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>Full-Path Directory-Name:</B>
     * 
     * <BR />Also, as mentioned above, the backup mechanism actually copies the archive to  a
     * subdirectory of the form:
     * 
     * <BR /><BR /><SPAN CLASS=JDFileDirName>
     * gs://Some.GCP.Bucket/BACKUP_TAR_FILE_GCS_DIR/2024/03 - March/2024-03-05-JavaHTML-1.8.tar.gz
     * </SPAN>
     * 
     * <BR />Notice that only the date is included in the file-name.  The actual system-time for
     * this  file is not included!  This means that no more than one backup-file (the last file
     * created  on any given Calendar-Day) will actually remain in the directory.  A file backed up
     * at 3:00 PM will be overwritten if another backup is copied at 5:00 PM on the same day.
     * 
     * <BR /><BR />This has turned out to be extremely valuable - as it has meant that all changes
     * made over the course of a single day's work (&amp; typing) are saved - <I>while intermediate
     * modifications are clobbered / overwritten whenever another Build is executed - on the same 
     * work-day as the previously executed build</I>.
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>Configuration-Field Use:</B>
     * 
     * <BR />The Stage 6 Builder-Class {@link S06_SyncTarJar} utilizes this field as follows:
     * 
     * <BR /><DIV CLASS=SNIP>{@code
     * final String CODE_DRIVE_BACKUP_FILE = (builder.BACKUP_TAR_FILE_GCS_DIR == null)
     * 
     *     ? null 
     *     :   builder.BACKUP_TAR_FILE_GCS_DIR +
     *         StringParse.ymDateStr('/', true) + '/' +
     *         StringParse.dateStr('-') + '-' + builder.TAR_FILE;
     * 
     * // Portion of Code Block Omitted
     * 
     * // Drive backup page
     * if (CODE_DRIVE_BACKUP_FILE != null)
     * {
     *     osr = gsutil.CP(builder.TAR_FILE, CODE_DRIVE_BACKUP_FILE);
     *     Util.HALT_ON_ERROR(osr);
     *     sw.println();
     * }
     * }</DIV>
     * 
     * <BR /><BR />For a better understanding, please see:
     * 
     * <BR /><BR /><UL CLASS=JDUL>
     * <LI><B>{@link StringParse#ymDateStr(char, boolean)}</B></LI>
     * <LI><B>{@link StringParse#dateStr(char)}</B></LI>
     * <LI><B>{@link GSUTIL#CP(String, String, String[])}</B></LI>
     * <LI><B>{@link Util#HALT_ON_ERROR(OSResponse)}</B></LI>
     * </UL>
     * 
     * <EMBED CLASS=defs DATA-F=BACKUP_TAR_FILE_GCS_DIR>
     * <EMBED CLASS='external-html' DATA-FILE-ID=DIRECT_COPY>
     * @see Config#BACKUP_TAR_FILE_GCS_DIR
     * @see S06_SyncTarJar
     */
    public final String BACKUP_TAR_FILE_GCS_DIR;

    /**
     * In Java-HTML there are a few Upgrade-Stage (Stage 3) processes that need to be executed 
     * before the actual {@link Upgrade#upgrade() upgrade} can run.  All of the processes currently
     * in the {@code 'preUpgraderScript'} are on a general "To Do List" for being moved into the 
     * actual Upgrade-API.
     * 
     * <BR /><BR />This Configuration-Field may be null, and if it is, it is ignored.  The Stage 3
     * Build-Class {@link S03_Upgrade} simply runs the following code, below.  This snippet was
     * block-copied directly from {@code 'S03_Upgrade.upgrade'}.
     * 
     * <BR /><DIV CLASS=SNIP>{@code
     * builder.timers.startStage03();
     * 
     * Printing.startStep(3);
     * 
     * // This is used as a Log-File Collector
     * StringBuilder sb = new StringBuilder();
     * 
     * // Check if there is a User-Provided "Pre-Upgrade Script", if so, then run it.
     * if (builder.preUpgraderScript != null) builder.preUpgraderScript.accept(builder, sb);
     * 
     * sb.append("... Note to Console about Starting Build ...");
     * 
     * // And now start the actual Upgrade
     * Stats result = builder.upgrader.upgrade(); 
     * }</DIV>
     * 
     * <BR /><BR />Clearly, a validity check on this Configuration-Field isn't possible.
     * 
     * <EMBED CLASS=defs DATA-F=preUpgraderScript>
     * <EMBED CLASS='external-html' DATA-FILE-ID=DIRECT_COPY>
     * @see Config#preUpgraderScript
     * @see #postUpgraderScript
     * @see Config#postUpgraderScript
     * @see S03_Upgrade
     */
    public final UpgradeProcessor preUpgraderScript;

    /**
     * This functions identically to the {@link #preUpgraderScript}, but is executed immediately
     * after Class {@link S03_Upgrade} has run to completion.
     * 
     * <BR /><BR />This field may be null, and if it is it will be silently ignored.  No validity
     * checks are executed for this Configuration-Field.
     * 
     * <EMBED CLASS=defs DATA-F=postUpgraderScript>
     * <EMBED CLASS='external-html' DATA-FILE-ID=DIRECT_COPY>
     * @see Config#postUpgraderScript
     * @see #preUpgraderScript
     * @see Config#preUpgraderScript
     * @see S03_Upgrade
     */
    public final UpgradeProcessor postUpgraderScript;




    // ********************************************************************************************
    // ********************************************************************************************
    // ********************************************************************************************
    // ********************************************************************************************
    // Fields - Composite stuff & Modified Stuff
    // ********************************************************************************************
    // ********************************************************************************************
    // ********************************************************************************************
    // ********************************************************************************************




    /**
     * Setting values for this {@code String[]}-Array allows a user to provide extra or additional
     * Command-Line switches to the Java-Compiler if it is invoked.
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>Validity Checking:</B>
     * 
     * <BR />No validity checks are done for the contents of these {@code 'javac'} "Extra
     * Switches".  However, if any faulty or erroneous switch elements in the User-Provided
     * {@code String[]}-Array are provided, then the Stage 1 Build-Class {@link S01_JavaCompiler}
     * will likely through exceptions when if it is invoked.
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>Copying {@link Config#extraSwitchesJAVAC}:</B>
     * 
     * <BR />The following is how this field is copied from the contents of class {@code Config}
     * (a User-Provided class):
     * 
     * <BR /><DIV CLASS=SNIP>{@code
     * // Config.extraSwitchesJAVAC     ==> String[]
     * // Builder.extraSwitchesJAVAC    ==> ReadOnlyList<String>
     * 
     * this.extraSwitchesJAVAC =
     *     ((config.extraSwitchesJAVAC == null) || (config.extraSwitchesJAVAC.length == 0))
     *          ? null
     *          : ReadOnlyList.of(config.extraSwitchesJAVAC);
     * }</DIV>
     * 
     * @see Config#extraSwitchesJAVAC
     * @see ReadOnlyList
     * @see S01_JavaCompiler
     */
    public final ReadOnlyList<String> extraSwitchesJAVAC;

    /**
     * Setting values for this {@code String[]}-Array allows a user to provide extra or additional
     * Command-Line switches to the {@code 'javadoc'} Tool if it is invoked.
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>Validity Checking:</B>
     * 
     * <BR />No validity checks are done for the contents of these {@code 'javadoc'} "Extra
     * Switches".  However, if any faulty or erroneous switch elements in the User-Provided
     * {@code String[]}-Array are provided, then the Stage 2 Build-Class {@link S02_JavaDoc}
     * will likely through exceptions when if it is invoked.
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>Copying {@link Config#extraSwitchesJAVADOC}:</B>
     * 
     * <BR />The following is how this field is copied from contents of User-Provided class
     * {@link Config}:
     * 
     * <BR /><DIV CLASS=SNIP>{@code
     * // Config.extraSwitchesJAVADOC     ==> String[]
     * // Builder.extraSwitchesJAVADOC    ==> ReadOnlyList<String>
     * 
     * this.extraSwitchesJAVADOC =
     *     ((config.extraSwitchesJAVADOC == null) || (config.extraSwitchesJAVADOC.length == 0))
     *          ? null
     *          : ReadOnlyList.of(config.extraSwitchesJAVADOC);
     * }</DIV>
     * 
     * @see Config#extraSwitchesJAVADOC
     * @see ReadOnlyList
     * @see S02_JavaDoc
     */
    public final ReadOnlyList<String> extraSwitchesJAVADOC;

    /**
     * This is the {@link Upgrade} instance that was passed to the class {@link Config} Field
     * {@link Config#upgrader}.
     * 
     * @see Config#upgrader
     * @see S03_Upgrade
     */
    public final Upgrade upgrader;

    /**
     * The Computed File-Name for the Project-Wide {@code '.tar'} Backup-File.
     * 
     * <BR /><BR />This Configuration-Field is computed using other fields, and cannot be
     * "supplied" by the User.  Below is the code used to generate this File-Name / Field.
     * 
     * <BR /><DIV CLASS=SNIP>{@code
     * // For Java-HTML, this would be, (for example) - "1.8"
     * final String NUM = VERSION_MAJOR_NUMBER + "." + VERSION_MINOR_NUMBER;
     * 
     * // For Project "JavaHTML", this would be "JavaHTML-1.8.tar.gz"
     * this.TAR_FILE = this.PROJECT_NAME + "-" + NUM + ".tar.gz";
     * }</DIV>
     * 
     * @see #PROJECT_NAME
     * @see #VERSION_MAJOR_NUMBER
     * @see #VERSION_MINOR_NUMBER
     * @see S04_TarJar
     * @see S06_SyncTarJar
     */
    public final String TAR_FILE;

    /**
     * The Computed File-Name for the Project's Distribution {@code '.jar'} File.
     * 
     * <BR /><BR />This Configuration-Field is computed using other fields, and cannot be
     * "supplied" by the User.  Below is the code used to generate this File-Name / Field.
     * 
     * <BR /><DIV CLASS=SNIP>{@code
     * // For Java-HTML, this would be, (for example) - "1.8"
     * final String NUM = VERSION_MAJOR_NUMBER + "." + VERSION_MINOR_NUMBER;
     * 
     * // For Project "JavaHTML", this would be "JavaHTML-1.8.jar"
     * this.JAR_FILE = this.PROJECT_NAME + "-" + NUM + ".jar";
     * }</DIV>
     * 
     * @see #PROJECT_NAME
     * @see #VERSION_MAJOR_NUMBER
     * @see #VERSION_MINOR_NUMBER
     * @see S04_TarJar
     * @see S06_SyncTarJar
     */
    public final String JAR_FILE;

    /**
     * The Computed File-Name for the Project's Javadoc Documentation {@code '.tar.gz'} File.
     * 
     * <BR /><BR />This Configuration-Field is computed using other fields, and cannot be
     * "supplied" by the User.  Below is the code used to generate this File-Name / Field.
     * 
     * <BR /><DIV CLASS=SNIP>{@code
     * // For Java-HTML, this would be, (for example) - "1.8"
     * final String NUM = VERSION_MAJOR_NUMBER + "." + VERSION_MINOR_NUMBER;
     * 
     * // For Project "JavaHTML", this would be "JavaHTML-javadoc-1.8.tar"
     * this.JAVADOC_TAR_FILE = this.PROJECT_NAME + "-javadoc-" + NUM + ".tar";
     * }</DIV>
     * 
     * @see #PROJECT_NAME
     * @see #VERSION_MAJOR_NUMBER
     * @see #VERSION_MINOR_NUMBER
     * @see S04_TarJar
     * @see S06_SyncTarJar
     */
    public final String JAVADOC_TAR_FILE;

    /**
     * This is an auto-generated field, that utilizes the {@link Config}-Class Field
     * {@link Config#JAR_FILE_MOVE_DIR}.  When this field is non-null, the {@code '.jar'} File that
     * is generated by the Stage 4 Build-Class {@link S04_TarJar} is copied to the directory
     * specified.
     * 
     * <BR /><DIV CLASS=SNIP>{@code
     * this.JAR_FILE_NAME = (config.JAR_FILE_MOVE_DIR != null)
     *     ? (config.JAR_FILE_MOVE_DIR + this.PROJECT_NAME + ".jar")
     *     : null;
     * }</DIV>
     * 
     * @see Config#JAR_FILE_MOVE_DIR
     * @see S04_TarJar
     * @see S06_SyncTarJar
     */
    public final String JAR_FILE_NAME;

    /**
     * This is the classpath that is passed to the Stage 1 Build-Class {@link S01_JavaCompiler}.
     * 
     * <BR /><BR />This field's value is computed and assigned by a package-only visible
     * initializer method in class {@link Config}.
     * 
     * @see S01_JavaCompiler
     */
    public final String CLASS_PATH_STR;

    /**
     * The helps the Build-Logic decide whether to use the Java-Compiler Switch {@code -Xlint:all}.
     * The default behavior is that the Java-Compiler will be invoked using that switch for all
     * {@code '.java'} Files that are being compiled.
     * 
     * <BR /><BR />The default behavior assigned in Configuration-Class {@link Config} can easily
     * be changed by reassigning the necessary value to field {@link Config#USE_XLINT_SWITCH}. When
     * this field is reassiged a new {@code boolean}, any invocation of the {@code Builder}'s 
     * Java-Compiler Stage will check whether to use the {@code -Xlint:all}, based on this field's
     * value.
     * 
     * <BR /><BR />On top of {@code Config.USE_XLINT_SWITCH}, a user has the option of passing the
     * Command-Line Wwitch {@code -TXL} when invoking the Java-Compiler Build-Stage which, in
     * effect, toggles whatever value was set by the original {@link Config#USE_XLINT_SWITCH}
     * setting.  (This may be done when invoking {@code 'Builder'} from the CLI).
     * 
     * <BR /><BR />This may be more clearly seen in the code used to assign this field's value:
     * 
     * <BR /><DIV CLASS=SNIP>{@code
     * this.USE_XLINT_SWITCH = this.cli.OVERRIDE_TOGGLE_USE_XLINT_SWITCH
     *     ? (! config.USE_XLINT_SWITCH)
     *     : config.USE_XLINT_SWITCH;
     * }</DIV>
     * 
     * @see Config#USE_XLINT_SWITCH
     * @see CLI#OVERRIDE_TOGGLE_USE_XLINT_SWITCH
     * @see S01_JavaCompiler
     */
    public final boolean USE_XLINT_SWITCH;

    /**
     * The helps the Build-Logic decide whether to use the Java-Compiler Switch
     * {@code -Xdiags:verbose}.  The default behavior is that the Java-Compiler will be invoked
     * using that switch for all {@code '.java'} Files that are being compiled.
     * 
     * <BR /><BR />The default behavior assigned in Configuration-Class {@link Config} can easily
     * be changed by reassigning the necessary value to field {@link Config#USE_XDIAGS_SWITCH}.
     * When this field is reassiged a new {@code boolean}, any invocation of the {@code Builder}'s
     * Java-Compiler Stage will check whether to use the {@code -Xdiags:verbose}, based on this
     * field's value.
     * 
     * <BR /><BR />On top of {@code Config.USE_XDIAGS_SWITCH}, a user has the option of passing the
     * Command-Line Wwitch {@code -TXL} when invoking the Java-Compiler Build-Stage which, in
     * effect, toggles whatever value was set by the original {@link Config#USE_XDIAGS_SWITCH}
     * setting.  (This may be done when invoking {@code 'Builder'} from the CLI).
     * 
     * <BR /><BR />This may be more clearly seen in the code used to assign this field's value:
     * 
     * <BR /><DIV CLASS=SNIP>{@code
     * this.USE_XDIAGS_SWITCH = this.cli.OVERRIDE_TOGGLE_USE_XDIAGS_SWITCH
     *     ? (! config.USE_XDIAGS_SWITCH)
     *     : config.USE_XDIAGS_SWITCH;
     * }</DIV>
     * 
     * @see Config#USE_XDIAGS_SWITCH
     * @see CLI#OVERRIDE_TOGGLE_USE_XDIAGS_SWITCH
     * @see S01_JavaCompiler
     */
    public final boolean USE_XDIAGS_SWITCH;

    /**
     * Requests that the {@code --frames} switch, which by default is passed to the Stage 2
     * Build-Class {@link S02_JavaDoc} be omitted.
     * 
     * <BR /><BR />By default, this Configuration-Field is assigned {@code FALSE}, which means that
     * the {@code --frames} switch, <I>by default, s passed to the {@code javadoc} stage</I>.
     * 
     * <BR /><BR />Make sure to remember that after the JDK 11 Release, the {@code --frames} switch
     * was fully deprecated and removed from the tool.  In such cases, make sure to assign
     * {@code TRUE} to the field {@link Config#NO_JAVADOC_FRAMES_SWITCH}, or the Stage 2
     * Build-Class will throw an exception.
     * 
     * <EMBED CLASS=defs DATA-F=NO_JAVADOC_FRAMES_SWITCH>
     * <EMBED CLASS='external-html' DATA-FILE-ID=DIRECT_COPY>
     * @see Config#NO_JAVADOC_FRAMES_SWITCH
     * @see S02_JavaDoc
     */
    public final boolean NO_JAVADOC_FRAMES_SWITCH;

    /**
     * This Configuration is largely copied, directly, from the User-Provided {@link Config} class
     * instance received.  This Configuration-Field simply contains the list of packages that 
     * comprise the Java Project being built, compiled, documented &amp; sychronized.
     * 
     * <BR /><BR />Class {@link Config}-Field {@link Config#packageList} contains a User-Provided
     * list of packages, as instances of {@link BuildPackage}.
     * 
     * <BR /><BR />There isn't any validation done on the input array, other than that it must be 
     * non-null, and contain at least Java Package.
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>Quick Build Note:</B>
     * 
     * <BR />The option to eliminate certain packages when doing a build is provided by class 
     * {@link BuildPackage}.  The {@code BuildPackage} Static-Flag
     * {@link BuildPackage#QUICKER_BUILD_SKIP} lets a user convey that, during development time, 
     * the compilation and documentation stages can skip certain packages altogether.
     * 
     * <BR /><BR />Note that if class {@link CLI} has specified its {@link CLI#QUICKER_BUILD}
     * field, then and only then, are packages designed as {@link BuildPackage#skipIfQuickerBuild}
     * actually removed.
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>Under Development Note:</B>
     * 
     * <BR />The option to eliminate certain packages because they are still under development is 
     * an option also provided by the class {@link BuildPackage} (via the
     * {@link BuildPackage#EARLY_DEVELOPMENT EARLY_DEVELOPMENT} flag, and by the
     * {@link BuildPackage#earlyDevelopment earlyDevelopment} field),
     * <B STYLE='color: red;'><I>and by the class</I></B> {@link CLI} (via the 
     * {@link CLI#INCLUDE_EARLY_DEV_PACKAGES INCLUDE_EARLY_DEV_PACKAGES} field).
     * 
     * <BR /><BR ><B CLASS=JDDescLabel>Assigning this Field:</B>
     * 
     * <BR />This field's reference/value is assigned in this class constructor as in the code
     * included below.  The value is generated by the class / method:
     * {@link Packages#packagesInThisBuild(CLI, BuildPackage[]) packagesInThisBuild}.
     * 
     * <BR /><DIV CLASS=SNIP>{@code
     * // This eliminates any packages that are irrelevant, as per the specifications
     * // by the User at the Command-Line Interface 'argv' parameter.
     * // 
     * // The included packages are in:    "Ret2.a"
     * // The eliminated packages are in:  "Ret2.b"
     * 
     * Ret2<ReadOnlyList<BuildPackage>, ReadOnlyList<BuildPackage>> ret2 =
     *     Packages.packagesInThisBuild(this.cli, config.packageList);
     * 
     * // This is used in S01_JavaCompiler, S02_JavaDoc and S04_TarJar
     * this.packageList = ret2.a;
     * }</DIV>
     * 
     * @see Packages#packagesInThisBuild(CLI, BuildPackage[])
     * @see Config#packageList
     * @see CLI#QUICKER_BUILD
     * @see BuildPackage#QUICKER_BUILD_SKIP
     * @see BuildPackage#skipIfQuickerBuild
     */
    public final ReadOnlyList<BuildPackage> packageList;

    /**
     * Additional &amp; Miscellaneous Files that must be incorporated into the Project's
     * {@code '.jar'} File.
     * 
     * <BR /><BR />This Configuration-Field's value is computed by using package-private 
     * initializer code, as follows:
     * 
     * <BR /><DIV CLASS=SNIP>{@code
     * this.jarIncludes = (config.jarIncludes != null)
     *     ? config.jarIncludes.getAllDesriptors()
     *     : null;
     * }</DIV>
     * 
     * @see Config#jarIncludes
     * @see S04_TarJar
     */
    public final ReadOnlyList<JarInclude.Descriptor> jarIncludes;

    /**
     * This is generated by parsing the Command-Line Arguments passed to this class constructor.
     * 
     * Class {@link CLI}'s constructor accepts an {@code 'argv'} parameter, which should have been
     * obtained from an invocation of any {@code public static void main} method.
     */
    public final CLI cli;


    // These are Package-Private, the user cannot use these.
    // They are useless outside of this pacage anyway.

    final Logs      logs;
    final Timers    timers;

    // The new thing - this will be fixed and updated - slowly.
    // For now, the "default" thing is being instantiated.

    final AbstractCloudSync<?> cloudSync = AbstractGSUTILCloudSync.getImpl();



    // ********************************************************************************************
    // ********************************************************************************************
    // ********************************************************************************************
    // ********************************************************************************************
    // Constructor
    // ********************************************************************************************
    // ********************************************************************************************
    // ********************************************************************************************
    // ********************************************************************************************




    /**
     * Run this class constructor, and afterwards the {@link #build()} method can be invoked.
     * 
     * @param config Any instance of class {@code Config}
     * 
     * @param argv Any {@code String[]}-Array instance that has been obtained from any invocation
     * of a {@code public static void main} method.
     * 
     * @throws FileNotFoundException Throw by the class {@link Config}
     * {@link Config#validate() validate} method if there are problems with the user's provided
     * configurations.
     */
    public Builder(Config config, String... argv) throws FileNotFoundException, IOException
    {
        config.validate();


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // Fields that are directly copied from "Config"
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

        this.HOME_DIR                   = config.HOME_DIR;
        this.LOCAL_JAVADOC_DIR          = config.LOCAL_JAVADOC_DIR;
        this.PROJECT_NAME               = config.PROJECT_NAME;
        this.VERSION_MAJOR_NUMBER       = config.VERSION_MAJOR_NUMBER;
        this.VERSION_MINOR_NUMBER       = config.VERSION_MINOR_NUMBER;
        this.JAVAC_BIN                  = config.JAVAC_BIN;
        this.JAVADOC_BIN                = config.JAVADOC_BIN;
        this.JAVA_RELEASE_NUM_SWITCH    = config.JAVA_RELEASE_NUM_SWITCH;
        this.JAVADOC_VER                = config.JAVADOC_VER;
        this.FAVICON                    = config.FAVICON;
        this.TAR_SOURCE_DIR             = config.TAR_SOURCE_DIR;
        this.GCS_DIR_DEV                = config.GCS_DIR_DEV;
        this.GCS_DIR_RELEASE            = config.GCS_DIR_RELEASE;
        this.BACKUP_TAR_FILE_GCS_DIR    = config.BACKUP_TAR_FILE_GCS_DIR;
        this.NO_JAVADOC_FRAMES_SWITCH   = config.NO_JAVADOC_FRAMES_SWITCH;
        this.preUpgraderScript          = config.preUpgraderScript;
        this.postUpgraderScript         = config.postUpgraderScript;


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // Package-Private, Internally-Used Fields (not useful to user)
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

        // These two are declared "Package-Private" - everything else is public
        this.logs   = new Logs(config.LOG_DIR);
        this.timers = new Timers();


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // Slightly Modified, but Copied Fields
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

        this.extraSwitchesJAVAC =
            ((config.extraSwitchesJAVAC == null) || (config.extraSwitchesJAVAC.length == 0))
                ? null
                : ReadOnlyList.of(config.extraSwitchesJAVAC);

        this.extraSwitchesJAVADOC =
            ((config.extraSwitchesJAVADOC == null) || (config.extraSwitchesJAVADOC.length == 0))
                ? null
                : ReadOnlyList.of(config.extraSwitchesJAVADOC);

        this.jarIncludes = (config.jarIncludes != null)
            ? config.jarIncludes.getAllDesriptors()
            : null;


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // Composite / Composed Config-Fields
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

        final String NUM = VERSION_MAJOR_NUMBER + "." + VERSION_MINOR_NUMBER;

        this.TAR_FILE           = this.PROJECT_NAME + "-" + NUM + ".tar.gz";
        this.JAR_FILE           = this.PROJECT_NAME + "-" + NUM + ".jar";
        this.JAVADOC_TAR_FILE   = this.PROJECT_NAME + "-javadoc-" + NUM + ".tar";

        this.JAR_FILE_NAME = (config.JAR_FILE_MOVE_DIR != null)
            ? (config.JAR_FILE_MOVE_DIR + this.PROJECT_NAME + ".jar")
            : null;


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // REQUIRES THE COMMAND-LINE / CLI (this.cli) INPUT-DATA TO ASSIGN THESE FIELDS
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

        // This is public, and it is needed by the next two fields, so it's constructed before them
        this.cli = new CLI(config.GCS_DIR_DEV, config.GCS_DIR_RELEASE, config.packageList, argv);

        this.RUN_MAKE_PUBLIC = this.cli.toReleaseOrDeveloper
            ? config.RUN_MAKE_PUBLIC_RELEASE
            : config.RUN_MAKE_PUBLIC_DEV;

        this.CLASS_PATH_STR = config.classPathStr(this.cli.INCLUDE_JAR_IN_CP, this.JAR_FILE_NAME);

        this.USE_XLINT_SWITCH = this.cli.OVERRIDE_TOGGLE_USE_XLINT_SWITCH
            ? (! config.USE_XLINT_SWITCH)
            : config.USE_XLINT_SWITCH;

        this.USE_XDIAGS_SWITCH = this.cli.OVERRIDE_TOGGLE_USE_XDIAGS_SWITCH
            ? (! config.USE_XDIAGS_SWITCH)
            : config.USE_XDIAGS_SWITCH;


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // Class Upgrade Itself
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

        final Upgrade tempUpgrader =
            config.upgrader.setLogFile(config.LOG_DIR + Logs.S03_UPGRADER);

        this.upgrader = (this.cli.userSpecifiedPackages == null)
            ? tempUpgrader 
            : tempUpgrader.setPackageList(this.cli.userSpecifiedPackages);


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // Build Package List
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // 
        // This eliminates any packages that are irrelevant, as per the specifications
        // by the User at the Command-Line Interface 'argv' parameter.
        // 
        // The included packages are in:    "Ret2.a"
        // The eliminated packages are in:  "Ret2.b"

        Ret2<ReadOnlyList<BuildPackage>, ReadOnlyList<BuildPackage>> ret2 =
            Packages.packagesInThisBuild(this.cli, config.packageList);

        // This is used in S01_JavaCompiler, S02_JavaDoc and S04_TarJar
        this.packageList = ret2.a;

        // The JavaDoc Upgrader will use this "Eliminated List" in the class
        // GenerateOverviewFrame

        Torello.JavaDoc.EXPORT_PORTAL.Upgrade$registerEliminatedBuildPackages
            (this.upgrader, ret2.b);

        // I thought this wasn't allowed?!?!  Oh well...  I'm not going to argue about this at the
        // moment.  Since 'this' isn't fully initialized yet, why is it letting me pass this as a
        // parameter??  was there ever a rule against passing 'this' inside of a constructor?

        this.cloudSync.registerBuilder(this);
    }




    // ********************************************************************************************
    // ********************************************************************************************
    // ********************************************************************************************
    // ********************************************************************************************
    // Build "Main" Method
    // ********************************************************************************************
    // ********************************************************************************************
    // ********************************************************************************************
    // ********************************************************************************************




    /**
     * Runs the build.  Uses all configurations that were passed to this class constructor.
     * @throws IOException There are many, many wonderful opportunities for this exception to throw
     */
    public void build() throws IOException
    {
        // Timers.start[0] is how the "Total Timer Count" is computed.  So 'touch it', and things
        // can start counting right from here.

        this.timers.touch();

        // Pushing it out to JavaHTML shouldn't happen all the time, only once in a while
        if (this.cli.toReleaseOrDeveloper) if (! Q.YN("Are You Sure?")) System.exit(0);

        switch (cli.MENU_CHOICE)
        {
            // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
            // COMPILER STEP
            // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

            case "1"    :   S01_JavaCompiler.compile(this);
                            break;


            // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
            // MAIN STEPS
            // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

            case "2"    :   S02_JavaDoc.javaDoc(this);      break;
            case "3"    :   S03_Upgrade.upgrade(this);      break;
            case "4"    :   S04_TarJar.compress(this);      break;
            case "5"    :   S05_SyncJavaDoc.sync(this);     break;
            case "6"    :   S06_SyncTarJar.sync(this);      break;
            case "7"    :   S07_SyncLogs.sync(this);        break;
            case "8"    :   S08_SetMaxAge.set(this);        break;


            // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
            // COMPOSITE STEPS - Complete Build's  (composed from the 8 steps above)
            // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

            // [Standard Build] - Steps #2 - #7
            case "cb1"  :   S02_JavaDoc.javaDoc(this);
                            S03_Upgrade.upgrade(this);
                            S04_TarJar.compress(this);
                            S05_SyncJavaDoc.sync(this);
                            S06_SyncTarJar.sync(this);
                            S07_SyncLogs.sync(this);
                            break;

            // [Standard Build, Set Max-Age] - Steps #2 - #8
            case "cb2" :    S02_JavaDoc.javaDoc(this);
                            S03_Upgrade.upgrade(this);
                            S04_TarJar.compress(this);
                            S05_SyncJavaDoc.sync(this);
                            S06_SyncTarJar.sync(this);
                            S07_SyncLogs.sync(this);
                            S08_SetMaxAge.set(this);
                            break;

            // [Standard Build] - Steps #2 - #7
            case "cb3" :    S02_JavaDoc.javaDoc(this);
                            S03_Upgrade.upgrade(this);
                            S04_TarJar.compress(this);
                            S05_SyncJavaDoc.sync(this);
                            S06_SyncTarJar.sync(this);
                            S07_SyncLogs.sync(this);
                            break;


            // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
            // COMPOSITE STEPS - Debug-Build's  (composed from the 8 steps above)
            // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

            // [Build Only, No GCS Copying] - Steps #2, #3
            case "pb1"  :   S02_JavaDoc.javaDoc(this);
                            S03_Upgrade.upgrade(this);
                            break;

            // [Build, Copy Docs Only, Set Max-Age] - Steps #2, #3, #5, #8
            case "pb2"  :   S02_JavaDoc.javaDoc(this);
                            S03_Upgrade.upgrade(this);
                            S05_SyncJavaDoc.syncPart(this);
                            S08_SetMaxAge.set(this);
                            break;


            // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
            // Run one of the special cases
            // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

            // Links-Checker Steps #2, #3
            case "lc"   :   if (1 == 1) throw new Torello.Java.ToDoException();
                            S02_JavaDoc.javaDoc(this);
                            // S03_Upgrade.upgradeWLC(U, ES, OS);
                            break;


            // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
            // DEFAULT - PRINT HELP AND EXIT
            // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

            default :   throw new UnreachableError();
        }

        this.timers.PRINT_TIMES();
    }
}