外殼覆蓋

Fuchsia 使用外部 Rust Crate，外部 Rust Crate 會放在 //third-party/rust_crates/vendor。這組 Crate 是 執行 Deployment 作業 //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 放入 vendor 目錄，以及 然後更新 Cargo.toml 和 Cargo.lock。

    您可能需要在 [gn.package.<crate>] 中提供額外設定 區段，位於 Cargo.toml 檔案中。適用於使用 build.rs 的 Crate 指令碼後，這項設定會取代指令碼 不支援建構系統這項設定也會用於 cargo-gnaw：這會從 Cargo.toml 檔案產生 GN 規則。 查看貨車的讀物 ，掌握更多詳細資訊。

    在本機修訂變更後，請執行 fx update-rustc-third-party 第二次，確保在未產生任何程式的情況下順利完成 並輸入變更內容您可以執行 git status 來確定情況。

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

      fx set core.x64 && fx build

  5. 請按照下列步驟操作，申請 OSRB 核准：

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

    • 在問題中，按照下列步驟操作：

      • 將 [Owner] (擁有者) 欄位留空。
        • OSRB 團隊會定期開會，調查問題。 我們大約需要一星期的時間做出回覆，請耐心等候。
      • 指定所有要新增的 Crate (無需列出 先前核准的 Crate)。納入您要新增的 Crate 以及執行指令後找到的依附元件 Crate fx update-rustc-third-party。
      • 如果來源存放區中有任何檔案未納入 時，請將您問題中的這些檔案指定至 OSRB適用對象 例如：僅供測試但排除的字型檔案。 因為供應商必須納入 OSRB 問題中
      ，瞭解如何調查及移除這項存取權。

  6. 如果您通過 OSRB 核准，請將變更上傳至 Gerrit 以供審查。 在變更中加入 OSRB 問題 ID 編號。

  7. 新增擁有者 做為程式碼審查人員您必須取得 來自存放區其中一位擁有者的 Code Review Label +2。

  8. 如果您能夠提交已核准的 修訂佇列 (CQ)，提交變更 將變更合併至 third_party/rust_crates。

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

    進一步瞭解每位貢獻者的相關動作 角色，請參閱角色矩陣。

更新外部 Crate

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

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

    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>] 區段。Crate 適用 使用 build.rs 指令碼的設定取代了該指令碼 這是建構系統刻意不支援的功能這個 cargo-gnaw 會使用這些設定產生 GN 規則 Cargo.toml 檔案。 詳情請參閱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 所新增的依附元件清單，以及連結後找到的依附元件 Crate 跑步 fx update-rustc-third-party。
      • 如果來源存放區中有任何檔案未納入 時，請將您問題中的這些檔案指定至 OSRB適用對象 例如：僅供測試但排除的字型檔案。 因為供應商必須納入 OSRB 問題中
      ，瞭解如何調查及移除這項存取權。

  5. 更新 OWNERS 檔案以用於修改的 Crate。詳情請參閱 「OWNERS 檔案」一節，進一步瞭解如何更新 OWNERS 檔案。

  6. 獲得 OSRB 核准後，請將變更項目上傳至 Gerrit。在變更中加入 OSRB 問題 ID 編號。

  7. 如果授權或依附元件沒有異動，您可以上傳變更 ，不需經過 OSRB 核准程序。

新增鏡像

積極參與上游存放區 維護 Fuchsia 存放區的長期分支，非常適合 使用完整的 Git 存放區 (而非 Cargo 的廠商工具) 匯入 Crate。 雖然這種方法很實用，但相較於 因此在處理預設流程時請務必謹慎小心

  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. 在以下位置的 [patch.crates-io] 部分新增一行： 使用 /third_party/rust_crates/Cargo.toml 指向新的 Crate：

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

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

  6. 新增 /third_party/rust_crates/forks/<my_crate>/README.fuchsia 檔案， 符合其他 Crate 的格式README.fuchsia後。詳情請見 花費 /third_party/rust_crates/forks/README.md 的內容 應包含

萬國碼 (Unicode) Crate

如果專案需要匯入新的外部 Crate 來處理 例如 Unicode 和國際化相關功能，建議優先使用 Crate UNIC 專案 (如有)。

豁免的非聯合國 Crate

下列非聯合國 Crate 已列入供應商，且符合豁免資格：

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

標準化的理由

UNIC Crate 與其他 Crate 相比有特別優勢：

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

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

  • UNIC Crate 是根據一組一致的 Unicode 資料檔案產生。

    • 每個獨立 Crate 會使用任意版本， 實體媒介包括儲存空間陣列 傳統硬碟、磁帶和 USB 隨身碟等舉例來說，不同的 Crate 可能會有不同的假設 指出系統是否已指派特定碼點、其屬性 等。

  • UNIC 專案旨在全面涵蓋各種功能，例如 ICU：Rust。如果專案 因此，對於不相關的 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 檔案 已匯入 Crate 的 OWNERS 中。舉例來說 src/lib/foo 等目標取決於 bar Crate，然後是 OWNERS 檔案 bar Crate 的層級會包含 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 的使用者人數大於仰賴的可靠性維護工作 (請參閱「旁觀者效果」)。其他商家則會針對 希望由特定團隊負責 審查程式碼

在這些情況下，請使用以下程式碼將項目新增至 //third_party/owners.toml 找到其他 OWNERS 檔案要參照的路徑，然後重新執行工具。 這會以覆寫值取代反向依附元件中繼資料擁有權 路徑。

更新頻率

Fuchsia 團隊中的 Rust 成員目前負責執行 定期發布 API 檔案詳情請參閱 https://fxbug.dev/42152910 追蹤 OWNERS 檔案的自動更新程序。

在本機覆寫

如果您有在上游提供資料，也可以覆寫第三方 Crate 並想執行樹狀結構內建構或測試方法如下： 100 萬步的訓練

  1. 複製 (或符號連結) 下方的上游存放區 third_party/rust_crates/forks/<my_crate>。
  2. 將覆寫值新增至以下項目的 [patch.crates-io] 部分： third_party/rust_crates/Cargo.toml。
[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-unknown-fuchsia"

留言後會變為：

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

這個問題已在上游追蹤追蹤。