mirror of
https://gitee.com/openharmony/third_party_rust_bindgen
synced 2025-03-02 19:55:59 +00:00
add oh user guide
Signed-off-by: fangting <fangting12@huawei.com>
This commit is contained in:
parent
d38bf94a83
commit
71a0ae1f77
109
README_zh.md
109
README_zh.md
@ -1,7 +1,7 @@
|
||||
[](https://crates.io/crates/bindgen)
|
||||
[](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"
|
||||
}
|
||||
```
|
||||
|
||||
**调测验证**
|
||||
|
||||

|
||||
|
||||
## 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
BIN
bindgen_test.png
Normal file
Binary file not shown.
After Width: | Height: | Size: 55 KiB |
Loading…
x
Reference in New Issue
Block a user