您可以從 @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)
或者,您也可以使用 use_repo_rule
直接在 MODULE.bazel 檔案中呼叫這些存放區規則:
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_tool, patches, remote_file_integrity, remote_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 |
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 個符記: auth_patterns = { "storage.cloudprovider.com": "Bearer <password>" } machine storage.cloudprovider.com password RANDOM-TOKEN 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,但 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 |
String; 選用 要使用的 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_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 |
String; 選用 下載檔案的預期 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` 檔案。您可以指定 `workspace_file` 或 `workspace_file_content`,也可以兩者都不指定,但不能同時指定。 |
workspace_file_content |
String; 選用 這個存放區的 WORKSPACE 檔案內容。您可以指定 `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 個符記: auth_patterns = { "storage.cloudprovider.com": "Bearer <password>" } machine storage.cloudprovider.com password RANDOM-TOKEN 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 |
字串;選用 下載檔案的預期總和檢查碼,格式為子資源完整性。此值必須與下載的檔案檢查和總和相符。由於遠端檔案可能會變更,因此省略總和檢查碼會造成安全性風險。_省略這個欄位的最佳做法是讓建構作業不具密封性。您可以選擇是否要使用此屬性來簡化開發作業,但應在發布前設定此屬性或 `sha256`。 |
netrc |
String; 選用 用於驗證的 .netrc 檔案位置 |
repo_mapping |
字典:字串 -> 字串 (選用)
僅限於 `WORKSPACE` 上下文:從本機存放區名稱到全域存放區名稱的字典。如此一來,即可控管這個存放區的依附元件的工作區依附元件解析方式。舉例來說,如果項目為 `"@foo": "@bar"`,則表示此存放區在任何依附 `@foo` 的情況下 (例如依附 `@foo//some:target` 的情況),實際上應在全域宣告的 `@bar` (`@bar//some:target`) 中解析該依附元件。 `MODULE.bazel` 情境 (在模組擴充功能的實作函式中叫用存放區規則時) _不_支援此屬性。 |
sha256 |
String; 選用 下載檔案的預期 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 個符記: auth_patterns = { "storage.cloudprovider.com": "Bearer <password>" } machine storage.cloudprovider.com password RANDOM-TOKEN 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 |
字典:字串 -> 字串 (選用)
僅限於 `WORKSPACE` 上下文:從本機存放區名稱轉換為全域存放區名稱的字典。這樣就能控管這個存放區依附元件的依附元件解析工作區。舉例來說,如果項目為 `"@foo": "@bar"`,則表示此存放區每次依附 `@foo` 時 (例如依附 `@foo//some:target` 的依附元件),實際上應在全域宣告的 `@bar` (`@bar//some:target`) 中解析該依附元件。 `MODULE.bazel` 內容中 (在模組擴充功能的實作函式中叫用存放區規則時) _不_支援此屬性。 |
sha256 |
String; 選用 下載檔案的預期 SHA-256。這必須與下載檔案的 SHA-256 相符。__由於遠端檔案可能會變更,因此省略 SHA-256 會帶來安全性風險。_最好省略這個欄位後,建構作業就會變得非密封。您可以選擇是否要使用這項屬性,以便簡化開發作業,但應在發布前設定這項屬性或「integrity」。 |
url |
String; 選用 可讓 Bazel 存取的檔案網址。 必須是檔案、http 或 https 網址。會遵循重新導向網址。不支援驗證。您可以使用 urls 參數指定要擷取的其他網址,藉此提高彈性。網址結尾必須是 `.jar`。 |
urls |
字串清單 (選用)
可讓 Bazel 存取的檔案網址清單。 每個項目都必須是檔案、http 或 https 網址。我們會遵循路線指示。 不支援驗證。系統會依序嘗試各個網址,直到其中一個成功為止,因此應先列出本機鏡像。如果所有下載作業都失敗,則規則也會失敗。所有網址都必須以「.jar」結尾。 |
環境變數
這個存放區規則取決於下列環境變數:
BAZEL_HTTP_RULES_URLS_AS_DEFAULT_CANONICAL_ID