Build and install

Build the SDK in one directory and install it into a new prefix. Keep those paths separate from any other checkout so headers, libraries, and package metadata cannot be mixed.

Requirements

• CMake 3.22 or newer.
• A compiler and standard library with C++20 support.
• For the documented audio-file path, a real libsndfile installation exporting the CMake target SndFile::sndfile.

The SDK can be configured without the file provider for host-neutral code, but reader and writer factories then return nullptr and file capability queries report unavailable. The procedure below deliberately selects SndFile so the installed package can run the audio-file example.

Build from source

If you do not already have the checkout, clone it and select the documented revision:

git clone https://github.com/boot-industries/treefall-sdk.git /tmp/treefall-sdk-docs-source
git -C /tmp/treefall-sdk-docs-source checkout --detach b8c8b87540fe585b5c7d5c8f25d193c1a1af93d5

Set paths for the source checkout, build tree, and install prefix. The source directory must be the documented SDK checkout.

export SDK_SOURCE=/path/to/treefall-sdk
export SDK_BUILD=/tmp/treefall-sdk-0.9.0-build
export SDK_PREFIX=/tmp/treefall-sdk-0.9.0-install
rm -rf "$SDK_BUILD" "$SDK_PREFIX"

cmake -S "$SDK_SOURCE" -B "$SDK_BUILD" \
  -DCMAKE_BUILD_TYPE=Release \
  -DCMAKE_INSTALL_PREFIX="$SDK_PREFIX" \
  -DORPHEUS_ENABLE_REALTIME=ON \
  -DORP_WITH_TESTS=OFF \
  -DORPHEUS_ENABLE_EXTENDED_TESTS=OFF \
  -DORPHEUS_SNDFILE_PROVIDER=SndFile
cmake --build "$SDK_BUILD"

ORPHEUS_ENABLE_REALTIME=ON adds transport, routing, audio I/O, and driver-manager targets. The source build tree is useful for building SDK-owned programs, but it is not the installed package boundary.

Install the package

cmake --install "$SDK_BUILD"

The prefix contains public headers, libraries, CMake package files, and the installed target manifest. Configure a separate consumer by pointing CMAKE_PREFIX_PATH at this prefix:

cmake -S /path/to/your-app -B /tmp/your-app-build \
  -DCMAKE_PREFIX_PATH="$SDK_PREFIX" \
  -DCMAKE_BUILD_TYPE=Release
cmake --build /tmp/your-app-build

The next page shows find_package(TreefallSDK 0.9.0 EXACT REQUIRED CONFIG) and the compatibility targets. Do not add the SDK source or build directories to a consumer’s include paths.

When configuration stops

• CMake is too old: install CMake 3.22 or newer; do not bypass the minimum.
• C++20 is unavailable: select a compiler/standard library with C++20 support.
• SndFile::sndfile is missing: install a development package that exports that target, then configure again. Selecting SndFile is intentionally a hard error when the target cannot be found.
• The consumer finds the wrong version or targets: remove its build directory and configure it with only the intended SDK_PREFIX. If necessary, delete and recreate both the SDK build and install directories.
• A file factory is null or file operations return NotReady: the package was built without a usable file provider. Rebuild with -DORPHEUS_SNDFILE_PROVIDER=SndFile and install into a new prefix.
• A device target is absent: a successful core build does not imply hardware support. Check the installed target manifest and runtime driver capabilities; use Dummy or host-neutral APIs when the platform has no supported production backend.

The build options and install layout are defined in the CMake project at this source revision. Provider resolution is in the audio I/O CMake configuration; installed dependency checks are in the Treefall package configuration and compatibility package configuration.