[FEAT][STUBGEN] Add Rust code generation backend

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

Author: Seven-Streams

cmake/Utils/Library.cmake

@@ -149,6 +149,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
@@ -171,6 +172,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)
@@ -196,6 +202,7 @@ function (tvm_ffi_configure_target target)
       STUB_DIR
       STUB_PKG
       STUB_PREFIX
+      STUB_TARGET
   )
   set(tvm_ffi_arg_multiValueArgs)
 
@@ -213,8 +220,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(
@@ -323,7 +339,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/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,120 @@ 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
+~~~~~~~~~~~~~~~~~
+
+For the type ``IntPair`` (fields ``a`` / ``b``, plus ``scale`` registered with
+``refl::default_value(1)``), the generated Rust code looks like this:
+
+.. code-block:: rust
+
+   #[repr(C)]
+   #[derive(tvm_ffi::derive::Object)]
+   #[type_key = "my_ffi_extension.IntPair"]
+   pub struct IntPairObj {
+       base: Object,   // the parent type (or `tvm_ffi::Object` if no parent), embedded as the first field
+       pub a: i64,     // fields are public: read (and write, if mutable) via `Deref`/`DerefMut`
+       pub b: i64,
+       pub scale: i64,
+   }
+
+   #[repr(C)]
+   #[derive(tvm_ffi::derive::ObjectRef, Clone)]
+   pub struct IntPair {
+       data: ObjectArc<IntPairObj>,
+   }
+
+   impl IntPair {
+       /// Native (FFI-free) construction: opens the builder. `scale` starts
+       /// prefilled with its reflected default (`1`); `a` / `b` start unset.
+       pub fn ffi_new() -> IntPairBuilder { /* ... */ }
+   }
+
+   pub struct IntPairBuilder { /* base + every own field */ }
+
+   impl IntPairBuilder {
+       /// One consuming setter per field -- one uniform API.
+       pub fn a(mut self, a: i64) -> Self { /* ... */ }
+       pub fn b(mut self, b: i64) -> Self { /* ... */ }
+       pub fn scale(mut self, scale: i64) -> Self { /* ... */ }
+       /// Allocates the object (`ObjectArc::new`); errors if a field without
+       /// a default is still unset.
+       pub fn build(self) -> Result<IntPair> { /* ... */ }
+       /// The bare struct value -- what a derived type's `base(...)` setter takes.
+       pub fn build_obj(self) -> Result<IntPairObj> { /* ... */ }
+   }
+
+The object has the same memory layout as its C++ counterpart. Users can create new objects
+on the Rust side and call the methods defined in C++:
+
+.. 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 via setter
+   let err = IntPair::ffi_new().a(1).build();                    // Err: field `b` is not set
+
+Construction is fully Rust-native and the API is uniform: ``ffi_new()`` is
+nullary for root and derived types alike, and every input -- own fields and a
+derived type's ``base`` -- is set through its like-named consuming setter.
+Fields with a ``refl::default_value`` are rendered as Rust literals at
+stub-generation time and prefilled in the builder; fields without a default
+start unset, and ``build()`` returns an error if any is still missing. The
+builder deliberately bypasses any C++ constructor logic; users who need the
+faithful C++ semantics can hand-write a ``new`` constructor (outside the
+generated markers) on top of the builder.
+
+A derived type's builder feeds its embedded parent through ``base(...)``,
+which takes the bare parent value produced by the parent builder's
+``build_obj()`` (emitted on every builder):
+
+.. code-block:: rust
+
+   let p3 = Point3D::ffi_new()
+       .base(Point::ffi_new().x(1).y(2).build_obj()?)
+       .z(3)
+       .build()?;
+
+When ``base`` is left unset, ``build()`` default-constructs the parent through
+its all-default builder -- silently when every parent field has a default, and
+with a build-time error naming ``base`` when one does not.
+
+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 +512,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`.

examples/rust_stubgen/rust/Cargo.toml

@@ -0,0 +1,26 @@
+# 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.
+
+[package]
+name = "rust_stubgen_example"
+version = "0.1.0"
+edition = "2021"
+license = "Apache-2.0"
+publish = false
+
+[dependencies]
+tvm-ffi = { path = "../../../rust/tvm-ffi" }