Skip to content

03-build.mdx

Latest commit

 

History

History
816 lines (667 loc) · 21.1 KB

03-build.mdx

File metadata and controls

816 lines (667 loc) · 21.1 KB
toc_max_heading_level 4

Build

The Unity Orb provides the build job to facilitate the process of building your Unity project for multiple platforms.

Parameters

Below you will find information on each parameter that can be passed to the build job.

build-method

The command used to build your project. A valid build-method contains the path to a static method in a class inside the Assets/Editor directory. The Unity Orb will fall back to the default script if this parameter is left empty.

To illustrate, if you were to modify the default script and use it to build your project, you would need to place its content in Assets/Editor/MyBuildMethod.cs and pass BuildCommand.PerformBuild as your build-method value.

If your custom build method requires additional parameters, see custom-parameters.

version: 2.1

orbs:
  unity: game-ci/unity@x.y

workflows:
  build-unity-project:
    jobs:
      - unity/build:
          build-method: 'BuildCommand.PerformBuild'
  • Default: N/A
  • Required: false
  • Type: string

build-name

Your build's name. If left blank, the build will be named after the target platform.

version: 2.1

orbs:
  unity: game-ci/unity@x.y

workflows:
  build-unity-project:
    jobs:
      - unity/build:
          build-name: 'MyUnityProject'
  • Default: N/A
  • Required: false
  • Type: string

build-target

The platform on which you want to run your game or application. Available targets can be found in the Unity Editor documentation.

version: 2.1

orbs:
  unity: game-ci/unity@x.y

workflows:
  build-unity-project:
    jobs:
      - unity/build:
          build-target: 'StandaloneLinux64'
  • Default: N/A
  • Required: true
  • Type: string

compress

Whether to compress the build output to a .tar.gz file. Set it to true if you want to download the build artifacts from the CircleCI web app. Otherwise, you will have to download each file individually. If set to false for decompressed WebGL builds, the built project can be run directly from the GameCI dashboard.

version: 2.1

orbs:
  unity: game-ci/unity@x.y

workflows:
  build-unity-project:
    jobs:
      - unity/build:
          compress: true
  • Default: true
  • Required: false
  • Type: boolean

custom-parameters

Additional parameters for the Unity CLI. This is useful if you want to change Unity's build options or pass custom parameters to your build method.

The parameters must be separated by space and must be in the format -key value or -key for booleans. Environment variables are supported and will be expanded in runtime.

version: 2.1

orbs:
  unity: game-ci/unity@x.y

workflows:
  build-unity-project:
    jobs:
      - unity/build:
          custom-parameters:
            '-customParam1 potato -customParam2 tomato -customParam3 $CIRCLE_WORKFLOW_ID
            -DetailedBuildReport'
  • Default: N/A
  • Required: false
  • Type: string

executor

The executor that you want to run your build job on. Bear in mind that projects using IL2CPP for a scripting backend should run on the same OS as the build target. For example, if you want to build for macOS using IL2CPP, then you must use the macos or macos-runner executor.

Each executor has its set of parameters. See the Executors section for more details.

version: 2.1

orbs:
  unity: game-ci/unity@x.y

workflows:
  build-unity-project:
    jobs:
      - unity/build:
          executor:
            name: 'unity/ubuntu'
            target_platform: 'linux-il2cpp'
            editor_version: '2021.3.2f1'
            resource_class: 'large'
  • Default: N/A
  • Required: true
  • Type: executor

no_output_timeout

Elapsed time without output before the job is canceled and stopped. The value can be in hours, minutes or seconds - a digit followed by h, m or s respectively. Consider increasing it if you see this error:

Too long with no output (exceeded 20m0s): context deadline exceeded

version: 2.1

orbs:
  unity: game-ci/unity@x.y

workflows:
  build-unity-project:
    jobs:
      - unity/build:
          no_output_timeout: 30m
  • Default: 20m
  • Required: false
  • Type: string

project-path

If your project sits at the root of your repository, leave it to the default value. Otherwise, enter the path to your Unity project. It should be the directory that has the "Assets" folder inside it.

version: 2.1

orbs:
  unity: game-ci/unity@x.y

workflows:
  build-unity-project:
    jobs:
      - unity/build:
          project-path: 'Unity2D-Demo-Game-CI-CD/src'
  • Default: .
  • Required: false
  • Type: string

return-license

Whether to manually return the Unity license after the build job is finished. This is usually unnecessary and only useful when running into an unrecoverable error while having a license active. Additionally, Unity only allows returning professional licenses.

version: 2.1

orbs:
  unity: game-ci/unity@x.y

workflows:
  build-unity-project:
    jobs:
      - unity/build:
          return-license: true
  • Default: false
  • Required: false
  • Type: boolean

step-name

Specify a custom step name to be shown in the CircleCI web app.

version: 2.1

orbs:
  unity: game-ci/unity@x.y

workflows:
  build-unity-project:
    jobs:
      - unity/build:
          step-name: 'Build my Unity project'
  • Default: Build the project
  • Required: false
  • Type: string

store-artifacts

Whether to store the build output. If set to false you won't be able to download your build in the CircleCI web app.

version: 2.1

orbs:
  unity: game-ci/unity@x.y

workflows:
  build-unity-project:
    jobs:
      - unity/build:
          store-artifacts: false
  • Default: true
  • Required: false
  • Type: boolean

fetch-submodules

Whether to fetch git submodules relating to the project repository.

version: 2.1

orbs:
  unity: game-ci/unity@x.y

workflows:
  build-unity-project:
    jobs:
      - unity/build:
          fetch-submodules: true
  • Default: false
  • Required: false
  • Type: boolean

unity-license-var-name

The name of the environment variable holding the license set in your Context. Only required when using a Personal License. See activation for more details.

version: 2.1

orbs:
  unity: game-ci/unity@x.y

workflows:
  build-unity-project:
    jobs:
      - unity/build:
          unity-license-var-name: 'UNITY_ENCODED_LICENSE'
  • Default: UNITY_ENCODED_LICENSE
  • Required: false
  • Type: env_var_name

unity-password-var-name

The name of the environment variable holding the password set in your Context. See activation for more details.

version: 2.1

orbs:
  unity: game-ci/unity@x.y

workflows:
  build-unity-project:
    jobs:
      - unity/build:
          unity-password-var-name: 'UNITY_PASSWORD'
  • Default: UNITY_PASSWORD
  • Required: false
  • Type: env_var_name

unity-serial-var-name

The name of the environment variable holding the serial set in your Context. Only required when using a Pro or Plus License. See activation for more details.

version: 2.1

orbs:
  unity: game-ci/unity@x.y

workflows:
  build-unity-project:
    jobs:
      - unity/build:
          unity-serial-var-name: 'UNITY_SERIAL'
  • Default: UNITY_SERIAL
  • Required: false
  • Type: env_var_name

unity-username-var-name

The name of the environment variable holding the username set in your Context. See Activation for more details.

version: 2.1

orbs:
  unity: game-ci/unity@x.y

workflows:
  build-unity-project:
    jobs:
      - unity/build:
          unity-username-var-name: 'UNITY_USERNAME'
  • Default: UNITY_USERNAME
  • Required: false
  • Type: env_var_name

Examples

In this section, you will find examples of workflows using this job. However, notice that the separation used in the examples is only for the sake of visualisation. You can build for all target platforms in the same workflow. All examples are based on CircleCI's Demo Project.

Personal License

This example shows how to build your project for several platforms using a Personal License.

IL2CPP
version: 2.1

orbs:
  unity: game-ci/unity@x.y

workflows:
  build-unity-project:
    jobs:
      # Linux IL2CPP
      - unity/build:
          name: 'build-linux64-il2cpp'
          step-name: 'Build StandaloneLinux64'
          unity-license-var-name: 'UNITY_ENCODED_LICENSE'
          unity-username-var-name: 'UNITY_USERNAME'
          unity-password-var-name: 'UNITY_PASSWORD'
          executor:
            name: 'unity/ubuntu'
            target_platform: 'linux-il2cpp'
            editor_version: '2021.3.1f1'
            resource_class: 'large'
          project-path: 'Unity2D-Demo-Game-CI-CD/src'
          build-target: StandaloneLinux64
          compress: true
          context: unity

      # Windows IL2CPP
      - unity/build:
          name: 'build-Windows64-il2cpp'
          step-name: 'Build StandaloneWindows64 il2cpp'
          unity-license-var-name: 'UNITY_ENCODED_LICENSE'
          unity-username-var-name: 'UNITY_USERNAME'
          unity-password-var-name: 'UNITY_PASSWORD'
          executor:
            name: 'unity/windows-2019'
            size: 'large'
            editor_version: '2021.3.2f1'
            target_platform: 'windows-il2cpp'
          project-path: 'Unity2D-Demo-Game-CI-CD/src'
          build-target: StandaloneWindows64
          compress: true
          context: unity

      # macOS IL2CPP
      - unity/build:
          name: 'build-osx-il2cpp'
          step-name: 'Build macOS IL2CPP'
          unity-license-var-name: 'UNITY_ENCODED_LICENSE'
          unity-username-var-name: 'UNITY_USERNAME'
          unity-password-var-name: 'UNITY_PASSWORD'
          executor:
            name: 'unity/macos'
            resource_class: 'large'
            editor_version: '2021.3.2f1'
          project-path: 'Unity2D-Demo-Game-CI-CD/src'
          build-target: StandaloneWindows64
          compress: true
          context: unity
Mono
version: 2.1

orbs:
  unity: game-ci/unity@x.y

workflows:
  build-unity-project:
    jobs:
      # Linux Mono
      - unity/build:
          name: 'build-linux64-mono'
          step-name: 'Build StandaloneLinux64'
          unity-license-var-name: 'UNITY_ENCODED_LICENSE'
          unity-username-var-name: 'UNITY_USERNAME'
          unity-password-var-name: 'UNITY_PASSWORD'
          executor:
            name: 'unity/ubuntu'
            target_platform: 'base'
            editor_version: '2021.3.1f1'
            resource_class: 'large'
          project-path: 'Unity2D-Demo-Game-CI-CD/src'
          build-target: StandaloneLinux64
          compress: true
          context: unity

      # Windows Mono
      - unity/build:
          name: 'build-Windows64-mono'
          step-name: 'Build StandaloneWindows64'
          unity-license-var-name: 'UNITY_ENCODED_LICENSE'
          unity-username-var-name: 'UNITY_USERNAME'
          unity-password-var-name: 'UNITY_PASSWORD'
          executor:
            name: 'unity/ubuntu'
            target_platform: 'windows-mono'
            editor_version: '2021.3.2f1'
            resource_class: 'large'
          project-path: 'Unity2D-Demo-Game-CI-CD/src'
          build-target: 'StandaloneWindows64'
          context: unity

      # macOS Mono
      - unity/build:
          name: 'build-osx-mono'
          step-name: 'Build StandaloneOSX'
          unity-license-var-name: 'UNITY_ENCODED_LICENSE'
          unity-username-var-name: 'UNITY_USERNAME'
          unity-password-var-name: 'UNITY_PASSWORD'
          executor:
            name: 'unity/ubuntu'
            target_platform: 'mac-mono'
            editor_version: '2021.3.2f1'
            resource_class: 'large'
          project-path: 'Unity2D-Demo-Game-CI-CD/src'
          build-target: 'StandaloneOSX'
          context: unity
Other Platforms
version: 2.1

orbs:
  unity: game-ci/unity@x.y

workflows:
  build-unity-project:
    jobs:
      # WebGL
      - unity/build:
          name: 'build-webgl'
          step-name: 'Build WebGL'
          unity-license-var-name: 'UNITY_ENCODED_LICENSE'
          unity-username-var-name: 'UNITY_USERNAME'
          unity-password-var-name: 'UNITY_PASSWORD'
          executor:
            name: 'unity/ubuntu'
            target_platform: 'webgl'
            editor_version: '2021.3.1f1'
            resource_class: 'large'
          project-path: 'Unity2D-Demo-Game-CI-CD/src'
          build-target: 'WebGL'
          compress: false
          context: unity

      # Android
      - unity/build:
          name: 'build-android'
          step-name: 'Build Android'
          unity-license-var-name: 'UNITY_ENCODED_LICENSE'
          unity-username-var-name: 'UNITY_USERNAME'
          unity-password-var-name: 'UNITY_PASSWORD'
          executor:
            name: 'unity/ubuntu'
            target_platform: 'android'
            editor_version: '2021.3.2f1'
            resource_class: 'large'
          project-path: 'Unity2D-Demo-Game-CI-CD/src'
          build-target: 'Android'
          context: unity

      # iOS
      - unity/build:
          name: 'build-ios'
          step-name: 'Build iOS'
          unity-license-var-name: 'UNITY_ENCODED_LICENSE'
          unity-username-var-name: 'UNITY_USERNAME'
          unity-password-var-name: 'UNITY_PASSWORD'
          executor:
            name: 'unity/ubuntu'
            target_platform: 'ios'
            editor_version: '2021.3.2f1'
            resource_class: 'large'
          project-path: 'Unity2D-Demo-Game-CI-CD/src'
          build-target: 'iOS'
          context: unity

      # tvOS
      - unity/build:
          name: 'build-tvOS'
          step-name: "Build Apple's tvOS"
          unity-license-var-name: 'UNITY_ENCODED_LICENSE'
          unity-username-var-name: 'UNITY_USERNAME'
          unity-password-var-name: 'UNITY_PASSWORD'
          executor:
            name: 'unity/windows-2019'
            size: 'large'
            editor_version: '2021.3.2f1'
            target_platform: 'appletv'
          project-path: 'Unity2D-Demo-Game-CI-CD/src'
          build-target: tvOS
          compress: true
          context: unity

Professional License

This example shows how to build your project for several platforms using a Pro License.

IL2CPP
version: 2.1

orbs:
  unity: game-ci/unity@x.y

workflows:
  build-unity-project:
    jobs:
      # Linux IL2CPP
      - unity/build:
          name: 'build-linux64-il2cpp'
          step-name: 'Build StandaloneLinux64'
          unity-serial-var-name: 'UNITY_SERIAL'
          unity-username-var-name: 'UNITY_USERNAME'
          unity-password-var-name: 'UNITY_PASSWORD'
          executor:
            name: 'unity/ubuntu'
            target_platform: 'linux-il2cpp'
            editor_version: '2021.3.1f1'
            resource_class: 'large'
          project-path: 'Unity2D-Demo-Game-CI-CD/src'
          build-target: StandaloneLinux64
          compress: true
          context: unity

      # Windows IL2CPP
      - unity/build:
          name: 'build-Windows64-il2cpp'
          step-name: 'Build StandaloneWindows64 il2cpp'
          unity-serial-var-name: 'UNITY_SERIAL'
          unity-username-var-name: 'UNITY_USERNAME'
          unity-password-var-name: 'UNITY_PASSWORD'
          executor:
            name: 'unity/windows-2019'
            size: 'large'
            editor_version: '2021.3.2f1'
            target_platform: 'windows-il2cpp'
          project-path: 'Unity2D-Demo-Game-CI-CD/src'
          build-target: StandaloneWindows64
          compress: true
          context: unity

      # macOS IL2CPP
      - unity/build:
          name: 'build-osx-il2cpp'
          step-name: 'Build macOS IL2CPP'
          unity-serial-var-name: 'UNITY_SERIAL'
          unity-username-var-name: 'UNITY_USERNAME'
          unity-password-var-name: 'UNITY_PASSWORD'
          executor:
            name: 'unity/macos'
            resource_class: 'large'
            editor_version: '2021.3.2f1'
          project-path: 'Unity2D-Demo-Game-CI-CD/src'
          build-target: StandaloneOSX
          compress: true
          context: unity
Mono
version: 2.1

orbs:
  unity: game-ci/unity@x.y

workflows:
  build-unity-project:
    jobs:
      # Linux Mono
      - unity/build:
          name: 'build-linux64-mono'
          step-name: 'Build StandaloneLinux64'
          unity-serial-var-name: 'UNITY_SERIAL'
          unity-username-var-name: 'UNITY_USERNAME'
          unity-password-var-name: 'UNITY_PASSWORD'
          executor:
            name: 'unity/ubuntu'
            target_platform: 'base'
            editor_version: '2021.3.1f1'
            resource_class: 'large'
          project-path: 'Unity2D-Demo-Game-CI-CD/src'
          build-target: StandaloneLinux64
          compress: true
          context: unity

      # Windows Mono
      - unity/build:
          name: 'build-Windows64-mono'
          step-name: 'Build StandaloneWindows64'
          unity-serial-var-name: 'UNITY_SERIAL'
          unity-username-var-name: 'UNITY_USERNAME'
          unity-password-var-name: 'UNITY_PASSWORD'
          executor:
            name: 'unity/ubuntu'
            target_platform: 'windows-mono'
            editor_version: '2021.3.2f1'
            resource_class: 'large'
          project-path: 'Unity2D-Demo-Game-CI-CD/src'
          build-target: 'StandaloneWindows64'
          context: unity

      # macOS Mono
      - unity/build:
          name: 'build-osx-mono'
          step-name: 'Build StandaloneOSX'
          unity-serial-var-name: 'UNITY_SERIAL'
          unity-username-var-name: 'UNITY_USERNAME'
          unity-password-var-name: 'UNITY_PASSWORD'
          executor:
            name: 'unity/ubuntu'
            target_platform: 'mac-mono'
            editor_version: '2021.3.2f1'
            resource_class: 'large'
          project-path: 'Unity2D-Demo-Game-CI-CD/src'
          build-target: 'StandaloneOSX'
          context: unity
Other Platforms
version: 2.1

orbs:
  unity: game-ci/unity@x.y

workflows:
  build-unity-project:
    jobs:
      # WebGL
      - unity/build:
          name: 'build-webgl'
          step-name: 'Build WebGL'
          unity-serial-var-name: 'UNITY_SERIAL'
          unity-username-var-name: 'UNITY_USERNAME'
          unity-password-var-name: 'UNITY_PASSWORD'
          executor:
            name: 'unity/ubuntu'
            target_platform: 'webgl'
            editor_version: '2021.3.1f1'
            resource_class: 'large'
          project-path: 'Unity2D-Demo-Game-CI-CD/src'
          build-target: 'WebGL'
          compress: false
          context: unity

      # Android
      - unity/build:
          name: 'build-android'
          step-name: 'Build Android'
          unity-serial-var-name: 'UNITY_SERIAL'
          unity-username-var-name: 'UNITY_USERNAME'
          unity-password-var-name: 'UNITY_PASSWORD'
          executor:
            name: 'unity/ubuntu'
            target_platform: 'android'
            editor_version: '2021.3.2f1'
            resource_class: 'large'
          project-path: 'Unity2D-Demo-Game-CI-CD/src'
          build-target: 'Android'
          context: unity

      # iOS
      - unity/build:
          name: 'build-ios'
          step-name: 'Build iOS'
          unity-serial-var-name: 'UNITY_SERIAL'
          unity-username-var-name: 'UNITY_USERNAME'
          unity-password-var-name: 'UNITY_PASSWORD'
          executor:
            name: 'unity/ubuntu'
            target_platform: 'ios'
            editor_version: '2021.3.2f1'
            resource_class: 'large'
          project-path: 'Unity2D-Demo-Game-CI-CD/src'
          build-target: 'iOS'
          context: unity

      # tvOS
      - unity/build:
          name: 'build-tvOS'
          step-name: "Build Apple's tvOS"
          unity-serial-var-name: 'UNITY_SERIAL'
          unity-username-var-name: 'UNITY_USERNAME'
          unity-password-var-name: 'UNITY_PASSWORD'
          executor:
            name: 'unity/windows-2019'
            size: 'large'
            editor_version: '2021.3.2f1'
            target_platform: 'appletv'
          project-path: 'Unity2D-Demo-Game-CI-CD/src'
          build-target: tvOS
          compress: true
          context: unity