Cmake

CMake Build Guide

Requirements: CMake 3.26+, Ninja (recommended), C++20 compiler (MSVC/Clang/GCC).

Quick Start

cmake -S . -B build -G Ninja -D CMAKE_BUILD_TYPE=Release
cmake --build build
cmake --install build --prefix dist

Platform specifics:

Linux:

export CC=clang-20 CXX=clang++-20
cmake -S . -B build -G Ninja -D CMAKE_BUILD_TYPE=Release

macOS:

export PATH="$PATH:/opt/homebrew/opt/llvm/bin"
export CC=/opt/homebrew/opt/llvm/bin/clang
export CXX=/opt/homebrew/opt/llvm/bin/clang++
export SDKROOT=$(xcrun --show-sdk-path)
cmake -S . -B build -G Ninja -D CMAKE_BUILD_TYPE=Release

Windows: Requires VS Developer Command Prompt. Or use Python bootstrap:

import bootstrap
bootstrap.prepare_msvc_environment()

scripts/agent_windows_cmake.py

One-shot configure + build + verify on Windows. CI-matching flags (LUISA_COMPUTE_ENABLE_RUST=OFF, LUISA_COMPUTE_ENABLE_REMOTE=OFF, LUISA_COMPUTE_ENABLE_CPU=OFF).

# Full pipeline: configure → build → verify
python scripts/agent_windows_cmake.py

# Individual steps
python scripts/agent_windows_cmake.py --config          # configure only
python scripts/agent_windows_cmake.py --build           # build only
python scripts/agent_windows_cmake.py --verify          # check key .lib/.dll outputs
python scripts/agent_windows_cmake.py --clean           # clear CMake cache

# Options
python scripts/agent_windows_cmake.py --type Debug      # Debug build
python scripts/agent_windows_cmake.py -j 8              # limit parallel jobs
python scripts/agent_windows_cmake.py --clean --config  # clean re-configure

Auto-finds cmake and ninja (PATH → .deps/ → pip). Auto-prepares MSVC environment via vswhere. Verifies: SPIRV-Tools-opt.lib, SPIRV-Tools.lib, luisa-ast.dll, luisa-core.dll.

Build Options

LUISA_COMPUTE_USE_SYSTEM_* options exist for STL, GLFW, LMDB, REPROC, SPDLOG, XXHASH, YYJSON, MAGIC_ENUM, and MARL.

The two Vulkan SPIR-V codegen options are mutually exclusive. The LLVM path also builds/links the common luisa-compute-spirv support library because the Vulkan artifact codec shares its SPIR-V validation and feature-reconciliation utilities.

CI minimal build:

cmake -S . -B build -G Ninja -D CMAKE_BUILD_TYPE=Release \
  -D LUISA_COMPUTE_ENABLE_RUST=OFF -D LUISA_COMPUTE_ENABLE_REMOTE=OFF \
  -D LUISA_COMPUTE_ENABLE_CPU=OFF
cmake --build build

Target Naming

Module Hierarchy

luisa-compute-include (INTERFACE, header-only)
  → luisa-compute-ext (INTERFACE, third-party deps)
    → luisa-compute-core (SHARED)
      → luisa-compute-ast (SHARED)
        → luisa-compute-xir (SHARED)
        → luisa-compute-ir (SHARED when Rust enabled)
      → luisa-compute-runtime (SHARED)
        → luisa-compute-dsl, luisa-compute-gui, luisa-compute-ir
          → luisa-compute-backends (INTERFACE aggregator)

Additional modules linked by the umbrella target luisa::compute include luisa-compute-vstl (object helper), luisa-compute-osl, luisa-compute-api, and luisa-compute-clangcxx.

Custom CMake Functions

luisa_compute_add_backend(name [SOURCES ...] [SUPPORT_DIR dir])

Creates a backend plugin MODULE target. Links luisa-compute-ast, luisa-compute-runtime, and luisa-compute-gui. Output name is luisa-backend-<name> and runtime artifacts are installed to bin/. If SUPPORT_DIR is given, its contents are copied next to the runtime outputs and installed to bin/.

luisa_compute_add_backend(cuda SOURCES ${LUISA_COMPUTE_CUDA_SOURCES})

luisa_compute_install(target)

Installs target with consistent destination paths.

luisa_compute_install(core SOURCES ${LUISA_COMPUTE_CORE_SOURCES})

luisa_compute_add_executable(name)

Creates executable linked to luisa::compute.

luisa_compute_add_executable(my_app)

luisa_compute_add_test(name source [LABELS ...] [ARGS ...])

File: src/tests/CMakeLists.txt. Builds one standalone executable per source. With LABELS, registers a CTest entry (CPU-only tests). Without LABELS, just builds the binary (GPU-using tests are invoked manually with a backend arg).

luisa_compute_add_test(test_basic_traits unit/core/test_basic_traits.cpp LABELS "unit;unit_core")
luisa_compute_add_test(test_my_gpu unit/runtime/test_my_gpu.cpp)  # no CTest

luisa_compute_add_example(name source... [MIRROR_AS_TEST])

File: examples/CMakeLists.txt. Builds example_<name> and, when MIRROR_AS_TEST is set, additionally builds a test_<name> mirror executable from the same sources. Reserved for auto-checkable examples (reference-image comparison, deterministic sims, headless compute). GUI/interop demos must omit the flag.

luisa_compute_add_example(example_path_tracing rendering/path_tracing.cpp MIRROR_AS_TEST)
luisa_compute_add_example(example_swapchain_qt gui/swapchain_qt.cpp)  # no mirror

luisa_example_pair_link(name <link-args>)

Companion to luisa_compute_add_example. Calls target_link_libraries on both example_<name> and its test_<name> mirror (if any). Use whenever an example needs extra libs.

luisa_compute_add_example(example_cuda_lcub extension/cuda_lcub.cpp MIRROR_AS_TEST)
luisa_example_pair_link(example_cuda_lcub PRIVATE CUDA::cudart CUDA::cuda_driver)

Backend Plugin Build

Backends built as MODULE (runtime-loadable shared libs):

luisa_compute_add_backend(cuda SOURCES ${LUISA_COMPUTE_CUDA_SOURCES})

Key: output renamed to luisa-backend-<name>, installed to bin/, supports luisa_embed_device_lib for builtin device libs.

Rust Integration

File: src/rust/CMakeLists.txt

Rust support is auto-enabled when a Rust toolchain is found (unless LUISA_COMPUTE_ENABLE_RUST=OFF is passed); the CPU and Remote backends require it. The custom command invokes cargo build (profile: dev for Debug, release for Release). CMake targets:

• luisa-compute-rust-meta (INTERFACE): static Rust libs
• luisa_compute_backend_impl (INTERFACE): shared Rust backend

Third-Party Extension Pattern

Each src/ext/<lib>/:

if (LUISA_COMPUTE_USE_SYSTEM_<LIB>)
    find_package(<LIB> REQUIRED)
    target_link_libraries(luisa-compute-ext INTERFACE <target>)
    target_compile_definitions(luisa-compute-ext INTERFACE LUISA_USE_SYSTEM_<LIB>=1)
else()
    add_subdirectory(<lib>)
    target_link_libraries(luisa-compute-ext INTERFACE <target>)
    luisa_compute_install_extension(<target> ...)
endif()

Output & RPATH

${CMAKE_BINARY_DIR}/bin  → Runtime outputs (DLLs, executables)
${CMAKE_BINARY_DIR}/lib  → Archive outputs (static libs, PDBs)

• macOS: @loader_path, @loader_path/../bin, @loader_path/../lib
• Linux: $ORIGIN, $ORIGIN/../bin, $ORIGIN/../lib