add oh user guide

Signed-off-by: fangting <fangting12@huawei.com>
This commit is contained in:
fangting 2023-05-04 11:41:38 +08:00
parent d38bf94a83
commit 71a0ae1f77
2 changed files with 105 additions and 4 deletions

View File

@ -1,7 +1,7 @@
[![crates.io](https://img.shields.io/crates/v/bindgen.svg)](https://crates.io/crates/bindgen)
[![docs.rs](https://docs.rs/bindgen/badge.svg)](https://docs.rs/bindgen/)
## bindgen
## 引入背景
`bindgen` 自动生成Rust与C和一些C++库的FFI绑定。
@ -99,10 +99,105 @@ bindgen的目录树结构如下
└── rustfmt.toml
```
## Bindgen工具在OH上的使用指导
## 使用指导
### 操作步骤
下面是一个使用bindgen实现Rust调用C的示例。
建议初学者先阅读[使用指导](https://rust-lang.github.io/rust-bindgen)然后build仓下rust/tests/test_bindgen_test来具体使用该工具加深理解。
1. 在C代码侧使用头文件lib.h定义两个接口接口FuncAAddB用来实现两数求和接口SayHello用来打印字符串。
```c
#ifndef BUILD_RUST_TESTS_BINDGEN_TEST_LIB_H_
#define BUILD_RUST_TESTS_BINDGEN_TEST_LIB_H_
#include <stdint.h>
#include "build/rust/tests/test_bindgen_test/test_for_hello_world/lib2.h"
uint32_t FuncAAddB(uint32_t a, uint32_t b);
void SayHello(const char *message);
#endif // BUILD_RUST_TESTS_BINDGEN_TEST_LIB_H_
```
2. 在lib.c中添加对两个接口的对应实现。
```c
#include "build/rust/tests/test_bindgen_test/test_for_hello_world/lib.h"
#include <stdint.h>
#include <stdio.h>
void SayHello(const char *message)
{
printf("This is a test for bindgen hello world:\n");
printf("%s\n", message);
}
uint32_t FuncAAddB(uint32_t a, uint32_t b)
{
printf("This is a test for bindgen of a + b:\n");
return a + b;
}
```
3. 添加文件main.rs就可以在Rust侧通过c_ffi实现对C侧的接口调用。注意Rust侧调用的不安全接口需要使用unsafe封装。
```rust
//! bindgen test for hello world
#![allow(clippy::approx_constant)]
mod c_ffi {
#![allow(dead_code)]
#![allow(non_upper_case_globals)]
#![allow(non_camel_case_types)]
include!(env!("BINDGEN_RS_FILE"));
}
/// pub fn add_two_numbers_in_c
pub fn add_two_numbers_in_c(a: u32, b: u32) -> u32 {
unsafe { c_ffi::FuncAAddB(a, b) }
}
use std::ffi::c_char;
use std::ffi::CString;
/// fn main()
fn main() {
println!("{} + {} = {}", 3, 7, add_two_numbers_in_c(3, 7));
let c_str = CString::new("This is a message from C").unwrap();
let c_world: *const c_char = c_str.as_ptr() as *const c_char;
unsafe {
c_ffi::SayHello(c_world);
}
}
```
4. 添加构建文件BUILD.gn建立Rust模块对C模块的依赖。
```GN
import("//build/ohos.gni")
ohos_shared_library("c_lib") {
sources = [ "lib.c" ]
defines = [ "COMPONENT_IMPLEMENTATION" ]
}
rust_bindgen("c_lib_bindgen") {
header = "lib.h"
}
ohos_rust_executable("bindgen_test") {
deps = [ ":c_lib" ]
deps += [ ":c_lib_bindgen" ]
sources = [ "main.rs" ]
bindgen_output = get_target_outputs(":c_lib_bindgen")
inputs = bindgen_output
rustenv = [ "BINDGEN_RS_FILE=" + rebase_path(bindgen_output[0]) ]
crate_root = "main.rs"
}
```
**调测验证**
![bindgen_test](./bindgen_test.png)
## MSRV
@ -110,10 +205,16 @@ Minimum support Rust版本是**1.60.0**。
目前还没有制定MSRV提升政策所以MSRV可能会在任何版本中增加。
MSRV是可用于编译`bindgen`的Minimum Rust版本。然而,`bindgen`可以生成与低于当前MSRV的Rust版本兼容的绑定。
MSRV是可用于编译`bindgen`的Minimum Rust版本。`bindgen`可以生成与低于当前MSRV的Rust版本兼容的绑定。
## API参考
[API参考文档在docs.rs上](https://docs.rs/bindgen)
## 开发者贡献
在使用该工具的过程中有任何问题欢迎开发者在社区issue中反馈。
<br>

BIN
bindgen_test.png Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 55 KiB