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 以获取教程、参考资料和示例代码。

概述

我们的想法是，在一个 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()。

示例

在这个示例中，我们正在编写一个希望利用现有C++客户端的大文件blobstore服务的Rust应用程序。这个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