Setup and installation

Setup and installation: Worker SDK in C

Requirements

Prerequisites

Follow the SpatialOS tools installation guide (Windows / macOS / Linux. This is a prerequisite for using the Worker SDK.

Supported compilers and runtimes

The Worker SDK in C works with any C compiler that supports the ANSI C standard, or any other language which is designed to work with C libraries. We compile native libraries which target at least the following toolchains and platforms:

  • Windows: Microsoft Visual Studio 2017 (toolset v141) and above.
  • macOS: Xcode 10 targeting OS X Yosemite (10.10) and above.
  • Linux: gcc 5.1.0 (GLIBCXX_3.4.21, CXXABI_1.3.9) and above (see here for more information).
  • iOS: iOS 11.4 and above.
  • Android: Android API level 22 and above.

On Windows, if you choose to use a worker package which has been compiled with the /MD or /MDd flags (multithreaded dynamic, and multithreaded dynamic debug), then any system which uses these libraries (including client systems) will also require Visual C++ Redistributable for Visual Studio 2015. Usually, MSVC projects will use the multi-threaded dynamic runtime (/MD) in the Release configuration, and the multi-threaded dynamic debug runtime (/MDd) in the Debug configuration.

iOS and Android support is currently in alpha. In particular, iOS apps using SpatialOS do not yet support IPv6 only networks. However, this will be resolved in the near future.

Packages

You can obtain packages through worker packages, our package management framework. You can specify these packages in a spatialos_worker_packages.json or download them manually by running spatial package get worker_sdk <package_name> <version> <destination zip> (for example: spatial package get worker_sdk c-static-x86_64-vc141_md-win32 14.0.0 windows.zip).

The Worker SDK in C is a native library, so it is compiled for a large variety of platforms, architectures and configurations. Each package contains native libraries built with a particular configuration. The header files are available in a separate package. For more information, see Building a worker.

The tables below list all the packages you can retrieve, relevant to the Worker SDK for C:

Package name Arch Build type More information
c_headers n/a n/a C API header files (*.h).
Package name Arch Build type More information
c-static-x86_64-vc141_md-win32 x86_64 Static VS 2017 with multithreaded runtime library (/MD)
c-static-x86_64-vc141_mdd-win32 x86_64 Static VS 2017 with multithreaded debug runtime library (/MDd)
c-static-x86_64-vc141_mt-win32 x86_64 Static VS 2017 with multithreaded static runtime library (/MT)
c-static-x86_64-vc141_mtd-win32 x86_64 Static VS 2017 with multithreaded static debug runtime library (/MTd)
c-dynamic-x86_64-vc141_md-win32 x86_64 Dynamic VS 2017 with multithreaded runtime library (/MD)
c-dynamic-dbgsym-x86_64-vcvc141_md-win32 x86_64 Dynamic Debug symbols (.pdb). VS 2017 with multithreaded runtime library (/MD)
c-dynamic-x86_64-vc141_mdd-win32 x86_64 Dynamic VS 2017 with multithreaded debug runtime library (/MDd)
c-dynamic-dbgsym-x86_64-vc141_mdd-win32 x86_64 Dynamic Debug symbols (.pdb). VS 2017 with multithreaded debug runtime library (/MDd)
c-dynamic-x86_64-vc141_mt-win32 x86_64 Dynamic VS 2017 with multithreaded static runtime library (/MT)
c-dynamic-dbgsym-x86_64-vc141_mt-win32 x86_64 Dynamic Debug symbols (.pdb). VS 2017 with multithreaded static runtime library (/MT)
c-dynamic-x86_64-vc141_mtd-win32 x86_64 Dynamic VS 2017 with multithreaded static debug runtime library (/MTd)
c-dynamic-dbgsym-x86_64-vc141_mtd-win32 x86_64 Dynamic Debug symbols (.pdb). VS 2017 with multithreaded static debug runtime library (/MTd)
c-static-x86-vc141_md-win32 x86 Static VS 2017 with multithreaded runtime library (/MD)
c-dynamic-x86-vc141_md-win32 x86 Dynamic VS 2017 with multithreaded static debug runtime library (/MTd)
c-dynamic-dbgsym-x86-vc141_md-win32 x86 Dynamic Debug symbols (.pdb). VS 2017 with multithreaded static debug runtime library (/MTd)
Package name Arch Build type More information
c-static-x86_64-clang-macos x86_64 Static Xcode 10 targeting macOS 10.10+ (-mmacosx-version-min=10.10)
c-dynamic-x86_64-clang-macos x86_64 Dynamic Xcode 10 targeting macOS 10.10+ (-mmacosx-version-min=10.10)
c-bundle-x86_64-clang-macos x86_64 Framework Bundle Xcode 10 targeting macOS 10.10+ (-mmacosx-version-min=10.10)
Package name Arch Build type More information
c-static-x86_64-gcc510-linux x86_64 Static gcc 5.4.0 with libstdc++
c-static-x86_64-gcc510_pic-linux x86_64 Static gcc 5.4.0 with libstdc++. Compiled as position-independent code (-fpic)
c-dynamic-x86_64-gcc510-linux x86_64 Dynamic gcc 5.4.0 with libstdc++
Package name Arch Build type More information
c-static-arm-clang-ios arm64 Static Xcode 10 targeting iOS 10+ (-miphoneos-version-min=10.10)
c-static-fullylinked-arm-clang-ios arm64 Static Xcode 10 targeting iOS 10+ (-miphoneos-version-min=10.10). All static libraries are merged into one.
c-dynamic-arm-clang-ios arm64 Dynamic Xcode 10 targeting iOS 10+ (-miphoneos-version-min=10.10)
c-bundle-arm-clang-ios arm64 Framework Bundle Xcode 10 targeting iOS 10+ (-miphoneos-version-min=10.10)
c-static-x86_64-clang-ios x86_64 (simulator) Static Xcode 10 targeting iOS 10+ (-miphoneos-version-min=10.10)
c-static-fullylinked-x86_64-clang-ios x86_64 (simulator) Static Xcode 10 targeting iOS 10+ (-miphoneos-version-min=10.10). All static libraries are merged into one.
c-dynamic-x86_64-clang-ios x86_64 (simulator) Dynamic Xcode 10 targeting iOS 10+ (-miphoneos-version-min=10.10)
c-bundle-x86_64-clang-ios x86_64 (simulator) Framework Bundle Xcode 10 targeting iOS 10+ (-miphoneos-version-min=10.10)
Package name Arch Build type More information
c-static-arm64v8a-clang_ndk21_pic-android arm64-v8a Static NDK r21 targeting API level 22 with libc++. Compiled as position-independent code (-fpic)
c-dynamic-arm64v8a-clang_ndk21-android arm64-v8a Dynamic NDK r21 targeting API level 22 with libc++
c-static-armv7a-clang_ndk21_pic-android armv7a Static NDK r21 targeting API level 22 with libc++. Compiled as position-independent code (-fpic)
c-dynamic-armv7a-clang_ndk21-android armv7a Dynamic NDK r21 targeting API level 22 with libc++
c-static-x86-clang_ndk21_pic-android x86 (emulator) Static NDK r21 targeting API level 22 with libc++. Compiled as position-independent code (-fpic)
c-dynamic-x86-clang_ndk21-android x86 (emulator) Dynamic NDK r21 targeting API level 22 with libc++
c-static-x86_64-clang_ndk21_pic-android x86_64 (emulator) Static NDK r21 targeting API level 22 with libc++. Compiled as position-independent code (-fpic)
c-dynamic-x86_64-clang_ndk21-android x86_64 (emulator) Dynamic NDK r21 targeting API level 22 with libc++

Setting up a worker using the SpatialOS build system

If you're using the flexible project layout, you don't need to do this.

Assuming you have a worker set up with a worker configuration file, and assuming that worker_dir is <project_root>/workers/<your_worker> you can obtain the relevant worker package as follows:

  1. First you'll need to add a file called <worker_dir>/spatialos_worker_packages.json to download the header files and libraries to <worker_dir>/dependencies/worker_sdk.
    In this file, we specify a set of packages to download during spatial worker build. We've provided an example below to start you off.
    In this example, we download both the Multithreaded Dynamic (MD) and Multithreaded Dynamic Debug (MDd) packages on Windows, plus binaries for macOS and Linux platforms to enable cross platform development. You'd need to later set up a build system and import the relevant libraries into your chosen build system.

spatialos_worker_packages.json:

{
  "targets": [
    {
      "path": "dependencies/worker_sdk/headers",
      "type": "worker_sdk",
      "packages": [
        {
          "name": "c_headers"
        }
      ]
    },
    {
      "path": "dependencies/worker_sdk/lib/windows/debug",
      "type": "worker_sdk",
      "packages": [
        {
          "name": "c-static-x86_64-vc141_mdd-win32"
        }
      ]
    },
    {
      "path": "dependencies/worker_sdk/lib/windows/release",
      "type": "worker_sdk",
      "packages": [
        {
          "name": "c-static-x86_64-vc141_md-win32"
        }
      ]
    },
    {
      "path": "dependencies/worker_sdk/lib/macos",
      "type": "worker_sdk",
      "packages": [
        {
          "name": "c-static-x86_64-clang-macos"
        }
      ]
    },
    {
      "path": "dependencies/worker_sdk/lib/linux",
      "type": "worker_sdk",
      "packages": [
        {
          "name": "c-static-x86_64-gcc510-linux"
        }
      ]
    }
  ]
}
  1. In a terminal, cd to <worker_dir> and run spatial package unpack (which is done automatically by spatial worker build if unpack dependencies is specified in the build.json).
    This will unpack the worker package specified above into the sub-directory. The downloaded worker package will be compatible with the SpatialOS SDK version used for your application (specified in <root>/spatialos.json under sdk_version).

Head to Building a worker for the next steps.


2021-jun-29 Page updated with editorial review: Removed reference to PS4 and Xbox One.

Updated 2 months ago


Setup and installation


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.