Get SpatialOS

Sites

Menu

Worker build configuration

The build field of a worker configuration file specifies how to build the worker. You can use the build scripts generated by SpatialOS, or write custom ones.

Using generated build scripts

To get spatial to download the default build scripts for one of the supported worker types, set the generated_build_scripts_type field. The supported worker types include unity, csharp and java. The build and tasks scripts shipped with these are:

  • C#: spatialos.csharp.build.json.
  • Java: spatialos.java.build.json.
  • UnityWorker: spatialos.unity.worker.build.json.
  • UnityClient: spatialos.unity.client.build.json.

For example, this sets up a build for the UnityWorker using the generated build scripts:

{
  "build": {
    "generated_build_scripts_type": "unity",
    "tasks_filename": "spatialos.unity.worker.build.json"
  }
}

The default build scripts contain all steps necessary to build a worker for each platform (Windows, macOS and Linux) and this will be done when running spatial worker build. In order to reduce iteration and build time it is possible to only build the worker for a specific platform by using spatial worker build --target=Windows (or macOS, or Linux), or by using spatial worker build --target=development (or --target=deployment) for Unity build scripts.

If there are two workers in the same worker directory using generated_build_scripts_type, they must use the same value for that field. If one worker relies on a default build script and another on a custom one then the custom build script’s name should be different from those of the spatialos.*.build.json files specified above as it might else be overwritten.

Using custom build scripts

The build field can specify either a set of tasks to be run (which must include Build, Codegen, and Clean) in a tasks list field, or the name of a file containing this task list.

For example, to define a set of tasks directly, use a build file with the following structure:

{
  "build": {
    "tasks": [
      {
        "name": "Clean",
        "steps": [
          {
            "name": "Run make clean",
            "command": "make",
            "arguments": ["clean"]
          }
          ...
        ]
      }
      ...
    ]
  }
}

Alternatively, you can define a set of tasks in a standalone file, named for example build-tasks.json:

{
  "tasks": [
    {
      "name": "Clean",
      "steps": [
        {
          "name": "Run make clean",
          "command": "make",
          "arguments": ["clean"]
        }
        ...
      ]
    }
    ...
  ]
}

And add a reference to it in the main build file by using the tasks_filename field:

{
  "build": {
    "tasks_filename": "build-tasks.json"
  }
}

Tasks

Each task has a name and a set of steps which are performed in the order they are defined when the task is run. A task can also have an optional description. In turn each step must contain a name and a list of arguments. Optional fields are:

  • A command that should be used to run this step.
  • A working_path that specifies the directory in which the step will be executed. Default is the worker’s directory.
  • An env map that allows you to specify environment variables that should be set with specific values for this stop to run. The mapping is from string to string.
  • A target that specifies for which target this should be run (default: any target). It should be used together with the --target=<string> option of the spatial worker build command. Targets are arbitrary, case-insensitive, strings.
  • A description with a string telling what this step does.

If no command is specified the arguments are interpreted as a command (i.e worker_package, process_schema, etc.) of spatial and its parameters. The first argument can also be invoke, invoke-task whose effects are described below.

Defining invoke-task steps

invoke-task causes another task in this configuration to be run. For example, the canonical Build task invokes Codegen as its first step:

...
"steps": [
  {
    "name": "Codegen",
    "arguments": ["invoke-task", "Codegen"]
  },
]
...

Defining invoke steps

invoke provides a user-friendly, cross-platform way to invoke specific external tools, such as unity-csharp-compiler. For a complete list of the supported commands, run spatial invoke --help.

Defining custom steps

When a command is present the contents of arguments is appended to it and the resulting string is executed. This is done outside of a shell so you will need to use bash as command in order to access tools like cp and mv.

...
"steps": [
  {
    "name": "Clean",
    "command": "make",
    "arguments": ["clean"]
  },
]
...

Was this page helpful?

Thanks for letting us know!

Thanks for your feedback

Need more help? Ask on the forums