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 目錄。您必須依賴 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。如果指定且非空白，Bazel 不會將檔案從快取取出，除非該檔案是透過要求相同的標準 ID 加入快取。如未指定或空白，Bazel 預設會使用檔案網址做為標準 ID。這麼做有助於找出更新網址時常見的錯誤，而不必一併更新雜湊，這樣會造成本機成功執行，但在沒有快取中檔案的機器上失敗。您可以使用 --repo_env=BAZEL_HTTP_RULES_URLS_AS_DEFAULT_CANONICAL_ID=0 停用這項行為。
`integrity`	字串；選用下載檔案的子資源完整性格式預期檢查碼。這必須與所下載檔案的總和檢查碼相符。由於遠端檔案可能會變更，因此省略總和檢查碼是安全風險。如果省略這個欄位，您的建構可能會變得不一致。您可以選擇讓開發程序更輕鬆，但請在運送前設定此屬性或「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 指令序列。如未設定這項屬性，系統將在 Windows 上執行 Patch_cmds 且需要 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」，當中包含「WORKSPACE」檔案，其中的「foo-lib-1.2.3/」目錄位於其中，且是「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"`、`"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`	字串；選用下載檔案的子資源完整性格式預期檢查碼。這必須與所下載檔案的總和檢查碼相符。由於遠端檔案可能會變更，因此省略總和檢查碼是安全風險。如果省略這個欄位，您的建構可能會變得不一致。您可以選擇讓開發程序更輕鬆，但請在運送前設定此屬性或「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/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。如果指定且非空白，Bazel 不會將檔案從快取取出，除非該檔案是透過要求相同的標準 ID 加入快取。如未指定或空白，Bazel 預設會使用檔案網址做為標準 ID。這麼做有助於找出更新網址時常見的錯誤，而不必一併更新雜湊，這樣會造成本機成功執行，但在沒有快取中檔案的機器上失敗。您可以使用 --repo_env=BAZEL_HTTP_RULES_URLS_AS_DEFAULT_CANONICAL_ID=0 停用這項行為。
`downloaded_file_name`	字串；選用指派給下載 jar 的檔案名稱
`integrity`	字串；選用下載檔案的子資源完整性格式預期檢查碼。這必須與所下載檔案的總和檢查碼相符。由於遠端檔案可能會變更，因此省略總和檢查碼是安全風險。如果省略這個欄位，您的建構可能會變得不一致。您可以選擇讓開發程序更輕鬆，但請在運送前設定此屬性或「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」結尾。