CXX 项目使用教程

1. 项目介绍

CXX 是一个用于 Rust 和 C++ 之间安全互操作的库。它提供了一种机制，使得从 Rust 调用 C++ 代码和从 C++ 调用 Rust 代码变得更加安全，避免了使用 bindgen 或 cbindgen 生成不安全 C 风格绑定时可能出现的许多问题。CXX 的核心安全特性在于，通过静态分析确保 Rust 和 C++ 之间的类型和函数签名一致，从而在编译时捕获潜在的错误。

2. 项目快速启动

2.1 安装依赖

首先，确保你已经安装了 Rust 和 Cargo。然后，在项目中添加 CXX 依赖：

[dependencies]
cxx = "1.0"

[build-dependencies]
cxx-build = "1.0"

2.2 创建 Rust 和 C++ 代码

假设你有一个 Rust 项目，并且希望在其中调用 C++ 代码。首先，创建一个 Rust 模块 ffi，并在其中定义 Rust 和 C++ 之间的接口：

#[cxx::bridge]
mod ffi {
    // 共享结构体
    struct BlobMetadata {
        size: usize,
        tags: Vec<String>,
    }

    extern "Rust" {
        // Rust 中的类型和函数
        type MultiBuf;
        fn next_chunk(buf: &mut MultiBuf) -> &[u8];
    }

    unsafe extern "C++" {
        // C++ 中的类型和函数
        include!("path/to/your/header.h");
        type BlobstoreClient;
        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;
    }
}

2.3 实现 Rust 和 C++ 代码

在 Rust 中实现 MultiBuf 和 next_chunk 函数：

pub struct MultiBuf {
    // 你的实现
}

pub fn next_chunk(buf: &mut MultiBuf) -> &[u8] {
    // 你的实现
}

在 C++ 中实现 BlobstoreClient 和相关函数：

#include "path/to/your/header.h"

class BlobstoreClient {
public:
    BlobstoreClient() {
        // 你的实现
    }

    uint64_t put(rust::Slice<const uint8_t> parts) {
        // 你的实现
    }

    void tag(uint64_t blobid, const rust::Str& tag) {
        // 你的实现
    }

    BlobMetadata metadata(uint64_t blobid) {
        // 你的实现
    }
};

2.4 编译和运行

在 build.rs 中添加以下内容，以确保 C++ 代码被正确编译：

fn main() {
    cxx_build::bridge("src/main.rs")
        .file("src/your_cpp_file.cc")
        .flag("-std=c++11")
        .compile("your_crate_name");

    println!("cargo:rerun-if-changed=src/main.rs");
    println!("cargo:rerun-if-changed=src/your_cpp_file.cc");
    println!("cargo:rerun-if-changed=path/to/your/header.h");
}

最后，运行你的 Rust 项目：

cargo run

3. 应用案例和最佳实践

3.1 案例：使用 C++ 库加速 Rust 应用

假设你有一个 Rust 应用，需要处理大量数据，而你发现 C++ 库在处理这些数据时性能更好。你可以使用 CXX 将 C++ 库集成到 Rust 应用中，从而在不牺牲性能的前提下，利用 Rust 的安全性和易用性。

3.2 最佳实践

• 类型安全：尽量使用 CXX 提供的类型安全机制，避免手动编写不安全的 FFI 代码。
• 静态分析：利用 CXX 的静态分析功能，确保 Rust 和 C++ 之间的接口一致性。
• 模块化设计：将 Rust 和 C++ 代码分离，确保每个模块的职责清晰，便于维护和扩展。

4. 典型生态项目

4.1 cxx-build

cxx-build 是 CXX 项目的一部分，用于在 Cargo 构建脚本中生成和编译 C++ 代码。它简化了 Rust 和 C++ 代码的集成过程。

4.2 cxxbridge-cmd

cxxbridge-cmd 是一个独立的命令行工具，用于在非 Cargo 构建系统中生成 C++ 代码。它适用于需要与 Bazel 或 Buck 等构建系统集成的项目。

通过这些工具和库，CXX 提供了一个完整的解决方案，使得 Rust 和 C++ 之间的互操作变得更加简单和安全。