HTTP 存放區規則

回報問題 查看原始碼 Nightly · 8.0 . 7.4 . 7.3 · 7.2 · 7.1 · 7.0 · 6.5

下列函式可從 @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。它需要依附 SSL 程式庫，可從 http://example.com/openssl.zip 取得。這個 .zip 檔案包含下列目錄結構：

  WORKSPACE
  src/
    openssl.cc
    openssl.h

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

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

如果將下列程式碼新增至 ~/chat-app/WORKSPACE，~/chat-app 存放區中的目標就能依賴這個目標：

  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 String；選用

相對於存放區目錄的目標目錄。將 `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 下載內容下載到已啟用 OAuth 2 的 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 (例如 BUILD.new-repo-name，這樣可以與存放區的實際 BUILD 檔案有所區別)。您可以指定 build_file 或 build_file_content，但不能同時指定。
build_file_content String；選用

這個存放區的 BUILD 檔案內容。您可以指定 build_file 或 build_file_content，但不能同時指定。
canonical_id String；選用

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

下載檔案的預期總和檢查碼，格式為子資源完整性。此值必須與下載的檔案檢查和總和相符。由於遠端檔案可能會變更，因此省略總和檢查碼會造成安全性風險。_省略這個欄位的最佳做法是讓建構作業不具密封性。您可以選擇是否要使用此屬性來簡化開發作業，但應在發布前設定此屬性或 `sha256`。
netrc String；選用

用於驗證的 .netrc 檔案位置
patch_args 字串清單 (選用)

提供給修補工具的引數。預設為 -p0，但通常需要 -p1 才能產生 git 修補程式。如果指定多個 -p 引數，最後一個引數會生效。如果指定的引數不是 -p，Bazel 會改用修補程式指令列工具，而非 Bazel 原生修補程式實作。當改用修補命令列工具且未指定 patch_tool 屬性時，系統會使用 `patch`。這項設定只會影響 `patches` 屬性中的修補檔案。
patch_cmds 字串清單 (選用)

套用修補程式後，在 Linux/Macos 上要套用的 Bash 指令序列。
patch_cmds_win 字串清單 (選用)

在套用修補程式後，要在 Windows 上套用的 PowerShell 指令序列。如果未設定這項屬性，patch_cmds 會在 Windows 上執行，這需要 Bash 二進位檔存在。
patch_tool String；選用

要使用的 patch(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 String；選用

下載檔案的預期 SHA-256。這必須與下載檔案的 SHA-256 相符。_由於遠端檔案可能會變更，因此省略 SHA-256 會造成安全性風險。_即使省略這個欄位，也只能讓建構作業變得不完整。您可以選擇是否要使用這項屬性，以便簡化開發作業，但應在發布前設定這項屬性或「integrity」。
strip_prefix String；選用

要從解壓縮檔案中移除的目錄前置字串。許多封存檔都包含頂層目錄，內含封存檔中的所有實用檔案。您不必在 `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 String；選用

下載檔案的封存類型。根據預設，系統會根據網址的副檔名判斷封存檔類型。如果檔案沒有副檔名，您可以明確指定下列其中一個：`"zip"`、`"jar"`、`"war"`、`"aar"`、`"tar"`、`"tar.gz"`、`"tgz"`、`"tar.xz"`、`"txz"`、`"tar.zst"`、`"tzst"`、`"tar.bz2"`、`"ar"` 或 `"deb"`。
url String；選用

將提供給 Bazel 的檔案網址。必須是檔案、http 或 https 網址。會遵循重新導向網址。不支援驗證。 您可以使用 urls 參數指定要擷取的其他網址，藉此提高彈性。
urls 字串清單 (選用)

要提供給 Bazel 的檔案網址清單。每個項目都必須是檔案、http 或 https 網址。會遵循重新導向網址。不支援驗證。 系統會依序嘗試各個網址，直到其中一個成功為止，因此應先列出本機鏡像。如果所有下載作業都失敗，則規則也會失敗。
workspace_file 標籤 (選用)

這個檔案會用於做為此存放區的 `WORKSPACE` 檔案。您可以指定 `workspace_file` 或 `workspace_file_content`，也可以兩者都不指定，但不能同時指定。
workspace_file_content String；選用

這個存放區的 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 下載內容下載到已啟用 OAuth 2 的 API 的範例屬性和 netrc：

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

canonical_id String；選用

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

指派給下載檔案的路徑
executable 布林值；選用

是否應將下載的檔案設為可執行。
integrity String；選用

下載檔案的預期總和檢查碼，格式為子資源完整性。此值必須與下載的檔案檢查和總和相符。由於遠端檔案可能會變更，因此省略總和檢查碼會造成安全性風險。_省略這個欄位的最佳做法是讓建構作業不具密封性。您可以選擇是否要使用此屬性來簡化開發作業，但應在發布前設定此屬性或 `sha256`。
netrc String；選用

用於驗證的 .netrc 檔案位置
repo_mapping 字典：字串 -> 字串；必要

從本機存放區名稱到全域存放區名稱的字典。這樣就能控管此存放區依附元件的依附元件解析工作區。

舉例來說，如果有個項目 `"@foo": "@bar"`，表示這個存放區每次依賴 `@foo` (例如依賴 `@foo//some:target`) 時，實際上應在全域宣告的 `@bar` (`@bar//some:target`) 中解析該依附元件。
sha256 String；選用

下載檔案的預期 SHA-256。這必須與下載檔案的 SHA-256 相符。_由於遠端檔案可能會變更，因此省略 SHA-256 會造成安全性風險。_即使省略這個欄位，也只能讓建構作業變得不完整。您可以選擇是否要設定這個值，以利開發作業，但應在發布前設定。
url String；選用

將提供給 Bazel 的檔案網址。必須是檔案、http 或 https 網址。會遵循重新導向網址。不支援驗證。 您可以使用 urls 參數指定要擷取的其他網址，藉此提高彈性。
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/WORKSPACE，~/chat-app 存放區中的目標就能依賴這個目標：

  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 下載內容下載到已啟用 OAuth 2 的 API 的範例屬性和 netrc：

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

canonical_id String；選用

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

指派給下載的 JAR 檔案的檔案名稱
integrity String；選用

下載檔案的預期總和檢查碼，格式為子資源完整性。此值必須與下載的檔案檢查和總和相符。由於遠端檔案可能會變更，因此省略總和檢查碼會造成安全性風險。_省略這個欄位的最佳做法是讓建構作業不具密封性。您可以選擇是否要使用此屬性來簡化開發作業，但應在發布前設定此屬性或 `sha256`。
netrc String；選用

用於驗證的 .netrc 檔案位置
repo_mapping 字典：字串 -> 字串；必要

從本機存放區名稱到全域存放區名稱的字典。這樣就能控管此存放區依附元件的依附元件解析工作區。

舉例來說，如果有個項目 `"@foo": "@bar"`，表示這個存放區每次依賴 `@foo` (例如依賴 `@foo//some:target`) 時，實際上應在全域宣告的 `@bar` (`@bar//some:target`) 中解析該依附元件。
sha256 String；選用

下載檔案的預期 SHA-256。這必須與下載檔案的 SHA-256 相符。_由於遠端檔案可能會變更，因此省略 SHA-256 會造成安全性風險。_即使省略這個欄位，也只能讓建構作業變得不完整。您可以選擇是否要使用這項屬性，以便簡化開發作業，但應在發布前設定這項屬性或「integrity」。
url String；選用

將提供給 Bazel 的檔案網址。必須是檔案、http 或 https 網址。會遵循重新導向網址。不支援驗證。 您可以使用 urls 參數指定要擷取的其他網址，藉此提高彈性。網址結尾必須是 `.jar`。
urls 字串清單 (選用)

要提供給 Bazel 的檔案網址清單。每個項目都必須是檔案、http 或 https 網址。會遵循重新導向網址。不支援驗證。 系統會依序嘗試各個網址，直到其中一個成功為止，因此應先列出本機鏡像。如果所有下載作業都失敗，則規則也會失敗。所有網址都必須以 `.jar` 結尾。