Build target configurations
Prerequisites
Before configuring a build target, you must configure your project's source control settings. You only need to do this for your first configuration.
Select Get started to configure your source control.
Create a build target
When you’ve configured your project for Unity DevOps, you can set up build options for each build target.
These options accommodate the more complex build processing options supported by the Unity Editor.
To access your build target’s options:
- Sign in to the Unity Cloud Dashboard.
- Select DevOps > Build automation > Configurations.
You have two options to set up a new build target:
Quick target setup
When you select Quick target setup, you see the basic configurations required to configure a build target for each platform. Choose this option if you don’t want to configure advanced settings for your build target.
Target setup
When you select Target setup, you first set up the basic settings required for launching your build target. Then, you can either save your configuration or move to the advanced settings.
Builder Configuration
After configuring your basic settings you will be prompted to select a Builder Configuration - this determines the specifications for the machine that will be used to run your build. Different options will be available based on the Builder Operating System you selected in Basic settings. For more information on these options, see Builder Machine Specifications.
Build target advanced settings overview
In the Advanced settings tab, the build target’s Advanced settings are displayed.
All advanced options are set per build target. This means that, for example, when you click the Advanced settings link for an iOS target, those options are only for that iOS target. Or, when you click Advanced settings for an Android target, those options are only for that Android target. You can use different pre- and post-methods per platform, and per build target.
The table below describes the Advanced settings.
| Property | Description |
|---|---|
| Build output | A build output includes debug symbols and enables the Profiler . |
| OS dependency settings | Specify settings related to the internal dependency of the OS used to build. |
| Script hooks -Pre-Build Script | Build Automation runs this script before the Unity build process starts. You can use this script for custom pre/post processing. |
| Script hooks -Post-Build Script | Build Automation runs this script after the Unity build process is completed. You can use this script for custom pre/post processing. |
| Script hooks-Pre-Export Method | Manipulate project files before the project is built. Examples include copying variables from an external file into the project, processing Assets, or working with plug-ins that require special treatment. |
| Script hooks- post-Export method | Add the public method you want to call after finishing the Unity build process (but before Xcode). |
| Environment variables | Use environment variables if you want to give different configurations to your code for different builds. |
| Tests | Use this to configure conditions to run tests and actions on failures. |
| Scenes | Use this to configure a build target to build a set of Scenes that’s different from what is set up in the project’s Build Settings menu in the Unity Editor. |
| Addressables | Use this to build the configured Addressables for the build target’s platform as part of the build process. For more information, see Using Addressables in Build Automation. |
| Asset bundles | Use this to build all configured Asset Bundles for this build target’s platform as part of the build process. For more information, see AssetBundles. |
Advanced settings in more detail
Build output
Build automation builds your projects for release by default. To run builds in strict mode, go to the build target’s Advanced Options and check the Run builds in strict mode box.
Headless Mode
Headless Mode is running a Unity application without a graphical user interface (GUI). It is typically used for running Unity applications on servers or in automated environments without rendering graphics. However, starting from Unity version 2022, Headless Mode is no longer supported. If you want to build projects using Headless Mode with Unity Build Automation, select a Unity version earlier than 2022 in your build target configurations.
Dedicated Server
Dedicated Server is a desktop sub-target that optimizes server build efficiency by automatically stripping unnecessary assets and code during project builds. This results in increased space and processing efficiency, making it more cost-effective for server operators to run server applications created with Unity. Dedicated Server is available in Unity version 2021.3 and above. As a result, if you want to build projects that use Dedicated Server with Unity Build Automation, you need to select Unity versions 2021.3 and later in your build target configurations.
Script hooks
Use script hooks to run custom scripts or Editor code before the build starts or after it’s completed.
Pre- and post-export methods
Use the pre- and post-export methods to trigger actions before and after your Unity Project is built. These methods must exist as code in your Project in the Assets/Editor folder. If the Editor folder doesn’t exist in your directory, you can create one.
> Important: The UnityEngine.CloudBuild.BuildManifestObject class is only available when running in Build automation, not locally. To compile your code locally, wrap your pre- and post-export methods in an #if UNITY_CLOUD_BUILD block. You can set pre- and post-export methods in the build target’s Advanced settings.
Pre-export method name
To use a pre-export method, create a public static method in your Unity Project that contains the code you want to execute before the Unity Editor exports your project and after the Unity Editor script compilation phase.
public static void PreExport()You can enable Build automation to pass the build manifest of the current build to the pre-export method by specifying a BuildManifestObject object as a parameter in the method signature. You can then make changes to the Project or Player settings before the Project is exported.
public static void PreExport(UnityEngine.CloudBuild.BuildManifestObject manifest)When Unity Build automation calls the method, it passes a BuildManifestObject object as an optional parameter, where BuildManifestObject is the build manifest of the current build.
Post-export method name
To use the post-export method, create a public static method in your Unity Project that contains the code you want executed after the Unity Editor exports your Project.
public static void PostExport(string exportPath)When Unity Build Automation calls the method, it passes a string:
- For non-iOS build targets, the string contains the path to the exported Project.
For iOS Projects, the string contains the path to the exported Xcode project. You can use the path to locate the exported Xcode Project to perform additional preprocessing before Xcode is called to complete the build process. Note: If you’ve tagged any methods in your code with the Unity PostProcessBuildAttribute, those methods are executed before any methods configured as post-export methods in Unity Build Automation.
Custom scripting #define directives
Using Build Automation, you can create custom scripting #define directives. On the Unity Cloud Dashboard, go to the build target’s Advanced settings.
In the Scripting Define Symbols field, you can add your own custom scripting #define directives to the built-in selection available. For each build target, enter the names of the symbols you want to define. You can then use these symbols as the conditions in #if directives, just like the built-in symbols. For more information, see Conditional Compilation.
Xcode frameworks
If your iOS Project requires additional Xcode frameworks, use the PBXProject API to add those frameworks to the Xcode Project files created by Unity Build Automation.
There are two ways to call this API to manipulate the Xcode project:
- Use the built-in Unity PostProcessBuildAttribute, which is executed before the Unity Build Automation Post-Export method runs.
- Use the Unity Build Automation post-export method.
Including specific Scenes
By default, Unity Build Automation builds the Scenes you’ve added to your project in the Unity Editor to File > Build Settings > Scenes in Build. Click Add Open Scenes to add additional Scenes. For more information, see Publishing builds.
To instruct Build Automation to ignore the Scenes in Build list in the Unity Editor and build a different list of Scenes, you need to provide a Scene List via the Unity Cloud dashboard.
On the Unity Cloud dashboard, go to the build target’s Advanced settings.
Add the list of Scenes you want to include to the Scene List. Provide the file path as a relative path from the Assets directory to each Scene file you wish to include.
This is useful for development. For example, you may have one build target that includes all the Scenes but takes a long time to build. If you’re only working on one Scene, it might be helpful to use another build target that only includes that Scene. This should build much faster, and allow for quicker iteration of development versions.
Build target group
You can group build target configurations together for easier management. See the Build target groups documentation for more information.
Installed Software
Many tools are pre-installed on our machines to help with the building process. However, certain tools are only be available for the specific Builder Operating System as followed:
Language and Runtime
- Bash
- Java JDK
- Node.js
- Powershell (Windows)
- Python
- Ruby
Package Management
- NVM
- Pyenv
- RVM
Tools and Utilities
- 7-Zip (Windows) / P7ZIP (MacOS)
- Android NDK
- Android SDK
- AWS CLI (Windows)
- Azure CLI (Windows)
- Cloud Content Delivery CLI
- Cygwin
- Git
- Git LFS
- jq (Available with Cygwin)
- Google CLI (Windows)
- Perforce CLI
- Plastic SCM CLI
- Subversion CLI
- Visual C++ Redist (Windows)
- Visual Studio Community
- Visual Studio Build Tools
- Xcode (MacOS)