本页面包含关于 Android 日志记录的信息，提供了一个 Rust AIDL 示例，告诉您如何从 C 调用 Rust ，并提供关于 使用 CXX 实现 Rust/C++ 互操作的说明。
Android 日志记录
以下示例展示了如何将消息记录到 logcat（设备上）或 stdout（主机上）。
在您的 Android.bp 模块中，添加 liblogger 和 liblog_rust 作为依赖项
rust_binary {
name: "logging_test",
srcs: ["src/main.rs"],
rustlibs: [
"liblogger",
"liblog_rust",
],
}
接下来，在您的 Rust 源代码中添加以下代码
use log::{debug, error, LevelFilter};
fn main() {
let _init_success = logger::init(
logger::Config::default()
.with_tag_on_device("mytag")
.with_max_level(LevelFilter::Trace),
);
debug!("This is a debug message.");
error!("Something went wrong!");
}
也就是说，添加上面显示的两个依赖项（liblogger 和 liblog_rust），调用 init 方法一次（如有必要，您可以多次调用），并使用提供的宏记录消息。请参阅 logger crate，了解可能的配置选项列表。
logger crate 提供了一个 API，用于定义您想要记录的内容。根据代码是在设备上还是在主机上运行（例如作为主机端测试的一部分），消息将使用 android_logger 或 env_logger 进行记录。
Rust AIDL 示例
本节提供了一个关于将 AIDL 与 Rust 结合使用的 Hello World 风格的示例。
使用 Android 开发者指南 AIDL 概览 部分作为起点，创建 external/rust/binder_example/aidl/com/example/android/IRemoteService.aidl，并在 IRemoteService.aidl 文件中包含以下内容
// IRemoteService.aidl
package com.example.android;
// Declare any non-default types here with import statements
/** Example service interface */
interface IRemoteService {
/** Request the process ID of this service, to do evil things with it. */
int getPid();
/**
* Demonstrates some basic types that you can use as parameters
* and return values in AIDL.
*/
void basicTypes(int anInt, long aLong, boolean aBoolean, float aFloat,
double aDouble, String aString);
}
然后，在 external/rust/binder_example/aidl/Android.bp 文件中，定义 aidl_interface 模块。您必须显式启用 Rust 后端，因为它默认情况下未启用。
aidl_interface {
name: "com.example.android.remoteservice",
srcs: [ "aidl/com/example/android/*.aidl", ],
unstable: true, // Add during development until the interface is stabilized.
backend: {
rust: {
// By default, the Rust backend is not enabled
enabled: true,
},
},
}
AIDL 后端是一个 Rust 源代码生成器，因此它的运行方式与其他 Rust 源代码生成器类似，并生成一个 Rust 库。生成的 Rust 库模块可以被其他 Rust 模块用作依赖项。作为使用生成的库作为依赖项的示例，可以在 external/rust/binder_example/Android.bp 中将 rust_library 定义如下
rust_library {
name: "libmyservice",
srcs: ["src/lib.rs"],
crate_name: "myservice",
rustlibs: [
"com.example.android.remoteservice-rust",
"libbinder_rs",
],
}
请注意，rustlibs 中使用的 AIDL 生成库的模块名称格式为 aidl_interface 模块名称后跟 -rust；在本例中为 com.example.android.remoteservice-rust。
然后可以在 src/lib.rs 中按如下方式引用 AIDL 接口
// Note carefully the AIDL crates structure:
// * the AIDL module name: "com_example_android_remoteservice"
// * next "::aidl"
// * next the AIDL package name "::com::example::android"
// * the interface: "::IRemoteService"
// * finally, the 'BnRemoteService' and 'IRemoteService' submodules
//! This module implements the IRemoteService AIDL interface
use com_example_android_remoteservice::aidl::com::example::android::{
IRemoteService::{BnRemoteService, IRemoteService}
};
use binder::{
BinderFeatures, Interface, Result as BinderResult, Strong,
};
/// This struct is defined to implement IRemoteService AIDL interface.
pub struct MyService;
impl Interface for MyService {}
impl IRemoteService for MyService {
fn getPid(&self) -> BinderResult<i32> {
Ok(42)
}
fn basicTypes(&self, _: i32, _: i64, _: bool, _: f32, _: f64, _: &str) -> BinderResult<()> {
// Do something interesting...
Ok(())
}
}
最后，在 Rust 二进制文件中启动服务，如下所示
use myservice::MyService;
fn main() {
// [...]
let my_service = MyService;
let my_service_binder = BnRemoteService::new_binder(
my_service,
BinderFeatures::default(),
);
binder::add_service("myservice", my_service_binder.as_binder())
.expect("Failed to register service?");
// Does not return - spawn or perform any work you mean to do before this call.
binder::ProcessState::join_thread_pool()
}
Async Rust AIDL 示例
本节提供了一个关于将 AIDL 与 async Rust 结合使用的 Hello World 风格的示例。
继续 RemoteService 示例，生成的 AIDL 后端库包括 async 接口，这些接口可用于为 AIDL 接口 RemoteService 实现 async 服务器实现。
生成的 async 服务器接口 IRemoteServiceAsyncServer 可以按如下方式实现
use com_example_android_remoteservice::aidl::com::example::android::IRemoteService::{
BnRemoteService, IRemoteServiceAsyncServer,
};
use binder::{BinderFeatures, Interface, Result as BinderResult};
/// This struct is defined to implement IRemoteServiceAsyncServer AIDL interface.
pub struct MyAsyncService;
impl Interface for MyAsyncService {}
#[async_trait]
impl IRemoteServiceAsyncServer for MyAsyncService {
async fn getPid(&self) -> BinderResult<i32> {
//Do something interesting...
Ok(42)
}
async fn basicTypes(&self, _: i32, _: i64, _: bool, _: f32, _: f64,_: &str,) -> BinderResult<()> {
//Do something interesting...
Ok(())
}
}
async 服务器实现可以按如下方式启动
#[tokio::main(flavor = "multi_thread", worker_threads = 2)]
async fn main() {
binder::ProcessState::start_thread_pool();
let my_service = MyAsyncService;
let my_service_binder = BnRemoteService::new_async_binder(
my_service,
TokioRuntime(Handle::current()),
BinderFeatures::default(),
);
binder::add_service("myservice", my_service_binder.as_binder())
.expect("Failed to register service?");
task::block_in_place(move || {
binder::ProcessState::join_thread_pool();
});
}
请注意，需要 block_in_place 来离开 async 上下文，从而允许 join_thread_pool 在内部使用 block_on。这是因为 #[tokio::main] 将代码包装在对 block_on 的调用中，并且 join_thread_pool 在处理传入的事务时可能会调用 block_on。从 block_on 中调用 block_on 会导致 panic。通过手动构建 tokio 运行时而不是使用 #[tokio::main]，然后在 block_on 方法之外调用 join_thread_pool，也可以避免这种情况。
此外，rust 后端生成的库包含一个接口，该接口允许为 RemoteService 实现 async 客户端 IRemoteServiceAsync，可以按如下方式实现
use com_example_android_remoteservice::aidl::com::example::android::IRemoteService::IRemoteServiceAsync;
use binder_tokio::Tokio;
#[tokio::main(flavor = "current_thread")]
async fn main() {
let binder_service = binder_tokio::wait_for_interface::<dyn IRemoteServiceAsync<Tokio>>("myservice");
let my_client = binder_service.await.expect("Cannot find Remote Service");
let result = my_client.getPid().await;
match result {
Err(err) => panic!("Cannot get the process id from Remote Service {:?}", err),
Ok(p_id) => println!("PID = {}", p_id),
}
}
从 C 调用 Rust
此示例展示了如何从 C 调用 Rust。
Rust 库示例
在 external/rust/simple_printer/libsimple_printer.rs 中定义 libsimple_printer 文件，如下所示
//! A simple hello world example that can be called from C
#[no_mangle]
/// Print "Hello Rust!"
pub extern fn print_c_hello_rust() {
println!("Hello Rust!");
}
Rust 库必须定义从属 C 模块可以拉取的标头，因此定义 external/rust/simple_printer/simple_printer.h 标头，如下所示
#ifndef SIMPLE_PRINTER_H
#define SIMPLE_PRINTER_H
void print_c_hello_rust();
#endif
按此处所示定义 external/rust/simple_printer/Android.bp
rust_ffi {
name: "libsimple_c_printer",
crate_name: "simple_c_printer",
srcs: ["libsimple_c_printer.rs"],
// Define export_include_dirs so cc_binary knows where the headers are.
export_include_dirs: ["."],
}
C 二进制文件示例
按如下所示定义 external/rust/c_hello_rust/main.c
#include "simple_printer.h"
int main() {
print_c_hello_rust();
return 0;
}
按如下所示定义 external/rust/c_hello_rust/Android.bp
cc_binary {
name: "c_hello_rust",
srcs: ["main.c"],
shared_libs: ["libsimple_c_printer"],
}
最后，通过调用 m c_hello_rust 进行构建。
Rust-Java 互操作
jni crate 通过 Java 本机接口 (JNI) 提供 Rust 与 Java 的互操作性。它定义了必要的类型定义，供 Rust 生成一个 Rust cdylib 库，该库直接插入到 Java 的 JNI（JNIEnv、JClass、JString 等）中。与通过 cxx 执行代码生成的 C++ 绑定不同，通过 JNI 实现 Java 互操作性在构建期间不需要代码生成步骤。因此，它不需要特殊的构建系统支持。Java 代码像加载任何其他原生库一样加载 Rust 提供的 cdylib。
用法
Rust 和 Java 代码中的用法都在 jni crate 文档中进行了介绍。请按照其中提供的 入门指南 示例进行操作。在您编写 src/lib.rs 后，返回此页面以了解如何使用 Android 的构建系统构建库。
构建定义
Java 要求 Rust 库以 cdylib 形式提供，以便可以动态加载它。Soong 中的 Rust 库定义如下
rust_ffi_shared {
name: "libhello_jni",
crate_name: "hello_jni",
srcs: ["src/lib.rs"],
// The jni crate is required
rustlibs: ["libjni"],
}
Java 库将 Rust 库列为 required 依赖项；这确保即使它不是构建时依赖项，也会将其与 Java 库一起安装到设备上
java_library {
name: "libhelloworld",
[...]
required: ["libhellorust"]
[...]
}
或者，如果您必须在 AndroidManifest.xml 文件中包含 Rust 库，请按如下所示将该库添加到 uses_libs
java_library {
name: "libhelloworld",
[...]
uses_libs: ["libhellorust"]
[...]
}
使用 CXX 实现 Rust–C++ 互操作
CXX crate 在 Rust 和 C++ 的子集之间提供安全的 FFI。CXX 文档提供了关于其工作原理的良好示例，我们建议您先阅读它，以熟悉该库以及它桥接 C++ 和 Rust 的方式。以下示例展示了如何在 Android 中使用它。
要让 CXX 生成 Rust 调用的 C++ 代码，请定义一个 genrule 来调用 CXX，并定义一个 cc_library_static 来将其捆绑到一个库中。如果您计划让 C++ 调用 Rust 代码，或使用 C++ 和 Rust 之间共享的类型，请定义第二个 genrule（以生成包含 Rust 绑定的 C++ 标头）。
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"],
}
// Generate the C++ code that Rust calls into.
genrule {
name: "libcxx_test_bridge_code",
tools: ["cxxbridge"],
cmd: "$(location cxxbridge) $(in) > $(out)",
srcs: ["lib.rs"],
out: ["libcxx_test_cxx_generated.cc"],
}
// Generate a C++ header containing the C++ bindings
// to the Rust exported functions in lib.rs.
genrule {
name: "libcxx_test_bridge_header",
tools: ["cxxbridge"],
cmd: "$(location cxxbridge) $(in) --header > $(out)",
srcs: ["lib.rs"],
out: ["lib.rs.h"],
}
上面的 cxxbridge 工具用于生成桥接的 C++ 端。libcxx_test_cpp 静态库接下来用作我们的 Rust 可执行文件的依赖项
rust_binary {
name: "cxx_test",
srcs: ["lib.rs"],
rustlibs: ["libcxx"],
static_libs: ["libcxx_test_cpp"],
}
在 .cpp 和 .hpp 文件中，根据需要定义 C++ 函数，使用所需的 CXX 包装器类型。例如，cxx_test.hpp 定义包含以下内容
#pragma once
#include "rust/cxx.h"
#include "lib.rs.h"
int greet(rust::Str greetee);
而 cxx_test.cpp 包含
#include "cxx_test.hpp"
#include "lib.rs.h"
#include <iostream>
int greet(rust::Str greetee) {
std::cout << "Hello, " << greetee << std::endl;
return get_num();
}
要从 Rust 中使用它，请在 lib.rs 中定义 CXX 桥接，如下所示
#[cxx::bridge]
mod ffi {
unsafe extern "C++" {
include!("cxx_test.hpp");
fn greet(greetee: &str) -> i32;
}
extern "Rust" {
fn get_num() -> i32;
}
}
fn main() {
let result = ffi::greet("world");
println!("C++ returned {}", result);
}
fn get_num() -> i32 {
return 42;
}