[FEAT][STUBGEN] Add Rust code generation backend

Signed-off-by: yuchuan <yuchuan.7streams@gmail.com>

Author: Seven-Streams

cmake/Utils/Library.cmake

@@ -172,6 +172,7 @@ endfunction ()
 #   target_name
 #   [LINK_SHARED ON|OFF] [LINK_HEADER ON|OFF] [DEBUG_SYMBOL ON|OFF] [MSVC_FLAGS ON|OFF]
 #   [STUB_INIT ON|OFF] [STUB_DIR <dir>] [STUB_PKG <pkg>] [STUB_PREFIX <prefix>]
+#   [STUB_TARGET python|rust]
 # )
 # Configure a target to integrate with TVM-FFI CMake utilities:
 #   - Link against tvm_ffi::header and/or tvm_ffi::shared
@@ -194,6 +195,11 @@ endfunction ()
 #   STUB_INIT:    Whether to allow generating new directives. Default: OFF (ON/OFF-style)
 #   STUB_PKG:     Package name passed to stub generator (requires STUB_DIR and STUB_INIT=ON; default: ${SKBUILD_PROJECT_NAME} if set, otherwise target name)
 #   STUB_PREFIX:  Module prefix passed to stub generator (requires STUB_DIR and STUB_INIT=ON; default: "<STUB_PKG>.")
+#   STUB_TARGET:  Code generator backend: "python" (default) or "rust". Passed to the stub
+#                 generator as --target. With "rust", object bindings are emitted into a Rust
+#                 module tree under STUB_DIR (global functions are not generated for Rust).
+#                 To generate both Python and Rust stubs for one target, call this function
+#                 twice with different STUB_DIR/STUB_TARGET values.
 # ~~~
 function (tvm_ffi_configure_target target)
   if (NOT target)
@@ -219,6 +225,7 @@ function (tvm_ffi_configure_target target)
       STUB_DIR
       STUB_PKG
       STUB_PREFIX
+      STUB_TARGET
   )
   set(tvm_ffi_arg_multiValueArgs)
 
@@ -236,8 +243,17 @@ function (tvm_ffi_configure_target target)
   if (NOT DEFINED tvm_ffi_arg__STUB_INIT)
     set(tvm_ffi_arg__STUB_INIT OFF)
   endif ()
+  if (NOT DEFINED tvm_ffi_arg__STUB_TARGET)
+    set(tvm_ffi_arg__STUB_TARGET "python")
+  endif ()
 
   # Validation
+  if (NOT tvm_ffi_arg__STUB_TARGET MATCHES "^(python|rust)$")
+    message(
+      FATAL_ERROR
+        "tvm_ffi_configure_target(${target}): STUB_TARGET must be 'python' or 'rust', got '${tvm_ffi_arg__STUB_TARGET}'."
+    )
+  endif ()
   if ((NOT DEFINED tvm_ffi_arg__STUB_DIR) OR (NOT tvm_ffi_arg__STUB_DIR))
     if (DEFINED tvm_ffi_arg__STUB_PKG OR DEFINED tvm_ffi_arg__STUB_PREFIX)
       message(
@@ -346,7 +362,9 @@ function (tvm_ffi_configure_target target)
       COMPONENTS Interpreter
       REQUIRED
     )
-    set(tvm_ffi_stub_cli_args "${tvm_ffi_arg__STUB_DIR_ABS}" --dlls $<TARGET_FILE:${target}>)
+    set(tvm_ffi_stub_cli_args "${tvm_ffi_arg__STUB_DIR_ABS}" --dlls $<TARGET_FILE:${target}>
+                              --target "${tvm_ffi_arg__STUB_TARGET}"
+    )
     if (tvm_ffi_arg__STUB_INIT)
       list(
         APPEND

docs/guides/rust_lang_guide.md

@@ -180,6 +180,22 @@ fn may_fail(value: i32) -> Result<()> {
 }
 ```
 
+### Generating Bindings with stubgen
+
+For registered C++ classes, `tvm-ffi-stubgen --target rust` generates typed Rust
+bindings whose memory layout mirrors C++ exactly, so you can construct and call
+objects without hand-written glue:
+
+```rust
+// generated for a C++ class `my_ext.IntPair` (fields `a`/`b`, defaulted `scale`, method `sum`)
+let mut pair = IntPair::ffi_new().a(1).b(2).build()?;  // builder; `scale` defaults to 1
+println!("sum = {}", pair.sum()?);                     // call a C++ method
+pair.a = 10;                                           // write a field through DerefMut
+```
+
+See {ref}`sec-stubgen-rust` for the full reference and the runnable
+[`examples/rust_stubgen`](https://github.com/apache/tvm-ffi/tree/main/examples/rust_stubgen).
+
 ## Examples
 
 The repository includes a complete example in `rust/tvm-ffi/examples/load_library.rs`.
@@ -213,5 +229,6 @@ For detailed API documentation, see the [Rust API Reference](../reference/rust/i
 ## Related Resources
 
 - [Quick Start Guide](../get_started/quickstart.rst) - General TVM FFI introduction
+- [Stub Generation](../packaging/stubgen.rst) - Full `tvm-ffi-stubgen` reference (Python and Rust targets)
 - [C++ Guide](./cpp_lang_guide.md) - C++ API usage
 - [Python Guide](./python_lang_guide.md) - Python API usage

docs/packaging/stubgen.rst

@@ -20,9 +20,12 @@
 Stub Generation
 ===============
 
-TVM-FFI provides ``tvm-ffi-stubgen``, a tool that generates Python type stubs from C++
-reflection metadata. It turns registered global functions and classes into proper Python
-type hints, enabling IDE auto-completion and static type checking.
+TVM-FFI provides ``tvm-ffi-stubgen``, a tool that generates typed language bindings from C++
+reflection metadata. It turns registered global functions and classes into native type hints,
+enabling IDE auto-completion and static type checking.
+
+The sections below describe the default Python target. The Rust target is covered in
+:ref:`sec-stubgen-rust`.
 
 .. admonition:: Prerequisite
    :class: hint
@@ -46,6 +49,7 @@ This runs stub generation automatically after each build.
        [STUB_INIT ON|OFF]
        [STUB_PKG <pkg>]
        [STUB_PREFIX <prefix>]
+       [STUB_TARGET python|rust]
    )
 
 From the example's
@@ -239,6 +243,9 @@ All three are required together. When omitted, the tool operates in directive-on
 
 **Optional arguments:**
 
+``--target``
+   Code generator backend: ``python`` (default) or ``rust``. See :ref:`sec-stubgen-rust`.
+
 ``--verbose``
    Print a unified diff of changes to each file.
 
@@ -253,6 +260,153 @@ All three are required together. When omitted, the tool operates in directive-on
 
 For a complete list of options, run ``tvm-ffi-stubgen --help``.
 
+.. _sec-stubgen-rust:
+
+Rust Code Stubgen (Experimental)
+--------------------------------
+
+TVM-FFI provides an efficient, easy-to-use mechanism for exposing C++ classes to Rust.
+Objects share the same memory representation, so Rust code can directly access objects
+created in C++. However, users have to hand-write the Rust definition of each registered
+object to avoid memory layout and alignment mismatches between the two sides. To eliminate
+this manual work, ``tvm-ffi-stubgen`` supports generating Rust code directly.
+
+To generate Rust stubs, pass ``STUB_TARGET rust`` to ``tvm_ffi_configure_target``
+(see :ref:`sec-stubgen-cmake`) or ``--target rust`` on the command line
+(see :ref:`sec-stubgen-cli`).
+
+Key Features
+~~~~~~~~~~~~
+
+- Generate Rust code for registered C++ classes automatically (via CLI or CMake).
+- Mirror the C++ memory layout exactly in Rust.
+- Provide Rust-native builder-style constructors for registered classes, with
+  reflected default values prefilled and overridable through setters.
+- Expose methods of registered classes through cross-language calls.
+
+Generation Output
+~~~~~~~~~~~~~~~~~
+
+This section uses `examples/rust_stubgen <https://github.com/apache/tvm-ffi/tree/main/examples/rust_stubgen>`_
+as the running example. The library registers a single type, ``rust_stubgen.IntPair``,
+with two required fields ``a`` / ``b``, a defaulted field ``scale``, and a method ``sum``:
+
+.. literalinclude:: ../../examples/rust_stubgen/src/int_pair.cc
+   :language: cpp
+   :start-after: [object.begin]
+   :end-before: [object.end]
+
+For this type the tool generates the following Rust code (bodies abridged):
+
+.. code-block:: rust
+
+   #[repr(C)]
+   #[derive(tvm_ffi::derive::Object)]
+   #[type_key = "rust_stubgen.IntPair"]
+   pub struct IntPairObj {
+       base: Object,   // the parent type, embedded as the first field
+       pub a: i64,
+       pub b: i64,
+       pub scale: i64,
+   }
+
+   #[repr(C)]
+   #[derive(tvm_ffi::derive::ObjectRef, Clone)]
+   pub struct IntPair {
+       data: ObjectArc<IntPairObj>,
+   }
+
+   impl IntPair {
+       pub fn ffi_new() -> IntPairBuilder { /* ... */ }
+       pub fn sum(&mut self) -> Result<i64> { /* ... */ }
+   }
+
+   pub struct IntPairBuilder { /* base + every field */ }
+
+   impl IntPairBuilder {
+       pub fn a(mut self, a: i64) -> Self { /* ... */ }
+       pub fn b(mut self, b: i64) -> Self { /* ... */ }
+       pub fn scale(mut self, scale: i64) -> Self { /* ... */ }
+       pub fn build(self) -> Result<IntPair> { /* ... */ }
+       pub fn build_obj(self) -> Result<IntPairObj> { /* ... */ }
+   }
+
+``IntPairObj`` mirrors the C++ memory layout exactly, so Rust code can directly
+access objects created in C++ and vice versa. ``IntPair`` is the reference type
+that owns an allocation of it; fields are read through ``Deref`` (and written
+through ``DerefMut``, since the class declares ``_type_mutable = true``), and
+``sum`` calls into the C++ implementation through the FFI.
+
+Builder-style Construction
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Construction is fully Rust-native -- no FFI call is involved -- and uniform: a
+nullary ``ffi_new()`` opens the builder, every field is set through its
+like-named consuming setter, and ``build()`` finishes the chain:
+
+.. code-block:: rust
+
+   let pair = IntPair::ffi_new().a(1).b(2).build()?;             // scale = 1 (default)
+   let scaled = IntPair::ffi_new().a(1).b(2).scale(10).build()?; // override the default
+   let err = IntPair::ffi_new().a(1).build();                    // Err: field `b` is not set
+
+``ffi_new() -> IntPairBuilder``
+   Opens the builder. A field with a ``refl::default_value`` (here ``scale``)
+   starts prefilled with its default, rendered as a Rust literal at
+   stub-generation time; every other field starts unset.
+
+``a(..)`` / ``b(..)`` / ``scale(..)``
+   One consuming setter per field. Setting a defaulted field overrides its
+   default.
+
+``build() -> Result<IntPair>``
+   Validates and allocates: returns an error if a field without a default is
+   still unset (the ``err`` case above), otherwise wraps the assembled value
+   in ``ObjectArc`` and returns the reference type. This is the endpoint to
+   use in ordinary code.
+
+``build_obj() -> Result<IntPairObj>``
+   Performs the same validation and assembly as ``build()`` -- ``build()`` in
+   fact delegates to it -- but stops at the bare, unallocated struct value.
+   It exists for inheritance: a C++ class deriving from ``IntPair`` embeds
+   ``IntPairObj`` as its first field, and the derived type's generated builder
+   gains a ``base(..)`` setter that takes exactly this value:
+
+   .. code-block:: rust
+
+      // for a hypothetical `Derived` extending IntPair with a field `c`
+      let d = Derived::ffi_new()
+          .base(IntPair::ffi_new().a(1).b(2).build_obj()?)
+          .c(3)
+          .build()?;
+
+   When ``base`` is left unset, the derived ``build()`` falls back to
+   default-constructing the parent through its all-default builder. This
+   succeeds silently when every parent field has a default; for ``IntPair``
+   it would fail with an error naming ``base``, since ``a`` and ``b`` carry
+   no default.
+
+The builder deliberately bypasses any C++ constructor logic (it never runs
+``IntPairObj``'s C++ constructor); users who need the faithful C++ semantics
+can hand-write a ``new`` constructor (outside the generated markers) on top of
+the builder.
+
+Limitations
+~~~~~~~~~~~
+
+A type that mentions an origin the Rust crate cannot represent -- in any
+position: field, method argument, return type, or nested inside another
+container -- is explicitly unsupported: the whole binding is skipped with a
+warning. This covers ``Map`` / ``Dict`` / ``List`` / ``Union`` (no Rust
+counterpart) as well as ``Optional`` / ``tuple`` (std ``Option<T>`` and Rust
+tuples do not match the C++ ``ffi::Optional`` / ``ffi::Tuple`` memory layout).
+
+A constructor alone cannot be generated when a default comes from a
+``refl::default_factory`` or when a default value has no Rust literal
+rendering: such types are emitted without ``ffi_new`` (a warning explains why),
+and construction stays on the C++ side -- e.g. through a ``def_static``
+factory.
+
 .. _sec-stubgen-advanced:
 
 Advanced Topics
@@ -391,7 +545,8 @@ When you run the tool, it:
       # tvm-ffi-stubgen(import-object): ffi.Object;False;_ffi_Object
 
    This imports ``ffi.Object`` as ``_ffi_Object`` for use in generated code. The second
-   field (``False``) indicates the import is not TYPE_CHECKING-only.
+   field (``False``) indicates the import is not TYPE_CHECKING-only. The Rust target
+   records the name as a plain ``use`` and ignores the other two fields.
 
 ``skip-file`` - Skip File
    Prevents the tool from modifying the file. Place anywhere in the file.

examples/rust_stubgen/CMakeLists.txt

@@ -0,0 +1,42 @@
+# 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.
+cmake_minimum_required(VERSION 3.18)
+project(rust_stubgen)
+
+find_package(
+  Python
+  COMPONENTS Interpreter
+  REQUIRED
+)
+execute_process(
+  COMMAND "${Python_EXECUTABLE}" -m tvm_ffi.config --cmakedir
+  OUTPUT_STRIP_TRAILING_WHITESPACE
+  OUTPUT_VARIABLE tvm_ffi_ROOT COMMAND_ERROR_IS_FATAL ANY
+)
+find_package(tvm_ffi CONFIG REQUIRED)
+# [example.cmake.begin]
+add_library(rust_stubgen SHARED src/int_pair.cc)
+tvm_ffi_configure_target(
+  rust_stubgen
+  STUB_DIR
+  "./rust/src/generated"
+  STUB_TARGET
+  rust
+  STUB_INIT
+  ON
+)
+# [example.cmake.end]

examples/rust_stubgen/README.md

@@ -0,0 +1,63 @@
+<!--- 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. -->
+
+# TVM FFI Rust Stubgen Example
+
+This is an example project that registers a C++ object (`IntPair`) and
+generates typed Rust bindings for it with `tvm-ffi-stubgen --target rust`,
+as documented in [docs/packaging/stubgen.rst](../../docs/packaging/stubgen.rst).
+
+## Build the library and generate the bindings
+
+Install tvm-ffi and activate the virtualenv first (from the repo root):
+
+```bash
+uv pip install -e .
+source .venv/bin/activate
+```
+
+Then build the C++ shared library:
+
+```bash
+cd examples/rust_stubgen
+cmake -B build
+cmake --build build
+```
+
+Stub generation runs as a post-build step
+(`tvm_ffi_configure_target(... STUB_TARGET rust STUB_INIT ON)` in
+`CMakeLists.txt`) and refreshes `rust/src/generated/`. The equivalent CLI
+invocation is:
+
+```bash
+tvm-ffi-stubgen rust/src/generated --target rust --dlls build/librust_stubgen.so \
+  --init-lib rust_stubgen --init-pypkg rust_stubgen --init-prefix "rust_stubgen."
+```
+
+## Run the example
+
+After building the C++ library, run the Rust demo:
+
+```bash
+cd rust
+cargo run
+```
+
+This runs four flows: constructing an `IntPair` via the generated builder
+(`ffi_new().a(1).b(2).build()`; the defaulted `scale` field may be omitted),
+calling the `sum` method, overriding the default through the `.scale(..)`
+setter, and writing a field through `DerefMut`.