Building the ML SDK Scenario Runner

The build system must have:

  • C/C++ 17 compiler: GCC or Clang on Linux, Clang on Darwin, or MSVC on Windows®.

  • CMake 3.25 or later.

  • Ninja 1.8.2 or later.

  • Python 3.10 through 3.14 and uv 0.9.26. Runtime, test, and tooling dependencies are declared in pyproject.toml and locked in uv.lock.

The following dependencies are also needed:

For the preferred dependency versions see the manifest file.

Building with the script

To build on Linux, run the following command:

SDK_PATH="path/to/sdk"
python3 ${SDK_PATH}/sw/scenario-runner/scripts/build.py -j $(nproc) \
    --flatbuffers-path ${SDK_PATH}/dependencies/flatbuffers \
    --argparse-path ${SDK_PATH}/dependencies/argparse \
    --json-path ${SDK_PATH}/dependencies/json \
    --vulkan-headers-path ${SDK_PATH}/dependencies/Vulkan-Headers \
    --glslang-path ${SDK_PATH}/dependencies/glslang \
    --dxc-path ${SDK_PATH}/dependencies/DirectXShaderCompiler \
    --spirv-headers-path ${SDK_PATH}/dependencies/SPIRV-Headers \
    --spirv-tools-path ${SDK_PATH}/dependencies/SPIRV-Tools \
    --vgf-lib-path ${SDK_PATH}/sw/vgf-lib \
    --gtest-path ${SDK_PATH}/dependencies/googletest

To build on Windows®, run the following command:

$env:SDK_PATH="path\to\sdk"
$cores = [System.Environment]::ProcessorCount
python "$env:SDK_PATH\sw\scenario-runner\scripts\build.py" -j $cores  `
    --flatbuffers-path "$env:SDK_PATH\dependencies\flatbuffers" `
    --argparse-path "$env:SDK_PATH\dependencies\argparse" `
    --json-path "$env:SDK_PATH\dependencies\json" `
    --vulkan-headers-path "$env:SDK_PATH\dependencies\Vulkan-Headers" `
    --glslang-path "$env:SDK_PATH\dependencies\glslang" `
    --dxc-path "$env:SDK_PATH\dependencies\DirectXShaderCompiler" `
    --spirv-headers-path "$env:SDK_PATH\dependencies\SPIRV-Headers" `
    --spirv-tools-path "$env:SDK_PATH\dependencies\SPIRV-Tools" `
    --vgf-lib-path "$env:SDK_PATH\sw\vgf-lib" `
    --gtest-path "$env:SDK_PATH\dependencies\googletest"

To build on Darwin from a Repo tool checkout, first configure the LunarG Vulkan® SDK for Darwin environment according to its documentation, then run:

export SDK_PATH=/absolute/path/to/ml-sdk
python3 "$SDK_PATH/sw/scenario-runner/scripts/build.py" \
    -j "$(sysctl -n hw.logicalcpu)"

At runtime, use the Vulkan® Loader to select either MoltenVK or KosmicKrisp and enable the ML Emulation Layer for Vulkan®. The ML SDK’s Darwin support is experimental.

To cross compile for AArch64 architecture, you can add the following option:

SDK_PATH="path/to/sdk"
python3 $SDK_PATH/sw/scenario-runner/scripts/build.py -j $(nproc) \
    --flatbuffers-path ${SDK_PATH}/dependencies/flatbuffers \
    --argparse-path ${SDK_PATH}/dependencies/argparse \
    --json-path ${SDK_PATH}/dependencies/json \
    --vulkan-headers-path ${SDK_PATH}/dependencies/Vulkan-Headers \
    --glslang-path ${SDK_PATH}/dependencies/glslang \
    --dxc-path ${SDK_PATH}/dependencies/DirectXShaderCompiler \
    --spirv-headers-path ${SDK_PATH}/dependencies/SPIRV-Headers \
    --spirv-tools-path ${SDK_PATH}/dependencies/SPIRV-Tools \
    --vgf-lib-path ${SDK_PATH}/sw/vgf-lib \
    --gtest-path ${SDK_PATH}/dependencies/googletest \
    --target-platform aarch64

(Experimental) To cross compile for Android™, and build an APK package, you must target Android™, provide the Android™ CMake toolchain, and request the apk package type.

SDK_PATH="path/to/sdk"
ANDROID_NDK_HOME="path/to/android-ndk"
python3 ${SDK_PATH}/sw/scenario-runner/scripts/build.py -j $(nproc) \
    --target-platform android \
    --cmake-toolchain-for-android ${ANDROID_NDK_HOME}/build/cmake/android.toolchain.cmake \
    --flatbuffers-path ${SDK_PATH}/dependencies/flatbuffers \
    --argparse-path ${SDK_PATH}/dependencies/argparse \
    --json-path ${SDK_PATH}/dependencies/json \
    --vulkan-headers-path ${SDK_PATH}/dependencies/Vulkan-Headers \
    --glslang-path ${SDK_PATH}/dependencies/glslang \
    --dxc-path ${SDK_PATH}/dependencies/DirectXShaderCompiler \
    --spirv-headers-path ${SDK_PATH}/dependencies/SPIRV-Headers \
    --spirv-tools-path ${SDK_PATH}/dependencies/SPIRV-Tools \
    --vgf-lib-path ${SDK_PATH}/sw/vgf-lib \
    --package-type apk

The APK build uses the gradle command, so Gradle 8.4 or later must be available on your PATH. The Android™ SDK installation pointed to by ANDROID_HOME should include build-tools;34.0.0 and platforms;android-34, or other compatible versions.

To build with RenderDoc support, add --enable-rdoc. If RenderDoc is installed outside the default search locations, also pass --renderdoc-path <renderdoc-install-root>.

At runtime, pass --capture-frame and enable the RenderDoc Vulkan® layer. When capturing a workload through the ML Emulation Layer for Vulkan®, order RenderDoc after the Graph and Tensor layers so it records the translated Vulkan® commands:

export VK_INSTANCE_LAYERS=VK_LAYER_ML_Graph_Emulation:VK_LAYER_ML_Tensor_Emulation:VK_LAYER_RENDERDOC_Capture
scenario-runner --capture-frame \
    --scenario scenario.json

Some RenderDoc configurations may not support VK_KHR_portability_enumeration. If RenderDoc reports that the extension is unsupported and the Vulkan® device does not require it, disable it with:

--disable-extension VK_KHR_portability_enumeration

To enable and run tests, use the --test flag. To lint the tests, use the --lint flag. To enable tests and documentation building python dependencies must be installed:

uv sync --locked --no-install-project --no-default-groups --group test --group tooling

Run build commands with uv run --no-sync python scripts/build.py to use the locked environment. To build documentation, pass --doc; Doxygen must also be installed on your machine.

You can install the build artifacts for this project into a specified location. To install the build artifacts, pass the --install option with the required path.

To create an archive with the build artifacts, you must add --package-type. The archive is stored in the provided location.

For more command line options, consult the program help:

python3 $SDK_PATH/sw/scenario-runner/scripts/build.py --help

Code coverage

Sync the locked test and tooling dependencies, then run the C++ and Python unit tests on Linux with GCC coverage instrumentation:

uv sync --locked --no-install-project --no-default-groups --group test --group tooling
uv run --no-sync python scripts/build.py --coverage --build-dir build-coverage

The coverage command writes a detailed HTML report to build-coverage/coverage/index.html and a machine-readable JSON summary to build-coverage/coverage/summary.json. Coverage is collected for Scenario Runner sources and public headers, including native code exercised through pytest. Python source-line coverage is not collected.