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边界涉及的项有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