Reproduce CI/CD

Reproduce CI/CD#

This guide explains how to reproduce CI checks and tests locally, and how wheel builds and releases work. Workflows are defined under .github/workflows/ and ci/jenkins/. To build the project from source, see Build from Source.

Linters#

Pre-commit#

The project uses pre-commit to run linters and formatters. All hooks are defined in .pre-commit-config.yaml. Install and register the hooks so they run automatically before each commit:

uv sync --only-group lint
uv run --no-sync pre-commit install

You can also run hooks manually:

# Run all hooks on every file
uv run --no-sync pre-commit run --all-files

# Run only on staged files
uv run --no-sync pre-commit run

# Run a single hook in isolation
uv run --no-sync pre-commit run ruff-check --all-files
uv run --no-sync pre-commit run clang-format --all-files

The main tools are:

  • Python – ruff checks and formats Python code.

  • C/C++ – clang-format formats native code.

  • YAML – yamllint checks syntax and style.

  • TOML – taplo formats configuration files.

  • Repository checks – ASF headers, allowed file types, whitespace, and generated CUDA launch files.

Hooks may fix files in place. Review the changes, stage them, and run again. Use pre-commit clean if a stale hook environment causes problems.

C++ Tests#

Configure, build, and run locally in the project .venv:

uv sync --only-group build
uv run --no-sync cmake . -B build_test -G Ninja -DTVM_TIRX_BUILD_TESTS=ON -DCMAKE_BUILD_TYPE=Debug
uv run --no-sync cmake --build build_test --config Debug --target tirx_cpptest
uv run --no-sync ctest -V -C Debug --test-dir build_test --output-on-failure

CMake uses an installed GoogleTest package or fetches it when needed. On Windows, run from a Visual Studio Developer Command Prompt.

Python Tests#

Reproduce locally in the project .venv:

# Install the editable package and test dependencies
uv sync --no-default-groups --group test

# Run the CPU tests
uv run --no-sync pytest -vvs tests/python -m "not gpu"

Use -m gpu for device tests with the matching backend, SDK, and hardware. For CUDA tests, add --group cuda to the sync command above. Pass a test file or directory to focus on the component you changed.

Build Python Wheels#

CI builds wheels using cibuildwheel on Linux (x86_64, aarch64), Windows (AMD64), and macOS (arm64). Wheel configuration lives in [tool.cibuildwheel] in pyproject.toml. Isolated builds install the exact LLVM/Z3 SDK pins from [build-system].requires; no separate LLVM prefix or Conda environment is needed. Linux builds require Docker. macOS arm64 wheels require MACOSX_DEPLOYMENT_TARGET=14.0, matching the pinned SDK. The separate Windows CUDA runtime sidecar still uses its existing Conda CUDA toolkit installer; that is independent of LLVM/Z3 discovery.

To build wheels locally:

uv tool install cibuildwheel
cibuildwheel --output-dir dist

TIRx uses TVM-FFI for bindings, making it agnostic to Python versions. The project sets wheel.py-api = "py3", so its py3-none-<platform> wheel works across supported Python 3 versions without rebuilding TIRx for each minor version. The package requires Python 3.10 or newer (classifiers list 3.10–3.13), with compatible TVM-FFI and other dependencies. OS, CPU architecture, and native runtime requirements still apply.

See also