Build and Configuration Options Reference#

This document provides a comprehensive technical reference for accelerator backends, environment variables, CMake build options, and C++ native extension integration in FlagGems.

1. Supported Accelerator Backends#

FlagGems maintains src/flag_gems/backends.yaml as the single source of truth for all hardware backend configurations and dependency stacks.

1.1 Querying Available Backends#

In an environment where flag_gems is installed, you can query all supported backend names using the flaggems-setup CLI tool:

flaggems-setup --list

1.2 Backends and Build Matrix#

The table below summarizes the mainstream hardware accelerator platforms, recommended Python versions, and corresponding C++ native extension backends (cmake_backend):

Each entry in backends.yaml specifies:

• Recommended Python runtime version;
• PyTorch dependencies and vendor-specific accelerator packages;
• Triton or FlagTree compiler distribution compatible with the hardware;
• Environment variables and setup scripts automatically sourced into .venv/bin/activate.

2. Environment Variables Reference#

Use the following environment variables to control installation, build options, and runtime dispatch:

2.1 Compiler and Build Control#

2.2 Runtime Control#

2.3 Device Visibility and Isolation#

When running in multi-GPU or shared multi-tenant clusters, isolate visible devices using the platform-specific environment variables:

3. CMake Build Options Reference#

When building C++ extensions (ENABLE_CPP=1), setup.sh sets appropriate CMake options automatically.

For manual builds or custom packaging, pass options via the CMAKE_ARGS environment variable:

CMAKE_ARGS="-DFLAGGEMS_BUILD_C_EXTENSIONS=ON -DFLAGGEMS_BACKEND=CUDA -DFLAGGEMS_BUILD_CTESTS=ON" \
  uv pip install --no-build-isolation ./cpp

3.1 CMake Parameters#

4. scikit-build-core Options#

The primary Python package flag-gems uses standard setuptools. scikit-build-core is used only when building C++ extensions from the cpp/ directory (e.g. flag-gems-cpp-cuda).

scikit-build-core bridges CMake with Python packaging tools and accepts configuration through the following environment variables:

4.1 Configuration Variables#

1. SKBUILD_CMAKE_BUILD_TYPE: CMake build configuration mode.
   • Values: Release (recommended), Debug, RelWithDebInfo, MinSizeRel.
2. SKBUILD_BUILD_DIR: Output directory for build artifacts.
   • Default: build/{cache_tag} (configured in pyproject.toml).
3. SKBUILD_CMAKE_ARGS: Arguments passed directly to CMake.

Delimiter difference:

• Multiple options in CMAKE_ARGS are separated by spaces (CMAKE_ARGS="-DFOO=1 -DBAR=2").
• Multiple options in SKBUILD_CMAKE_ARGS must be separated by semicolons (SKBUILD_CMAKE_ARGS="-DFOO=1;-DBAR=2").

5. External libtriton_jit Library Integration#

FlagGems C++ extensions rely on libtriton_jit, an open-source C++ runtime that enables C++ programs to execute Triton JIT GPU/NPU kernels.

By default, the build system handles dependencies automatically. If you want to use a locally compiled or custom version of TritonJIT:

1. Build and install libtriton_jit to a custom path (e.g. /usr/local/lib/libtriton_jit);
2. Enable external TritonJIT and pass -DTritonJIT_ROOT=<install path> to CMake:

CMAKE_ARGS="-DFLAGGEMS_BUILD_C_EXTENSIONS=ON -DFLAGGEMS_USE_EXTERNAL_TRITON_JIT=ON -DTritonJIT_ROOT=/usr/local/lib/libtriton_jit" \
ENABLE_CPP=1 ./setup.sh nvidia-cuda128