CXX — Rust 和 C++ 之间安全的 FFI

此库提供了一个 安全的 机制来从 Rust 调用 C++ 代码，并从 C++ 调用 Rust 代码，不受使用 bindgen 或 cbindgen 生成不安全的 C 风格绑定时可能出现的问题的影响。

但这并不意味着 100% 的 C++ 代码都是不安全的。在审计项目时，你将负责审计所有的 Rust 不安全代码和 所有的 C++ 代码。在此新模型下的核心安全主张是，仅审计 C++ 一侧就足以捕获所有问题，即 Rust 一侧可以 100% 安全。

[dependencies]
cxx = "1.0"

[build-dependencies]
cxx-build = "1.0"

编译器支持：需要 rustc 1.63+ 和 c++11 或更高版本
发行说明

指南

请参阅 https://cxx.rs 以获取教程、参考资料和示例代码。

概述

我们的想法是将我们 FFI 边界两边的签名定义在一起嵌入到一个 Rust 模块中（下一节将展示一个示例）。基于此，CXX 可以获得关于边界的完整视图，以对类型和函数签名进行静态分析，以维护 Rust 和 C++ 的不变性和要求。

如果一切检查无误，则 CXX 使用一对代码生成器，在两边的相关 extern "C" 签名上同时发出，以及在任何必要的静态断言，以在构建过程中的后续阶段验证正确性。在 Rust 一侧，此代码生成器只是一个属性过程宏。在 C++ 一侧，如果您的构建由 Cargo 管理，则可以是一个小的 Cargo 构建脚本，或者对于 Bazel 或 Buck 等其他构建系统，我们提供了一个命令行工具，该工具生成头文件和源文件，应该易于集成。

结果 FFI 桥接在零或可忽略的开销下运行，即无需复制、序列化、内存分配或运行时检查。

FFI签名可以使用任一端的本地类型，例如Rust的String或C++的std::string，Rust的Box或C++的std::unique_ptr，Rust的Vec或C++的std::vector等，以任何组合方式。CXX确保一个ABI兼容的签名，双方都理解，基于对关键标准库类型的内置绑定来暴露给另一语言的惯用API。例如，当从Rust操作C++字符串时，其len()方法变为调用C++定义的size()成员函数；当从C++操作Rust字符串时，其size()成员函数调用Rust的len()。

示例

在这个例子中，我们编写了一个Rust应用程序，该程序希望利用现有的大文件blobstore服务的C++客户端。Blobstore支持对不连续缓冲区上传的put操作。例如，我们可能会上传循环缓冲区的快照，这些快照通常由2个块组成，或者由于某些原因在内存中分散的文件片段。

此示例的可执行版本位于此存储库的demo目录下。要尝试运行，请在该目录中运行cargo run。

#[cxx::bridge]
mod ffi {
    // Any shared structs, whose fields will be visible to both languages.
    struct BlobMetadata {
        size: usize,
        tags: Vec<String>,
    }

    extern "Rust" {
        // Zero or more opaque types which both languages can pass around but
        // only Rust can see the fields.
        type MultiBuf;

        // Functions implemented in Rust.
        fn next_chunk(buf: &mut MultiBuf) -> &[u8];
    }

    unsafe extern "C++" {
        // One or more headers with the matching C++ declarations. Our code
        // generators don't read it but it gets #include'd and used in static
        // assertions to ensure our picture of the FFI boundary is accurate.
        include!("demo/include/blobstore.h");

        // Zero or more opaque types which both languages can pass around but
        // only C++ can see the fields.
        type BlobstoreClient;

        // Functions implemented in C++.
        fn new_blobstore_client() -> UniquePtr<BlobstoreClient>;
        fn put(&self, parts: &mut MultiBuf) -> u64;
        fn tag(&self, blobid: u64, tag: &str);
        fn metadata(&self, blobid: u64) -> BlobMetadata;
    }
}

现在我们只需提供extern "Rust"块中所有内容的Rust定义和extern "C++"块中所有内容的C++定义，并安全地进行相互调用。

以下是涉及此演示的完整源文件集合的链接

• demo/src/main.rs
• demo/build.rs
• demo/include/blobstore.h
• demo/src/blobstore.cc

查看由CXX代码生成器在两种语言中为示例生成的代码的详细信息

   # run Rust code generator and print to stdout
   # (requires https://github.com/dtolnay/cargo-expand)
$ cargo expand --manifest-path demo/Cargo.toml

   # run C++ code generator and print to stdout
$ cargo run --manifest-path gen/cmd/Cargo.toml -- demo/src/main.rs

细节

如示例所示，FFI边界涉及3种类型的项

• 共享结构 — 其字段对两种语言都可见。在cxx::bridge中编写的定义是单一事实来源。

• 不可见类型 — 其字段对另一语言保密。这些类型不能通过值传递给FFI，而只能通过间接方式传递，例如引用&、Rust的Box或UniquePtr。可以是类型别名，用于任意复杂度的泛型语言特定类型，具体取决于您的使用情况。

• 函数 — 在任一语言中实现，可从另一语言调用。

# Cargo.toml

[build-dependencies]
cxx-build = "1.0"

// build.rs

fn main() {
    cxx_build::bridge("src/main.rs")  // returns a cc::Build
        .file("src/demo.cc")
        .std("c++11")
        .compile("cxxbridge-demo");

    println!("cargo:rerun-if-changed=src/main.rs");
    println!("cargo:rerun-if-changed=src/demo.cc");
    println!("cargo:rerun-if-changed=include/demo.h");
}

$ cargo install cxxbridge-cmd

$ cxxbridge src/main.rs --header > path/to/mybridge.h
$ cxxbridge src/main.rs > path/to/mybridge.cc