1 个不稳定版本

0.4.3	2020 年 9 月 7 日

#890 在编程语言中

MIT/Apache

6KB
144 行

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++定义，然后可以安全地相互调用。

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

要查看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。可以是类型别名，表示根据您的用例，任意复杂的特定语言泛型类型。

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

在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不同，在那里函数签名由人类打字一次，工具在一种语言中消耗它们，然后在另一种语言中发出它们。这是因为CXX扮演着略微不同的角色。在某种程度上，它是比bindgen或cbindgen更底层的工具；你可以将其视为我们熟悉的extern "C"签名的替代品，而不是bindgen的替代品。在CXX之上构建一个更高层次的bindgen-like工具是合理的，该工具消耗C++头文件和/或Rust模块（和/或像Thrift这样的IDL）作为真实来源，并生成cxx::bridge，从而消除重复，同时利用CXX的静态分析安全保证。但请注意，在其他方面，CXX比bindgens更高级，它对常见的标准库类型提供了丰富的支持。通常在使用bindgen时，当我们处理一个惯用的C++ API时，我们最终会手动将该API包装在C风格的原始指针函数中，应用bindgen以获取不安全的原始指针Rust函数，然后再次复制API以在Rust中以惯用的方式公开它们。这是一种更糟糕的重复形式，因为它从头到尾都是不安全的。通过使用CXX桥接作为语言之间的共同理解，而不是使用extern "C" C风格签名作为共同理解，常见的FFI用例可以使用100%安全的代码表达。也可以合理地混合使用，对于95%的FFI使用CXX桥接，因为这部分是直接的，而对于剩下的少数不规则的签名，则以传统的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特质将行为连接到另一种语言执行的模板实例化的方法。内置类型除了所有原始类型（i32 <=> int32_t）之外，以下常见类型也可以用于共享结构体的字段以及函数的参数和返回值。 Rust中的名称 C++中的名称限制字符串 rust::String &str rust::Str &[T] rust::Slice<const T> ^{无法容纳不透明C++类型} &mut [T] rust::Slice ^{无法容纳不透明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 ^{仅作为返回类型允许} 本仓库中的include/cxx.h文件定义了rust命名空间下的C++ API。当与这些类型一起使用时，您需要在C++代码中包含此头文件。以下类型“很快”将得到支持，但尚未实现。我不认为这些会很难实现，但为每种语言设计良好的API是一个问题。 Rust中的名称 C++中的名称 BTreeMap ^待定 HashMap ^待定 Arc ^待定 Option ^待定 ^待定 std::map ^待定 std::unordered_map 剩余工作 CXX还处于早期阶段；我将其作为一个最小可行产品发布，以收集关于方向和邀请合作者的反馈。请检查公开的问题。特别是，如果您在构建或链接任何这些内容时遇到问题，请报告问题。我确信有方法可以使构建方面更加友好或更健壮。最后，我比C++库设计更了解Rust库设计，所以如果有人有建议，我会很感激，使这个项目的C++ API更加符合惯例。许可证 ^{根据您的选择，在Apache License, Version 2.0或MIT许可证下许可。} _{除非您明确表示，否则，根据Apache-2.0许可证的定义，您故意提交以包含在本项目中的任何贡献，均应按上述方式双重许可，不附加任何额外条款或条件。}

Rust中的名称	C++中的名称	限制
字符串	rust::String
&str	rust::Str
&[T]	rust::Slice<const T>	^{无法容纳不透明C++类型}
&mut [T]	rust::Slice	^{无法容纳不透明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

没有运行时依赖