概述

Rust是一門(mén)靜態(tài)強(qiáng)類(lèi)型語(yǔ)言，具有更安全的內(nèi)存管理、更好的運(yùn)行性能、原生支持多線(xiàn)程開(kāi)發(fā)等優(yōu)勢(shì)。Rust官方也使用Cargo工具來(lái)專(zhuān)門(mén)為Rust代碼創(chuàng)建工程和構(gòu)建編譯。 OpenHarmony為了集成C/C++代碼和提升編譯速度，使用了GN + Ninja的編譯構(gòu)建系統(tǒng)。GN的構(gòu)建語(yǔ)言簡(jiǎn)潔易讀，Ninja的匯編級(jí)編譯規(guī)則直接高效。 為了在OpenHarmony中集成Rust代碼，并最大程度發(fā)揮Rust和OpenHarmony中原有C/C++代碼的交互性，采用GN作為統(tǒng)一構(gòu)建工具，即通過(guò)GN構(gòu)建Rust源碼文件(xxx.rs)，并增加與C/C++互操作、編譯時(shí)lint、測(cè)試、IDL轉(zhuǎn)換、三方庫(kù)集成、IDE等功能。同時(shí)擴(kuò)展gn框架，支持接口自動(dòng)化轉(zhuǎn)換，最大程度簡(jiǎn)化開(kāi)發(fā)。

基本概念

配置規(guī)則

OpenHarmony提供了用于Rust代碼編譯構(gòu)建的各類(lèi)型GN模板，可以用于編譯Rust可執(zhí)行文件，動(dòng)態(tài)庫(kù)和靜態(tài)庫(kù)等。各類(lèi)型模板說(shuō)明如下：

配置指導(dǎo)

配置Rust模塊與C/C++模塊類(lèi)似，參考[模塊配置規(guī)則]。下面是使用不同模板的示例。

開(kāi)發(fā)前請(qǐng)熟悉鴻蒙開(kāi)發(fā)指導(dǎo)文檔：[gitee.com/li-shizhen-skin/harmony-os/blob/master/README.md]

配置Rust靜態(tài)庫(kù)示例

該示例用于測(cè)試Rust可執(zhí)行bin文件和靜態(tài)庫(kù)rlib文件的編譯，以及可執(zhí)行文件對(duì)靜態(tài)庫(kù)的依賴(lài)，使用模板ohos_rust_executable和ohos_rust_static_library。操作步驟如下：

1. 創(chuàng)建build/rust/tests/test_rlib_crate/src/simple_printer.rs，如下所示：

   //! simple_printer
   
   /// struct RustLogMessage
   
   pub struct RustLogMessage {
       /// i32: id
       pub id: i32,
       /// String: msg
       pub msg: String,
   }
   
   /// function rust_log_rlib
   pub fn rust_log_rlib(msg: RustLogMessage) {
       println!("id:{} message:{:?}", msg.id, msg.msg)
   }
   

2. 創(chuàng)建build/rust/tests/test_rlib_crate/src/main.rs，如下所示：

   //! rlib_crate example for Rust.
   
   extern crate simple_printer_rlib;
   
   use simple_printer_rlib::rust_log_rlib;
   use simple_printer_rlib::RustLogMessage;
   
   fn main() {
       let msg: RustLogMessage = RustLogMessage {
           id: 0,
           msg: "string in rlib crate".to_string(),
       };
       rust_log_rlib(msg);
   }
   

3. 配置gn腳本build/rust/tests/test_rlib_crate/BUILD.gn，如下所示：

   import("http://build/ohos.gni")
   
   ohos_rust_executable("test_rlib_crate") {
     sources = [ "src/main.rs" ]
     deps = [ ":simple_printer_rlib" ]
   }
   
   ohos_rust_static_library("simple_printer_rlib") {
     sources = [ "src/simple_printer.rs" ]
     crate_name = "simple_printer_rlib"
     crate_type = "rlib"
     features = [ "std" ]
   }
   

4. 執(zhí)行編譯得到的可執(zhí)行文件，運(yùn)行結(jié)果如下：
   

配置三方庫(kù)示例

rust三方庫(kù)的BUILD.gn文件可通過(guò)cargo2gn工具自動(dòng)生成。參見(jiàn)：[Cargo2gn工具操作指導(dǎo)]

該示例用于測(cè)試包含預(yù)編譯文件build.rs的三方靜態(tài)庫(kù)rlib文件的編譯，使用了模板ohos_rust_executable和ohos_rust_cargo_crate。操作步驟如下：

1. 創(chuàng)建build/rust/tests/test_rlib_cargo_crate/crate/src/lib.rs，如下所示：

   include!(concat!(env!("OUT_DIR"), "/generated/generated.rs"));
   
   pub fn say_hello_from_crate() {
       assert_eq!(run_some_generated_code(), 45);
       #[cfg(is_new_rustc)]
       println!("Is new rustc");
       #[cfg(is_old_rustc)]
       println!("Is old rustc");
       #[cfg(is_ohos)]
       println!("Is ohos");
       #[cfg(is_mac)]
       println!("Is darwin");
       #[cfg(has_feature_a)]
       println!("Has feature_a");
       #[cfg(not(has_feature_a))]
       panic!("Wasn't passed feature_a");
       #[cfg(not(has_feature_b))]
       #[cfg(test_a_and_b)]
       panic!("feature_b wasn't passed");
       #[cfg(has_feature_b)]
       #[cfg(not(test_a_and_b))]
       panic!("feature_b was passed");
   }
   
   #[cfg(test)]
   mod tests {
       /// Test features are passed through from BUILD.gn correctly. This test is the target configuration.
       #[test]
       #[cfg(test_a_and_b)]
       fn test_features_passed_target1() {
           #[cfg(not(has_feature_a))]
           panic!("feature a was not passed");
           #[cfg(not(has_feature_b))]
           panic!("feature b was not passed");
       }
   
       #[test]
       fn test_generated_code_works() {
           assert_eq!(crate::run_some_generated_code(), 45);
       }
   }
   

2. 創(chuàng)建build/rust/tests/test_rlib_cargo_crate/crate/src/main.rs，如下所示：

   pub fn main() {
       test_rlib_crate::say_hello_from_crate();
   }
   

3. 創(chuàng)建build/rust/tests/test_rlib_cargo_crate/crate/build.rs，如下所示：

   use std::env;
   use std::path::Path;
   use std::io::Write;
   use std::process::Command;
   use std::str::{self, FromStr};
   
   fn main() {
       println!("cargo:rustc-cfg=build_script_ran");
       let my_minor = match rustc_minor_version() {
           Some(my_minor) = > my_minor,
           None = > return,
       };
   
       if my_minor >= 34 {
           println!("cargo:rustc-cfg=is_new_rustc");
       } else {
           println!("cargo:rustc-cfg=is_old_rustc");
       }
   
       let target = env::var("TARGET").unwrap();
   
       if target.contains("ohos") {
           println!("cargo:rustc-cfg=is_ohos");
       }
       if target.contains("darwin") {
           println!("cargo:rustc-cfg=is_mac");
       }
   
       let feature_a = env::var_os("CARGO_FEATURE_MY_FEATURE_A").is_some();
       if feature_a {
           println!("cargo:rustc-cfg=has_feature_a");
       }
       let feature_b = env::var_os("CARGO_FEATURE_MY_FEATURE_B").is_some();
       if feature_b {
           println!("cargo:rustc-cfg=has_feature_b");
       }
   
       // Some tests as to whether we're properly emulating various cargo features.
       assert!(Path::new("build.rs").exists());
       assert!(Path::new(&env::var_os("CARGO_MANIFEST_DIR").unwrap()).join("build.rs").exists());
       assert!(Path::new(&env::var_os("OUT_DIR").unwrap()).exists());
   
       // Confirm the following env var is set
       env::var_os("CARGO_CFG_TARGET_ARCH").unwrap();
   
       generate_some_code().unwrap();
   }
   
   fn generate_some_code() - > std::io::Result< () > {
       let test_output_dir = Path::new(&env::var_os("OUT_DIR").unwrap()).join("generated");
       let _ = std::fs::create_dir_all(&test_output_dir);
       // Test that environment variables from .gn files are passed to build scripts
       let preferred_number = env::var("ENV_VAR_FOR_BUILD_SCRIPT").unwrap();
       let mut file = std::fs::File::create(test_output_dir.join("generated.rs"))?;
       write!(file, "fn run_some_generated_code() - > u32 {{ {} }}", preferred_number)?;
       Ok(())
   }
   
   fn rustc_minor_version() - > Option< u32 > {
       let rustc_bin = match env::var_os("RUSTC") {
           Some(rustc_bin) = > rustc_bin,
           None = > return None,
       };
   
       let output = match Command::new(rustc_bin).arg("--version").output() {
           Ok(output) = > output,
           Err(_) = > return None,
       };
   
       let rustc_version = match str::from_utf8(&output.stdout) {
           Ok(rustc_version) = > rustc_version,
           Err(_) = > return None,
       };
   
       let mut pieces = rustc_version.split('.');
       if pieces.next() != Some("rustc 1") {
           return None;
       }
   
       let next_var = match pieces.next() {
           Some(next_var) = > next_var,
           None = > return None,
       };
   
       u32::from_str(next_var).ok()
   }
   

4. 配置gn腳本build/rust/tests/test_rlib_cargo_crate/BUILD.gn，如下所示：

   import("http://build/templates/rust/ohos_cargo_crate.gni")
   
   ohos_cargo_crate("target") {
     crate_name = "test_rlib_crate"
     crate_root = "crate/src/lib.rs"
     sources = [ "crate/src/lib.rs" ]
   
     #To generate the build_script binary
     build_root = "crate/build.rs"
     build_sources = [ "crate/build.rs" ]
     build_script_outputs = [ "generated/generated.rs" ]
   
     features = [
       "my-feature_a",
       "my-feature_b",
       "std",
     ]
     rustflags = [
       "--cfg",
       "test_a_and_b",
     ]
     rustenv = [ "ENV_VAR_FOR_BUILD_SCRIPT=45" ]
   }
   
   # Exists to test the case that a single crate has both a library and a binary
   ohos_cargo_crate("test_rlib_crate_associated_bin") {
     crate_root = "crate/src/main.rs"
     crate_type = "bin"
     sources = [ "crate/src/main.rs" ]
   
     #To generate the build_script binary
     build_root = "crate/build.rs"
     build_sources = [ "crate/build.rs" ]
     features = [
       "my-feature_a",
       "my-feature_b",
       "std",
     ]
     rustenv = [ "ENV_VAR_FOR_BUILD_SCRIPT=45" ]
     deps = [ ":target" ]
   }
   

5. 執(zhí)行編譯得到的可執(zhí)行文件，運(yùn)行結(jié)果如下：
   

其他源碼實(shí)例

在build/rust/tests目錄下有Rust各類(lèi)型模塊的配置實(shí)例可供參考：

參考

特性點(diǎn)實(shí)例

Rust源碼依賴(lài)調(diào)用C/C++庫(kù)

OpenHarmony上C/C++模塊動(dòng)態(tài)庫(kù)默認(rèn)用.z.so后綴，但是Rust的編譯命令通過(guò)-l鏈接時(shí)，默認(rèn)只會(huì)鏈接.so后綴的動(dòng)態(tài)庫(kù)。因此如果要依賴(lài)一個(gè)C/C++動(dòng)態(tài)庫(kù)編譯模塊，需要在該動(dòng)態(tài)庫(kù)的GN構(gòu)建文件中添加output_extension = "so"的聲明，這樣編譯得到的動(dòng)態(tài)庫(kù)將會(huì)以".so"作為后綴，而不是".z.so"。 在Rust源碼中如果直接鏈接動(dòng)態(tài)庫(kù)，后綴也需要使用".so"，這時(shí)使用動(dòng)態(tài)庫(kù)的中間名，不需要添加lib前綴。例如Rust源碼中鏈接libhilog.so:

#[link(name = "hilog")]

externs使用

某個(gè)模塊如果依賴(lài)二進(jìn)制的rlib庫(kù)，可以使用externs屬性：

executable("foo") {
    sources = [ "main.rs" ]
    externs = [{                    # 編譯時(shí)會(huì)轉(zhuǎn)成`--extern bar=path/to/bar.rlib`
        crate_name = "bar"
        path = "path/to/bar.rlib"
    }]
}

Lint規(guī)則

OpenHarmony框架支持rustc lints和clippy lints兩種Lint，每種Lint劃為三個(gè)等級(jí)的標(biāo)準(zhǔn)："openharmony"、"vendor"和"none"，嚴(yán)格程度按照"openharmony" -> "vendor" -> "none"逐級(jí)遞減。 配置Rust模塊時(shí)可以通過(guò)rustc_lints和clippy_lints來(lái)指定使用Lint的等級(jí)。 模塊中沒(méi)有配置rustc_lints或者clippy_lints時(shí)會(huì)根據(jù)模塊所在路徑來(lái)匹配lints等級(jí)。不同路徑下的Rust代碼的語(yǔ)法規(guī)范會(huì)有不同程度地約束，因此用戶(hù)在OpenHarmony配置Rust代碼編譯模塊時(shí)還應(yīng)關(guān)注模塊所在路徑。

rustc lints和clippy lints的各等級(jí)標(biāo)志

代碼路徑與lints等級(jí)的對(duì)應(yīng)關(guān)系

審核編輯 黃宇