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 文件中相同主机名的等 101 效值。格式化后，结果将设置为 HTTP 请求的 Authorization 字段的值。 以下是使用持有者令牌向启用 oauth2 的 API 进行 http 下载的属性和 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 字符串；可选

下载文件的子资源完整性格式的预期校验和。 这必须与下载文件的校验和一致。_省略校验和存在安全风险，因为远程文件可能会发生更改。_ 最好的情况是，省略此字段会使您的构建不具有密封性。为了方便开发，此字段是可选的，但在发布之前，应设置此属性或 `sha256`。

netrc 字符串；可选

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

patch_args 字符串列表；可选

提供给补丁工具的实参。默认为 -p0，但对于 git 生成的补丁，通常需要 -p1。如果指定了多个 -p 实参，则最后一个实参将生效。如果指定了 -p 以外的实参，Bazel 将回退为使用 patch 命令行工具，而不是 Bazel 原生补丁实现。回退到 patch 命令行工具且未指定 patch_tool 属性时，将使用 `patch`。这只会影响 `patches` 属性中的补丁文件。

patch_cmds 字符串列表；可选

在应用补丁后，要在 Linux/Macos 上应用的一系列 Bash 命令。

patch_cmds_win 字符串列表；可选

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

patch_tool 字符串；可选

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

patches 标签列表；可选

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

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 存在安全风险，因为远程文件可能会发生更改。_ 最好的情况是，省略此字段会使您的构建不具有密封性。为了方便开发，此字段是可选的，但在发布之前，应设置此属性或 `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 字符串；可选

此代码库的 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 文件中相同主机名的等 101 效值。格式化后，结果将设置为 HTTP 请求的 Authorization 字段的值。 以下是使用持有者令牌向启用 oauth2 的 API 进行 http 下载的属性和 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 字符串；可选

下载文件的子资源完整性格式的预期校验和。 这必须与下载文件的校验和一致。_省略校验和存在安全风险，因为远程文件可能会发生更改。_ 最好的情况是，省略此字段会使您的构建不具有密封性。为了方便开发，此字段是可选的，但在发布之前，应设置此属性或 `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 参数允许指定要从中提取的备用网址，从而实现更高的灵活性。

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。它需要依赖于一个 SSL 库，该库可从 http://example.com/openssl-0.2.jar 获取。

如果将以下行添加到 ~/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 文件中相同主机名的等 101 效值。格式化后，结果将设置为 HTTP 请求的 Authorization 字段的值。 以下是使用持有者令牌向启用 oauth2 的 API 进行 http 下载的属性和 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 字符串；可选

下载文件的子资源完整性格式的预期校验和。 这必须与下载文件的校验和一致。_省略校验和存在安全风险，因为远程文件可能会发生更改。_ 最好的情况是，省略此字段会使您的构建不具有密封性。为了方便开发，此字段是可选的，但在发布之前，应设置此属性或 `sha256`。

netrc 字符串；可选

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

repo_mapping 字典：字符串 -> 字符串；必需

从本地代码库名称到全局代码库名称的字典。这样便可以控制此代码库的依赖项的工作区依赖项解析。

例如，条目 `"@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` 结尾。