HTTP 存放區規則

這個頁面中的內容
設定
http_archive
http_file
http_jar

回報問題查看來源 Nightly · 8.3 · 8.2 · 8.1 · 8.0 · 7.6

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

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

設定

如要在模組擴充功能中使用這些規則，請在 .bzl 檔案中載入規則，然後從擴充功能的實作函式呼叫規則。舉例來說，如要使用 http_archive：

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

def _my_extension_impl(mctx):
  http_archive(name = "foo", urls = [...])

my_extension = module_extension(implementation = _my_extension_impl)

或者，您也可以在 MODULE.bazel 檔案中直接呼叫這些存放區規則，方法是使用 use_repo_rule：

http_archive = use_repo_rule("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
http_archive(name = "foo", urls = [...])

http_archive

load("@bazel//tools/build_defs/repo:http.bzl", "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_strip, patch_tool,
             patches, remote_file_integrity, remote_file_urls, remote_module_file_integrity,
             remote_module_file_urls, 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`	字串；選用相對於存放區目錄的目標目錄。套用 `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。如果指定且不為空白，除非檔案是由具有相同標準 ID 的要求加入快取，否則 Bazel 不會從快取中取得檔案。如未指定或空白，Bazel 預設會使用檔案的網址做為標準 ID。這有助於避免常見錯誤，也就是更新網址但未同時更新雜湊，導致建構作業在本機成功，但在快取中沒有檔案的機器上失敗。您可以使用 --repo_env=BAZEL_HTTP_RULES_URLS_AS_DEFAULT_CANONICAL_ID=0 停用這項行為。
`integrity`	字串；選用下載檔案的子資源完整性格式預期總和檢查碼。這必須與下載檔案的總和檢查碼相符。_省略總和檢查碼會造成安全風險，因為遠端檔案可能會變更。_省略這個欄位最多只會導致建構作業不具密封性。您可以選擇是否要設定這個屬性，以簡化開發作業，但出貨前必須設定這個屬性或 `sha256`。
`netrc`	字串；選用用於驗證的 .netrc 檔案位置
`patch_args`	字串清單 (選用) 提供給修補工具的引數。預設為 -p0 (請參閱 `patch_strip` 屬性)，但通常需要 -p1 才能用於 Git 產生的修補程式。如果指定多個 -p 引數，系統會採用最後一個引數。如果指定 -p 以外的引數，Bazel 會改用 patch 指令列工具，而非 Bazel 原生修補程式實作。如果系統改用修補程式指令列工具，且未指定 patch_tool 屬性，則會使用 `patch`。這只會影響 `patches` 屬性中的修補程式檔案。
`patch_cmds`	字串清單 (選用) 修補程式套用後，要在 Linux/macOS 上執行的 Bash 指令序列。
`patch_cmds_win`	字串清單 (選用) 在套用修補程式後，要在 Windows 上執行的 PowerShell 指令序列。如未設定這項屬性，系統會在 Windows 上執行 patch_cmds，這需要 Bash 二進位檔存在。
`patch_strip`	整數；選用如果設為 `N`，這相當於在 `patch_args` 開頭插入 `-pN`。
`patch_tool`	字串；選用要使用的 patch(1) 公用程式。如果指定此屬性，Bazel 會使用指定的修補程式工具，而非 Bazel 原生的修補程式實作。
`patches`	標籤清單 (選用) 解壓縮封存檔後要套用為修補程式的檔案清單。根據預設，它會使用 Bazel 原生修補程式實作，但這項實作不支援模糊比對和二進位修補程式。不過，如果指定 `patch_tool` 屬性，或 `patch_args` 屬性中含有 `-p` 以外的引數，Bazel 就會改用修補程式指令列工具。
`remote_file_integrity`	字典：字串 -> 字串；選用檔案相對路徑 (鍵) 對應至完整性值 (值) 的對應。這些相對路徑應對應至 `remote_file_urls` 屬性中的檔案 (鍵)。
`remote_file_urls`	字典：字串 -> 字串清單；選用相對路徑 (鍵) 對應至網址清單 (值) 的對應，這些網址會下載並做為存放區的疊加檔案。如要在現有存放區頂端新增 WORKSPACE 或 BUILD.bazel 檔案，這項功能就相當實用。系統會先下載檔案，再套用 `patches` 屬性中的修補程式，且網址清單應全都是相同檔案的鏡像。系統會依序嘗試這些網址，直到其中一個成功為止。
`remote_module_file_integrity`	字串；選用僅供內部使用。
`remote_module_file_urls`	字串清單 (選用) 僅供內部使用。
`remote_patch_strip`	整數；選用要從遠端修補程式的檔案名稱中移除的開頭斜線數量。
`remote_patches`	字典：字串 -> 字串；選用修補程式檔案網址對應完整性值的對應表，會在解壓縮封存檔後套用，並在套用 `patches` 屬性中的修補程式檔案前套用。這項功能使用 Bazel 原生修補程式實作，您可以透過 `remote_patch_strip` 指定修補程式剝除編號
`repo_mapping`	字典：字串 -> 字串；選用僅限 `WORKSPACE` 環境：從本機存放區名稱到全域存放區名稱的字典。這樣就能控管這個存放區依附元件的工作區依附元件解析度。舉例來說，項目 `"@foo": "@bar"` 會宣告，每當這個存放區依附於 `@foo` (例如依附於 `@foo//some:target`) 時，實際上應在全域宣告的 `@bar` 中解析該依附元件 (`@bar//some:target`)。在 `MODULE.bazel` 環境中 (在模組擴充功能的實作函式內叫用存放區規則時)，系統「不」支援這項屬性。
`sha256`	字串；選用下載檔案的預期 SHA-256。這必須與下載檔案的 SHA-256 相符。__省略 SHA-256 會造成安全風險，因為遠端檔案可能會變更。__省略這個欄位最多只會導致建構作業不具密封性。這個屬性為選用屬性，可簡化開發作業，但出貨前應設定這個屬性或 `integrity`。
`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"`、`"tar.zst"`、`"tzst"`、`"tar.bz2"`、`"ar"` 或 `"deb"`。
`url`	字串；選用 Bazel 可存取的檔案網址。這必須是檔案、http 或 https 網址。會追蹤重新導向。不支援驗證。 urls 參數可指定要擷取的替代網址，因此更具彈性。
`urls`	字串清單 (選用) 系統會將檔案網址清單提供給 Bazel。每個項目都必須是檔案、http 或 https 網址。會追蹤重新導向。不支援驗證。系統會依序嘗試網址，直到成功為止，因此您應先列出本機鏡像。如果所有下載作業都失敗，規則就會失敗。
`workspace_file`	標籤 (選填) 無運算屬性，請勿使用。
`workspace_file_content`	字串；選用無運算屬性，請勿使用。

環境變數

這項存放區規則依據下列環境變數：

BAZEL_HTTP_RULES_URLS_AS_DEFAULT_CANONICAL_ID

http_file

load("@bazel//tools/build_defs/repo:http.bzl", "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。如果指定且不為空白，除非檔案是由具有相同標準 ID 的要求加入快取，否則 Bazel 不會從快取中取得檔案。如未指定或空白，Bazel 預設會使用檔案的網址做為標準 ID。這有助於避免常見錯誤，也就是更新網址但未同時更新雜湊，導致建構作業在本機成功，但在快取中沒有檔案的機器上失敗。您可以使用 --repo_env=BAZEL_HTTP_RULES_URLS_AS_DEFAULT_CANONICAL_ID=0 停用這項行為。
`downloaded_file_path`	字串；選用指派給下載檔案的路徑
`executable`	布林值；選用下載的檔案是否應設為可執行檔。
`integrity`	字串；選用下載檔案的子資源完整性格式預期總和檢查碼。這必須與下載檔案的總和檢查碼相符。_省略總和檢查碼會造成安全風險，因為遠端檔案可能會變更。_省略這個欄位最多只會導致建構作業不具密封性。您可以選擇是否要設定這個屬性，以簡化開發作業，但出貨前必須設定這個屬性或 `sha256`。
`netrc`	字串；選用用於驗證的 .netrc 檔案位置
`repo_mapping`	字典：字串 -> 字串；選用僅限 `WORKSPACE` 環境：從本機存放區名稱到全域存放區名稱的字典。這樣就能控管這個存放區依附元件的工作區依附元件解析度。舉例來說，項目 `"@foo": "@bar"` 會宣告，每當這個存放區依附於 `@foo` (例如依附於 `@foo//some:target`) 時，實際上應在全域宣告的 `@bar` 中解析該依附元件 (`@bar//some:target`)。在 `MODULE.bazel` 環境中 (在模組擴充功能的實作函式內叫用存放區規則時)，系統「不」支援這項屬性。
`sha256`	字串；選用下載檔案的預期 SHA-256。這必須與下載檔案的 SHA-256 相符。__省略 SHA-256 會造成安全風險，因為遠端檔案可能會變更。__省略這個欄位最多只會導致建構作業不具密封性。這項設定可簡化開發作業，但出貨前必須設定。
`url`	字串；選用 Bazel 可存取的檔案網址。這必須是檔案、http 或 https 網址。會追蹤重新導向。不支援驗證。 urls 參數可指定要擷取的替代網址，因此更具彈性。
`urls`	字串清單 (選用) 系統會將檔案網址清單提供給 Bazel。每個項目都必須是檔案、http 或 https 網址。會追蹤重新導向。不支援驗證。系統會依序嘗試網址，直到成功為止，因此您應先列出本機鏡像。如果所有下載作業都失敗，規則就會失敗。

環境變數

這項存放區規則依據下列環境變數：

BAZEL_HTTP_RULES_URLS_AS_DEFAULT_CANONICAL_ID

http_jar

load("@bazel//tools/build_defs/repo:http.bzl", "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 下載至已啟用 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。如果指定且不為空白，除非檔案是由具有相同標準 ID 的要求加入快取，否則 Bazel 不會從快取中取得檔案。如未指定或空白，Bazel 預設會使用檔案的網址做為標準 ID。這有助於避免常見錯誤，也就是更新網址但未同時更新雜湊，導致建構作業在本機成功，但在快取中沒有檔案的機器上失敗。您可以使用 --repo_env=BAZEL_HTTP_RULES_URLS_AS_DEFAULT_CANONICAL_ID=0 停用這項行為。
`downloaded_file_name`	字串；選用指派給下載的 JAR 檔案的檔案名稱
`integrity`	字串；選用下載檔案的子資源完整性格式預期總和檢查碼。這必須與下載檔案的總和檢查碼相符。_省略總和檢查碼會造成安全風險，因為遠端檔案可能會變更。_省略這個欄位最多只會導致建構作業不具密封性。您可以選擇是否要設定這個屬性，以簡化開發作業，但出貨前必須設定這個屬性或 `sha256`。
`netrc`	字串；選用用於驗證的 .netrc 檔案位置
`repo_mapping`	字典：字串 -> 字串；選用僅限 `WORKSPACE` 環境：從本機存放區名稱到全域存放區名稱的字典。這樣就能控管這個存放區依附元件的工作區依附元件解析度。舉例來說，項目 `"@foo": "@bar"` 會宣告，每當這個存放區依附於 `@foo` (例如依附於 `@foo//some:target`) 時，實際上應在全域宣告的 `@bar` 中解析該依附元件 (`@bar//some:target`)。在 `MODULE.bazel` 環境中 (在模組擴充功能的實作函式內叫用存放區規則時)，系統「不」支援這項屬性。
`sha256`	字串；選用下載檔案的預期 SHA-256。這必須與下載檔案的 SHA-256 相符。__省略 SHA-256 會造成安全風險，因為遠端檔案可能會變更。__省略這個欄位最多只會導致建構作業不具密封性。這個屬性為選用屬性，可簡化開發作業，但出貨前應設定這個屬性或 `integrity`。
`url`	字串；選用 Bazel 可存取的檔案網址。這必須是檔案、http 或 https 網址。會追蹤重新導向。不支援驗證。 urls 參數可指定要擷取的替代網址，因此更具彈性。網址必須以 `.jar` 結尾。
`urls`	字串清單 (選用) 系統會將檔案網址清單提供給 Bazel。每個項目都必須是檔案、http 或 https 網址。會追蹤重新導向。不支援驗證。系統會依序嘗試網址，直到成功為止，因此您應先列出本機鏡像。如果所有下載作業都失敗，規則就會失敗。所有網址都必須以 `.jar` 結尾。

環境變數

這項存放區規則依據下列環境變數：

BAZEL_HTTP_RULES_URLS_AS_DEFAULT_CANONICAL_ID