源發生器

此頁面提供如何支援生成的來源以及如何在建置系統中使用它的高級視圖。

所有來源產生器都提供類似的建置系統功能。三個建置系統支援的原始碼產生用例是使用bindgen、AIDL 介面和protobuf 介面產生C 綁定。

來自生成來源的板條箱

每個產生原始碼的 Rust 模組都可以用作 crate，就像定義為rust_library一樣。 （這意味著它可以定義為rustlibs 、 rlibs和dylibs屬性中的依賴項。）平台程式碼的最佳使用模式是將產生的來源用作 crate。雖然包括include!產生的來源支援宏，其主要目的是支援駐留在external/中的第三方程式碼。

在某些情況下，平台程式碼可能仍然透過include!()巨集使用產生的原始程式碼，例如當您使用genrule模組以獨特的方式產生原始程式碼時。

使用 include!() 包含生成的來源

每個特定（各自）模組頁面中的範例都涵蓋了使用生成的來源作為板條箱。本節介紹如何透過include!()巨集引用產生的原始碼。請注意，此過程對於所有來源產生器都是相似的。

先決條件

此範例基於以下假設：您已定義rust_bindgen模組 ( libbuzz_bindgen )，並且可以繼續執行使用include!()巨集包含生成來源的步驟。如果還沒有，請前往定義 rust bindgen 模組，建立libbuzz_bindgen ，然後回到這裡。

請注意，其中的建置檔案部分適用於所有來源產生器。

包含生成來源的步驟

使用以下內容建立external/rust/hello_bindgen/Android.bp ：

rust_binary {
   name: "hello_bzip_bindgen_include",
   srcs: [
         // The primary rust source file must come first in this list.
         "src/lib.rs",

         // The module providing the bindgen bindings is
         // included in srcs prepended by ":".
         ":libbuzz_bindgen",
    ],

    // Dependencies need to be redeclared when generated source is used via srcs.
    shared_libs: [
        "libbuzz",
    ],
}

使用以下內容建立external/rust/hello_bindgen/src/bindings.rs ：

#![allow(clippy::all)]
#![allow(non_upper_case_globals)]
#![allow(non_camel_case_types)]
#![allow(non_snake_case)]
#![allow(unused)]
#![allow(missing_docs)]

// Note that "bzip_bindings.rs" here must match the source_stem property from
// the rust_bindgen module.
include!(concat!(env!("OUT_DIR"), "/bzip_bindings.rs"));

使用以下內容建立external/rust/hello_bindgen/src/lib.rs ：

mod bindings;

fn main() {
    let mut x = bindings::foo { x: 2 };
    unsafe { bindings::fizz(1, &mut x as *mut bindings::foo) }
}

為什麼生成來源的板條箱

與 C/C++ 編譯器不同， rustc只接受表示二進位檔案或函式庫的入口點的單一原始檔。它期望源樹的結構能夠自動發現所有必需的來源檔案。這意味著產生的原始程式碼必須放置在原始碼樹中，或透過原始程式碼中的 include 指令提供：

include!("/path/to/hello.rs");

Rust 社群依賴build.rs腳本以及有關 Cargo 建置環境的假設來處理這種差異。建置時， cargo指令會設定一個OUT_DIR環境變量， build.rs腳本將在其中放置生成的原始程式碼。使用以下命令包含原始碼：

include!(concat!(env!("OUT_DIR"), "/hello.rs"));

這給 Soong 帶來了挑戰，因為每個模組的輸出都放置在自己的out/目錄1中。沒有一個OUT_DIR依賴項輸出其產生的來源。

對於平台程式碼，AOSP 更喜歡將產生的原始程式碼打包到可以匯入的 crate 中，原因如下：

  • 防止產生的來源檔案名稱發生衝突。
  • 減少整個樹中簽入的需要維護的樣板程式碼。將產生的原始碼編譯到套件中所需的任何樣板都可以集中維護。
  • 避免產生的程式碼和周圍的板條箱之間的隱式2互動。
  • 透過動態連結常用的生成來源來減少記憶體和磁碟的壓力。

因此，所有 Android 的 Rust 原始碼產生模組類型都會產生可以編譯並用作crate 的程式碼。如果模組的所有產生的來源依賴項都複製到單一每個模組目錄中（類似於 Cargo），Soong 仍然支援第三方 crate，無需修改。在這種情況下，Soong 在編譯模組時將OUT_DIR環境變數設定為該目錄，以便可以找到產生的原始碼。但是，出於已經描述的原因，最佳實踐是僅在絕對必要時才在平台程式碼中使用此機制。

  1. 對於 C/C++ 和類似語言來說，這不會有任何問題，因為產生來源的路徑直接提供給編譯器。 ↩

  2. 既然include!透過文字包含工作，它可能引用封閉名稱空間中的值、修改名稱空間或使用#![foo]等結構。這些隱式互動可能很難維護。當真正需要與板條箱的其餘部分進行互動時，總是更喜歡巨集。 ↩

,

此頁面提供如何支援生成的來源以及如何在建置系統中使用它的高級視圖。

所有來源產生器都提供類似的建置系統功能。三個建置系統支援的原始碼產生用例是使用bindgen、AIDL 介面和protobuf 介面產生C 綁定。

來自生成來源的板條箱

每個產生原始碼的 Rust 模組都可以用作 crate，就像定義為rust_library一樣。 （這意味著它可以定義為rustlibs 、 rlibs和dylibs屬性中的依賴項。）平台程式碼的最佳使用模式是將產生的來源用作 crate。雖然包括include!產生的來源支援宏，其主要目的是支援駐留在external/中的第三方程式碼。

在某些情況下，平台程式碼可能仍然透過include!()巨集使用產生的原始程式碼，例如當您使用genrule模組以獨特的方式產生原始程式碼時。

使用 include!() 包含生成的來源

每個特定（各自）模組頁面中的範例都涵蓋了使用生成的來源作為板條箱。本節介紹如何透過include!()巨集引用產生的原始碼。請注意，此過程對於所有來源產生器都是相似的。

先決條件

此範例基於以下假設：您已定義rust_bindgen模組 ( libbuzz_bindgen )，並且可以繼續執行使用include!()巨集包含生成來源的步驟。如果還沒有，請前往定義 rust bindgen 模組，建立libbuzz_bindgen ，然後回到這裡。

請注意，其中的建置檔案部分適用於所有來源產生器。

包含生成來源的步驟

使用以下內容建立external/rust/hello_bindgen/Android.bp ：

rust_binary {
   name: "hello_bzip_bindgen_include",
   srcs: [
         // The primary rust source file must come first in this list.
         "src/lib.rs",

         // The module providing the bindgen bindings is
         // included in srcs prepended by ":".
         ":libbuzz_bindgen",
    ],

    // Dependencies need to be redeclared when generated source is used via srcs.
    shared_libs: [
        "libbuzz",
    ],
}

使用以下內容建立external/rust/hello_bindgen/src/bindings.rs ：

#![allow(clippy::all)]
#![allow(non_upper_case_globals)]
#![allow(non_camel_case_types)]
#![allow(non_snake_case)]
#![allow(unused)]
#![allow(missing_docs)]

// Note that "bzip_bindings.rs" here must match the source_stem property from
// the rust_bindgen module.
include!(concat!(env!("OUT_DIR"), "/bzip_bindings.rs"));

使用以下內容建立external/rust/hello_bindgen/src/lib.rs ：

mod bindings;

fn main() {
    let mut x = bindings::foo { x: 2 };
    unsafe { bindings::fizz(1, &mut x as *mut bindings::foo) }
}

為什麼生成來源的板條箱

與 C/C++ 編譯器不同， rustc只接受表示二進位檔案或函式庫的入口點的單一原始檔。它期望源樹的結構能夠自動發現所有必需的來源檔案。這意味著產生的原始程式碼必須放置在原始碼樹中，或透過原始程式碼中的 include 指令提供：

include!("/path/to/hello.rs");

Rust 社群依賴build.rs腳本以及有關 Cargo 建置環境的假設來處理這種差異。建置時， cargo指令會設定一個OUT_DIR環境變量， build.rs腳本將在其中放置生成的原始程式碼。使用以下命令包含原始碼：

include!(concat!(env!("OUT_DIR"), "/hello.rs"));

這給 Soong 帶來了挑戰，因為每個模組的輸出都放置在自己的out/目錄1中。沒有一個OUT_DIR依賴項輸出其產生的來源。

對於平台程式碼，AOSP 更喜歡將產生的原始程式碼打包到可以匯入的 crate 中，原因如下：

  • 防止產生的來源檔案名稱發生衝突。
  • 減少整個樹中簽入的需要維護的樣板程式碼。將產生的原始碼編譯到套件中所需的任何樣板都可以集中維護。
  • 避免產生的程式碼和周圍的板條箱之間的隱式2互動。
  • 透過動態連結常用的生成來源來減少記憶體和磁碟的壓力。

因此，所有 Android 的 Rust 原始碼產生模組類型都會產生可以編譯並用作crate 的程式碼。如果模組的所有產生的來源依賴項都複製到單一每個模組目錄中（類似於 Cargo），Soong 仍然支援第三方 crate，無需修改。在這種情況下，Soong 在編譯模組時將OUT_DIR環境變數設定為該目錄，以便可以找到產生的原始碼。但是，出於已經描述的原因，最佳實踐是僅在絕對必要時才在平台程式碼中使用此機制。

  1. 對於 C/C++ 和類似語言來說，這不會有任何問題，因為產生的原始程式碼的路徑是直接提供給編譯器的。 ↩

  2. 既然include!透過文字包含工作，它可能引用封閉名稱空間中的值、修改名稱空間或使用#![foo]等結構。這些隱式互動可能很難維護。當真正需要與板條箱的其餘部分進行互動時，總是更喜歡巨集。 ↩

,

此頁面提供如何支援生成的來源以及如何在建置系統中使用它的高級視圖。

所有來源產生器都提供類似的建置系統功能。三個建置系統支援的原始碼產生用例是使用bindgen、AIDL 介面和protobuf 介面產生C 綁定。

來自生成來源的板條箱

每個產生原始碼的 Rust 模組都可以用作 crate，就像定義為rust_library一樣。 （這意味著它可以定義為rustlibs 、 rlibs和dylibs屬性中的依賴項。）平台程式碼的最佳使用模式是將產生的來源用作 crate。雖然包括include!產生的來源支援宏，其主要目的是支援駐留在external/中的第三方程式碼。

在某些情況下，平台程式碼可能仍然透過include!()巨集使用產生的原始程式碼，例如當您使用genrule模組以獨特的方式產生原始程式碼時。

使用 include!() 包含生成的來源

每個特定（各自）模組頁面中的範例都涵蓋了使用生成的來源作為板條箱。本節介紹如何透過include!()巨集引用產生的原始碼。請注意，此過程對於所有來源產生器都是相似的。

先決條件

此範例基於以下假設：您已定義rust_bindgen模組 ( libbuzz_bindgen )，並且可以繼續執行使用include!()巨集包含生成來源的步驟。如果還沒有，請前往定義 rust bindgen 模組，建立libbuzz_bindgen ，然後回到這裡。

請注意，其中的建置檔案部分適用於所有來源產生器。

包含生成來源的步驟

使用以下內容建立external/rust/hello_bindgen/Android.bp ：

rust_binary {
   name: "hello_bzip_bindgen_include",
   srcs: [
         // The primary rust source file must come first in this list.
         "src/lib.rs",

         // The module providing the bindgen bindings is
         // included in srcs prepended by ":".
         ":libbuzz_bindgen",
    ],

    // Dependencies need to be redeclared when generated source is used via srcs.
    shared_libs: [
        "libbuzz",
    ],
}

使用以下內容建立external/rust/hello_bindgen/src/bindings.rs ：

#![allow(clippy::all)]
#![allow(non_upper_case_globals)]
#![allow(non_camel_case_types)]
#![allow(non_snake_case)]
#![allow(unused)]
#![allow(missing_docs)]

// Note that "bzip_bindings.rs" here must match the source_stem property from
// the rust_bindgen module.
include!(concat!(env!("OUT_DIR"), "/bzip_bindings.rs"));

使用以下內容建立external/rust/hello_bindgen/src/lib.rs ：

mod bindings;

fn main() {
    let mut x = bindings::foo { x: 2 };
    unsafe { bindings::fizz(1, &mut x as *mut bindings::foo) }
}

為什麼生成來源的板條箱

與 C/C++ 編譯器不同， rustc只接受表示二進位檔案或函式庫的入口點的單一原始檔。它期望源樹的結構能夠自動發現所有必需的來源檔案。這意味著產生的原始程式碼必須放置在原始碼樹中，或透過原始程式碼中的 include 指令提供：

include!("/path/to/hello.rs");

Rust 社群依賴build.rs腳本以及有關 Cargo 建置環境的假設來處理這種差異。建置時， cargo指令會設定一個OUT_DIR環境變量， build.rs腳本將在其中放置生成的原始程式碼。使用以下命令包含原始碼：

include!(concat!(env!("OUT_DIR"), "/hello.rs"));

這給 Soong 帶來了挑戰，因為每個模組的輸出都放置在自己的out/目錄1中。沒有一個OUT_DIR依賴項輸出其產生的來源。

對於平台程式碼，AOSP 更喜歡將產生的原始程式碼打包到可以匯入的 crate 中，原因如下：

  • 防止產生的來源檔案名稱發生衝突。
  • 減少整個樹中簽入的需要維護的樣板程式碼。將產生的原始碼編譯到套件中所需的任何樣板都可以集中維護。
  • 避免產生的程式碼和周圍的板條箱之間的隱式2互動。
  • 透過動態連結常用的生成來源來減少記憶體和磁碟的壓力。

因此，所有 Android 的 Rust 原始碼產生模組類型都會產生可以編譯並用作crate 的程式碼。如果模組的所有產生的來源依賴項都複製到單一每個模組目錄中（類似於 Cargo），Soong 仍然支援第三方 crate，無需修改。在這種情況下，Soong 在編譯模組時將OUT_DIR環境變數設定為該目錄，以便可以找到產生的原始碼。但是，出於已經描述的原因，最佳實踐是僅在絕對必要時才在平台程式碼中使用此機制。

  1. 對於 C/C++ 和類似語言來說，這不會有任何問題，因為產生來源的路徑直接提供給編譯器。 ↩

  2. 既然include!透過文字包含工作，它可能引用封閉名稱空間中的值、修改名稱空間或使用#![foo]等結構。這些隱式互動可能很難維護。當真正需要與板條箱的其餘部分進行互動時，總是更喜歡巨集。 ↩