外殼覆蓋

Fuchsia 會使用外部 Rust 箱。外部 Rust 箱會放置在 //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. 針對要新增的 Crate，在 third_party/rust_crates/Cargo.toml 中新增項目。

  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，以及執行 fx update-rustc-third-party 後所識別的依附元件 Crate。
      • 如果來源存放區中含有供應商未納入的任何檔案，請在 OSRB 中指出這些檔案。舉例來說，如果字型檔案僅用於測試，但在 crate 供應時遭到排除，就必須納入 OSRB 問題。

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

  7. 將外部 Rust Crate 目錄的擁有者新增為程式碼審查者。您必須向其中一個存放區擁有者索取 Code Review Label +2。

  8. 如果您可以將已核准的變更提交至 Commit Queue (CQ)，請提交變更，將該變更合併至 third_party/rust_crates。

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

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

更新外部 Crate

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

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

    • 如果是傳遞式依附元件 (不會顯示在 third_party_rust_crates/Cargo.toml 中)，請改為執行 fx host-tool cargo update --manifest-path third_party/rust_crates/Cargo.toml --package $crate_name。指令的輸出內容會列印 $crate_name 已更新至的版本。接著，請檢查 third_party/rust_crates/BUILD.gn 中的 $crate_name 參照，並據此更新版本字串。

  2. 執行下列指令：

      fx update-rustc-third-party

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

  3. 請確認已在 third_party/rust_crates/BUILD.gn 中正確更新更新版 Crate 的版本字串，並視需要手動調整。

    在本機提交變更後，請再次執行 fx update-rustc-third-party，並確保其順利完成，且不會產生任何變更。您可以執行 git status 來確認。

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

      fx set core.x64 && fx build

  5. 檢查變更是否會影響授權或依附項目。如果有這類變更，您必須通過 OSRB 核准程序。如要申請 OSRB 核准，請按照下列步驟操作：

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

    • 在問題中執行下列操作：

      • 將「Owner」欄位留空。
        • OSRB 團隊會定期開會審查問題。請耐心等候，我們會在約一週內回覆。
      • 指定要新增的所有 Crate。納入您要新增的 Crate，以及執行 fx update-rustc-third-party 後所識別的依附元件 Crate。
      • 如果來源存放區中含有供應商未納入的任何檔案，請在 OSRB 中指出這些檔案。舉例來說，如果字型檔案僅用於測試，但在 crate 供應時遭到排除，就必須納入 OSRB 問題。

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

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

  8. 如果沒有執照或依附元件的變更，您可以上傳變更項目進行審查，而無須經過 OSRB 核准程序。

新增鏡像

當您積極為上游存放區做出貢獻，或維護 Fuchsia 存放區的長期分支時，使用完整的 Git 存放區，而非 Cargo 的供應商工具，匯入 Crate 可能會很有幫助。雖然這種做法很實用，但相較於預設流程，其負擔相當大，因此應謹慎使用。

  1. 請前往 fuchsia.googlesource.com 要求新增鏡像。
  2. 將鏡像新增至 Jiri 資訊清單，以便執行 Rust。
  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 箱

下列非 UNIC 箱已供應，因此不受影響：

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

標準化的原因

UNIC 箱與其他箱相比，具有以下獨特優勢：

  • UNIC 箱是在單一存放區中開發，共用通用程式碼和單一版本配置。

    • 獨立開發的 Crate 不會共用通用的發布時程、版本編號方案，也不會遵循任何特定版本的 Unicode 標準。

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

    • 每個獨立的 Crate 都會使用任意版本和資料的子集。舉例來說，不同 Crate 可能會對特定代碼點是否已指派、其屬性為何等問題做出不同的假設。

  • UNIC 專案旨在提供全面的功能涵蓋率，類似於 Rust 的 ICU。如果專案成功，我們對不相關的 Unicode 箱的依附元件應該會隨著時間減少。

OWNERS 檔案

OWNERS 檔案會為所有外部 Rust 箱保留，以指出負責審查及更新的人員。這些檔案是由建構圖中繼資料和明確的覆寫檔案組合產生。

update-rustc-third-party 工具會盡力使用有限的資料更新這些檔案，但可能會出錯。update-3p-owners 工具可直接從建構圖重新產生 OWNERS 檔案，進而提供更優異的服務。

執行工具

這項工具會找出哪些建構目標會依賴特定 Crate，也就是說，它需要從完成的最大「廚房水槽」建構作業中取得中繼資料：

  1. 執行 fx set core.x64 --with //bundles/buildbot/core --with //bundles/kitchen_sink --with-host '//tools/gn_desc:install_gn_desc(//build/toolchain:host_x64)' 個
  2. 執行 fx update-3p-owners --rust-metadata <FUCHSIA_BUILD_DIR>/rustlang/3p-crates-metadata.json。

手動更新 OWNERS

供應商第三方 Crate 的 OWNERS 檔案會從兩個主要來源建構：

  1. 依附於第三方 Rust Crate 的目標，其 OWNERS 檔案會匯入依附 Crate 的 OWNERS。舉例來說，如果 src/lib/foo 這類目標依賴 bar crate，則 bar crate 的 OWNERS 檔案會包含 src/lib/foo/OWNERS。
  2. 依附於其他第三方 Rust Crate 的第三方 Rust Crate，會將其依附元件的 OWNERS 檔案匯入自己的檔案。舉例來說，如果 bar crate 依賴 baz crate，則 bar crate 的 OWNERS 檔案會包含 third_party/rust_crates/vendor/bar-1.0.0/OWNERS。

針對現有 Crate 的版本升級，通常只要將包含陳述式更新為最新版本的 Crate 即可。

新增覆寫值

有些 Crate 的使用者人數超過了可用於維護的使用者人數 (請參閱「旁觀者效應」)。其他人則會實作安全性等特定領域的行為，我們建議由特定團隊負責審查程式碼。

在這種情況下，請將其他 OWNERS 檔案的路徑新增至 //third_party/owners.toml 的項目，以便做為參照，然後重新執行工具。這會將反向依附中繼資料擁有權取代為覆寫的路徑。

更新頻率

Fuchsia 團隊的 Rust 成員目前負責定期執行這項工具。請參閱 https://fxbug.dev/42152910，瞭解如何自動更新 OWNERS 檔案。

在本機覆寫

如果您要貢獻至上游，並想執行樹狀結構內的建構或測試，則覆寫第三方 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 中註解您的 Fuchsia 目標：

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

註解後會變成：

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

這個問題正在上游追蹤中。