For a general overview of the Automation Tool see AutomationTool
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.
- Sets up logger
- Call
ParseCommandLine
(populatesAutomationToolCommandLine
and ``CommandsToExecute`) - Waits for debugger attachment if
AutomationCommandLine
detects-WaitForDebugger
is set. - If MacOS or Linux setup Ctrl+C to be handled correctly so there is no zombie process situation.
- Set the working directory for the Environment (to the Engine's root directory)
- Various contextual logging ( operating env, whether launched from launcher, app version...)
- Run
MainProc
usingProcessSingleton.RunSingleInstanceAsync
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). |
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.
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.
- Profile File Identification: Identifies if a
-profile
argument is present in the command line and extracts the profile file path. - Arguments Initialization: Initializes a list to store the arguments extracted from the profile file.
- Iterating Command Line Arguments: Iterates through command line arguments, treating
-profile=
as the profile file path, and adds other arguments to the Arguments list. - Profile File Existence Check: Verifies if the specified profile file actually exists.
- Reading and Parsing Profile File: Reads the content of the profile file and parses it as JSON to extract a dictionary of settings.
- 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.
- Updating Command Line Arguments: Replaces the original command line arguments with the updated Arguments list containing information processed from the profile file.
Used by ParseCommandLine
.
- Checks for Ignored Parameters: Identifies and skips parameters that are not relevant for processing, ensuring efficiency in parsing.
- Global Parameter Setting: Sets global parameters that affect the overall operation of the tool, based on the identified command-line arguments.
- Handling Specific Options: Specifically processes options like
-ScriptsForProject
,-ScriptDir
, and-Telemetry
, adjusting the tool's behavior accordingly. - 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.
- Setting Command-line Arguments in
AutomationToolCommandLine
: Populates theAutomationToolCommandLine
with the parsed parameters, which is a key resource used throughout the tool. - Exception Handling: Implements error handling to manage potential issues during the parsing process, ensuring stability and user feedback.
- Parameter Verification: Checks if the dictionary parameter is not null, ensuring it's suitable for processing.
- Dictionary Iteration: Iterates through each key-value pair in the dictionary parameter.
- 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.
- 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).
- Recursive Handling: In cases where values are collections (like lists or dictionaries),
ParseDictionary
may recursively call itself or other parsing methods (likeParseList
) to ensure all elements are properly processed. - 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:
- Parameter Verification: Checks if the string parameter is null or empty to ensure only valid strings are processed.
- Trimming Whitespace: Removes leading or trailing whitespace from the parameter string for uniform processing.
- String Processing: Applies specific processing to the cleaned string parameter, such as format conversion or additional parsing logic.
- Parameter Verification: Ensures the list parameter is not null for safe processing.
- List Iteration: Goes through each element in the list parameter.
- Element Processing: Trims whitespace, validates, and converts each list element to the required format or type.
- Compiling Processed Elements: Creates a new list or array from the processed elements, prepared for further use in the tool's workflow.
Core of the AutomationTool's operation, orchestrating the parsing of command-line arguments and executing the necessary commands.
- Logger Initialization: Sets up a logger for information logging.
- Initialization Message: Logs the initialization of script modules.
- Start Time Recording: Records the start time for performance tracking.
- 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
). - Command Preparation: Prepares the list of commands to be executed based on the command-line arguments.
- Script Module Compilation: Initializes and compiles script modules, handling any build processes required and logging related information.
- Build Success Check: Checks if the script module build was successful. If not, returns an error exit code.
- Script Module Validation: Ensures that at least one script module (like AutomationUtils) is available after compilation.
- Loading AutomationUtils Assembly: Loads the
AutomationUtils.Automation.dll
assembly, essential for further processing. - Automation Process Invocation: Invokes the
ProcessAsync
method from theAutomationTool.Automation
class, which drives the execution of the tool's functionality based on the prepared script modules and command-line arguments. - Execution Time Logging: Logs the total time taken for script module initialization.
- Awaiting Process Completion: Awaits the completion of the
ProcessAsync
method and returns its result as an exit code.
Captures all log output during startup until a log file writer has been created