This is an automated email from the ASF dual-hosted git repository.
Seven-Streams pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/tvm-tirx.git
The following commit(s) were added to refs/heads/main by this push:
new d6cd4dbd3 [CI][DOCS] Run the C++ and Rust IR guide examples, and
describe Rust as a peer of C++ (#226)
d6cd4dbd3 is described below
commit d6cd4dbd3397c5e58578a4accf889d7329e83671
Author: Linzhang Li <[email protected]>
AuthorDate: Sat Nov 7 19:21:16 2026 -0500
[CI][DOCS] Run the C++ and Rust IR guide examples, and describe Rust as a
peer of C++ (#226)
The C++ and Rust chapters of the IR Guides run their code from
`examples/ir_guides`, a package that builds a C++ and a Rust library
against the installed TIRx. CI ran only the Python examples of that
directory (`run_all_cpu.sh`), so `working_with_ir_in_cpp.py` and
`working_with_ir_in_rust.py` were never run, and a change that broke
them would still pass. Checking the guides against the code also turned
up one stale excerpt in the extension guide.
The docs also called the Rust crate "bindings". Rust is a peer of C++:
Rust code defines and registers IR types, operators, and passes as C++
code does. The IR objects that `tvm-ffi-stubgen` generates for Rust
from the C++ reflection share the ABI layout of their C++ definitions,
so an object passes between the two languages as the same pointer,
without conversion.
---
AGENTS.md | 18 +++++++++------
ci/jenkins/jenkinsfile.groovy | 1 +
docs/advanced/defining_ir_extensions.rst | 4 ++--
docs/ir_guides/working_with_ir_in_rust.rst | 6 ++---
docs/reference/rust/index.rst | 6 ++---
rust/Cargo.toml | 4 ++--
rust/src/ir/op.rs | 2 +-
rust/src/lib.rs | 9 ++++----
.../structural_visit_with_constraint_context.rs | 2 +-
rust/tests/target/main.rs | 2 +-
tests/scripts/task_native_examples_cpu.sh | 27 ++++++++++++++++++++++
11 files changed, 57 insertions(+), 24 deletions(-)
diff --git a/AGENTS.md b/AGENTS.md
index 2d0a31d25..2d06444d3 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -34,7 +34,7 @@ harnesses on top. The Python package is `tvm_tirx`; the
distribution is
include/tvm/ C++ public headers (ir, sym, tirx, target, runtime,
backends)
src/ C++ compiler and runtime implementations
python/tvm_tirx/ Python package and reflected C++ bindings
-rust/ Rust bindings (stubgen) and extension tools
+rust/ Rust crate: IR, analysis, passes, and extension APIs
tests/cpp/ GoogleTest C++ tests
tests/python/ pytest tests organized by owning namespace and backend
tests/lint/ ASF header and file-type checks
@@ -127,12 +127,16 @@ describe missing coverage; they do not demonstrate that a
backend works.
`rust/` is a standalone crate (`tvm-tirx`) over the initialized
`3rdparty/tvm-ffi/rust` submodule sources. Release CI requires the submodule
on an exact TVM FFI release tag and rewrites the dependency to that exact
-crates.io version before packaging or publishing. Its IR
-bindings are generated by `tvm-ffi-stubgen` between `tvm-ffi-stubgen(begin)`
and
-`(end)` markers. The crate links `libtvm_tirx_compiler` from the directory
-`tvm-tirx-config --libdir` prints, so build TIRx first. Its build script needs
-`tvm-ffi-config` and `tvm-tirx-config` on `PATH`, which `uv run` provides after
-the editable install:
+crates.io version before packaging or publishing. The Rust definitions of
+the IR objects are generated by `tvm-ffi-stubgen` from the reflection of
+`libtvm_tirx_compiler`, between `tvm-ffi-stubgen(begin)` and `(end)` markers.
+They share the ABI layout of the C++ objects: `#[repr(C)]` structs with the
+C++ field offsets, whose size and alignment are checked at compile time.
+`--check` below verifies that they match the build. The crate links
+`libtvm_tirx_compiler` from the directory `tvm-tirx-config --libdir` prints,
+so build TIRx first. Its build script needs `tvm-ffi-config` and
+`tvm-tirx-config` on `PATH`, which `uv run` provides after the editable
+install:
```bash
uv run --no-sync tvm-ffi-stubgen rust/src --target rust --dlls
build/lib/libtvm_tirx_compiler.so --check
diff --git a/ci/jenkins/jenkinsfile.groovy b/ci/jenkins/jenkinsfile.groovy
index 3f7159e3b..f928c7b59 100644
--- a/ci/jenkins/jenkinsfile.groovy
+++ b/ci/jenkins/jenkinsfile.groovy
@@ -78,6 +78,7 @@ parallel(
source ./tests/scripts/test_task_install_dist_wheels.sh
./tests/scripts/task_python_unittest.sh
./tests/scripts/task_minimal_examples_cpu.sh
+ ./tests/scripts/task_native_examples_cpu.sh
'""",
label: 'Run CPU unit tests and examples on the CUDA wheel',
)
diff --git a/docs/advanced/defining_ir_extensions.rst
b/docs/advanced/defining_ir_extensions.rst
index 9a872488c..24de828b1 100644
--- a/docs/advanced/defining_ir_extensions.rst
+++ b/docs/advanced/defining_ir_extensions.rst
@@ -283,10 +283,10 @@ The rewrites are:
:start-after: // begin lowering
:end-before: // end lowering
:prepend: struct Lowering {
- bindings: Vec<(Var, Var, Var)>,
+ bindings: Vec<(Var, PrimVar, PrimVar)>,
}
impl Lowering {
- fn parts(&self, expr: &Expr) -> Result<(Expr, Expr)> { ... }
+ fn parts(&self, expr: &Expr) -> Result<(PrimExpr, PrimExpr)> {
... }
}
#[dispatch(map, (AnyView<'_>,), Result<UnchangedOr<Any>>)]
impl Lowering {
diff --git a/docs/ir_guides/working_with_ir_in_rust.rst
b/docs/ir_guides/working_with_ir_in_rust.rst
index 89f29a155..4a2364532 100644
--- a/docs/ir_guides/working_with_ir_in_rust.rst
+++ b/docs/ir_guides/working_with_ir_in_rust.rst
@@ -41,9 +41,9 @@ The examples are packaged as ``tirx_ir_guide_examples`` under
`examples/ir_guides
<https://github.com/apache/tvm-tirx/tree/main/examples/ir_guides>`__.
When cargo is available, installing the package builds the Rust crate in
``rust/`` into a library; ``CMakeLists.txt`` and ``pyproject.toml`` in the
-same directory show how. The crate uses the bindings from this checkout,
-so install TIRx from the same source tree. We install without build isolation
-to build against that installation instead of fetching one from PyPI:
+same directory show how. The crate depends on the ``tvm-tirx`` crate of this
+checkout, so install TIRx from the same source tree. We install without build
+isolation to build against that installation instead of fetching one from PyPI:
.. code-block:: bash
diff --git a/docs/reference/rust/index.rst b/docs/reference/rust/index.rst
index 07cfed0f1..6e2adf60f 100644
--- a/docs/reference/rust/index.rst
+++ b/docs/reference/rust/index.rst
@@ -46,8 +46,8 @@ Crates
- Description
* - 📦 `tvm-tirx <generated/tvm_tirx/index.html>`_
- The IR, TIRx, symbolic analysis, target, backend, runtime, codegen and
script
- bindings, the Rust IR constructors and operators, and the definition of
new
+ modules, their IR constructors and operators, and the definition of new
types, operators, and passes.
* - 📦 `tvm-ffi <generated/tvm_ffi/index.html>`_
- - The TVM FFI objects, functions, containers and ``static_init_block!``
the
- bindings are built on, re-exported as ``tvm_tirx::tvm_ffi``.
+ - The TVM FFI objects, functions, containers and ``static_init_block!``
that
+ ``tvm-tirx`` is built on, re-exported as ``tvm_tirx::tvm_ffi``.
diff --git a/rust/Cargo.toml b/rust/Cargo.toml
index 8a491e2b5..5fdac8a72 100644
--- a/rust/Cargo.toml
+++ b/rust/Cargo.toml
@@ -21,13 +21,13 @@ version = "0.1.0-alpha.5"
edition = "2021"
# The oldest toolchain that builds the crate and tvm-ffi; CMake checks cargo
against it.
rust-version = "1.95"
-description = "Rust API for the TVM TIRx compiler: IR bindings and IR
extensions"
+description = "The TVM TIRx compiler in Rust: IR, analysis, passes, and IR
extensions"
license = "Apache-2.0"
homepage = "https://tvm.apache.org/tirx/";
documentation = "https://tvm.apache.org/tirx/reference/rust/";
repository = "https://github.com/apache/tvm-tirx";
keywords = ["tvm", "compiler", "tensor", "ir", "ffi"]
-categories = ["compilers", "api-bindings"]
+categories = ["compilers"]
# The build directories CMake creates here are not part of the crate.
include = ["/build.rs", "/src", "/examples", "/tests"]
diff --git a/rust/src/ir/op.rs b/rust/src/ir/op.rs
index 9b56eceac..736923fd8 100644
--- a/rust/src/ir/op.rs
+++ b/rust/src/ir/op.rs
@@ -24,7 +24,7 @@
// tvm-ffi-stubgen(missing-docs): allow
// `ir.Op` has three unreflected members, so its complete layout is
hand-written below.
// tvm-ffi-stubgen(ty-map): ir.Op -> crate::ir::op::Op
-// Names the hand-written `Op` binding uses: the import section keeps them
even when no
+// Names the hand-written `Op` definition uses: the import section keeps them
even when no
// generated block does.
// tvm-ffi-stubgen(import-object): std::ops::Deref
// tvm-ffi-stubgen(import-object): tvm_ffi::Any
diff --git a/rust/src/lib.rs b/rust/src/lib.rs
index cead6f4c2..ed14c7cd9 100644
--- a/rust/src/lib.rs
+++ b/rust/src/lib.rs
@@ -33,13 +33,14 @@
//! - [`codegen`]: compiling IR modules into runtime modules.
//! - [`script`]: printing IR objects as TVMScript.
//!
-//! # Using the bindings
+//! # Using the crate
//!
//! The crate links `libtvm_tirx_compiler`, which the build script finds
through
//! `tvm-tirx-config --libdir`; `tvm-tirx-config` and `tvm-ffi-config` must be
on `PATH` when the
-//! crate is built. Native functions have Rust wrappers, such as
[`target::Target::new`] for
-//! `target.Target`, and any of them can be called through
[`tvm_ffi::Function::get_global`]. A
-//! program that uses only `tvm_ffi`, without calling a wrapper, must link the
library itself
+//! crate is built. Many of its APIs call global functions of that library, as
+//! [`target::Target::new`] calls `target.Target`, and any global function can
also be called
+//! through [`tvm_ffi::Function::get_global`]. A program that calls them only
through `tvm_ffi`,
+//! without an API of this crate, must link the library itself
//! (`tvm-tirx-config --libs compiler`).
//!
//! ```
diff --git a/rust/src/tirx/structural_visit_with_constraint_context.rs
b/rust/src/tirx/structural_visit_with_constraint_context.rs
index 406c9fbe3..8b0f30797 100644
--- a/rust/src/tirx/structural_visit_with_constraint_context.rs
+++ b/rust/src/tirx/structural_visit_with_constraint_context.rs
@@ -66,7 +66,7 @@ impl StructuralVisitorWithConstraintContextBase {
}
// SAFETY: repr(C) mirrors the complete base in the matching native header.
-// Stub generation cannot certify its private tail; the binding requires the
+// Stub generation cannot certify its private tail; the definition requires the
// matching native build. All fields begin with the same state as the native
// constructor. Native-mutated fields use UnsafeCell. The type identity is the
// registered specialized type, while the shared engine installs its vtable and
diff --git a/rust/tests/target/main.rs b/rust/tests/target/main.rs
index 54ef018d6..c89b466b5 100644
--- a/rust/tests/target/main.rs
+++ b/rust/tests/target/main.rs
@@ -39,7 +39,7 @@ fn native_target(name: &str) -> Target {
#[test]
fn generated_types_match_the_registry() {
- // Both hold members reflection does not describe, so both bindings are
opaque.
+ // Both hold members reflection does not describe, so both definitions are
opaque.
assert_type_contracts!(false; TargetObj: Object, TargetKindObj: Object);
}
diff --git a/tests/scripts/task_native_examples_cpu.sh
b/tests/scripts/task_native_examples_cpu.sh
new file mode 100755
index 000000000..fe1bd6c3b
--- /dev/null
+++ b/tests/scripts/task_native_examples_cpu.sh
@@ -0,0 +1,27 @@
+#!/usr/bin/env bash
+# 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.
+
+set -euxo pipefail
+
+# The C++ and Rust examples of the IR Guides are functions of a package that
builds a C++ and a
+# Rust library against the installed TIRx. Install it as the guides do, then
run them.
+source ./tests/scripts/task_install_rust.sh
+uv pip install "scikit-build-core>=0.11,!=1.1.0"
+uv pip install --no-build-isolation --no-deps ./examples/ir_guides
+uv run --no-sync python examples/ir_guides/working_with_ir_in_cpp.py
+uv run --no-sync python examples/ir_guides/working_with_ir_in_rust.py
