UE5_Study/docs/Build & Automation System/AutomationTool.md

# Automation Tool

A simple C# program to help a user script unattended processes the engine can complete.  
The entire tool is implemented within `Program.cs` and has all its implmentationw within the `Program` class.  
The following headers will be a breakdown of each of its members.

Note: See alos [ue4-unreal-automation-tool](https://github.com/botman99/ue4-unreal-automation-tool). As its a repo with some more indepth info.

## Main

1. Sets up logger
2. Call `ParseCommandLine` (populates `AutomationToolCommandLine` and ``CommandsToExecute`)
3. Waits for debugger attachment if `AutomationCommandLine` detects `-WaitForDebugger` is set.
4. If MacOS or Linux setup Ctrl+C to be handled correctly so there is no zombie process situation.
5. Set the working directory for the Environment (to the Engine's root directory)
6. Various contextual logging ( operating env, whether launched from launcher, app version...)
7. Run `MainProc` using `ProcessSingleton.RunSingleInstanceAsync`

## AutomationToolCommandLine

A static data member. Is of type `System.ParsedCommandline`. and popualated by `Main`.

| Flag                         | Summary                                                                                             |
|------------------------------|-----------------------------------------------------------------------------------------------------|
| `-Verbose`                   | Enables verbose logging.                                                                            |
| `-VeryVerbose`               | Enables very verbose logging.                                                                       |
| `-TimeStamps`                | Adds timestamps to log entries (no specific description provided).                                  |
| `-Submit`                    | Allows UAT command to submit changes.                                                               |
| `-NoSubmit`                  | Prevents any submit attempts.                                                                       |
| `-NoP4`                      | Disables Perforce functionality (default if not run on a build machine).                            |
| `-P4`                        | Enables Perforce functionality (default if run on a build machine).                                 |
| `-IgnoreDependencies`        | Ignores script dependencies (no specific description provided).                                     |
| `-Help`                      | Displays help information.                                                                          |
| `-List`                      | Lists all available commands.                                                                       |
| `-NoKill`                    | Does not kill any spawned processes on exit.                                                        |
| `-UTF8Output`                | Outputs logs in UTF-8 encoding (no specific description provided).                                  |
| `-AllowStdOutLogVerbosity`   | Allows standard output log verbosity settings (no specific description provided).                   |
| `-NoAutoSDK`                 | Disables automatic SDK setup (no specific description provided).                                    |
| `-Compile`                   | Force all script modules to be compiled.                                                            |
| `-NoCompile`                 | Do not compile any script modules, run with whatever is up to date.                                 |
| `-IgnoreBuildRecords`        | Ignore build records in determining if script modules are up to date.                               |
| `-UseLocalBuildStorage`      | Use local storage for root build storage dir, changing default to `Engine\Saved\LocalBuilds`.       |
| `-WaitForDebugger`           | Waits for a debugger to be attached, and breaks once debugger successfully attached.                |
| `-BuildMachine`              | Indicates the program is running on a build machine (no specific description provided).             |
| `-WaitForUATMutex`           | Waits for the Unreal Automation Tool mutex (no specific description provided).                      |
| `-msbuild-verbose`           | Increases verbosity for MSBuild operations.                                                         |
| `-NoCompileUAT`              | Disables compilation of the Unreal Automation Tool (UAT).                                           |

## ParseCommandLine

Populates `AutomationToolCommandLine` and `CommandsToExecute` (which is within the former and is of type `List<CommandInfo>`).

It will throw execptions if it finds anything wrong with the commands passed.

## ParseProfile

Used by `ParseCommandLine`. Used if `-Profile` is passed to the automation tool.  
Handles profile files which are used to configure how the AutomationTool executes. These profile files can contain a variety of settings and scripts that need to be processed.

1. **Profile File Identification**: Identifies if a `-profile` argument is present in the command line and extracts the profile file path.
2. **Arguments Initialization**: Initializes a list to store the arguments extracted from the profile file.
3. **Iterating Command Line Arguments**: Iterates through command line arguments, treating `-profile=` as the profile file path, and adds other arguments to the Arguments list.
4. **Profile File Existence Check**: Verifies if the specified profile file actually exists.
5. **Reading and Parsing Profile File**: Reads the content of the profile file and parses it as JSON to extract a dictionary of settings.
6. **Processing Scripts in Profile**: Extracts and processes scripts from the `scripts` section in the JSON:
    - Extracts the name of each script and adds it to the Arguments list if not already present.
    - Removes the 'script' key from the script's dictionary.
    - Calls `ParseDictionary` on the dictionary to parse and add these settings to the Arguments list.
7. **Updating Command Line Arguments**: Replaces the original command line arguments with the updated Arguments list containing information processed from the profile file.

## ParseParam

Used by `ParseCommandLine`.

1. **Checks for Ignored Parameters**: Identifies and skips parameters that are not relevant for processing, ensuring efficiency in parsing.
2. **Global Parameter Setting**: Sets global parameters that affect the overall operation of the tool, based on the identified command-line arguments.
3. **Handling Specific Options**: Specifically processes options like `-ScriptsForProject`, `-ScriptDir`, and `-Telemetry`, adjusting the tool's behavior accordingly.
4. **Managing Unknown Parameters and Environment Variables**: Handles parameters that are unrecognized or not standard, and also manages the influence of environment variables on the tool.
5. **Setting Command-line Arguments in `AutomationToolCommandLine`**: Populates the `AutomationToolCommandLine` with the parsed parameters, which is a key resource used throughout the tool.
6. **Exception Handling**: Implements error handling to manage potential issues during the parsing process, ensuring stability and user feedback.

## ParseDictionary

1. **Parameter Verification**: Checks if the dictionary parameter is not null, ensuring it's suitable for processing.
2. **Dictionary Iteration**: Iterates through each key-value pair in the dictionary parameter.
3. **Key Processing**: Processes the keys of the dictionary, which could involve validation, formatting, or conversion to ensure they are in the correct format for further operations.
4. **Value Processing**: Examines and processes the values associated with each key. This step may involve additional parsing logic, especially if the values are complex types (like nested dictionaries or lists).
5. **Recursive Handling**: In cases where values are collections (like lists or dictionaries), `ParseDictionary` may recursively call itself or other parsing methods (like `ParseList`) to ensure all elements are properly processed.
6. **Constructing Processed Dictionary**: Builds a new dictionary with the processed keys and values, which is then ready for use in the tool's operations.

Uses the following helper functions:

### ParseString

1. **Parameter Verification**: Checks if the string parameter is null or empty to ensure only valid strings are processed.
2. **Trimming Whitespace**: Removes leading or trailing whitespace from the parameter string for uniform processing.
3. **String Processing**: Applies specific processing to the cleaned string parameter, such as format conversion or additional parsing logic.

### ParseList

1. **Parameter Verification**: Ensures the list parameter is not null for safe processing.
2. **List Iteration**: Goes through each element in the list parameter.
3. **Element Processing**: Trims whitespace, validates, and converts each list element to the required format or type.
4. **Compiling Processed Elements**: Creates a new list or array from the processed elements, prepared for further use in the tool's workflow.

## MainProc

Core of the AutomationTool's operation, orchestrating the parsing of command-line arguments and executing the necessary commands.

1. **Logger Initialization**: Sets up a logger for information logging.
2. **Initialization Message**: Logs the initialization of script modules.
3. **Start Time Recording**: Records the start time for performance tracking.
4. **Command Line Argument Processing**: Retrieves and processes various command-line arguments related to scripts, compilation, and execution modes (e.g., `-ScriptsForProject`, `-ScriptDir`, `-Compile`, `-NoCompile`, `-IgnoreBuildRecords`).
5. **Command Preparation**: Prepares the list of commands to be executed based on the command-line arguments.
6. **Script Module Compilation**: Initializes and compiles script modules, handling any build processes required and logging related information.
7. **Build Success Check**: Checks if the script module build was successful. If not, returns an error exit code.
8. **Script Module Validation**: Ensures that at least one script module (like AutomationUtils) is available after compilation.
9. **Loading AutomationUtils Assembly**: Loads the `AutomationUtils.Automation.dll` assembly, essential for further processing.
10. **Automation Process Invocation**: Invokes the `ProcessAsync` method from the `AutomationTool.Automation` class, which drives the execution of the tool's functionality based on the prepared script modules and command-line arguments.
11. **Execution Time Logging**: Logs the total time taken for script module initialization.
12. **Awaiting Process Completion**: Awaits the completion of the `ProcessAsync` method and returns its result as an exit code.

## StartupListener

> Captures all log output during startup until a log file writer has been created