外殼覆蓋

Fuchsia 使用外部 Rust Crate。外部 Rust Crate 會放在 //third-party/rust_crates/vendor 中。這組 Crate 以 //third_party/rust_crates/Cargo.toml 中列出的依附元件為基礎。

一般來說，新增或更新外部 Crate 時，須留意以下幾點：

  • 計算外部 Crate 的依附元件。

  • 申請開放原始碼審查委員會 (OSRB) 核准。

  • 正在等待 OSRB 核准。

  • 上傳變更以進行程式碼審查。

新增外部 Crate

如果找不到要使用的現有 Crate，您可能需要將外部 Crate 新增至 Fuchsia。

如要新增外部 Crate，請按照下列步驟操作：

  1. 變更為 Fuchsia 存放區的基本目錄。

    舉例來說，如果您的 fuchsia 目錄為 ~/fuchsia，請執行下列指令：

      cd ~/fuchsia

  2. 在 third_party/rust_crates/Cargo.toml 中針對您要新增的 Crate 新增項目。

  3. 執行下列指令來下載所需的 Crate，然後計算該 Crate 的依附元件：

      fx update-rustc-third-party

    fx update-rustc-third-party 會下載 rust_crates/Cargo.toml 中列出的所有 Crate 及其依附元件，然後將下載的 Crate 放入 vendor 目錄，然後更新 Cargo.toml 和 Cargo.lock。

    您可能需要在 Cargo.toml 檔案的 [gn.package.<crate>] 區段中提供額外設定。針對使用 build.rs 指令碼的 Crate，這項設定會取代建構系統刻意不支援的指令碼。cargo-gnaw 會使用這項設定，以便從 Cargo.toml 檔案產生 GN 規則。詳情請參閱 cargo-gnaw 的 README。

    在本機修訂變更後，再次執行 fx update-rustc-third-party，並確保該作業順利完成，而不會產生任何變更。您可以執行 git status 來確定。

  4. 執行下列指令來執行建構測試：

      fx set core.x64 && fx build

  5. 請按照下列步驟提出核准 OSRB 要求：

    • 使用開放原始碼審查委員會 (OSRB) 範本建立問題。

    • 發生問題時，請按照下列步驟操作：

      • 將「Owner」(擁有者) 欄位留空。
        • OSRB 團隊會定期進行會議，檢視問題。大約需要一週的時間來回覆你。
      • 指定您要 新增 的所有 crate (無需列出先前核准的 crate)。請加入您要新增的 Crate，以及執行 fx update-rustc-third-party 之後識別的依附元件 Crate。
      • 如果原始碼存放區中有任何檔案不在廠商提交時納入，請將問題中的這些檔案指定給 OSRB。舉例來說，如果字型檔案僅用於測試，但廠商提供 Crate 時就會排除在 OSRB 問題中。

  6. 如果收到 OSRB 核准，請將變更內容上傳到 Gerrit 進行審查。 請在變更內容中加入 OSRB 問題 ID 編號。

  7. 將外部 rust crate 目錄的 OWNER 新增為程式碼審查者。您必須從存放區擁有者處取得 Code Review Label +2。

  8. 如果您可以向修訂佇列 (CQ) 提交已核准的變更，請提交變更，將這項變更合併至 third_party/rust_crates。

    如果您無法提交已核准的變更，請回覆 Gerrit 變更，並要求其中一位存放區擁有者提交變更。

    如要進一步瞭解每個協作者角色的相關動作，請參閱角色矩陣。

更新外部 Crate

如要更新外部 Crate，請按照下列步驟操作：

  1. 增加 third_party/rust_crates/Cargo.toml 中的 Crate 修補程式編號

    1. 針對遞移性依附元件 (不會顯示在根 Cargo.toml 中)，您可以改用 cargo +fuchsia update --manifest-path third_party/rust_crates/Cargo.toml --package $crate_name 等指令。

  2. 執行下列指令：

      fx update-rustc-third-party

    您可能需要在 Cargo.toml 檔案的 [gn.package.<crate>] 區段中更新或提供其他設定。針對使用 build.rs 指令碼的 Crate，這項設定會取代建構系統刻意不支援的指令碼。cargo-gnaw 會使用這項設定，從 Cargo.toml 檔案產生 GN 規則。詳情請參閱 cargo-gnaw 的 README。

    在本機修訂變更後，再次執行 fx update-rustc-third-party，並確保該作業順利完成，而不會產生任何變更。您可以執行 git status 來確定。

  3. 執行下列指令來執行建構測試：

      fx set core.x64 && fx build

  4. 檢查授權或依附元件的任何變更。如有這幾類變更，就必須完成 OSRB 核准程序。請按照下列步驟提出核准 OSRB 要求：

    • 使用開放原始碼審查委員會 (OSRB) 範本建立問題。

    • 發生問題時，請按照下列步驟操作：

      • 將「Owner」(擁有者) 欄位留空。
        • OSRB 團隊會定期進行會議，檢視問題。大約需要一週的時間來回覆你。
      • 指定您要新增的所有 Crate。包括您要新增的 Crate，以及執行 fx update-rustc-third-party 之後識別的依附元件 Crate。
      • 如果原始碼存放區中有任何檔案不在廠商提交時納入，請將問題中的這些檔案指定給 OSRB。舉例來說，如果字型檔案僅用於測試，但廠商提供 Crate 時就會排除在 OSRB 問題中。

  5. 針對已修改的 Crate 更新 OWNERS 檔案。如要進一步瞭解如何更新 OWNERS 檔案，請參閱「OWNERS 檔案」一節。

  6. 如果您收到 OSRB 核准，請將變更內容上傳至 Gerrit。請在變更內容中加入 OSRB 問題 ID 編號。

  7. 如果授權或依附元件沒有任何變更，您可以將變更項目上傳以供審查，不必經過 OSRB 核准程序。

新增鏡像

當您積極向上游存放區提供內容，或是維護 Fuchsia 存放區的長期分支時，使用完整的 Git 存放區匯入 Crate，就不適合使用 Cargo 的廠商工具。雖然這個方法很有用，但與預設流程相比，負擔較大，使用時請謹慎小心。

  1. 前往 fuchsia.googlesource.com 要求新增鏡像。
  2. 將鏡像新增至 Rust 執行階段的 Jiri 資訊清單。
  3. 將 Crate 的修補程式區段新增至工作區。
  4. 執行更新指令碼。

匯入 Crate 中的一部分檔案

在某些情況下，您可能只想匯入 Crate 中的部分檔案。舉例來說，外部存放區中的選用授權可能與 Fuchsia 的授權規定不相容。請參考這個發生情境的 OSRB 審查範例。

如要這麼做，您需要將 Crate 的檔案新增至 /third_party/rust_crates/forks。

  1. 按照新增外部 Crate 的操作說明進行。
  2. 執行 fx update-rustc-third-party 後，將下載的 Crate 副本從 /third_party/rust_crates/vendor/<my_crate> 移至 /third_party/rust_crates/forks/<my_crate>。
  3. 視需要變更匯入檔案的內容。

  4. 在 /third_party/rust_crates/Cargo.toml 的 [patch.crates-io] 區段新增一行，指向新的 Crate：

    [patch.crates-io]
...
my_crate = { path = "forks/<my_crate>" }
...

  5. 重新執行 fx update-rustc-third-party 和 fx build。

  6. 新增符合其他 Crate README.fuchsia 格式的 /third_party/rust_crates/forks/<my_crate>/README.fuchsia 檔案。請參閱 /third_party/rust_crates/forks/README.md，瞭解其中應包含的內容。

萬國碼 (Unicode) Crate

如果專案需要匯入新的外部 Crate 以處理 Unicode 和國際化相關的功能，請優先選擇來自 UNIC 專案的 Crate (如果可用)。

豁免的非 UNIC Crate

下列非 UNIC Crate 已獲廠商提供且符合豁免資格：

  • unicode-bidi
  • unicode-normalization
  • unicode-segmentation
  • unicode-width
  • unicode-xid

標準化的理由

相較於其他 Crate，UNIC Crate 具備獨特優勢：

  • UNIC Crate 在單一存放區中開發，具有共用的通用程式碼和單一版本架構。

    • 獨立開發的 Crate 不會共用通用的發布時間表、版本管理配置，或未遵循任何特定版本的萬國碼 (Unicode) 標準。

  • 由一組一致的 Unicode 資料檔案產生的 UNIC Crate。

    • 每個獨立 Crate 都會使用任意版本和部分的資料。例如，不同的 Crate 可能對於是否獲派特定碼點、其屬性等方面有不同的假設。

  • UNIC 專案旨在提供完整的功能涵蓋範圍，就像 Rust 的 ICU 一樣。如果專案成功，我們應隨著時間減少對不相關 Unicode Crate 的依附元件。

OWNERS 檔案

所有外部 Rust Crate 都會維護 OWNERS 檔案，以表明誰負責審查與更新。這些檔案是由建構圖表中繼資料與明確覆寫檔案的組合所產生。

update-rustc-third-party 工具會盡可能使用有限的資料來更新這些檔案，但可能會出錯。update-3p-owners 工具可以直接從建構圖表重新產生 OWNERS 檔案，達到更好的效果。

執行工具

此工具會探索哪些建構目標會依附於特定 Crate，這表示在完成最大「廚房接收器」建構作業後需要中繼資料：

  1. 執行 fx set core.x64 --with //bundles/buildbot/core --with //bundles/kitchen_sink 個
  2. 執行 fx update-3p-owners --rust-metadata <FUCHSIA_BUILD_DIR>/rustlang/3p-crates-metadata.json。

正在手動更新 OWNERS

廠商第三方 Crate 的 OWNERS 檔案是以兩個主要來源建構：

  1. 對於依附於第三方 Rust crate 的目標，系統會將其 OWNERS 檔案匯入 OWNERS，以便提供其依附的 Crate。例如，假設 src/lib/foo 等目標依附於 bar Crate，則 bar Crate 的 OWNERS 檔案會包含 src/lib/foo/OWNERS。
  2. 依附於其他第三方 Rust Crate 的第三方 Rust Crate，會將其依附元件的 OWNERS 檔案匯入自己的 Crate。舉例來說，如果 bar Crate 依附於 baz Crate，則 bar Crate 的 OWNERS 檔案會包含 third_party/rust_crates/vendor/bar-1.0.0/OWNERS。

若是現有 Crate 的版本異動，通常足夠將 include 陳述式更新為最新版本的已更新 Crate。

新增覆寫值

部分 Crate 擁有的使用者人數，超出可維護的依賴程度 (請參閱旁觀效果一節)。有些則實作特定領域 (例如安全性) 的特定行為，並希望由特定團隊負責審查程式碼。

在這種情況下，請在 //third_party/owners.toml 中新增項目，並將路徑加入其他要參照的 OWNERS 檔案，然後重新執行工具。這會將反依附元件中繼資料的擁有權替換為覆寫的路徑。

更新頻率

目前，Fussia 團隊的 Rust 成員負責定期執行該工具。如要追蹤自動更新 OWNERS 檔案的程序，請參閱 https://fxbug.dev/42152910。

在本機覆寫值

如果您提供了上游，並想要執行樹狀結構內結構建構或測試，則覆寫第三方 Crate，可能會很有幫助。您可以按照下列步驟完成這項作業。

  1. 複製 third_party/rust_crates/forks/<my_crate> 下的上游存放區 (或符號連結)。
  2. 將覆寫值新增至 third_party/rust_crates/Cargo.toml 中的 [patch.crates-io] 區段。
[patch.crates-io]
my_crate = { path = "forks/<my_crate>" }
  1. 您必須確保 Crate 的 Cargo.toml 底下的版本符合 third_party/rust_crates/Cargo.toml 中該 Crate 的所有參照。
  2. 執行 fx update-rustc-third-party。

疑難排解

設定無效

執行 fx update-rustc-third-party 後，如果您遇到下列錯誤：

Generating GN file from /$HOME/fuchsia/third_party/rust_crates/Cargo.toml
Error: GNaw config exists for crates that were not found in the Cargo
build graph:

library crate, package handlebars version 2.0.0-beta.2
library crate, package core-foundation-sys version 0.7.0
library crate, package pulldown-cmark version 0.6.0
library crate, package nix version 0.18.0

您可以修正在 .cargo/config 中向會員顯示目標的這項問題：

[build]
...
target = "x86_64-fuchsia"

留言後，就會變成：

[build]
...
# target = "x86_64-fuchsia"

我們正在追蹤這個問題上游程式庫。