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.67+ 和 C++11 或更高版本
发布说明

指南

请参阅 https://cxx.rs 了解教程、参考材料和示例代码。

概述

我们的想法是在一个 Rust 模块（下一节将展示示例）中定义 FFI 边界两边的签名，并将它们嵌入在一起。基于此，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应用程序，该程序希望利用现有的C++客户端来利用大型文件blobstore服务。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边界涉及三种类型的项目

• 共享结构体 — 其字段对两种语言都是可见的。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