hicc

将 C++ 接口转换为 Rust API，以及将 Rust 接口转换为 C ABI 的工具链。

方向对应关系：

• hicc = C++ → Rust：在 Rust 中调用 C++ 代码
• hicc-rs = Rust → C：将 Rust 代码导出为 C ABI 供 C/Python 调用

项目一览

方向	项目	说明
C++ → Rust	hicc	C++ 接口转换为 Rust API 的基础功能
	hicc-build	构建支持，编译内嵌 C++ 代码
	hicc-std	C++ 标准库容器操作映射为 Rust API
Rust → C	hicc-rs	Rust 接口转换为跨语言 C ABI
	hicc-cbindgen	为 hicc-rs 导出 C 头文件或 Python ctypes 绑定

---

hicc — C++ → Rust

在 Rust 中嵌入 C++ 代码并调用 C++ 函数和类。

核心能力

• hicc::cpp! 宏嵌入 C++ 代码
• hicc::import_lib! 宏声明需要调用的 C++ API
• hicc::import_class! 宏将 C++ 类映射为 Rust struct
• import_lib! 支持 impl Foo { ... } 语句定义关联函数（#[cpp(func = ...)]，Self 自动替换）
• 支持函数重载、缺省参数、模板类、虚函数 Rust 实现、va_list 等 C++ 特性
• hicc-std 提供对 STL 容器（map、vector、string、unordered_set、array 等）的完整支持

快速使用

hicc::cpp! {
    #include <iostream>
    static int add(int a, int b) {
        return a + b;
    }
}

hicc::import_lib! {
    #![link_name = "example"]
    #[cpp(func = "int add(int, int)")]
    fn add(a: i32, b: i32) -> i32;
}

fn main() {
    println!("{}", add(1, 2));  // 3
}

详细用法见 hicc/README.md 和 reference.md。

在 import_lib 中定义关联函数

方法（带 self）写在 class 中并通过 #[cpp(method = ...)] 映射；关联函数（无 self） 可写在 impl 语句中，通过 #[cpp(func = ...)] 映射（与 import_lib! 内嵌 class 定义方式完全等价）：

hicc::import_lib! {
    #![link_name = "example"]

    #[cpp(class = "Foo")]
    class Foo {
        #[cpp(method = "void bar() const")]
        fn bar(&self);
    }

    impl Foo {
        #[cpp(func = "Foo* Foo::new_instance()")]
        fn new() -> Foo;        // Self 自动替换为 Foo
    }

    // 泛型类的具体实例化也支持
    #[cpp(class = "template<typename T> Generic<T>")]
    class Generic<T> {
        #[cpp(method = "void display() const")]
        fn display(&self);
    }

    impl Generic<hicc::Pod<i32>> {
        #[cpp(func = "Generic<int>* hicc_new_generic_int()")]
        fn create() -> Self;    // Self → Generic<hicc::Pod<i32>>
    }
}

规则要点：

• 仅提取带 #[cpp(...)] 的声明式关联函数；impl 内无 #[cpp] 的普通函数/方法（允许函数体）一律保留透传；
• 提取后 impl 块为空则整体删除；
• 泛型 impl（impl<T> Foo<T>）与 trait impl 透传不处理；
• 生成的成员函数名带 _hicc_ 前缀（如 _hicc_Foo_new），预留内部命名空间避免与用户函数冲突。

import_lib! 内嵌 class 定义（类体直接声明关联函数）作为另一等价写法也支持，详见 hicc crate 文档。

示例

示例	说明
examples/hello_world	基础 C++ 函数调用
examples/stl	通过 import_class 调用 std::string
examples/import_lib_class	import_lib 内嵌类 + impl 语句定义关联函数
examples/placement_new	在 Rust 内存空间中构造 C++ 对象
examples/rust_any	RustAny 支持 STL 容器存储 Rust 数据
examples/hicc-std	STL 容器（map/vector/string 等）完整操作

---

hicc-rs — Rust → C

通过过程宏自动将 Rust 类型和方法封装为 #[repr(C)] 的 FFI 类型，配合 hicc-cbindgen 生成 C 头文件或 Python ctypes 绑定，实现跨语言调用 Rust 代码。

核心特点

• 过程宏驱动：#[export_class] 将类型方法导出为虚方法表，#[export_lib] 将函数导出为函数表
• 全类型覆盖：支持 Option、Result、String、Vec、Box、Rc、Arc、Cell、RefCell、Mutex、RwLock、HashMap、BTreeMap、HashSet、BTreeSet、OnceLock、CString、tuple、array、slice 等标准类型
• 引用/借用安全：&T、&mut T、&str、&[T] 跨 FFI 传递时自动映射为借用，使用 'static 生命周期
• 闭包回调：跨语言传递闭包，支持 Fn、FnMut、FnOnce
• 异步支持：async 方法映射为 Box<dyn AbiFuture<R>>，支持阻塞等待和基于 Notify 的非阻塞回调
• 所有权管理：自动生成 destroy() 方法释放 Rust 堆内存

快速使用

use hicc_rs::{export_class, export_lib};

#[export_class]
impl<T> Vec<T> {
    fn push(&mut self, val: T);
    fn pop(&mut self) -> Option<T>;
    fn len(&self) -> usize;
}

#[export_lib(name = "demo")]
mod ffi {
    fn add(x: i32, y: i32) -> i32;
}

# 构建（需要 nightly feature）
RUSTC_BOOTSTRAP=1 cargo build --features cbindgen

# 生成 C 头文件
hicc-cbindgen -c . -o demo.h

# 生成 Python ctypes 绑定
hicc-cbindgen -c . -l python -o demo.py

最近更新

• Rc<T> / Arc<T> 新增 clone 和 get_mut 接口：clone(&self) -> Self（引用计数 +1），get_mut(&mut self) -> Option<&mut T>（引用计数为 1 时返回可变引用）

参考文档

• 完整开发文档
• 内置类型清单
• 异步函数参考
• 闭包 ABI 规范
• Python 绑定说明

示例

示例	说明
hicc-rs-examples/basic_lib/	函数表导出 + C/Python/Cython FFI
hicc-rs-examples/async/	异步函数/异步关联方法 + C/Python FFI
hicc-rs-examples/foreign_type/	foreign 模式封装第三方类型 + C/Python/Cython FFI
hicc-rs-examples/foo_bar_baz/	跨 crate 类型别名 + C/Python FFI
hicc-rs-examples/rust-std/	core/alloc/std 全类型覆盖 + C/Python FFI
hicc-rs-examples/no-std/	no_std 环境 + C/Python FFI（手写绑定）