This is an automated email from the ASF dual-hosted git repository.
junrushao pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/tvm-ffi.git
The following commit(s) were added to refs/heads/main by this push:
new 245bd0d doc: More Developer Manuals (#437)
245bd0d is described below
commit 245bd0d2512ca164eb57b1c18da12245981a9b17
Author: Junru Shao <[email protected]>
AuthorDate: Sun Feb 8 14:04:43 2026 -0800
doc: More Developer Manuals (#437)
---
CONTRIBUTING.md | 174 ++-----------------------------
README.md | 41 ++++++--
docs/README.md | 91 +---------------
docs/_stubs/cpp_index.rst | 2 +
docs/conf.py | 9 ++
docs/dev/build_from_source.md | 98 -----------------
docs/dev/ci_cd.rst | 203 ++++++++++++++++++++++++++++++++++++
docs/dev/doc_build.rst | 129 +++++++++++++++++++++++
docs/dev/release_process.rst | 1 +
docs/dev/source_build.rst | 151 +++++++++++++++++++++++++++
docs/guides/export_func_cls.rst | 4 +-
docs/index.rst | 4 +-
docs/packaging/cpp_tooling.rst | 1 +
docs/packaging/python_packaging.rst | 5 +-
docs/reference/cpp/index.rst | 7 +-
15 files changed, 553 insertions(+), 367 deletions(-)
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 837df87..084b2f9 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -17,96 +17,8 @@
# Contributing to TVM FFI
-We welcome contributions of all kinds, including bug fixes, documentation
improvements, enhancements,
-and more. To ensure a smooth process, Here is a general guide to contributing.
-
-## Installation
-
-For development, you can install through editable installation:
-
-```bash
-git clone https://github.com/apache/tvm-ffi --recursive
-cd tvm-ffi
-pip install --no-build-isolation -e . -v
-```
-
-We recommend using the `--no-build-isolation` flag to ensure compatibility
with your existing environment.
-
-## Setting Up Pre-commit Hooks
-
-This project uses [pre-commit](https://pre-commit.com/) to maintain code
quality and consistency.
-Pre-commit hooks automatically check your code for common issues before you
commit changes.
-
-### Installing Pre-commit
-
-First, install pre-commit (requires version 2.18.0 or later):
-
-```bash
-pip install pre-commit
-```
-
-### Installing the Git Hooks
-
-After cloning the repository, install the pre-commit hooks:
-
-```bash
-cd tvm-ffi
-pre-commit install
-```
-
-This configures git to automatically run the hooks before each commit.
-
-### Running Hooks Manually
-
-You can run the hooks manually on all files:
-
-```bash
-pre-commit run --all-files
-```
-
-Or run them only on staged files:
-
-```bash
-pre-commit run
-```
-
-### What the Hooks Check
-
-The pre-commit configuration includes checks for:
-
-- **License headers**: Ensures all files have proper Apache Software
Foundation headers
-- **Code formatting**: Runs clang-format (C++), ruff (Python), shfmt (Shell
scripts)
-- **Linting**: Runs clang-tidy, ruff, shellcheck, markdownlint, yamllint, and
more
-- **Type checking**: Runs ty for Python type annotations
-- **File quality**: Checks for trailing whitespace, file sizes, merge
conflicts, etc.
-
-### Troubleshooting
-
-If you encounter errors:
-
-1. **Version issues**: Ensure you have pre-commit 2.18.0 or later:
-
- ```bash
- pre-commit --version
- pip install --upgrade pre-commit
- ```
-
-2. **Cache issues**: Clean the pre-commit cache:
-
- ```bash
- pre-commit clean
- ```
-
-3. **Hook failures**: Most formatting hooks will automatically fix issues.
Review the changes and stage them:
-
- ```bash
- git add -u
- git commit
- ```
-
-## Contributing Workflow
-
-You can contribute to the repo through the following steps.
+We welcome contributions of all kinds, including bug fixes, documentation
+improvements, enhancements, and more.
- Fork the repository and create a new branch for your work.
- Push your changes to your fork and open a pull request to the main
repository.
@@ -114,78 +26,14 @@ You can contribute to the repo through the following steps.
- Create necessary test cases and documentation.
- Work with the community by incorporating feedback from reviewers until the
change is ready to be merged.
-For significant changes, it's often a good idea to open a GitHub issue first
(with `[RFC] title`) to discuss your proposal.
-It is optional, but can be very helpful as it allows the maintainers and the
community to provide feedback and helps ensure your
-work aligns with the project's goals.
-
-## Development with Docker
-
-The repository ships a development container that contains the full toolchain
for
-building the core library, and running examples.
-
-```bash
-# Build the image (from the repository root)
-docker build -t tvm-ffi-dev -f tests/docker/Dockerfile tests/docker
-
-# Start an interactive shell
-docker run --rm -it \
- -v "$(pwd)":/workspace/tvm-ffi \
- -w /workspace/tvm-ffi \
- tvm-ffi-dev bash
-
-# Start an interactive shell with GPU access
-docker run --rm -it --gpus all \
- -v "$(pwd)":/workspace/tvm-ffi \
- -w /workspace/tvm-ffi \
- tvm-ffi-dev bash
-
-> **Note** Ensure the [NVIDIA Container
Toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html)
-> is installed on the host to make GPUs available inside the container.
-```
-
-Inside the container you can install the project in editable mode and run the
quick
-start example exactly as described in `examples/quick_start/README.md`:
-
-```bash
-# In /workspace/tvm-ffi/ see
https://tvm.apache.org/ffi/guides/build_from_source.html for reference
-pip install --force-reinstall --verbose -e . \
- --config-settings cmake.define.TVM_FFI_ATTACH_DEBUG_SYMBOLS=ON
-
-# Change working directory to sample
-cd examples/quickstart
-
-# Install dependency, Build and run all examples
-bash raw_compile.sh
-```
-
-All build artifacts are written to the mounted workspace on the host machine,
so you
-can continue editing files with your local tooling.
-
-## Stability and Minimalism
-
-C ABI stability is the top priority of this project. We also prioritize
minimalism and efficiency
-in the core so it is portable and can be used broadly.
-We also recognize potential needs for evolution to ensure it works best for
the machine
-learning systems community, and would like to work together collectively with
the community for such evolution.
-
-- When proposing a change, consider first whether things can be built on top
of the current mechanism.
-- We welcome RFCs and DISCUSS discussions for ABI discussions and rationales.
-- We will communicate very mindfully to the community about major changes.
-
-Feature improvements in the Python layer and C++ headers (that do not impact
the ABI) have
-comparatively less significant impacts on downstream users, so they can follow
normal contribution
-process in general open source projects.
-
-## Status and Release Versioning
-
-The project is in the RFC stage, which means the main features are complete.
-We anticipate the API will be reasonably stable but will continue to work with
the community to evolve it.
-More importantly, the RFC stage is a period where we are working with the open
source communities
-to ensure we evolve the ABI to meet the needs of frameworks.
+For significant changes, it's often a good idea to open a GitHub issue first
+(with `[RFC] title`) to discuss your proposal. It is optional, but can be very
+helpful as it allows the maintainers and the community to provide feedback and
+helps ensure your work aligns with the project's goals.
-Releases during the RFC stage will be `0.X.Y`, where bumps in `X` indicate C
ABI-breaking changes
-and `Y` indicates other changes. We may also produce pre-releases (beta
releases) during this period.
+The full developer manual is hosted at <https://tvm.apache.org/ffi/>. Key
pages:
-We anticipate the RFC stage will last for a few months, then we will start to
follow
-[Semantic
Versioning](https://packaging.python.org/en/latest/discussions/versioning/)
-(`major.minor.patch`) going forward.
+- [Build from Source](https://tvm.apache.org/ffi/dev/source_build.html) --
editable install, CMake flags, C++-only build
+- [Build This Doc Site](https://tvm.apache.org/ffi/dev/doc_build.html) --
building the documentation locally
+- [Reproduce CI/CD](https://tvm.apache.org/ffi/dev/ci_cd.html) -- linters,
pre-commit, unit tests, wheel building
+- [Release Process](https://tvm.apache.org/ffi/dev/release_process.html) --
versioning and release workflow
diff --git a/README.md b/README.md
index 0f2f22b..3430275 100644
--- a/README.md
+++ b/README.md
@@ -46,12 +46,6 @@ pip install apache-tvm-ffi
pip install torch-c-dlpack-ext # compatibility package for torch <= 2.9
```
-Visit our [documentation](https://tvm.apache.org/ffi/) to learn more.
-
-- [Quick Start](https://tvm.apache.org/ffi/get_started/quickstart.html)
-- [Stable C ABI](https://tvm.apache.org/ffi/get_started/stable_c_abi.html)
-- [Python
Packaging](https://tvm.apache.org/ffi/packaging/python_packaging.html)
-
## Status and Release Versioning
**C ABI stability** is our top priority.
@@ -64,3 +58,38 @@ Releases during the RFC stage will be `0.X.Y`, where bumps
in `X` indicate C ABI
and `Y` indicates other changes. We anticipate the RFC stage will last for
three months, then we will start following
[Semantic
Versioning](https://packaging.python.org/en/latest/discussions/versioning/)
(`major.minor.patch`) going forward.
+
+## Documentation
+
+Our [documentation site](https://tvm.apache.org/ffi/) includes:
+
+### Get Started
+
+- [Quick Start](https://tvm.apache.org/ffi/get_started/quickstart.html)
+- [Stable C ABI](https://tvm.apache.org/ffi/get_started/stable_c_abi.html)
+
+### Guides
+
+- [Export Functions &
Classes](https://tvm.apache.org/ffi/guides/export_func_cls.html)
+- [Kernel Library
Guide](https://tvm.apache.org/ffi/guides/kernel_library_guide.html)
+
+### Concepts
+
+- [ABI Overview](https://tvm.apache.org/ffi/concepts/abi_overview.html)
+- [Any](https://tvm.apache.org/ffi/concepts/any.html)
+- [Object & Class](https://tvm.apache.org/ffi/concepts/object_and_class.html)
+- [Tensor](https://tvm.apache.org/ffi/concepts/tensor.html)
+- [Function & Module](https://tvm.apache.org/ffi/concepts/func_module.html)
+- [Exception
Handling](https://tvm.apache.org/ffi/concepts/exception_handling.html)
+
+### Packaging
+
+- [Python
Packaging](https://tvm.apache.org/ffi/packaging/python_packaging.html)
+- [Stub Generation](https://tvm.apache.org/ffi/packaging/stubgen.html)
+- [C++ Tooling](https://tvm.apache.org/ffi/packaging/cpp_tooling.html)
+
+### Developer Manual
+
+- [Build from Source](https://tvm.apache.org/ffi/dev/source_build.html)
+- [Reproduce CI/CD](https://tvm.apache.org/ffi/dev/ci_cd.html)
+- [Release Process](https://tvm.apache.org/ffi/dev/release_process.html)
diff --git a/docs/README.md b/docs/README.md
index d790e07..4bbc562 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -14,94 +14,7 @@
<!--- KIND, either express or implied. See the License for the -->
<!--- specific language governing permissions and limitations -->
<!--- under the License. -->
-# TVM FFI Documentation
-
-This guide walks through building and maintaining the TVM FFI documentation
set.
-
-## Prerequisites
-
-- [`uv`](https://docs.astral.sh/uv/) manages the Python environment for all
docs commands.
-- Ensure you are in the repository root before running the commands below.
-- Optional: Install `Doxygen` if you plan to generate the C++ API reference
(see "Build with C++ Docs").
-
-## Build Workflows
-
-### Interactive build (auto-reload)
-
-Rebuilds and serves the documentation locally with live reload:
-
-```bash
-uv run --group docs sphinx-autobuild docs docs/_build/html --ignore
docs/reference/cpp/generated
-```
-
-By default, open `http://127.0.0.1:8000` in your browser after the initial
build completes.
-
-### One-off build
-
-Generates the HTML documentation once, without running a server:
-
-```bash
-uv run --group docs sphinx-build -M html docs docs/_build
-```
-
-### Build with C++ Docs
-
-Generating the C++ reference takes longer and requires Doxygen:
-
-```bash
-brew install doxygen # macOS
-sudo apt install doxygen # Linux
-```
-Set `BUILD_CPP_DOCS=1` on the desired build command to enable the extra step:
-
-```bash
-# Interactive build with auto-rebuild on C++ header changes
-BUILD_CPP_DOCS=1 uv run --group docs sphinx-autobuild docs docs/_build/html
--ignore docs/reference/cpp/generated --watch include
-# One-off build
-BUILD_CPP_DOCS=1 uv run --group docs sphinx-build -M html docs docs/_build
-```
-
-The C++ documentation will automatically rebuild when header files change
during `sphinx-autobuild` sessions.
-
-### Build with Rust Docs
-
-Generating the Rust reference requires `cargo` to be installed:
-
-```bash
-# Install Rust toolchain if not already installed
-curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
-```
-
-Set `BUILD_RUST_DOCS=1` on the desired build command to enable Rust
documentation:
-
-```bash
-# Interactive build with auto-rebuild on Rust source changes
-BUILD_RUST_DOCS=1 uv run --group docs sphinx-autobuild docs docs/_build/html
--ignore docs/reference/rust/generated --watch rust
-# One-off build (clean rebuild)
-BUILD_RUST_DOCS=1 uv run --group docs sphinx-build -M html docs docs/_build
-```
-
-The Rust documentation will automatically rebuild when source files change
during `sphinx-autobuild` sessions.
-
-### Build All Documentation
-
-To build documentation with all language references enabled:
-
-```bash
-# Interactive build
-BUILD_CPP_DOCS=1 BUILD_RUST_DOCS=1 uv run --group docs sphinx-autobuild docs
docs/_build/html --ignore docs/reference/cpp/generated --ignore
docs/reference/rust/generated --watch include --watch rust
-# One-off build
-BUILD_CPP_DOCS=1 BUILD_RUST_DOCS=1 uv run --group docs sphinx-build -M html
docs docs/_build
-```
-
-## Cleanup
-
-Remove generated artifacts when they are no longer needed:
+# TVM FFI Documentation
-```bash
-rm -rf docs/_build/
-rm -rf docs/reference/python/generated
-rm -rf docs/reference/cpp/generated
-rm -rf docs/reference/rust/generated
-```
+See the full guide at: <https://tvm.apache.org/ffi/dev/doc_build.html>
diff --git a/docs/_stubs/cpp_index.rst b/docs/_stubs/cpp_index.rst
index 766de11..06500e2 100644
--- a/docs/_stubs/cpp_index.rst
+++ b/docs/_stubs/cpp_index.rst
@@ -15,6 +15,8 @@
specific language governing permissions and limitations
under the License.
+:orphan:
+
==============
Full API Index
==============
diff --git a/docs/conf.py b/docs/conf.py
index 41e61b0..123b7c1 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -241,6 +241,14 @@ def _copy_rust_docs_to_output(app:
sphinx.application.Sphinx, exception: Excepti
)
+def _mark_exhale_root_orphan(
+ app: sphinx.application.Sphinx, docname: str, source: list[str]
+) -> None:
+ """Prepend :orphan: to exhale-generated root so it stays out of the
sidebar."""
+ if docname == "reference/cpp/generated/index":
+ source[0] = ":orphan:\n\n" + source[0]
+
+
def setup(app: sphinx.application.Sphinx) -> None:
"""Register custom Sphinx configuration values."""
_prepare_stub_files()
@@ -248,6 +256,7 @@ def setup(app: sphinx.application.Sphinx) -> None:
app.add_config_value("build_exhale", build_exhale, "env")
app.add_config_value("build_rust_docs", build_rust_docs, "env")
app.connect("config-inited", _apply_config_overrides)
+ app.connect("source-read", _mark_exhale_root_orphan)
app.connect("build-finished", _copy_rust_docs_to_output)
app.connect("autodoc-skip-member", _filter_inherited_members)
app.connect("autodoc-process-docstring", _link_inherited_members)
diff --git a/docs/dev/build_from_source.md b/docs/dev/build_from_source.md
deleted file mode 100644
index f5ba145..0000000
--- a/docs/dev/build_from_source.md
+++ /dev/null
@@ -1,98 +0,0 @@
-<!--- Licensed to the Apache Software Foundation (ASF) under one -->
-<!--- or more contributor license agreements. See the NOTICE file -->
-<!--- distributed with this work for additional information -->
-<!--- regarding copyright ownership. The ASF licenses this file -->
-<!--- to you under the Apache License, Version 2.0 (the -->
-<!--- "License"); you may not use this file except in compliance -->
-<!--- with the License. You may obtain a copy of the License at -->
-
-<!--- http://www.apache.org/licenses/LICENSE-2.0 -->
-
-<!--- Unless required by applicable law or agreed to in writing, -->
-<!--- software distributed under the License is distributed on an -->
-<!--- "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY -->
-<!--- KIND, either express or implied. See the License for the -->
-<!--- specific language governing permissions and limitations -->
-<!--- under the License. -->
-# Build from Source
-
-This guide covers two common workflows:
-
-- Python package building, which automatically includes building the core C++
library;
-- C++-only package Building without Python.
-
-```{admonition} Prerequisite
-:class: tip
-
-- Python: 3.9 or newer
-- Compiler: C++17-capable toolchain
- - Linux: GCC or Clang with C++17 support
- - macOS: Apple Clang (via Xcode Command Line Tools)
- - Windows: MSVC (Visual Studio 2019 or 2022, x64)
-- Build tools: CMake 3.18+; Ninja
-```
-
-## Build the Python Package
-
-Download the source via:
-
-```bash
-git clone --recursive https://github.com/apache/tvm-ffi
-cd tvm-ffi
-```
-
-```{note}
-Always clone with ``--recursive`` to pull submodules. If you already cloned
without it, run:
-
- git submodule update --init --recursive
-
-```
-
-Follow the instruction below to build the Python package with
scikit-build-core, which drives CMake to compile the C++ core and Cython
extension.
-
-```bash
-pip install --force-reinstall --verbose -e . \
- --config-settings cmake.define.TVM_FFI_ATTACH_DEBUG_SYMBOLS=ON
-```
-
-The ``--reinstall`` flag forces a rebuild, and ``-e/--editable`` install means
future Python-only changes are reflected immediately without having to rebuild.
-
-```{warning}
-However, changes to C++/Cython always require re-running the install command.
-```
-
-Verify the install:
-
-```bash
-python -c "import tvm_ffi; print(tvm_ffi.__version__)"
-tvm-ffi-config -h
-```
-
-```{tip}
-Use ``tvm-ffi-config`` to query include and link flags when consuming TVM FFI
from external C/C++ projects:
- tvm-ffi-config --includedir
- tvm-ffi-config --dlpack-includedir
- tvm-ffi-config --libfiles # or --libs/--ldflags on Unix
-```
-
-## Build the C/C++ Library Only
-
-TVM FFI can be used as a standalone C/C++ library without Python. The
instruction below should work for Linux, macOS and Windows.
-
-```bash
-cmake . -B build_cpp -DCMAKE_BUILD_TYPE=RelWithDebInfo
-cmake --build build_cpp --parallel --config RelWithDebInfo --target
tvm_ffi_shared
-cmake --install build_cpp --config RelWithDebInfo --prefix ./dist
-```
-
-After installation, you should see:
-
-- Headers are installed under ``dist/include/``;
-- Libraries are installed under ``dist/lib/``.
-
-## Troubleshooting
-
-- Rebuilding after C++/Cython changes: re-run ``pip install --reinstall -e
.``. Editable installs only auto-reflect pure Python changes.
-- Submodules missing: run ``git submodule update --init --recursive`` from the
repo root.
-- Library not found at import time: ensure your dynamic loader can find the
shared library. If built from source, add the ``lib`` directory to
``LD_LIBRARY_PATH`` (Linux), ``DYLD_LIBRARY_PATH`` (macOS), or ``PATH``
(Windows).
-- Wrong generator/build type: Ninja/Unix Makefiles use
``-DCMAKE_BUILD_TYPE=...``; Visual Studio requires ``--config ...`` at
build/ctest time.
diff --git a/docs/dev/ci_cd.rst b/docs/dev/ci_cd.rst
new file mode 100644
index 0000000..68d2a11
--- /dev/null
+++ b/docs/dev/ci_cd.rst
@@ -0,0 +1,203 @@
+.. Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+.. http://www.apache.org/licenses/LICENSE-2.0
+
+.. Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+Reproduce CI/CD
+===============
+
+This guide explains how to reproduce CI checks and tests locally,
+and how wheel builds and releases work.
+All CI/CD workflows are defined under `.github/workflows/
<https://github.com/apache/tvm-ffi/tree/main/.github/workflows>`__.
+For building the project from source, see :doc:`source_build`.
+
+Linters
+-------
+
+Pre-commit
+~~~~~~~~~~
+
+The project uses `pre-commit <https://pre-commit.com/>`__ to run linters and
+formatters. All hooks are defined in `.pre-commit-config.yaml
<https://github.com/apache/tvm-ffi/blob/main/.pre-commit-config.yaml>`__.
Install and
+register the git hooks so they run automatically before each commit:
+
+.. code-block:: bash
+
+ uv tool install pre-commit
+ pre-commit install
+
+You can also run hooks manually:
+
+.. code-block:: bash
+
+ # Run all hooks on every file
+ pre-commit run --all-files
+
+ # Run only on staged files
+ pre-commit run
+
+ # Run a single hook in isolation
+ pre-commit run ruff-check --all-files
+ pre-commit run clang-format --all-files
+
+The main linters per language are:
+
+- **Python** -- ``ruff`` (lint + format), ``ty`` (type checking)
+- **C/C++** -- ``clang-format`` (format), ``clang-tidy`` (lint, see below)
+- **Cython** -- ``cython-lint``
+- **CMake** -- ``cmake-format``, ``cmake-lint``
+- **Shell** -- ``shfmt``, ``shellcheck``
+
+If you run into issues with pre-commit:
+
+- **Version problems** -- ensure you have pre-commit 2.18.0 or later
+ (``pre-commit --version``).
+- **Stale cache** -- run ``pre-commit clean`` to clear the hook cache.
+- **Auto-fixed files** -- most formatting hooks fix issues in place. Review the
+ changes, stage them with ``git add -u``, and commit again.
+
+clang-tidy
+~~~~~~~~~~
+
+``clang-tidy`` is run as a separate CI job (not as a pre-commit hook) and only
+checks C++ files that have changed. To reproduce it locally:
+
+.. code-block:: bash
+
+ # Run clang-tidy on specific files
+ uv run --no-project --with "clang-tidy==21.1.1" \
+ python tests/lint/clang_tidy_precommit.py \
+ --build-dir=build-pre-commit \
+ --jobs=$(nproc) \
+ include/tvm/ffi/c_api.h src/some_file.cc
+
+ # Or run on all C++ sources
+ uv run --no-project --with "clang-tidy==21.1.1" \
+ python tests/lint/clang_tidy_precommit.py \
+ --build-dir=build-pre-commit \
+ --jobs=$(nproc) \
+ ./src/ ./include ./tests
+
+.. note::
+
+ On macOS, ``clang-tidy`` is resolved through ``xcrun``. The wrapper
+ ``tests/lint/clang_tidy_precommit.py`` handles this automatically.
+
+
+C++ Tests
+---------
+
+Build and run locally. First, set ``CMAKE_BUILD_PARALLEL_LEVEL`` to speed up
+the build:
+
+.. code-block:: bash
+
+ export CMAKE_BUILD_PARALLEL_LEVEL=$(nproc) # Linux
+ export CMAKE_BUILD_PARALLEL_LEVEL=$(sysctl -n hw.ncpu) # macOS
+
+Then configure, build, and run:
+
+.. code-block:: bash
+
+ # Configure with tests enabled
+ cmake . -B build_test -DTVM_FFI_BUILD_TESTS=ON -DCMAKE_BUILD_TYPE=Debug
+
+ # Build the test target
+ cmake --build build_test --clean-first --config Debug --target tvm_ffi_tests
+
+ # Run tests
+ ctest -V -C Debug --test-dir build_test --output-on-failure
+
+.. note::
+
+ On Windows, make sure you run the build from a
+ **Developer Command Prompt for VS** or have the MSVC toolchain on your
+ ``PATH``.
+
+
+Python Tests
+------------
+
+Reproduce locally with:
+
+.. code-block:: bash
+
+ # Install the project in editable mode with test dependencies
+ uv pip install --reinstall --verbose -e ".[test]"
+
+ # Run the full test suite
+ uv run pytest -vvs tests/python
+
+
+Rust Tests
+----------
+
+Rust tests live in the ``rust/`` workspace. Run them with:
+
+.. code-block:: bash
+
+ cd rust && cargo test
+
+This tests all workspace members (``tvm-ffi``, ``tvm-ffi-sys``,
+``tvm-ffi-macros``).
+
+.. note::
+
+ CI runs Rust tests only after the Python package is installed (
+ ``uv pip install -e ".[test]"``), because the Rust FFI bindings link
+ against the built shared library. Make sure the Python package is
+ installed before running ``cargo test``.
+
+
+Build Python Wheels
+-------------------
+
+CI builds wheels using `cibuildwheel <https://cibuildwheel.pypa.io/>`__
+on Linux (x86_64, aarch64), Windows (AMD64), and macOS (arm64).
+The wheel configuration lives in the ``[tool.cibuildwheel]`` section of
+``pyproject.toml``.
+
+To build a wheel locally:
+
+.. code-block:: bash
+
+ uv tool install cibuildwheel
+ cibuildwheel --output-dir dist
+
+You can restrict the build to a single platform:
+
+.. code-block:: bash
+
+ # Build only for the current platform
+ cibuildwheel --only cp312-macosx_arm64
+
+Use environment variables to control the target platform:
+
+.. code-block:: bash
+
+ # Choose manylinux image (e.g. manylinux2014, manylinux_2_28)
+ CIBW_MANYLINUX_X86_64_IMAGE=manylinux_2_28 cibuildwheel --output-dir dist
+
+ # Set macOS deployment target
+ CIBW_ENVIRONMENT_MACOS="MACOSX_DEPLOYMENT_TARGET=10.14" cibuildwheel
--output-dir dist
+
+ # Build only specific Python versions
+ CIBW_BUILD="cp312-*" cibuildwheel --output-dir dist
+
+.. seealso::
+
+ - :doc:`../packaging/python_packaging`: Packaging shared libraries as
+ Python wheels with scikit-build-core.
+ - :doc:`release_process`: Publishing wheels and creating release artifacts.
diff --git a/docs/dev/doc_build.rst b/docs/dev/doc_build.rst
new file mode 100644
index 0000000..8301bbd
--- /dev/null
+++ b/docs/dev/doc_build.rst
@@ -0,0 +1,129 @@
+.. Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+.. http://www.apache.org/licenses/LICENSE-2.0
+
+.. Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+Build This Doc Site
+===================
+
+This guide walks through building the TVM FFI documentation locally.
+Building the docs requires the Python package to be installed first; see
+:doc:`source_build` for instructions.
+
+.. admonition:: Prerequisite
+ :class: hint
+
+ - `uv <https://docs.astral.sh/uv/>`__ manages the Python environment for
+ all docs commands.
+ - Ensure you are in the repository root before running the commands below.
+ - Optional: install ``Doxygen`` if you plan to generate the C++ API
+ reference (see :ref:`build-cpp-docs`).
+
+Interactive Build (Auto-Reload)
+-------------------------------
+
+Rebuilds and serves the documentation locally with live reload:
+
+.. code-block:: bash
+
+ uv run --group docs sphinx-autobuild docs docs/_build/html \
+ --ignore docs/reference/cpp/generated
+
+By default, open ``http://127.0.0.1:8000`` in your browser after the initial
+build completes.
+
+One-Off Build
+-------------
+
+Generates the HTML documentation once, without running a server:
+
+.. code-block:: bash
+
+ uv run --group docs sphinx-build -M html docs docs/_build
+
+.. _build-cpp-docs:
+
+Build with C++ Docs
+-------------------
+
+Generating the C++ reference takes longer and requires Doxygen:
+
+.. code-block:: bash
+
+ brew install doxygen # macOS
+ sudo apt install doxygen # Linux
+
+Set ``BUILD_CPP_DOCS=1`` on the desired build command to enable the extra step:
+
+.. code-block:: bash
+
+ # Interactive build with auto-rebuild on C++ header changes
+ BUILD_CPP_DOCS=1 uv run --group docs sphinx-autobuild docs docs/_build/html
\
+ --ignore docs/reference/cpp/generated --watch include
+
+ # One-off build
+ BUILD_CPP_DOCS=1 uv run --group docs sphinx-build -M html docs docs/_build
+
+Build with Rust Docs
+--------------------
+
+Generating the Rust reference requires ``cargo`` to be installed:
+
+.. code-block:: bash
+
+ # Install Rust toolchain if not already installed
+ curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
+
+Set ``BUILD_RUST_DOCS=1`` on the desired build command to enable Rust
+documentation:
+
+.. code-block:: bash
+
+ # Interactive build with auto-rebuild on Rust source changes
+ BUILD_RUST_DOCS=1 uv run --group docs sphinx-autobuild docs
docs/_build/html \
+ --ignore docs/reference/rust/generated --watch rust
+
+ # One-off build
+ BUILD_RUST_DOCS=1 uv run --group docs sphinx-build -M html docs docs/_build
+
+Build All Documentation
+-----------------------
+
+To build documentation with all language references enabled:
+
+.. code-block:: bash
+
+ # Interactive build
+ BUILD_CPP_DOCS=1 BUILD_RUST_DOCS=1 uv run --group docs sphinx-autobuild \
+ docs docs/_build/html \
+ --ignore docs/reference/cpp/generated \
+ --ignore docs/reference/rust/generated \
+ --watch include --watch rust
+
+ # One-off build
+ BUILD_CPP_DOCS=1 BUILD_RUST_DOCS=1 uv run --group docs sphinx-build \
+ -M html docs docs/_build
+
+Cleanup
+-------
+
+Remove generated artifacts when they are no longer needed:
+
+.. code-block:: bash
+
+ rm -rf docs/_build/
+ rm -rf docs/reference/python/generated
+ rm -rf docs/reference/cpp/generated
+ rm -rf docs/reference/rust/generated
diff --git a/docs/dev/release_process.rst b/docs/dev/release_process.rst
index 7489094..b8c4513 100644
--- a/docs/dev/release_process.rst
+++ b/docs/dev/release_process.rst
@@ -116,6 +116,7 @@ trigger the docs release.
**Step 2.1.** Conclude voting results:
`<https://github.com/apache/tvm-ffi/issues/new>`__. (`Example
<https://github.com/apache/tvm-ffi/issues/366>`__)
**Step 2.2.** Publish PyPI wheel:
`<https://github.com/apache/tvm-ffi/actions/workflows/publish_wheel.yml>`__.
+(See :doc:`ci_cd` for how wheels are built with cibuildwheel.)
**Step 2.3.** Update documentation to latest:
`<https://github.com/apache/tvm-site/actions/workflows/publish_tvm_ffi_docs.yml>`__.
diff --git a/docs/dev/source_build.rst b/docs/dev/source_build.rst
new file mode 100644
index 0000000..f293aae
--- /dev/null
+++ b/docs/dev/source_build.rst
@@ -0,0 +1,151 @@
+.. Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+.. http://www.apache.org/licenses/LICENSE-2.0
+
+.. Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+Build from Source
+=================
+
+This guide covers two common workflows:
+
+- Python package building, which automatically includes building the core C++
+ library;
+- C++-only package building without Python.
+
+.. admonition:: Prerequisite
+ :class: tip
+
+ - Python: 3.9 or newer
+ - Compiler: C++17-capable toolchain
+
+ - Linux: GCC or Clang with C++17 support
+ - macOS: Apple Clang (via Xcode Command Line Tools)
+ - Windows: MSVC (Visual Studio 2019 or 2022, x64)
+
+ - Build tools: CMake 3.18+; Ninja
+
+Build the Python Package
+------------------------
+
+Download the source via:
+
+.. code-block:: bash
+
+ git clone --recursive https://github.com/apache/tvm-ffi
+ cd tvm-ffi
+
+.. note::
+
+ Always clone with ``--recursive`` to pull submodules. If you already cloned
+ without it, run:
+
+ .. code-block:: bash
+
+ git submodule update --init --recursive
+
+Build the Python package with scikit-build-core, which drives CMake to compile
+the C++ core and Cython extension:
+
+.. code-block:: bash
+
+ uv pip install --force-reinstall --verbose -e .
+
+The ``--force-reinstall`` flag forces a rebuild, and ``-e`` (editable) install
+means future Python-only changes are reflected immediately without having to
+rebuild.
+
+**CMake flags** can be passed via ``--config-settings
cmake.define.<FLAG>=<VALUE>``.
+For example, to attach debug symbols:
+
+.. code-block:: bash
+
+ uv pip install --force-reinstall --verbose -e . \
+ --config-settings cmake.define.TVM_FFI_ATTACH_DEBUG_SYMBOLS=ON
+
+Available CMake options (see `CMakeLists.txt
<https://github.com/apache/tvm-ffi/blob/main/CMakeLists.txt>`__) include:
+
+- ``TVM_FFI_ATTACH_DEBUG_SYMBOLS`` -- Attach debug symbols even in release
+ mode (default: ``OFF``).
+- ``TVM_FFI_USE_LIBBACKTRACE`` -- Enable libbacktrace (default: ``ON``).
+- ``TVM_FFI_USE_EXTRA_CXX_API`` -- Enable extra C++ API in shared lib
+ (default: ``ON``).
+- ``TVM_FFI_BACKTRACE_ON_SEGFAULT`` -- Set signal handler to print backtrace
+ on segfault (default: ``ON``).
+- ``CMAKE_EXPORT_COMPILE_COMMANDS`` -- Generate ``compile_commands.json`` for
+ clangd and other tools (default: ``OFF``).
+
+.. warning::
+
+ However, changes to C++/Cython always require re-running the install
+ command.
+
+Verify the install:
+
+.. code-block:: bash
+
+ uv run python -c "import tvm_ffi; print(tvm_ffi.__version__)"
+ uv run tvm-ffi-config -h
+
+.. tip::
+
+ Use ``tvm-ffi-config`` to query include and link flags when consuming TVM
+ FFI from external C/C++ projects:
+
+ .. code-block:: bash
+
+ tvm-ffi-config --includedir
+ tvm-ffi-config --dlpack-includedir
+ tvm-ffi-config --libfiles # or --libs/--ldflags on Unix
+
+Build the C/C++ Library Only
+----------------------------
+
+TVM FFI can be used as a standalone C/C++ library without Python. The
+instruction below should work for Linux, macOS and Windows.
+
+.. code-block:: bash
+
+ cmake . -B build_cpp -DCMAKE_BUILD_TYPE=RelWithDebInfo
+ cmake --build build_cpp --parallel --config RelWithDebInfo --target
tvm_ffi_shared
+ cmake --install build_cpp --config RelWithDebInfo --prefix ./dist
+
+After installation, you should see:
+
+- Headers are installed under ``dist/include/``;
+- Libraries are installed under ``dist/lib/``.
+
+Troubleshooting
+---------------
+
+- **Rebuilding after C++/Cython changes**: re-run
+ ``uv pip install --force-reinstall -e .``. Editable installs only
+ auto-reflect pure Python changes.
+- **Submodules missing**: run ``git submodule update --init --recursive`` from
+ the repo root.
+- **Library not found at import time**: ensure your dynamic loader can find the
+ shared library. If built from source, add the ``lib`` directory to
+ ``LD_LIBRARY_PATH`` (Linux), ``DYLD_LIBRARY_PATH`` (macOS), or ``PATH``
+ (Windows).
+- **Wrong generator/build type**: Ninja/Unix Makefiles use
+ ``-DCMAKE_BUILD_TYPE=...``; Visual Studio requires ``--config ...`` at
+ build/ctest time.
+
+.. seealso::
+
+ - :doc:`ci_cd`: Reproduce linters, unit tests, and wheel builds locally.
+ - :doc:`../get_started/quickstart`: End-to-end walkthrough of building and
+ running a C++/CUDA kernel.
+ - :doc:`../packaging/cpp_tooling`: CMake integration, compiler flags, and
+ library distribution for downstream projects.
diff --git a/docs/guides/export_func_cls.rst b/docs/guides/export_func_cls.rst
index 5123049..cc0f32d 100644
--- a/docs/guides/export_func_cls.rst
+++ b/docs/guides/export_func_cls.rst
@@ -139,10 +139,10 @@ is:
- ``nbytes``: total byte count following this header.
- ``import_tree``: a CSR sparse array
- (``<indptr: vec<u64>> <child_indices: vec<u64>>``) encoding the parent–child
+ (``<indptr: vec<u64>> <child_indices: vec<u64>>``) encoding the parent-child
relationships among module nodes.
- Each ``key`` is a module kind string, or the special value ``_lib`` for the
- host dynamic library itself. For non-\ ``_lib`` entries, ``val`` contains the
+ host dynamic library itself. For entries other than ``_lib``, ``val``
contains the
serialized bytes of the custom sub-module.
- Both ``str`` and ``bytes`` values are length-prefixed: ``<size: u64>
<content>``.
diff --git a/docs/index.rst b/docs/index.rst
index 4955811..73b1eea 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -86,5 +86,7 @@ Table of Contents
:maxdepth: 1
:caption: Developer Manual
- dev/build_from_source.md
+ dev/source_build.rst
+ dev/doc_build.rst
+ dev/ci_cd.rst
dev/release_process.rst
diff --git a/docs/packaging/cpp_tooling.rst b/docs/packaging/cpp_tooling.rst
index 4dbad2d..3609305 100644
--- a/docs/packaging/cpp_tooling.rst
+++ b/docs/packaging/cpp_tooling.rst
@@ -272,6 +272,7 @@ Further Reading
---------------
- :doc:`../get_started/quickstart`: End-to-end walkthrough building and
shipping a C++/CUDA kernel
+- :doc:`../dev/source_build`: Building TVM-FFI from source with CMake flags
- :doc:`stubgen`: Generating Python type stubs from C++ reflection metadata
- :doc:`python_packaging`: Packaging shared libraries as Python wheels
- :doc:`../concepts/func_module`: Defining and exporting TVM-FFI functions
diff --git a/docs/packaging/python_packaging.rst
b/docs/packaging/python_packaging.rst
index c3c828f..7a9a898 100644
--- a/docs/packaging/python_packaging.rst
+++ b/docs/packaging/python_packaging.rst
@@ -186,5 +186,6 @@ registered global functions and classes.
.. seealso::
- :doc:`stubgen` for the complete stub generation guide, including
directive-based
- customization and command-line usage.
+ - :doc:`stubgen`: Complete stub generation guide, including directive-based
+ customization and command-line usage.
+ - :doc:`../dev/ci_cd`: Reproducing wheel builds locally with cibuildwheel.
diff --git a/docs/reference/cpp/index.rst b/docs/reference/cpp/index.rst
index e715482..11d6328 100644
--- a/docs/reference/cpp/index.rst
+++ b/docs/reference/cpp/index.rst
@@ -103,9 +103,4 @@ Key Classes
Full API Index
--------------
-.. ifconfig:: build_exhale
-
- .. toctree::
- :maxdepth: 2
-
- generated/index
+`Browse the full API index <generated/index.html>`__
