7.2 与 C++ 互操作 on 编程那些事儿

7.2.1 桥接模块

Tue, 11 Aug 2026 11:30:00 +0800

译文 · 基于 Comprehensive Rust

原文链接: https://google.github.io/comprehensive-rust/android/interoperability/cpp/bridge.html

7.2.1 桥接模块

CXX 依赖对将从每种语言向另一种语言暴露的函数签名的描述。你在一个用 #[cxx::bridge] 属性宏标注的 Rust 模块中，通过 extern 块提供该描述。

// Copyright 2023 Google LLC
// SPDX-License-Identifier: Apache-2.0
#[allow(unsafe_op_in_unsafe_fn)]
#[cxx::bridge(namespace = "org::blobstore")]
mod ffi {
 // Shared structs with fields visible to both languages.
 struct BlobMetadata {
 size: usize,
 tags: Vec<String>,
 }

 // Rust types and signatures exposed to C++.
 extern "Rust" {
 type MultiBuf;

 fn next_chunk(buf: &mut MultiBuf) -> &[u8];
 }

 // C++ types and signatures exposed to Rust.
 unsafe extern "C++" {
 include!("include/blobstore.h");

 type BlobstoreClient;

 fn new_blobstore_client() -> UniquePtr<BlobstoreClient>;
 fn put(self: Pin<&mut BlobstoreClient>, parts: &mut MultiBuf) -> u64;
 fn tag(self: Pin<&mut BlobstoreClient>, blobid: u64, tag: &str);
 fn metadata(&self, blobid: u64) -> BlobMetadata;
 }
}

桥接一般声明在 crate 内的 ffi 模块中。

根据桥接模块中的声明，CXX 会生成匹配的 Rust 与 C++ 类型/函数定义，以便将这些项暴露给两种语言。

要查看生成的 Rust 代码，使用 cargo-expand 查看展开后的 proc macro。对大多数示例你会用 cargo expand ::ffi 只展开 ffi 模块（不过这不适用于 Android 项目）。

要查看生成的 C++ 代码，请查看 target/cxxbridge。

7.2.2 Rust 桥接

Tue, 11 Aug 2026 11:30:00 +0800

译文 · 基于 Comprehensive Rust

原文链接: https://google.github.io/comprehensive-rust/android/interoperability/cpp/rust-bridge.html

7.2.2 Rust 桥接

// Copyright 2023 Google LLC
// SPDX-License-Identifier: Apache-2.0
#[cxx::bridge]
mod ffi {
 extern "Rust" {
 type MyType; // Opaque type
 fn foo(&self); // Method on `MyType`
 fn bar() -> Box<MyType>; // Free function
 }
}

struct MyType(i32);

impl MyType {
 fn foo(&self) {
 println!("{}", self.0);
 }
}

fn bar() -> Box<MyType> {
 Box::new(MyType(123))
}

extern "Rust" 中声明的项引用父模块作用域中的项。

CXX 代码生成器使用你的 extern "Rust" 区段生成包含对应 C++ 声明的 C++ 头文件。生成的头文件路径与包含桥接的 Rust 源文件相同，只是扩展名为 .rs.h。

7.2.3 生成的 C++

Tue, 11 Aug 2026 11:30:00 +0800

译文 · 基于 Comprehensive Rust

原文链接: https://google.github.io/comprehensive-rust/android/interoperability/cpp/generated-cpp.html

7.2.3 生成的 C++

// Copyright 2023 Google LLC
// SPDX-License-Identifier: Apache-2.0
#[cxx::bridge]
mod ffi {
 // Rust types and signatures exposed to C++.
 extern "Rust" {
 type MultiBuf;

 fn next_chunk(buf: &mut MultiBuf) -> &[u8];
 }
}

大致会得到如下 C++：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


struct MultiBuf final : public ::rust::Opaque {
 ~MultiBuf() = delete;

private:
 friend ::rust::layout;
 struct layout {
 static ::std::size_t size() noexcept;
 static ::std::size_t align() noexcept;
 };
};

::rust::Slice<::std::uint8_t const> next_chunk(::org::blobstore::MultiBuf &buf) noexcept;

7.2.4 C++ 桥接

Tue, 11 Aug 2026 11:30:00 +0800

译文 · 基于 Comprehensive Rust

原文链接: https://google.github.io/comprehensive-rust/android/interoperability/cpp/cpp-bridge.html

7.2.4 C++ 桥接

// Copyright 2023 Google LLC
// SPDX-License-Identifier: Apache-2.0
#[cxx::bridge]
mod ffi {
 // C++ types and signatures exposed to Rust.
 unsafe extern "C++" {
 include!("include/blobstore.h");

 type BlobstoreClient;

 fn new_blobstore_client() -> UniquePtr<BlobstoreClient>;
 fn put(self: Pin<&mut BlobstoreClient>, parts: &mut MultiBuf) -> u64;
 fn tag(self: Pin<&mut BlobstoreClient>, blobid: u64, tag: &str);
 fn metadata(&self, blobid: u64) -> BlobMetadata;
 }
}

大致会得到如下 Rust：

7.2.5 共享类型

Tue, 11 Aug 2026 11:30:00 +0800

译文 · 基于 Comprehensive Rust

原文链接: https://google.github.io/comprehensive-rust/android/interoperability/cpp/shared-types.html

7.2.5 共享类型

// Copyright 2023 Google LLC
// SPDX-License-Identifier: Apache-2.0
#[cxx::bridge]
mod ffi {
 #[derive(Clone, Debug, Hash)]
 struct PlayingCard {
 suit: Suit,
 value: u8, // A=1, J=11, Q=12, K=13
 }

 enum Suit {
 Clubs,
 Diamonds,
 Hearts,
 Spades,
 }
}

只支持类 C（unit）枚举。

共享类型上的 #[derive()] 只支持有限数量的 trait。对应功能也会为 C++ 代码生成，例如若你 derive Hash，也会为对应的 C++ 类型生成 std::hash 实现。

7.2.6 共享枚举

Tue, 11 Aug 2026 11:30:00 +0800

译文 · 基于 Comprehensive Rust

原文链接: https://google.github.io/comprehensive-rust/android/interoperability/cpp/shared-enums.html

7.2.6 共享枚举

// Copyright 2023 Google LLC
// SPDX-License-Identifier: Apache-2.0
#[cxx::bridge]
mod ffi {
 enum Suit {
 Clubs,
 Diamonds,
 Hearts,
 Spades,
 }
}

生成的 Rust：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


// Copyright 2023 Google LLC
// SPDX-License-Identifier: Apache-2.0
#[derive(Copy, Clone, PartialEq, Eq)]
#[repr(transparent)]
pub struct Suit {
 pub repr: u8,
}

#[allow(non_upper_case_globals)]
impl Suit {
 pub const Clubs: Self = Suit { repr: 0 };
 pub const Diamonds: Self = Suit { repr: 1 };
 pub const Hearts: Self = Suit { repr: 2 };
 pub const Spades: Self = Suit { repr: 3 };
}

生成的 C++：

7.2.7 Rust 错误处理

Tue, 11 Aug 2026 11:30:00 +0800

译文 · 基于 Comprehensive Rust

原文链接: https://google.github.io/comprehensive-rust/android/interoperability/cpp/rust-result.html

7.2.7 Rust 错误处理

// Copyright 2023 Google LLC
// SPDX-License-Identifier: Apache-2.0
#[cxx::bridge]
mod ffi {
 extern "Rust" {
 fn fallible(depth: usize) -> Result<String>;
 }
}

fn fallible(depth: usize) -> anyhow::Result<String> {
 if depth == 0 {
 return Err(anyhow::Error::msg("fallible1 requires depth > 0"));
 }

 Ok("Success!".into())
}

返回 Result 的 Rust 函数在 C++ 一侧会翻译成异常。

抛出的异常类型始终是 rust::Error，它主要提供获取错误消息字符串的方式。错误消息来自错误类型的 Display 实现。

从 Rust 展开到 C++ 的 panic 总会导致进程立即终止。

7.2.8 C++ 错误处理

Tue, 11 Aug 2026 11:30:00 +0800

译文 · 基于 Comprehensive Rust

原文链接: https://google.github.io/comprehensive-rust/android/interoperability/cpp/cpp-exception.html

7.2.8 C++ 错误处理

// Copyright 2023 Google LLC
// SPDX-License-Identifier: Apache-2.0
#[cxx::bridge]
mod ffi {
 unsafe extern "C++" {
 include!("example/include/example.h");
 fn fallible(depth: usize) -> Result<String>;
 }
}

fn main() {
 if let Err(err) = ffi::fallible(99) {
 eprintln!("Error: {}", err);
 process::exit(1);
 }
}

声明为返回 Result 的 C++ 函数会在 C++ 一侧捕获任何抛出的异常，并将其作为 Err 值返回给调用的 Rust 函数。

若异常从 CXX 桥接未声明返回 Result 的 extern “C++” 函数抛出，程序会调用 C++ 的 std::terminate。行为等价于同一异常穿过一个 noexcept C++ 函数。

7.2.9 其他类型

Tue, 11 Aug 2026 11:30:00 +0800

译文 · 基于 Comprehensive Rust

原文链接: https://google.github.io/comprehensive-rust/android/interoperability/cpp/type-mapping.html

7.2.9 其他类型

Rust 类型	C++ 类型
`String`	`rust::String`
`&str`	`rust::Str`
`CxxString`	`std::string`
`&[T]`/`&mut [T]`	`rust::Slice`
`Box<T>`	`rust::Box<T>`
`UniquePtr<T>`	`std::unique_ptr<T>`
`Vec<T>`	`rust::Vec<T>`
`CxxVector<T>`	`std::vector<T>`

这些类型可用于共享结构体的字段，以及 extern 函数的参数与返回值。

注意 Rust 的 String 并不直接映射到 std::string。原因有几点：

std::string 并不维护 String 所要求的 UTF-8 不变量。

两种类型在内存中的布局不同，因此不能在语言之间直接传递。

std::string 需要与 Rust 移动语义不匹配的移动构造函数，因此 std::string 不能按值传给 Rust。

7.2.10 为 Android 构建：Genrules

Tue, 11 Aug 2026 11:30:00 +0800

译文 · 基于 Comprehensive Rust

原文链接: https://google.github.io/comprehensive-rust/android/interoperability/cpp/android-cpp-genrules.html

7.2.10 为 Android 构建：Genrules

创建两个 genrule：一个生成 CXX 头文件，一个生成 CXX 源文件。它们随后用作 cc_library_static 的输入。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


// 生成包含 C++ 绑定的 C++ 头文件，
// 对应 lib.rs 中导出的 Rust 函数。
genrule {
 name: "libcxx_test_bridge_header",
 tools: ["cxxbridge"],
 cmd: "$(location cxxbridge) $(in) --header > $(out)",
 srcs: ["lib.rs"],
 out: ["lib.rs.h"],
}

// 生成 Rust 将调用的 C++ 代码。
genrule {
 name: "libcxx_test_bridge_code",
 tools: ["cxxbridge"],
 cmd: "$(location cxxbridge) $(in) > $(out)",
 srcs: ["lib.rs"],
 out: ["lib.rs.cc"],
}

cxxbridge 工具是生成桥接模块 C++ 一侧的独立工具。它已包含在 Android 中，并可作为 Soong 工具使用。

按约定，若你的 Rust 源文件是 lib.rs，头文件将命名为 lib.rs.h，源文件将命名为 lib.rs.cc。不过这一命名约定并未强制执行。

7.2.11 为 Android 构建：C++

Tue, 11 Aug 2026 11:30:00 +0800

译文 · 基于 Comprehensive Rust

原文链接: https://google.github.io/comprehensive-rust/android/interoperability/cpp/android-build-cpp.html

7.2.11 为 Android 构建：C++

创建一个 cc_library_static 来构建 C++ 库，包括 CXX 生成的头文件与源文件。

1
2
3
4
5
6
7
8
9


cc_library_static {
 name: "libcxx_test_cpp",
 srcs: ["cxx_test.cpp"],
 generated_headers: [
 "cxx-bridge-header",
 "libcxx_test_bridge_header"
 ],
 generated_sources: ["libcxx_test_bridge_code"],
}

指出 libcxx_test_bridge_header 与 libcxx_test_bridge_code 是 CXX 生成的 C++ 绑定的依赖。下一页会展示如何设置它们。

注意你还需要依赖 cxx-bridge-header 库，以便引入通用的 CXX 定义。

在 Android 中使用 CXX 的完整文档见 Android 文档。你可能想把该链接分享给学员，以便他们知道以后在哪里可以再次找到这些说明。

7.2.12 为 Android 构建：Rust

Tue, 11 Aug 2026 11:30:00 +0800

译文 · 基于 Comprehensive Rust

原文链接: https://google.github.io/comprehensive-rust/android/interoperability/cpp/android-build-rust.html

7.2.12 为 Android 构建：Rust

创建一个依赖 libcxx 与你的 cc_library_static 的 rust_binary。

1
2
3
4
5
6


rust_binary {
 name: "cxx_test",
 srcs: ["lib.rs"],
 rustlibs: ["libcxx"],
 static_libs: ["libcxx_test_cpp"],
}