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 的聊天程序的源代码。它需要依赖于可从 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`	字典：String -> String；可选将主机名映射到自定义授权模式的可选字典。如果此字典中包含网址的主机名，则在为 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`	Label（可选）；要用作此代码库的 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_CANONIAL_ID=0 停用此行为。
`integrity`	字符串；可选所下载文件的子资源完整性格式的预期校验和。此校验和必须与所下载文件的校验和匹配。_省略校验和会带来安全风险，因为远程文件可能会发生变化。至少省略此字段会使您的 build 不封闭。为了简化开发，可选操作，但应在发布之前设置此属性或 `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 命令序列。如果未设置该属性，则补丁_cmds 将在 Windows 上执行，这需要 Bash 二进制文件存在。
`patch_tool`	字符串；可选要使用的补丁(1) 实用程序。如果指定，Bazel 将使用指定的补丁工具，而不是 Bazel 原生补丁实现。
`patches`	标签列表（可选）提取归档文件后要作为补丁应用的文件列表。默认情况下，它使用不支持模糊匹配和二进制补丁的 Bazel 原生补丁实现，但如果指定了“patch_tool”属性或者“patch_args”属性中存在除“-p”以外的参数，Bazel 将回退为使用补丁命令行工具。
`remote_patch_strip`	整数（可选）要从远程补丁的文件名中删除的前导斜杠数量。
`remote_patches`	字典：String -> String；可选补丁文件网址与其完整性值的映射，在提取归档文件之后、从 `patches` 属性应用补丁文件之前应用。它使用 Bazel 原生补丁实现，您可以使用“remote_patch_strip”指定补丁条带编号
`repo_mapping`	字典：String -> String；必需从本地代码库名称到全局代码库名称的字典。这样，您就可以控制此代码库依赖项的工作区依赖项解析。例如，条目"@foo": "@bar"` 就声明，每当此代码库依赖于“@foo”（例如对“@foo//some:target”的依赖项），它实际上应在全局声明的 `@bar`（“@bar//some:target”）中解析该依赖项。
`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"`, "tar.zst"`, "`", "deb."`, "`.", ", ", ", ", "，），".
`url`	字符串；可选指向将可供 Bazel 使用的文件的网址。此网址必须是文件、http 或 https 网址。遵循重定向。不支持身份验证。 urls 参数允许指定要从中提取备用网址，从而提高灵活性。
`urls`	字符串列表（可选）可供 Bazel 使用的文件的网址列表。每个条目都必须是文件、http 或 https 网址。遵循重定向。不支持身份验证。系统会按顺序尝试网址，直到一个成功为止，因此您应该先列出本地镜像。如果所有下载都失败，该规则就会失败。
`workspace_file`	Label（可选）；要用作此代码库的“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`	字典：String -> String；可选将主机名映射到自定义授权模式的可选字典。如果此字典中包含网址的主机名，则在为 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_CANONIAL_ID=0 停用此行为。
`downloaded_file_path`	字符串；可选分配给所下载文件的路径
`executable`	布尔值；可选下载的文件是否应设为可执行文件。
`integrity`	字符串；可选所下载文件的子资源完整性格式的预期校验和。此校验和必须与所下载文件的校验和匹配。_省略校验和会带来安全风险，因为远程文件可能会发生变化。至少省略此字段会使您的 build 不封闭。为了简化开发，可选操作，但应在发布之前设置此属性或 `sha256`。
`netrc`	字符串；可选用于进行身份验证的 .netrc 文件的位置
`repo_mapping`	字典：String -> String；必需从本地代码库名称到全局代码库名称的字典。这样，您就可以控制此代码库依赖项的工作区依赖项解析。例如，条目"@foo": "@bar"` 就声明，每当此代码库依赖于“@foo”（例如对“@foo//some:target”的依赖项），它实际上应在全局声明的 `@bar`（“@bar//some:target”）中解析该依赖项。
`sha256`	字符串；可选所下载文件的预期 SHA-256。此标识符必须与所下载文件的 SHA-256 一致。_省略 SHA-256 会带来安全风险，因为远程文件可能会发生变化。至少省略此字段会使您的 build 进行非封闭。为简化开发操作是可选的，但应在交付之前进行设置。
`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`	字典：String -> String；可选将主机名映射到自定义授权模式的可选字典。如果此字典中包含网址的主机名，则在为 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_CANONIAL_ID=0 停用此行为。
`downloaded_file_name`	字符串；可选分配给下载的 jar 的文件名
`integrity`	字符串；可选所下载文件的子资源完整性格式的预期校验和。此校验和必须与所下载文件的校验和匹配。_省略校验和会带来安全风险，因为远程文件可能会发生变化。至少省略此字段会使您的 build 不封闭。为了简化开发，可选操作，但应在发布之前设置此属性或 `sha256`。
`netrc`	字符串；可选用于进行身份验证的 .netrc 文件的位置
`repo_mapping`	字典：String -> String；必需从本地代码库名称到全局代码库名称的字典。这样，您就可以控制此代码库依赖项的工作区依赖项解析。例如，条目"@foo": "@bar"` 就声明，每当此代码库依赖于“@foo”（例如对“@foo//some:target”的依赖项），它实际上应在全局声明的 `@bar`（“@bar//some:target”）中解析该依赖项。
`sha256`	字符串；可选所下载文件的预期 SHA-256。此标识符必须与所下载文件的 SHA-256 一致。_省略 SHA-256 会带来安全风险，因为远程文件可能会发生变化。至少省略此字段会使您的 build 进行非封闭。为了简化开发，您可以视需要做出选择，但在发布之前应设置此属性或 `integrity`。
`url`	字符串；可选指向将可供 Bazel 使用的文件的网址。此网址必须是文件、http 或 https 网址。遵循重定向。不支持身份验证。 urls 参数允许指定要从中提取备用网址，从而提高灵活性。网址必须以“.jar”结尾。
`urls`	字符串列表（可选）可供 Bazel 使用的文件的网址列表。每个条目都必须是文件、http 或 https 网址。遵循重定向。不支持身份验证。系统会按顺序尝试网址，直到一个成功为止，因此您应该先列出本地镜像。如果所有下载都失败，该规则就会失败。所有网址都必须以“.jar”结尾。