Build Instructions

Overview

Building the Steam Audio SDK involves the following steps:

  1. Building the SDK binaries (phonon.dll on Windows, for example). This step involves compiling C++ code, and must be done separately on each supported platform.

  2. (Optional) Generating the zip file (steamaudio.zip) for distribution.

Directory Structure

Below is an overview of the directories contained within the source repository for the Steam Audio SDK:

Directory

Contents

bin/

Compiled binaries placed by the INSTALL target of the build system generated by CMake.

build/

Build scripts and the build system generated by CMake.

deps/

Third-party tools and libraries that the SDK depends on.

dist/

The zip file generated by the PACKAGE target.

doc/

Documentation.

src/

Source code.

src/core/

C++ source code for the Steam Audio SDK.

src/test/

C++ source code for unit tests.

src/itest/

C++ source code for interactive tests involving listening and/or visualization.

src/benchmark/

C++ source code for performance benchmarks.

src/samples/

C++ source code for sample programs.

Building the SDK

Requirements

To build the SDK on any platform, you need the following software:

To build for Windows, you will need:

To build for Linux, you will need:

  • g++ 4.8 or later (install using your distribution’s package manager)

  • g++-multilib 4.8 or later if building the 32-bit binaries on a 64-bit system (install using your distribution’s package manager)

  • glibc 2.19 or later

To build for macOS, you will need:

  • Xcode 7.0 or later (install from the Mac App Store)

To build for Android, you will need:

To build for iOS, you will need:

  • Xcode 14.0 or later (install from the Mac App Store)

Setting up third-party libraries

Steam Audio depends on multiple third-party libraries, which are not included in the source distribution. Before building Steam Audio, you must download them using:

$ cd build
$ python get_dependencies.py --platform <platform>

This will download all third-party dependencies, build them for the platform <platform> from source, and place them in the appropriate location under deps/.

The get_dependencies.py script understands the following command-line parameters:

--platform <platform>

The target platform that dependencies should be downloaded for. Use the --help parameter to see a list of currently-supported platforms.

—architecture <architecture> The target CPU architecture that dependencies should be downloaded for. Use the --help parameter to see a list of currently-supported architectures.

--toolchain <version>

The version of Visual Studio to use. This is required when either the host platform or the target platform is Windows, i.e., if either you are building for Windows, or are building for another platform on a Windows system. Use the --help parameter to see a list of currently-supported Visual Studio versions.

—ndk <path> The absolute path to the Android NDK. This is required when the target platform is Android.

--clean <option>

If <option> is output, then all dependencies will be removed from deps/. If <option> is build, then all intermediate build files for the dependencies will be removed. If <option> is all, then the both the dependencies as well as their intermediate build files will be removed.

—dependency <name> Download and build/extract only the dependency called <name>. This is intended mainly for troubleshooting purposes. For a full list of dependencies, refer to the dependencies.json file, and the comments in get_dependencies.py.

--extra

Also build certain dependencies that are marked as “extra”. These are optional dependencies, and may have complicated build system requirements, so are disabled by default.

—debug Build debug binaries.

Note

One of the dependencies, Radeon Rays (https://github.com/GPUOpen-LibrariesAndSDKs/RadeonRays_SDK), requires Visual Studio 2015 (or the Visual Studio 2015 Build Tools) and Intel Integrated Performance Primitives (see Closed-sourc dependencies below) in order to build. This dependency only applies to Windows 64-bit builds, and is optional. If get_dependencies.py is unable to build Radeon Rays successfully for any reason, the Steam Audio CMake scripts will automatically disable this functionality.

Note

The get_dependencies.py script will create a directory called deps-build under core. This directory contains downloaded source code and binary files, along with intermediate build files for all the dependencies. Nothing in this directory needs to be checked in to any form of source control. After the dependencies are successfully built and copied to deps by the script, deps-build can be safely deleted.

Closed-source dependencies

Some dependencies are closed-source and cannot currently be downloaded automatically. These are all optional, and if they are not present, Steam Audio will automatically switch to using open-source alternatives, or disable the feature.

For Windows, Linux, and macOS:

  • Intel Integrated Performance Primitives (IPP). Provides high-performance vector math and FFT implementations on Intel-based PC platforms. This is an optional dependency, and Steam Audio will fall back to using built-in vector math implementations, and PFFFT for FFT implementations. However, IPP is recommended in order to achieve the same performance as the binaries shipped with Steam Audio releases. Download from https://www.intel.com/content/www/us/en/developer/tools/oneapi/ipp.html, and install using the downloaded installer. Find the directory under your IPP installation that contains the files ipp.h, ippvm.h, and ipps.h. Place the contents of this directory in deps/ipp/include. Place ippcoremt.lib / libippcore.a, ippvmmt.lib / libippvm.a, and ippsmt.lib / libipps.a in the appropriate platform-specific subdirectory of deps/ipp/lib.

Note

In the above instructions, “platform-specific subdirectory of lib/” means:

  • lib/windows-x86 for Windows 32-bit

  • lib/windows-x64 for Windows 64-bit

  • lib/linux-x86 for Linux 32-bit

  • lib/linux-x64 for Linux 64-bit

  • lib/osx for macOS

  • lib/android-armv7 for Android 32-bit ARM (ARMv7)

  • lib/android-armv8 for Android 64-bit ARM (ARMv8)

  • lib/android-x86 for Android 32-bit Intel

  • lib/android-x64 for Android 64-bit Intel

  • lib/ios for iOS

Building the SDK

Building using the build script

To build, run the following from a command prompt in the core directory of the repository:

$ cd build
$ python build.py --minimal

This will generate a build system that can build the Steam Audio SDK and unit tests with minimal dependencies. This means that several features that require additional dependencies will be disabled, but allows you to get a working build quickly.

On Windows, this will generate a Visual Studio 2015 solution for 64-bit Windows (build/windows-vs2015-x64/Phonon.sln) and build it in the Release configuration.

On Linux, this will generate a Makefile for 64-bit Linux (build/linux-x64-release/Makefile) and build it.

On macOS, this will generate an Xcode project (build/osx/Phonon.xcodeproj) and build it in the Release configuration.

On Android, this will generate a Makefile for 32-bit ARM (build/android-armv7-release/Makefile) and build it.

On iOS, this will generate an Xcode project (build/ios/Phonon.xcodeproj) and build it in the Release configuration.

If CMake cannot generate the build system due to missing dependencies, you can run CMake directly and adjust settings that control where CMake looks for dependencies, and which targets it builds.

The Steam Audio build script (build.py) lets you specify the following command line parameters to control its behavior:

-p, --platform NAME

Specifies the target platform. Valid options are windows, linux, osx, android, and ios. Default is the current host platform.

-t, --toolchain NAME

Specifies the compiler version (on Windows only). Valid options are vs2013, vs2015, vs2017, vs2019. Default is vs2015.

-a, --architecture NAME

Specifies the CPU architecture to build for. Valid options are x86 (32-bit Intel, available on Windows, Linux, and Android), x64 (64-bit Intel, available on Windows, Linux, macOS, and Android), armv7 (32-bit ARM, available on Android), and arm64 (64-bit ARM, available on Android and iOS). Default is x64 for Windows, Linux, and macOS; armv7 for Android; and arm64 for iOS.

-c, --configuration NAME

Specifies the build configuration. Valid options are debug and release. Default is release.

-o, --operation NAME

Specifies the CMake operation to perform. Valid options are generate (generates the build system), build (build all targets in the build system), install (runs the INSTALL target, which copies binaries to the bin/ folder), package (runs the PACKAGE target, which generates the zip file and copies it to the dist/ folder), ci_build (which runs generate, then build, then install), and ci_package (which runs generate, then package). Default is generate followed by build.

—minimal Specifies that the generated build system should use minimal dependencies. This means that documentation, interactive tests, benchmarks, and sample programs will not be built. Support for Embree, Radeon Rays, and TrueAudio Next will also be disabled, and Intel IPP will also be disabled.

Building using CMake directly

You can also directly using CMake to generate the build system. This is useful if you need to specify non-default paths for CMake to search for dependencies. To do this, first create the directory in which you want to generate the build system:

$ cd build
$ mkdir windows-vs2019-x64

Now run CMake:

$ cmake ../..

Alternatively, use cmake-gui if you prefer using a GUI to configure various CMake options:

$ cmake-gui ../..

When building for Android, Steam Audio provides the following toolchain files that you can use:

Toolchain File

Platform

build/toolchain_android_armv7.cmake

32-bit ARM

build/toolchain_android_armv8.cmake

64-bit ARM

build/toolchain_android_x86.cmake

32-bit Intel

build/toolchain_android_x64.cmake

64-bit Intel

When building for iOS, Steam Audio provides the following toolchain files that you can use:

Toolchain File

Platform

build/toolchain_ios.cmake

64-bit ARM

Below are some of the CMake options you may want to configure:

Option

Description

BUILD_SHARED_LIBS

Build shared libraries instead of static.

STEAMAUDIO_BUILD_TESTS

Build unit tests.

STEAMAUDIO_BUILD_ITESTS

Build interactive tests. (Windows x64 only)

STEAMAUDIO_BUILD_BENCHMARKS

Build benchmarks.

STEAMAUDIO_BUILD_SAMPLES

Build samples.

STEAMAUDIO_BUILD_DOCS

Build documentation.

STEAMAUDIO_ENABLE_AVX

Enable AVX intrinsics. (Windows only)

STEAMAUDIO_ENABLE_IPP

Enable Intel IPP support for accelerated FFT and vector math operations. (Windows, Linux, macOS only)

STEAMAUDIO_ENABLE_FFTS

Enable FFTS support for accelerated FFT operations. (Android only)

STEAMAUDIO_ENABLE_EMBREE

Enable Intel Embree support for ray tracing. (Windows, Linux, macOS only)

STEAMAUDIO_ENABLE_RADEONRAYS

Enable AMD Radeon Rays support for GPU-accelerated ray tracing. (Windows x64 only)

STEAMAUDIO_ENABLE_TRUEAUDIONEXT

Enable AMD TrueAudio Next support for GPU-accelerated convolution. (Windows x64 only)

Generating the zip file

As an optional step, you can package the SDK, including documentation, into a zip file. To do this, run the following from a command prompt in the core directory of the repository:

$ cd build
$ python build.py -o install
$ python build.py -o package

This will place the generated zip file in dist/steamaudio.zip.