Skip to content

Latest commit

 

History

History
200 lines (160 loc) · 7.97 KB

USAGE.md

File metadata and controls

200 lines (160 loc) · 7.97 KB

Plugin Usage

This document provides an elementary description of the plugin and an overview of its capabilities. It assumes that the plugin is already installed on your TeamCity instance.

Table of Contents

Engine installation detection

The plugin looks for the following files and directories on build agent machines to detect existing Unreal Engine installations (both installed from the Epic Games Launcher and built from the source code):

  • The LauncherInstalled.dat file. Typically located at:
    • Windows — {ProgramData}\Epic\UnrealEngineLauncher\​
    • MacOS — {home}/Library/Application Support/Epic/UnrealEngineLauncher/
    • Linux — {home}/.config/Epic/UnrealEngineLauncher/
  • The Install.ini file. Typically located at:
    • Linux — {home}/.config/Epic/UnrealEngine/
    • MacOS — {home}/Library/Application Support/Epic/UnrealEngine/
  • The SOFTWARE\Epic Games\Unreal Engine\Builds registry key (Windows)

Once an engine is detected, its identifier and path are written to corresponding agent properties. TeamCity utilizes these properties to match compatible agents with build configurations that manage UE solutions.

Build Graph

The plugin supports two build graph execution models:

  • Single machine
  • Distributed

When in distributed mode, your build will be split across all of the available agents based on the description in your BuildGraph XML file: every agent will become a separate build configuration, and each node will become a build step.

Currently, there are a few settings that you should be aware of:

  • Agent types are converted into the agent requirements, and you're free to mark your agents however you like.

    For example, suppose your agent definition in the build graph XML looks like this

    <Agent Name="Do something dope" Type="Foo;Bar">
        ...
    <Agent>

    So, in order to make an agent eligible to run this build you should mark it via declaring custom agent configuration parameter with the name unreal-engine.build-graph.agent.type. It might look like this

    unreal-engine.build-graph.agent.type = Foo

    or you could list as many types as you want like this

    unreal-engine.build-graph.agent.type = Foo;Bar;Baz

    As long as the agent has at least one matching type it will be eligible to run the build.

  • When distributing a build it usually makes sense to set up a proper shared storage. Currently, you have to specify network share in the similar fashion via declaring another agent property with the name unreal-engine.build-graph.agent.shared-dir for each of the agents participating in a build process.

How does that work?

As mentioned earlier, when in distributed mode, the build graph will be converted from one representation (Epic's JSON file, generated by running the BuildGraph command with the -Export parameter) to another (TeamCity's build chain). Snapshot dependencies within the chain will be configured based on how you set them up between nodes in the graph. It's worth mentioning that the resulting build configurations will include all the dependencies of their respective nodes.

It's better to demonstrate with an example. Suppose we have the following part of the BuildGraph description (unimportant details are omitted):

<Agent Name="Work A">
    <Node Name="Step A.1">
        ...
    </Node>
    <Node Name="Step A.2">
        ...
    </Node>
</Agent>
<Agent Name="Work B">
    <Node Name="Step B.1" Requires="Step A.1">
        ...
    </Node>
</Agent>

This will result in 2 build configurations:

  • Work A
    • Step A.1
    • Step A.2
  • Work B
    • Step B.1

The build configuration "Work B" will depend on a build configuration "Work A" despite the fact it might already have been run after completing step "Step A.1". This is due to the nature of snapshot dependencies and the limitation in TeamCity where triggering another build after completing a build step is impossible. Keep that in mind when writing your scripts.

UGS integration

The integration allows you to notify the UGS (Unreal Game Sync) metadata server about the result of a build using badges. As the build progresses, the plugin will post the corresponding information to the metadata server, from which UGS will eventually retrieve it. For more detailed information about UGS, please refer to the official documentation.

One thing to keep in mind: currently, the endpoints provided by the UGS metadata server are not secured with authorization. Presumably, it's supposed to run within a closed network.

The integration is implemented in two forms:

Commit Status Publisher

The behavior is similar to other publishers: you need to select the corresponding one and fill out the required parameters.

Commit Status Publisher

You can also configure it from Kotlin DSL:

commitStatusPublisher {
    publisher = ugsMetadataServer {
        serverUrl = "http://localhost:3000"
        badge = "Foo Badge"
        project = "//foo/bar/project"
    }
}

Build Graph

To enable support within a BuildGraph build, you should run it in “distributed” mode and configure the settings as follows:

unrealEngine {
    command = buildGraph {
        // irrelevant settings are omitted
        executionMode = distributed {
            badges = enableBadges {
                metadataServer = "http://localhost:3000"
            }
        }
    }
}

Alternatively, you can configure it in the UI: BuildGraph badges

In this case all the badges defined in the script will be published according to the dependent nodes they are linked to.

As an example of the script:

<BuildGraph >
    ...
    <Agent Name="Build A" Type="A">
        <Node Name="Node A.1">
            ...
        </Node>
        <Node Name="Node A.2">
            ...
        </Node>
    </Agent>

    <Agent Name="Build B" Type="B">
        <Node Name="Node B.1">
            ...
        </Node>
        <Node Name="Node B.2">
            ...
        </Node>
    </Agent>

    <Badge Name="Foo Badge" Project="//foo/bar/project" Requires="Node A.2;Node B.1"/>
    ...
</BuildGraph>

Here, the badge "Foo Badge" tracks the execution of two nodes: "Node A.2" and "Node B.1". As soon as one of them starts executing, the badge will update its status. If one of them fails, the status will change to "Failure". The badge will only show "Success" when all dependencies complete successfully.

Limitations

  • Currently, for the distributed BuildGraph mode to work, your build configuration must contain exactly one active build step. This should be addressed in TW-89015

Resources

If you'd like to learn more about the plugin, check out these blog posts: