Setting up Continuous Integration with Unity

A recent question about Continuous Integration and Unity led me to try and get something up and running.

The motivation was to see how hard it is to setup a basic CI system for auto building Unity projects and later on be used for running automated testing as well.

Here are my observations.

Disclaimer: although I consider myself to be a Unity noob, I am well experienced with CI, build servers, unit tests and other fancy software engineering practices.

Continuous Integration

The term “Continuous Integration” as I see it is actually an umbrella term for a few things:

  1. Code Integration – Building your code quickly that is triggered on every check in to the source control system.
  2. Automated Builds – Your code gets built automatically (and repeatedly) in a single automated step.
  3. Automated Testing – Automated tests (whether unit tests or other types) that validate various pieces of functionality of your code.

Although many CI products are available today (free and commercial), i will focus on TeamCity out of 2 reasons:

  1. It is absolutely FREE (with some limitations).
  2. There is an open source project that offers building Unity projects from it directly.

Let’s get started!

Ingredients

In order to get started you will need to get the following:

  1. TeamCity 7.0.1
  2. Unity3d Build Runner

Setup

Installing TeamCity

Installation of TeamCity is pretty straightforward, just “Next, Next” your way through it.

TeamCity uses a concept of “Build Agents”, which are basically a piece of software that does the actual building of the game.

The free version of TeamCity supports up to 3 build agents. For the sake of this example we are installing the server + agent on the same machine.

Note that for larger setups, Unity must be installed on each machine that  the agent will be installed on.

Installing Unity Build Runner

Unity build runner is an open source project of a TeamCity custom build runner.
Special thanks goes to Mind Candy for creating it and sharing it as an open source project).
It wraps Unity’s command line interface into an easy to operate menu. It is also responsible for reporting errors and sending logs back to TeamCity.
The build runner must be compiled from its sources, as it is only available as source code.
Luckily i have already done that, and the compiled output (.zip file) can be found here: unityRunner.zip
In case you would like to build the runner yourself (loads of fun!), you’ll need IntelliJ (free):

Configuring a new project

Here are the basic steps for configuring a new TeamCity project and 2 build configurations, that will build the “AngryBots” demo that comes with unity in 2 flavors (Web and Windows).

  1. Create a new project in TeamCity: Administration menu -> Create Project
  2. Add build configurations per platform you’d like to build (One for Windows and another for Web Player)
  3. Per configuration, add a build step with “Unity build runner”
    Example of a windows build

    Example configuration of a Web player build

That’s all there is to it! We have a basic CI system running that can automatically build Unity games in different flavors.

Optionally, A build trigger can be set per each configuration to start a build upon a source control check in. For the sake of our example the build will be started on demand from the TeamCity UI.

Caveats

Here’s a list of issues I’ve come across:

  1. In case of certain errors during the build, Unity build runner will fail to report these to the build log. I have already contacted the owner of this project, although i may attempt to fix it myself.
  2. When building a Windows version of the game, the path given to the build runner should be the .exe file’s full path. When building a web player project, the path should be a folder name.
  3. There are no mobile platforms (iOS/Android) available in the build runner dropdown. These are also not documented in Unity’s command line reference page (not sure if they are available).
  4. Unity enforces a single running instance per project. The command line mode runs the same executable, and so it will fail to work when an instance of the engine is running and has the project being built open.
  5. Unity doesn’t have a separate compiler/builder platform. The engine’s executable needs to be loaded to build the game, which can be CPU and memory intensive.
In the next post i will attempt to start exploring options of building upon this setup to add some basic automated testing of our built project, and show how it all integrates with TeamCity.

Additional Resources

About these ads