172 个版本 (稳定版)

1.0.126	2024 年 8 月 15 日
1.0.124	2024 年 6 月 14 日
1.0.120	2024 年 3 月 23 日
1.0.111	2023 年 12 月 17 日
0.2.1	2020 年 3 月 31 日

在 FFI 中排名 #11

每月下载量 77,300

MIT/Apache

330KB
9K SLoC

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++客户端来利用大型文件blob存储服务。Blob存储支持对不连续缓冲区上传的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++定义，并安全地双向调用。

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

查看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。可以是特定语言类型别名，具体取决于您的使用情况。

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

在CXX桥接的extern "Rust"部分，我们列出了类型和函数，这些类型和函数以Rust为真实来源。这些都隐式地引用了super模块，即CXX桥接的父模块。您可以将上面列出的两个示例项目想象成类似于use super::MultiBuf和use super::next_chunk，除了重新导出到C++。父模块将直接包含简单事物的定义，或者包含相关的use语句，从其他地方引入它们。在extern "C++"部分，我们列出了类型和函数，这些类型和函数以C++为真实来源，以及声明这些API的头文件。在未来，这个部分可能可以通过bindgen风格从头文件中生成，但到目前为止，我们需要写出签名；静态断言将验证它们的准确性。您的函数实现，无论是在C++还是Rust中，不需要被定义为extern "C" ABI或no_mangle。CXX将在需要的地方插入正确的shim，以确保一切正常工作。与bindgen和cbindgen的比较请注意，在使用CXX时，所有函数签名都是重复的：它们在定义实现的地方（在C++或Rust中）被键入一次，然后在cxx::bridge模块内部再次键入，尽管编译时断言保证了这些签名保持同步。这与bindgen和cbindgen不同，在bindgen和cbindgen中，人类一次键入函数签名，工具在一个语言中消耗它们，并在另一个语言中输出。这是因为CXX扮演着略有不同的角色。从某种意义上说，它是一个比bindgen或cbindgen更低级的工具；您可以将它视为是我们所知道的extern "C"签名的替代品，而不是bindgen的替代品。在CXX之上构建一个高级的bindgen-like工具是合理的，该工具消耗C++头文件和/或Rust模块（和/或类似Thrift的IDL）作为真实来源，并生成cxx::bridge，消除重复，同时利用CXX的静态分析安全性保证。但请注意，在其他方面，CXX比bindgens更高级，具有对常见标准库类型的丰富支持。通常在使用bindgen时，当我们处理一个惯用的C++ API时，我们最终会手动将此API包装在C-style原始指针函数中，应用bindgen以获取不安全的原始指针Rust函数，并再次复制API以在Rust中习惯性地公开这些API。这是一种更糟糕的重复形式，因为它是全程不安全的。通过使用CXX桥接作为语言之间的共享理解，而不是作为共享理解的extern "C" C-style签名，常见的FFI用例可以使用100%安全的代码来表示。也可以合理地混合搭配，使用CXX桥接器处理您95%的FFI，这部分FFI是直接简单的，剩下的少量复杂签名则采用传统的bindgen和cbindgen方式处理，如果CXX的静态限制影响了某些方面。如果您采取这种方法，请提交一个问题，以便我们知道有哪些方式值得改进这个工具的表达能力。基于Cargo的设置对于由Cargo编排的构建，您将使用一个构建脚本，该脚本运行CXX的C++代码生成器，并编译生成的C++代码以及您crate中的任何其他C++代码。标准的构建脚本如下。指示的行返回一个cc::Build实例（来自广泛使用的cccrate），您可以在其上设置任何额外的源文件和编译器标志，就像平常一样。 # 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设置对于Bazel或Buck等非Cargo构建，CXX提供了一种作为独立命令行工具调用C++代码生成器的替代方法。该工具作为crates.io上的cxxbridge-cmdcrate打包，也可以从该repo的gen/cmd目录构建。 $ cargo install cxxbridge-cmd $ cxxbridge src/main.rs --header > path/to/mybridge.h $ cxxbridge src/main.rs > path/to/mybridge.cc 安全性请注意，这个库的设计故意是受限的和有观点的！我们的目标不是足够强大以处理任意语言中的任意签名。相反，这个项目是为了创建一组合理可表达的功能，关于这些功能，我们今天可以做出有用的安全保证，也许随着时间的推移可以扩展。您可能会发现，要有效地使用CXX桥接器需要一些练习，因为它不会以您习惯的所有方式工作。确保安全性的考虑因素包括出于设计，我们的配对代码生成器共同工作，以控制FFI边界的两侧。通常在Rust中，编写自己的extern "C"块是不安全的，因为Rust编译器不知道您所编写的签名是否与另一语言中实现的签名匹配。使用CXX，我们实现了这种可见性并知道另一侧是什么。我们的静态分析检测并防止将不应按值传递的类型从C++传递到Rust，例如，因为它们可能包含Rust的移动行为会搞砸的内部指针。出人意料的是，Rust中的一个结构和C++中的一个结构可以具有完全相同的布局/字段/对齐/一切，但在按值传递时仍然可能不是相同的ABI。这是一个长期存在的bindgen错误，会导致看起来完全正确的代码发生段错误（rust-lang/rust-bindgen#778）。CXX知道这一点，可以在需要的地方透明地插入必要的零成本解决方案，所以您可以放心地按值传递结构体。这是通过拥有边界的两边而不是一边来实现的。模板实例化：例如，为了在Rust中暴露由真实的C++ unique_ptr支持的UniquePtr<T>类型，我们有一种使用Rust trait将行为连接到另一语言执行的模板实例化的方式。内置类型除了所有原始类型（i32 <=> int32_t）之外，以下常见类型可以用作共享结构体的字段以及函数的参数和返回值。 Rust中的名称 C++中的名称限制 String rust::String &str rust::Str &[T] rust::Slice<const T> ^{不能持有不透明的C++类型} &mut [T] rust::Slice<T> ^{不能持有不透明的C++类型} CxxString std::string ^{不能按值传递} Box rust::Box ^{不能持有不透明的C++类型} UniquePtr std::unique_ptr ^{无法持有不透明的Rust类型} SharedPtr std::shared_ptr ^{无法持有不透明的Rust类型} [T; N] std::array ^{不能持有不透明的C++类型} Vec rust::Vec ^{不能持有不透明的C++类型} CxxVector std::vector ^{不能按值传递，无法持有不透明的Rust类型} *mut T, *const T T*, const T* ^{使用原始指针参数的fn必须声明为unsafe才能调用} fn(T, U) -> V rust::Fn ^{目前只实现了从Rust传递到C++} Result throw/catch ^{仅作为返回类型允许} 此repo中的include/cxx.h文件定义了rust命名空间的C++ API。当使用这些类型时，您需要在C++代码中包含此头文件。以下类型计划“很快”支持，但尚未实现。我不认为这些会有太大的困难，但这是一个为每种语言设计良好API的问题。 Rust中的名称 C++中的名称 BTreeMap ^待定 HashMap ^待定 Arc ^待定 Option ^待定 ^待定 std::map ^待定 std::unordered_map 剩余工作 CXX还处于早期阶段；我将其作为一个最小可行产品发布，以收集关于方向的反馈并邀请合作者。请检查开放的问题。特别是，如果您在构建或链接这些内容时遇到问题，请特别报告这些问题。我确信有办法使构建方面更友好或更健壮。最后，我对Rust库设计比C++库设计了解更多，所以如果有人有建议，我会很高兴得到帮助，使本项目的C++ API更具一致性。许可证 ^{根据您的选择，许可在Apache License, Version 2.0或MIT许可下。请参阅Apache License, Version 2.0或MIT license。} _{除非您明确说明，否则根据Apache-2.0许可定义的您有意提交的任何贡献，都应如上所述双许可，不附加任何其他条款或条件。}

Rust中的名称	C++中的名称	限制
String	rust::String
&str	rust::Str
&[T]	rust::Slice<const T>	^{不能持有不透明的C++类型}
&mut [T]	rust::Slice<T>	^{不能持有不透明的C++类型}
CxxString	std::string	^{不能按值传递}
Box	rust::Box	^{不能持有不透明的C++类型}
UniquePtr	std::unique_ptr	^{无法持有不透明的Rust类型}
SharedPtr	std::shared_ptr	^{无法持有不透明的Rust类型}
[T; N]	std::array	^{不能持有不透明的C++类型}
Vec	rust::Vec	^{不能持有不透明的C++类型}
CxxVector	std::vector	^{不能按值传递，无法持有不透明的Rust类型}
mut T, const T	T, const T	^{使用原始指针参数的fn必须声明为unsafe才能调用}
fn(T, U) -> V	rust::Fn	^{目前只实现了从Rust传递到C++}
Result	throw/catch	^{仅作为返回类型允许}

Rust中的名称	C++中的名称
BTreeMap	^待定
HashMap	^待定
Arc	^待定
Option	^待定
^待定	std::map
^待定	std::unordered_map

依赖项 ~1.7–9MB ~76K SLoC clap 4.3+error-context+help+std+suggestions+usage codespan-reporting proc-macro2+span-locations quote syn+clone-impls+full+parsing+printing 其他功能 experimental-async-fn