HTTP 存放區規則

回報問題 查看來源

您可以從 @bazel_tools//tools/build_defs/repo:http.bzl 載入下列函式。

透過 HTTP 下載檔案與封存的規則。

設定

如要使用這些規則，請在 WORKSPACE 檔案中載入這些規則，如下所示：

load(
    "@bazel_tools//tools/build_defs/repo:http.bzl",
    "http_archive",
    "http_file",
    "http_jar",
)

這些規則是原生 http 規則的改良版本，最終會取代原生規則。

http_archive

http_archive(name, add_prefix, auth_patterns, build_file, build_file_content, canonical_id,
             integrity, netrc, patch_args, patch_cmds, patch_cmds_win, patch_tool, patches,
             remote_patch_strip, remote_patches, repo_mapping, sha256, strip_prefix, type, url, urls,
             workspace_file, workspace_file_content)

以壓縮封存檔的形式下載 Bazel 存放區，將其解壓縮，並讓其目標可供繫結。

支援的副檔名包括："zip"、"jar"、"war"、"aar"、"tar"、"tar.gz"、"tgz"、"tar.xz"、"txz"、"tar.zst"、"tzst"、tar.bz2、"ar" 或 "deb"。

範例：假設目前的存放區包含即時通訊程式的原始碼，原始碼位於 ~/chat-app 目錄。它必須依附於 http://example.com/openssl.zip 提供的 SSL 程式庫。這個 .zip 檔案包含下列目錄結構：

  WORKSPACE
  src/
    openssl.cc
    openssl.h

使用者在本機存放區中建立 openssl.BUILD 檔案，其中包含下列目標定義：

  cc_library(
      name = "openssl-lib",
      srcs = ["src/openssl.cc"],
      hdrs = ["src/openssl.h"],
  )

如果 ~/chat-app 存放區中的目標在 ~/chat-app/WORKSPACE 中新增下列幾行，則該目標可以依附這個目標：

  load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")

  http_archive(
      name = "my_ssl",
      url = "http://example.com/openssl.zip",
      sha256 = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
      build_file = "@//:openssl.BUILD",
  )

接著目標會將 @my_ssl//:openssl-lib 指定為依附元件。

屬性

name 名稱；必填

這個存放區的專屬名稱。
add_prefix 字串；選用

存放區目錄的相關目的地目錄。 將「strip_prefix」 (如有) 套用至封存中的檔案路徑後，系統會將封存解壓縮到這個目錄。例如，如果 `add_prefix = "bar"` 和 `strip_prefix = "foo-1.2.3"`，系統會將 `foo-1.2.3/src/foo.h` 檔案解壓縮至「bar/src/foo.h」。
auth_patterns 字典：字串 -> 字串；選用

選用的字典，將主機名稱對應至自訂授權模式。 如果此字典中有網址的主機名稱，系統會在產生 http 要求的授權標頭時，使用該值做為模式。這麼一來，您就能使用於許多常見雲端儲存空間供應商提供的自訂授權配置。 這個模式目前支援 2 個符記：<login> 和 <password>。這兩種符記會替換為相同主機名稱 netrc 檔案中的對等值。格式化後，結果會設為 HTTP 要求的 Authorization 欄位值。使用不記名權杖以 HTTP 下載至已啟用 OAuth2 的 API 屬性範例和 Netrc 範例： 

auth_patterns = {
    "storage.cloudprovider.com": "Bearer <password>"
}
netrc： 
machine storage.cloudprovider.com
        password RANDOM-TOKEN
最終的 HTTP 要求會有以下標頭： 
Authorization: Bearer RANDOM-TOKEN

build_file 標籤 (選用)

要做為這個存放區 BUILD 檔案的檔案。這個屬性是絕對標籤 (主要存放區使用「@//」)。這個檔案不必命名為 BUILD，但可以是 (BUILD.new-repo-name 這樣的名稱，有助於區分檔案與存放區的實際 BUILD 檔案)。只能指定 build_file 或 build_file_content，但不能兩者都指定。

build_file_content 字串；選用

這個存放區的 BUILD 檔案內容。只能指定 build_file 或 build_file_content，但不能兩者都指定。

canonical_id 字串；選用

下載檔案的標準 ID。 如有指定且非空白，Bazel 不會將檔案從快取中移除，除非該檔案是透過具有相同標準 ID 的要求加入快取。 如果未指定或空白，Bazel 預設會使用檔案的網址做為標準 ID。這有助於在不一併更新雜湊的情況下找出更新網址的常見錯誤，導致建構作業在本機成功，但在快取中沒有檔案的情況下會失敗。您可以使用 --repo_env=BAZEL_HTTP_RULES_URLS_AS_DEFAULT_CANONICAL_ID=0 停用這項行為。
integrity 字串；選用

下載檔案的子資源完整性格式預期總和檢查碼。 這個 ID 必須與下載檔案的總和檢查碼相符。__由於遠端檔案可能會變更，因此省略總和檢查碼會帶來安全性風險。最好省略這個欄位會讓建構作業變得非密封。你可以選擇是否要在出貨前設定這項屬性或「sha256」，以便簡化開發作業。
netrc 字串；選用

用於驗證的 .netrc 檔案位置

patch_args 字串清單；選用

提供給修補工具的引數。預設為 -p0，但 Git 產生的修補程式通常需要 -p1。如果指定多個 -p 引數，最後一個引數將會生效。如果指定 -p 以外的引數，Bazel 將改回使用修補程式指令列工具，而不是使用 Bazel 原生修補程式實作。改回使用修補程式指令列工具和 patch_tool 屬性時，系統會使用「patch」。這只會影響「patches」屬性中的修補檔案。
patch_cmds 字串清單；選用

套用修補程式後，要套用到 Linux/Macos 的 Bash 指令序列。

patch_cmds_win 字串清單；選用

套用修補程式後，要在 Windows 上套用的 Powershell 指令序列。如未設定這項屬性，patch_cmds 會在 Windows 上執行，因此需要 Bash 二進位檔。

patch_tool 字串；選用

要使用的修補程式(1) 公用程式。如有指定，Bazel 會使用指定的修補程式工具，而非 Bazel 原生的修補程式實作。

patches 標籤清單 (選用)

擷取封存檔案後，要套用為修補程式的檔案清單。根據預設，它會使用不支援模糊比對和二進位檔修補程式的 Bazel 原生修補程式實作項目，但如果已指定「patch_tool」屬性，或是在「patch_args」屬性中含有「-p」以外的引數，Bazel 就會改用修補程式指令列工具。

remote_patch_strip 整數；選用

遠端修補程式中，要移除檔案名稱開頭的斜線數量。

remote_patches 字典：字串 -> 字串；選用

修補檔案網址與其完整性值的對應，會在擷取封存檔後套用，然後再從 `patches` 屬性套用修補檔案之前套用。此工具使用 Bazel 原生修補程式實作項目，您可以使用「remote_patch_strip」來指定修補程式去除編號

repo_mapping 字典：字串 -> 字串；必要

從本機存放區名稱到全域存放區名稱的字典。如此一來，即可控管這個存放區的依附元件的工作區依附元件解決方案。

舉例來說，項目 `"@foo": "@bar"` 會宣告，每當這個存放區在任何情況下都依賴 `@foo` (例如 `@foo//some:target` 上的依附元件)，實際上應在全域宣告的 `@bar` (`@bar//some:target`) 中解析該依附元件。

sha256 字串；選用

下載檔案的預期 SHA-256。 這個引數必須與下載檔案的 SHA-256 相符。__由於遠端檔案可能會變更，因此省略 SHA-256 會帶來安全性風險。_最好省略這個欄位後，建構作業就會變得非密封。你可以選擇是否要在提交前設定這項屬性或「完整性」，藉此簡化開發作業。
strip_prefix 字串；選用

要從已擷取檔案中移除的目錄前置字串。許多封存都包含頂層目錄，其中包含所有封存的實用檔案。這個欄位可用於從所有擷取的檔案中移除該前置字串，而不必在「build_file」中反覆指定這個前置字串。舉例來說，假設您使用的「foo-lib-latest.zip」，其中包含「foo-lib-1.2.3/」目錄，其中有「WORKSPACE」檔案，且是「src/」、「lib/」和「test/」目錄，其中包含您要建構的實際程式碼。指定「strip_prefix = "foo-lib-1.2.3"」以使用「foo-lib-1.2.3」目錄做為頂層目錄。請注意，若此目錄外有檔案，這些檔案將遭到捨棄且無法存取 (例如頂層授權檔案)。這包括開頭為前置字串，但不在目錄中的檔案/目錄 (例如「foo-lib-1.2.3.release-notes」。如果指定的前置字串與封存中的目錄不符，Bazel 會傳回錯誤。
type 字串；選用

下載檔案的封存類型。 根據預設，封存類型取決於網址的副檔名。如果檔案沒有副檔名，您可以明確指定下列其中一項："zip"、`"jar"、`"war"、`"aar"、`"tar"`、`"tar.gz"、`"tgz"`、 `"tar.xz"`、"txz"、`tgz"、 `"tar.xz"`、"txz"、`"tar.zst"、`tar"z"。

url 字串；選用

可讓 Bazel 存取的檔案網址。 格式必須為檔案、http 或 https 網址。我們會遵循路線指示。 不支援驗證機制。 運用網址參數參數指定要擷取的替代網址，您就能享有更多彈性。
urls 字串清單；選用

可讓 Bazel 存取的檔案網址清單。 每個項目都必須是檔案、http 或 https 網址。我們會遵循路線指示。 不支援驗證機制。 系統會依序嘗試網址，直到成功網址為止，因此您應先列出本機的鏡像。 如果所有下載作業都失敗，規則就會失敗。

workspace_file 標籤 (選用)

要做為這個存放區「WORKSPACE」檔案使用的檔案。只能指定「workspace_file」或「workspace_file_content」的值，但兩者只能擇一。

workspace_file_content 字串；選用

這個存放區的 WORKSPACE 檔案內容。只能指定「workspace_file」或「workspace_file_content」的值，但兩者只能擇一。

http_file

http_file(name, auth_patterns, canonical_id, downloaded_file_path, executable, integrity, netrc,
          repo_mapping, sha256, url, urls)

從網址下載檔案，以做為檔案群組使用。

範例：假設您需要為自訂規則提供 Debian 套件。您可以前往 http://example.com/package.deb 取得這個套件。接著，您可以新增至 WORKSPACE 檔案：

  load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_file")

  http_file(
      name = "my_deb",
      url = "http://example.com/package.deb",
      sha256 = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
  )

目標會將 @my_deb//file 指定為依附此檔案的依附元件。

屬性

name 名稱；必填

這個存放區的專屬名稱。
auth_patterns 字典：字串 -> 字串；選用

選用的字典，將主機名稱對應至自訂授權模式。 如果此字典中有網址的主機名稱，系統會在產生 http 要求的授權標頭時，使用該值做為模式。這麼一來，您就能使用於許多常見雲端儲存空間供應商提供的自訂授權配置。 這個模式目前支援 2 個符記：<login> 和 <password>。這兩種符記會替換為相同主機名稱 netrc 檔案中的對等值。格式化後，結果會設為 HTTP 要求的 Authorization 欄位值。使用不記名權杖以 HTTP 下載至已啟用 OAuth2 的 API 屬性範例和 Netrc 範例： 

auth_patterns = {
    "storage.cloudprovider.com": "Bearer <password>"
}
netrc： 
machine storage.cloudprovider.com
        password RANDOM-TOKEN
最終的 HTTP 要求會有以下標頭： 
Authorization: Bearer RANDOM-TOKEN

canonical_id 字串；選用

下載檔案的標準 ID。 如有指定且非空白，Bazel 不會將檔案從快取中移除，除非該檔案是透過具有相同標準 ID 的要求加入快取。 如果未指定或空白，Bazel 預設會使用檔案的網址做為標準 ID。這有助於在不一併更新雜湊的情況下找出更新網址的常見錯誤，導致建構作業在本機成功，但在快取中沒有檔案的情況下會失敗。您可以使用 --repo_env=BAZEL_HTTP_RULES_URLS_AS_DEFAULT_CANONICAL_ID=0 停用這項行為。
downloaded_file_path 字串；選用

指派給下載檔案的路徑

executable 布林值 (選用)

如果下載的檔案應設為可執行狀態。
integrity 字串；選用

下載檔案的子資源完整性格式預期總和檢查碼。 這個 ID 必須與下載檔案的總和檢查碼相符。__由於遠端檔案可能會變更，因此省略總和檢查碼會帶來安全性風險。最好省略這個欄位會讓建構作業變得非密封。你可以選擇是否要在出貨前設定這項屬性或「sha256」，以便簡化開發作業。
netrc 字串；選用

用於驗證的 .netrc 檔案位置

repo_mapping 字典：字串 -> 字串；必要

從本機存放區名稱到全域存放區名稱的字典。如此一來，即可控管這個存放區的依附元件的工作區依附元件解決方案。

舉例來說，項目 `"@foo": "@bar"` 會宣告，每當這個存放區在任何情況下都依賴 `@foo` (例如 `@foo//some:target` 上的依附元件)，實際上應在全域宣告的 `@bar` (`@bar//some:target`) 中解析該依附元件。

sha256 字串；選用

下載檔案的預期 SHA-256。 這個引數必須與下載檔案的 SHA-256 相符。__由於遠端檔案可能會變更，因此省略 SHA-256 會帶來安全性風險。_最好省略這個欄位後，建構作業就會變得非密封。您也可以選擇在提交前設定此屬性，以便簡化開發作業，但應在提交前設定。
url 字串；選用

可讓 Bazel 存取的檔案網址。 格式必須為檔案、http 或 https 網址。我們會遵循路線指示。 不支援驗證機制。 運用網址參數參數指定要擷取的替代網址，您就能享有更多彈性。
urls 字串清單；選用

可讓 Bazel 存取的檔案網址清單。 每個項目都必須是檔案、http 或 https 網址。我們會遵循路線指示。 不支援驗證機制。 系統會依序嘗試網址，直到成功網址為止，因此您應先列出本機的鏡像。 如果所有下載作業都失敗，規則就會失敗。

http_jar

http_jar(name, auth_patterns, canonical_id, downloaded_file_name, integrity, netrc, repo_mapping,
         sha256, url, urls)

從網址下載 jar 檔案，並以 java_import 的形式提供

下載的檔案副檔名必須是 .jar。

範例：假設目前的存放區包含即時通訊程式的原始碼，原始碼位於 ~/chat-app 目錄。它需要依附於 http://example.com/openssl-0.2.jar 提供的 SSL 程式庫。

如果 ~/chat-app 存放區中的目標在 ~/chat-app/WORKSPACE 中新增下列幾行，則該目標可以依附這個目標：

  load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_jar")

  http_jar(
      name = "my_ssl",
      url = "http://example.com/openssl-0.2.jar",
      sha256 = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
  )

目標會將 @my_ssl//jar 指定為依附元件，以依附此 jar 檔案。

如果您使用的是 Unix 系統，也可以使用「file:///path/to/file」參照目前系統 (localhost) 上的檔案。如果是 Windows 電腦，請使用「file:///c:/path/to/file」。在這兩個範例中，請留意三條斜線 (/)，前兩個斜線屬於 file://，第三個斜線屬於檔案的絕對路徑。

屬性

name 名稱；必填

這個存放區的專屬名稱。
auth_patterns 字典：字串 -> 字串；選用

選用的字典，將主機名稱對應至自訂授權模式。 如果此字典中有網址的主機名稱，系統會在產生 http 要求的授權標頭時，使用該值做為模式。這麼一來，您就能使用於許多常見雲端儲存空間供應商提供的自訂授權配置。 這個模式目前支援 2 個符記：<login> 和 <password>。這兩種符記會替換為相同主機名稱 netrc 檔案中的對等值。格式化後，結果會設為 HTTP 要求的 Authorization 欄位值。使用不記名權杖以 HTTP 下載至已啟用 OAuth2 的 API 屬性範例和 Netrc 範例： 

auth_patterns = {
    "storage.cloudprovider.com": "Bearer <password>"
}
netrc： 
machine storage.cloudprovider.com
        password RANDOM-TOKEN
最終的 HTTP 要求會有以下標頭： 
Authorization: Bearer RANDOM-TOKEN

canonical_id 字串；選用

下載檔案的標準 ID。 如有指定且非空白，Bazel 不會將檔案從快取中移除，除非該檔案是透過具有相同標準 ID 的要求加入快取。 如果未指定或空白，Bazel 預設會使用檔案的網址做為標準 ID。這有助於在不一併更新雜湊的情況下找出更新網址的常見錯誤，導致建構作業在本機成功，但在快取中沒有檔案的情況下會失敗。您可以使用 --repo_env=BAZEL_HTTP_RULES_URLS_AS_DEFAULT_CANONICAL_ID=0 停用這項行為。
downloaded_file_name 字串；選用

指派給已下載 jar 的檔案名稱
integrity 字串；選用

下載檔案的子資源完整性格式預期總和檢查碼。 這個 ID 必須與下載檔案的總和檢查碼相符。__由於遠端檔案可能會變更，因此省略總和檢查碼會帶來安全性風險。最好省略這個欄位會讓建構作業變得非密封。你可以選擇是否要在出貨前設定這項屬性或「sha256」，以便簡化開發作業。
netrc 字串；選用

用於驗證的 .netrc 檔案位置

repo_mapping 字典：字串 -> 字串；必要

從本機存放區名稱到全域存放區名稱的字典。如此一來，即可控管這個存放區的依附元件的工作區依附元件解決方案。

舉例來說，項目 `"@foo": "@bar"` 會宣告，每當這個存放區在任何情況下都依賴 `@foo` (例如 `@foo//some:target` 上的依附元件)，實際上應在全域宣告的 `@bar` (`@bar//some:target`) 中解析該依附元件。

sha256 字串；選用

下載檔案的預期 SHA-256。 這個引數必須與下載檔案的 SHA-256 相符。__由於遠端檔案可能會變更，因此省略 SHA-256 會帶來安全性風險。_最好省略這個欄位後，建構作業就會變得非密封。你可以選擇是否要在提交前設定這項屬性或「完整性」，藉此簡化開發作業。
url 字串；選用

可讓 Bazel 存取的檔案網址。 格式必須為檔案、http 或 https 網址。我們會遵循路線指示。 不支援驗證機制。 運用網址參數參數指定要擷取的替代網址，您就能享有更多彈性。網址結尾必須是「.jar」。

urls 字串清單；選用

可讓 Bazel 存取的檔案網址清單。 每個項目都必須是檔案、http 或 https 網址。我們會遵循路線指示。 不支援驗證機制。 系統會依序嘗試網址，直到成功網址為止，因此您應先列出本機的鏡像。 如果所有下載作業都失敗，規則就會失敗。 所有網址都必須以「.jar」結尾。