package Torello.Java.Build;

import static Torello.Java.C.BGREEN;
import static Torello.Java.C.RESET;

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

import Torello.Java.FileNodeException;
import Torello.Java.FileRW;
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.Java.Additional.ByRef;

import Torello.JavaDoc.Upgrade;

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

import java.io.FileNotFoundException;
import java.io.IOException;
import java.io.File;
import java.util.Objects;

/**
 * This class contains all configurations that are needed to run a build.  This class contains no
 * publicly exposed methods.  Rather this is strictly a constant "Record Class" that is extremely
 * similar to the JDK 21+ LTS Records.  There are a few of non-public Package-Private fields inside
 * this class.  All fields which ar adorned with the {@code public}-Modifier are also declared as
 * {code 'final'}.
 * 
 * <BR /><BR /><H2 CLASS=JDBanner>
 * Internally-Used Class: The exposed API here is not needed to the End-User.
 * </H2>
 * 
 * <I CLASS=JDBanner>This class is generated, internally, as a Configuration-Class to be passed
 * to the 8 Build-Stages which are executed by this Build-Tool.  The contents of this class have
 * been thoroughly documented and explained, <SPAN STYLE='color: red;'>solely for the purpose of
 * explaining, exactly, the steps this Tool is taking during a Build!</SPAN>
 * 
 * <BR /><BR />This class is not declared Package-Private in order to facilitate providing a more 
 * detailed explanation of what this Build-Tool entails, and not because it is important to the
 * End-User when running a build.
 * </I>
 * 
 * <BR /><B CLASS=JDDescLabel>Generating an Instance:</B>
 * 
 * <BR />An instance of this class may be generated by making a call to the class {@link Config}
 * method {@link Config#createBuilder(String[])}.
 * 
 * <BR /><BR />The Data-Contents of this class are created based on data from the following
 * sources:
 * 
 * <BR /><BR /><UL CLASS=JDUL>
 * 
 * <LI> <B>{@link Config} Instance</B>.  Performing a Build with this Tool requires that the user
 *      provide an instance of class {@link Config}, which should contain all of the needed 
 *      Configurations to compile, document, archive and synchronize the generated archive files
 *      and {@code '.html'}-Files to some Cloud-Storage System.
 *      <BR /><BR /></LI>
 * 
 * <LI> <B>{@code String[]} Instance</B>.  This {@code BuilderRecord} also requires the actual
 *      Command-Line Switches that the "User's End User" has provided at the Command-Line.  This
 *      is, actually, just the Java-Provided {@code String[]}-Array that has been passed at the
 *      Command-Line Terminal-Shell Window to the User's {@code public static void main} method.
 *      </LI>
 * 
 * </UL>
 * 
 * <BR /><BR /><B CLASS=JDDescLabel>Checking this Record's Contents anyway:</B>
 * 
 * <BR />Though there should be no need to actually monitor the values assigned to the
 * {@code public} fields in this class, most of them have been declared {@code public}.  This is
 * made possible, because they are also {@code 'final'} and cannot be changed.  Retrieving the
 * instance of this class that is ultimately used by the {@link RunBuild#run(BuilderRecord)}
 * method is relatively easy.
 * 
 * <BR /><BR />Here are the simple steps needed to actually perform a Build, using this Tool,
 * <B><I STYLE='color: red;'>once the appropriate settings have been assigned to an instance of
 * class {@link Config}!</I></B>.
 * 
 * <DIV CLASS=EXAMPLE>{@code
 * Config config = new Config();
 * 
 * // Perform as many assignments to the Configuration-Fields as is necessary!
 * // Below are just a few lines that are used to build the Java-HTML JAR.
 * 
 * config.LOCAL_JAVADOC_DIR        = "javadoc/";
 * config.PROJECT_NAME             = "JavaHTML";
 * config.VERSION_MAJOR_NUMBER     = 1;
 * config.VERSION_MINOR_NUMBER     = 8;
 * config.JAVA_RELEASE_NUM_SWITCH  = 11;
 * 
 * // NOTE: 'argv' is obtained from the method's header, which should be as follows:
 * // ==>   public static void main(String[] argv)
 * 
 * BuilderRecord rec = config.createBuilder(argv);
 * 
 * // HERE: You may review the settings that have been applied using the Command-Line
 * //       Input retrieved from "The User's User" by simply inspecting the fields present
 * /        in the BuilderRecord instance that was returned from "Config.createBuilder"
 * 
 * RunBuild.run(rec);
 * }</DIV>
 * 
 * @see CLI
 * @see Config
 * @see Config#createBuilder(String[])
 * @see RunBuild
 * @see RunBuild#run(BuilderRecord)
 */
public class BuilderRecord
{
    public static final String BUILDER_RECORD_LOG_FILENAME = "Builder-Record.log.sb";


    // ********************************************************************************************
    // ********************************************************************************************
    // ********************************************************************************************
    // ********************************************************************************************
    // Fields - Package-Private
    // ********************************************************************************************
    // ********************************************************************************************
    // ********************************************************************************************
    // ********************************************************************************************




    // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
    // Package-Private, the user cannot use these - They are useless outside of this package
    // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
    // 
    // These are assigned inside this class' construtor.  They serve no purpose to the end user,
    // and furthermore, they contain stateful-non-constant information, and therefore cannot be
    // exposed to the public API.

    final Logs      logs;
    final Timers    timers;


    // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
    // 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 - User-Visible / Public-Fields
    // ********************************************************************************************
    // ********************************************************************************************
    // ********************************************************************************************
    // ********************************************************************************************




    /**
     * 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;

    /**
     * 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.aor.OVERRIDE_TOGGLE_USE_XLINT_SWITCH
     *     ? (! config.USE_XLINT_SWITCH)
     *     : config.USE_XLINT_SWITCH;
     * }</DIV>
     * 
     * @see Config#USE_XLINT_SWITCH
     * @see AuxiliaryOptRecord#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.aor.OVERRIDE_TOGGLE_USE_XDIAGS_SWITCH
     *     ? (! config.USE_XDIAGS_SWITCH)
     *     : config.USE_XDIAGS_SWITCH;
     * }</DIV>
     * 
     * @see Config#USE_XDIAGS_SWITCH
     * @see AuxiliaryOptRecord#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 AuxiliaryOptRecord#INCLUDE_EARLY_DEV_PACKAGES_SWITCH
     * INCLUDE_EARLY_DEV_PACKAGES_SWITCH} 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;

    /**
     * Multiple Cloud-Synchronization Options may be presented within the User-Provided class
     * {@link Config} instance.  This instance is to be populated, at configuration time, by 
     * simply invoking that class' {@link Config#addCloudSync(CloudSync)} method.
     * 
     * <BR /><BR />Once a {@code Config} instance is creaed, it is likely next to be used to parse
     * "The User's User" Command-Line Terminal-Shell Menu-Input.  Specificaly, the logic that
     * processes the CLI Switches executes, and it is at that point that one of the (possibly
     * multiple) Cloud Storage-Buckets or Storage-Systems are selected.
     * 
     * <BR /><BR />This field should contain a reference to the {@link CloudSync} instance that
     * was chosen at the Command-Line.
     */
    public final CloudSync cloudSync;



    // ********************************************************************************************
    // ********************************************************************************************
    // ********************************************************************************************
    // ********************************************************************************************
    // Package-Private 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.
     */
    BuilderRecord(Config config, String... argv) throws FileNotFoundException, IOException
    {
        Objects.requireNonNull(config);
        config.validate();


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // Initialize the BuilderRecord Log
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

        final StringBuilder dataRecLogSB = new StringBuilder();

        dataRecLogSB.append(
            Printing.DATA_REC_LOG_LINES +
            "String[] argv:\n" + 
            Printing.DATA_REC_LOG_LINES + '\n' +
            BGREEN + String.join(", ", argv) + RESET + "\n\n" +
            
            Printing.DATA_REC_LOG_LINES +
            "Config:\n" + 
            Printing.DATA_REC_LOG_LINES + '\n' +
            config.toString() + "\n\n"
        );


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // 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.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 a "Pass By Reference", so that the Constructor can also return a value.  The
        // value (reference, actually) returned "into" the ByRef is the CloudSync insstance that is
        // associated with the Command-Line Option that the user selected at the Command Line.

        @SuppressWarnings("rawtypes")
        ByRef<CloudSync> selectedCloudSync = new ByRef<>(null);

        // This is public, and it is needed by the next two fields, so it's constructed before them
        this.cli = new CLI(
            config.cloudSyncListBuilder.build(),
            new ReadOnlyArrayList<>(config.packageList),
            argv,
            selectedCloudSync,
            dataRecLogSB
        );


        // This is also recently added, but it is very simple.  The above "pass by reference" 
        // actually retrieves / extracts the selected "CloudSync" from the Constructor.

        this.cloudSync = selectedCloudSync.f;

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

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

        this.USE_XDIAGS_SWITCH = this.cli.aor.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);

        /*
        System.out.println(
            "this.cli.sor.userSpecifiedPackages: " +
            this.cli.sor.userSpecifiedPackages
        );
        */

        this.upgrader = (this.cli.sor.userSpecifiedPackages == null)
            ? tempUpgrader 
            : tempUpgrader.setPackageList(this.cli.sor.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.  If you want to see the
        // heuristic for what is in the included-list and what is in the eliminated-list, please
        // review the notes inside of class 'Packages'.
        // 
        // It is not completely trivial because of the 'Quick-Build' and the 'Under-development'
        // BuildPackage Flags.
        // 
        // 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);


        // NOTE: this.cloudSync is null when, for example, the user passes "-1" at the CLI.  Since
        //       the "-1" command-switch doesn't involve any synchronization at all, it doesn't
        //       even bother to figure out which CloudSync instance the user selected.  In fact the
        //       user didn't select any of them in such cases  (Build Options #1 through #4).
        // 
        // Note that every one of the exported fields inside of abstract-class "CloudSync" are
        // declared public & final - except the Package-Private Builder-Instance reference. 

        if (this.cloudSync != null) this.cloudSync.brec = this;


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // Data-Records Output-Log
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

        dataRecLogSB.append(
            Printing.DATA_REC_LOG_LINES +
            "CLI:\n" + 
            Printing.DATA_REC_LOG_LINES + '\n' +
            this.cli.toString() + "\n\n"
        );

        final String dataRecLog = dataRecLogSB.toString();

        FileRW.writeFile(
            dataRecLog,
            config.LOG_DIR + File.separator + BUILDER_RECORD_LOG_FILENAME + ".txt"
        );

        final String dataRecLogHTML =
            Torello.Java.C.toHTML(dataRecLog, true, false, "Build Record-Contents Log");

        FileRW.writeFile(
            dataRecLogHTML,
            config.LOG_DIR + File.separator + BUILDER_RECORD_LOG_FILENAME + ".html"
        );
    }
}