可以从 @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_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
目录下。它需要依赖于可从 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/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 |
Dictionary: String -> String;可选
将主机名映射到自定义授权格式的可选字典。
如果此字典中存在网址的主机名,则在为 http 请求生成授权标头时,该值将用作格式。这样一来,您就可以使用许多常见的云端存储空间服务中使用的自定义授权方案。该模式目前支持 2 个令牌: 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_网址S_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_file_integrity |
Dictionary: String -> String;可选
文件相对路径(键)到其完整性值(值)的映射。这些相对路径应映射到“remote_file_urls”属性中的文件(键)。 |
remote_file_urls |
Dictionary: String -> List of strings;可选
相对路径(键)到网址(值)列表的映射,这些网址(值)将被下载并在代码库中作为叠加文件提供。如果您想在现有代码库上添加 WORKSPACE 或 BUILD.bazel 文件,这会非常有用。这些文件是在应用 `patches` 属性中的补丁之前下载的,其网址列表应是同一文件的可能镜像。系统会按顺序尝试这些网址,直到成功为止。 |
remote_patch_strip |
整数;可选
要从远程补丁的文件名中删除的前导斜杠的数量。 |
remote_patches |
Dictionary: String -> String;可选
补丁文件网址到其完整性值的映射。在提取归档文件之后、通过 `patches` 属性应用补丁文件之前,系统会先应用补丁文件网址。它使用 Bazel 原生补丁实现,您可以使用“remote_patch_strip”指定补丁条编号 |
repo_mapping |
Dictionary: String -> String;必需
从本地代码库名称到全局代码库名称的字典。这样,您就可以控制此代码库的依赖项的工作区依赖项解析。 例如,“@foo": "@bar"` 条目声明:无论何时此仓库依赖于 `@foo`(例如 `@foo//some:target` 的依赖项),它实际上都应在全局声明的 `@bar` (`@bar//some:target`) 中解析该依赖项。 |
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"`, debtz.b"`"`、" |
url |
字符串;可选
指向可供 Bazel 使用的文件的网址。 此网址必须是文件、http 或 https 网址。遵循重定向。 不支持身份验证。 使用 urls 参数可以指定从中获取的备用网址,从而实现更高的灵活性。 |
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 |
Dictionary: String -> String;可选
将主机名映射到自定义授权格式的可选字典。
如果此字典中存在网址的主机名,则在为 http 请求生成授权标头时,该值将用作格式。这样一来,您就可以使用许多常见的云端存储空间服务中使用的自定义授权方案。该模式目前支持 2 个令牌: 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_网址S_AS_DEFAULT_CANONical_ID=0 停用此行为。 |
downloaded_file_path |
字符串;可选
分配给所下载文件的路径 |
executable |
布尔值;可选
下载的文件是否应设为可执行文件。 |
integrity |
字符串;可选
所下载文件的校验和应采用子资源完整性格式。 必须与所下载文件的校验和一致。_省略校验和会带来安全风险,因为远程文件可能会发生变化。_最好省略此字段会导致构建非封闭。为了简化开发,这是可选操作,但应在发布前设置此属性或 `sha256`。 |
netrc |
字符串;可选
用于身份验证的 .netrc 文件的位置 |
repo_mapping |
Dictionary: String -> String;必需
从本地代码库名称到全局代码库名称的字典。这样,您就可以控制此代码库的依赖项的工作区依赖项解析。 例如,“@foo": "@bar"` 条目声明:无论何时此仓库依赖于 `@foo`(例如 `@foo//some:target` 的依赖项),它实际上都应在全局声明的 `@bar` (`@bar//some:target`) 中解析该依赖项。 |
sha256 |
字符串;可选
所下载文件的预期 SHA-256。 此签名必须与所下载文件的 SHA-256 一致。省略 SHA-256 会带来安全风险,因为远程文件可能会发生变化。最多省略此字段会导致构建非封闭。为了简化开发,您可以视需要进行设置,但应在发布前进行设置。 |
url |
字符串;可选
指向可供 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 |
Dictionary: String -> String;可选
将主机名映射到自定义授权格式的可选字典。
如果此字典中存在网址的主机名,则在为 http 请求生成授权标头时,该值将用作格式。这样一来,您就可以使用许多常见的云端存储空间服务中使用的自定义授权方案。该模式目前支持 2 个令牌: 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_网址S_AS_DEFAULT_CANONical_ID=0 停用此行为。 |
downloaded_file_name |
字符串;可选
为下载的 jar 分配的文件名 |
integrity |
字符串;可选
所下载文件的校验和应采用子资源完整性格式。 必须与所下载文件的校验和一致。_省略校验和会带来安全风险,因为远程文件可能会发生变化。_最好省略此字段会导致构建非封闭。为了简化开发,这是可选操作,但应在发布前设置此属性或 `sha256`。 |
netrc |
字符串;可选
用于身份验证的 .netrc 文件的位置 |
repo_mapping |
Dictionary: String -> String;必需
从本地代码库名称到全局代码库名称的字典。这样,您就可以控制此代码库的依赖项的工作区依赖项解析。 例如,“@foo": "@bar"` 条目声明:无论何时此仓库依赖于 `@foo`(例如 `@foo//some:target` 的依赖项),它实际上都应在全局声明的 `@bar` (`@bar//some:target`) 中解析该依赖项。 |
sha256 |
字符串;可选
所下载文件的预期 SHA-256。 此签名必须与所下载文件的 SHA-256 一致。省略 SHA-256 会带来安全风险,因为远程文件可能会发生变化。最多省略此字段会导致构建非封闭。为了简化开发,这是可选操作,但应在发布前设置此属性或 `integrity`。 |
url |
字符串;可选
指向可供 Bazel 使用的文件的网址。 此网址必须是文件、http 或 https 网址。遵循重定向。 不支持身份验证。 使用 urls 参数可以指定从中获取的备用网址,从而实现更高的灵活性。 网址必须以“.jar”结尾。 |
urls |
字符串列表;可选
指向可供 Bazel 使用的文件的网址列表。 每个条目都必须是文件、http 或 https 网址。遵循重定向。 不支持身份验证。 系统会按顺序尝试网址,直到成功成功为止。因此,您应先列出本地镜像。 如果所有下载均失败,则规则将会失败。 所有网址都必须以“.jar”结尾。 |