HTTP 代码库规则

报告问题 查看来源 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。它需要依赖于可从 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 字典:字符串 -> 字符串;可选

一个可选的字典,用于将主机名映射到自定义授权模式。 如果网址的主机名存在于此字典中,则在为 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(例如,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 字符串;可选

下载文件的预期校验和(采用子资源完整性格式)。 此值必须与下载的文件的校验和一致。_省略校验和存在安全风险,因为远程文件可能会发生更改。_省略此字段最多只会导致您的 build 不密封。为了方便开发,此属性是可选的,但在发布之前,应设置此属性或 `sha256` 属性。

netrc 字符串;可选

用于身份验证的 .netrc 文件的位置

patch_args 字符串列表;可选

传递给补丁工具的实参。默认值为 -p0(请参阅 `patch_strip` 属性),但对于由 Git 生成的补丁,通常需要使用 -p1。如果指定了多个 -p 实参,则最后一个实参会生效。如果指定了除 -p 以外的实参,Bazel 将回退为使用 patch 命令行工具,而不是 Bazel 原生的 patch 实现。回退到补丁命令行工具且未指定 patch_tool 属性时,将使用“patch”。这只会影响 `patches` 属性中的补丁文件。

patch_cmds 字符串列表;可选

在应用补丁后,要在 Linux/macOS 上应用的 Bash 命令序列。

patch_cmds_win 字符串列表;可选

在应用补丁后要在 Windows 上应用的 PowerShell 命令序列。如果未设置此属性,patch_cmds 将在 Windows 上执行,这需要存在 Bash 二进制文件。

patch_strip 整数;可选

如果设置为“N”,则相当于在“patch_args”的开头插入“-pN”。

patch_tool 字符串;可选

要使用的 patch(1) 实用程序。如果指定了此属性,Bazel 将使用指定的补丁工具,而不是 Bazel 原生的补丁实现。

patches 标签列表;可选

在提取归档文件后要作为补丁应用的文件列表。默认情况下,它使用不支持模糊匹配和二进制补丁的 Bazel 原生补丁实现,但如果指定了 `patch_tool` 属性或 `patch_args` 属性中存在除 `-p` 之外的实参,Bazel 将回退到使用 patch 命令行工具。

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 会带来安全风险,因为远程文件可能会发生变化。_省略此字段最多只会导致您的 build 不密封。为了方便开发,此属性是可选的,但在发布之前,应设置此属性或 `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。 如果指定了此标志且不为空,Bazel 将不会从缓存中获取相应文件,除非该文件是通过具有相同规范 ID 的请求添加到缓存中的。 如果未指定或为空,Bazel 默认使用文件的网址作为规范 ID。这有助于发现常见错误,即更新网址但未同时更新哈希,导致本地构建成功,但在缓存中没有相应文件的机器上构建失败。您可以使用 --repo_env=BAZEL_HTTP_RULES_网址S_AS_DEFAULT_CANONICAL_ID=0 停用此行为。

downloaded_file_path 字符串;可选

分配给下载文件的路径

executable 布尔值;可选

下载的文件是否应设为可执行文件。

integrity 字符串;可选

下载文件的预期校验和(采用子资源完整性格式)。 此值必须与下载的文件的校验和一致。_省略校验和存在安全风险,因为远程文件可能会发生更改。_省略此字段最多只会导致您的 build 不密封。为了方便开发,此属性是可选的,但在发布之前,应设置此属性或 `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 会带来安全风险,因为远程文件可能会发生变化。_省略此字段最多只会导致您的 build 不密封。为了方便开发,此属性是可选的,但应在发布前设置。

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。 如果指定了此标志且不为空,Bazel 将不会从缓存中获取相应文件,除非该文件是通过具有相同规范 ID 的请求添加到缓存中的。 如果未指定或为空,Bazel 默认使用文件的网址作为规范 ID。这有助于发现常见错误,即更新网址但未同时更新哈希,导致本地构建成功,但在缓存中没有相应文件的机器上构建失败。您可以使用 --repo_env=BAZEL_HTTP_RULES_网址S_AS_DEFAULT_CANONICAL_ID=0 停用此行为。

downloaded_file_name 字符串;可选

分配给下载的 JAR 的文件名

integrity 字符串;可选

下载文件的预期校验和(采用子资源完整性格式)。 此值必须与下载的文件的校验和一致。_省略校验和存在安全风险,因为远程文件可能会发生更改。_省略此字段最多只会导致您的 build 不密封。为了方便开发,此属性是可选的,但在发布之前,应设置此属性或 `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 会带来安全风险,因为远程文件可能会发生变化。_省略此字段最多只会导致您的 build 不密封。为了方便开发,此属性是可选的,但在发布之前,应设置此属性或 `integrity` 属性。

url 字符串;可选

将提供给 Bazel 的文件的网址。 必须是文件、HTTP 或 HTTPS 网址。系统会跟踪重定向。 不支持身份验证。 urls 参数可用于指定要从中提取的替代网址,从而实现更高的灵活性。 网址必须以“.jar”结尾。

urls 字符串列表;可选

将提供给 Bazel 的文件网址列表。 每个条目都必须是文件、http 或 https 网址。系统会跟踪重定向。 不支持身份验证。 系统会按顺序尝试网址,直到成功为止,因此您应先列出本地镜像。 如果所有下载均失败,则规则将失败。 所有网址都必须以 `.jar` 结尾。

环境变量

此代码库规则依赖于以下环境变量:

  • BAZEL_HTTP_RULES_URLS_AS_DEFAULT_CANONICAL_ID