Workspace 规则

报告问题 查看源代码

工作区规则用于提取外部依赖项,通常是位于主代码库以外的源代码。

注意:除了原生工作区规则之外,Bazel 还嵌入了各种 Starlark 工作区规则,尤其是用于处理 Web 上托管的 Git 代码库或归档的规则。

规则

绑定

查看规则来源
bind(name, actual, compatible_with, deprecation, distribs, features, licenses, restricted_to, tags, target_compatible_with, testonly, visibility)

警告:不建议使用 bind()。请参阅考虑移除绑定,详细了解其问题和替代方案。具体来讲,请考虑使用 repo_mapping 代码库特性

警告:不能在 bind() 中使用 select()。如需了解详情,请参阅可配置属性常见问题解答

为目标提供 //external 软件包中的别名。

//external 软件包不是“普通”软件包:没有 external/ 目录,因此可以将其视为包含所有绑定目标的“虚拟软件包”。

示例

如需为目标指定别名,请在 WORKSPACE 文件中对其执行 bind 操作。例如,假设有一个名为 //third_party/javacc-v2java_library 目标。您可以通过将以下内容添加到 WORKSPACE 文件来使用别名:

bind(
    name = "javacc-latest",
    actual = "//third_party/javacc-v2",
)

现在,目标可以依赖于 //external:javacc-latest,而不是 //third_party/javacc-v2。如果发布了 javacc-v3,则 bind 规则可以更新,并且依赖于 //external:javacc-latest 的所有 BUILD 文件现在都将依赖于 javacc-v3,而无需进行修改。

绑定也可用于将外部代码库中的目标设为工作区。例如,如果在 WORKSPACE 文件中导入了一个名为 @my-ssl 的远程代码库,并且该库具有 cc_library 目标 //src:openssl-lib,则您可以使用 bind 为此目标创建别名:

bind(
    name = "openssl",
    actual = "@my-ssl//src:openssl-lib",
)

然后,在工作区的 BUILD 文件中,可按以下方式使用绑定目标:

cc_library(
    name = "sign-in",
    srcs = ["sign_in.cc"],
    hdrs = ["sign_in.h"],
    deps = ["//external:openssl"],
)

sign_in.ccsign_in.h 中,可以使用 //external:openssl 提供的头文件相对于其代码库根目录来引用它们。例如,如果 @my-ssl//src:openssl-lib 的规则定义如下所示:

cc_library(
    name = "openssl-lib",
    srcs = ["openssl.cc"],
    hdrs = ["openssl.h"],
)

那么,sign_in.cc 的包含内容可能如下所示:

#include "sign_in.h"
#include "src/openssl.h"

参数

特性
name

Name; required

此目标的唯一名称。

actual

Label; optional

要别名的目标。

此目标必须存在,但可以是任何类型的规则(包括绑定)。

如果省略此属性,则 //external 中引用此目标的规则将根本无法看到此依赖项边缘。请注意,这与完全省略 bind 规则不同:如果 //external 依赖项没有关联的 bind 规则,则会发生错误。

local_repository

查看规则来源
local_repository(name, path, repo_mapping)

允许绑定本地目录中的目标。这意味着当前代码库可以使用在另一个目录中定义的目标。如需了解详情,请参阅绑定部分

示例

假设当前代码库是一个聊天客户端,位于 ~/chat-app 目录下,且想使用另一个代码库中定义的 SSL 库:~/ssl。SSL 库的目标为 //src:openssl-lib

用户可以通过向 ~/chat-app/WORKSPACE 添加以下代码行来添加对此目标的依赖项:

local_repository(
    name = "my-ssl",
    path = "/home/user/ssl",
)

目标会将 @my-ssl//src:openssl-lib 指定为依赖项,以依赖此库。

参数

特性
name

Name; required

此目标的唯一名称。

path

String; required

本地代码库的目录路径。

该路径必须是包含代码库 WORKSPACE 文件的目录的路径。路径可以是绝对路径,也可以是相对于主代码库的 WORKSPACE 文件的路径。

repo_mapping

Dictionary: String -> String; optional

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

例如,条目 "@foo": "@bar" 声明,只要此代码库依赖于 "@foo"(例如 "@foo//some:target" 的依赖项),它就应该在全局声明的 "@bar" ("@bar//some:target") 内解析该依赖项。

new_local_repository

查看规则来源
new_local_repository(name, build_file, build_file_content, path, repo_mapping, workspace_file, workspace_file_content)

允许将本地目录转换为 Bazel 代码库。这意味着,当前代码库可以在文件系统上的任意位置定义和使用目标。

此规则会创建一个 Bazel 代码库,方法是创建一个 WORKSPACE 文件和子目录(其中包含指向 BUILD 文件和路径的符号链接)。构建文件应创建相对于 path 的目标。对于已包含 WORKSPACE 文件和 BUILD 文件的目录,可以使用 local_repository 规则。

示例

假设当前代码库是一个聊天客户端,其根目录位于 ~/chat-app 中。该目录想要使用在不同目录中定义的 SSL 库:~/ssl

用户可以通过为 SSL 库 (~/chat-app/BUILD.my-ssl) 创建一个包含以下内容的 build 文件来添加依赖项:

java_library(
    name = "openssl",
    srcs = glob(['*.java'])
    visibility = ["//visibility:public"],
)

然后,他们可以将以下行添加到 ~/chat-app/WORKSPACE

new_local_repository(
    name = "my-ssl",
    path = "/home/user/ssl",
    build_file = "BUILD.my-ssl",
)

这将创建一个 @my-ssl 代码库,该代码库会链接至 /home/user/ssl。 目标可以通过将 @my-ssl//:openssl 添加到目标的依赖项来依赖于此库。

您还可以使用 new_local_repository 来包含单个文件,而不仅仅是目录。例如,假设您在 /home/username/Downloads/piano.jar 中有一个 jar 文件。您可以将以下内容添加到 WORKSPACE 文件中,从而仅将该文件添加到您的 build 中:

new_local_repository(
    name = "piano",
    path = "/home/username/Downloads/piano.jar",
    build_file = "BUILD.piano",
)

并创建以下 BUILD.piano 文件:

java_import(
    name = "play-music",
    jars = ["piano.jar"],
    visibility = ["//visibility:public"],
)
然后,目标可以依赖 @piano//:play-music 来使用 piano.jar。

参数

特性
name

Name; required

此目标的唯一名称。

build_file

String; optional

用作此目录的 BUILD 文件的文件。

必须指定 build_file 或 build_file_content。

此属性是相对于主工作区的标签。该文件不需要命名为 BUILD,但可以将其命名为。(类似 BUILD.new-repo-name 可能非常适合将其与代码库的实际 BUILD 文件区分开。)

build_file_content

String; optional

此代码库的 BUILD 文件的内容。

必须指定 build_file 或 build_file_content。

path

String; required

本地文件系统上的路径。

这可以是绝对代码库,也可以是相对于主代码库的 WORKSPACE 文件。

repo_mapping

Dictionary: String -> String; optional

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

例如,条目 "@foo": "@bar" 声明,只要此代码库依赖于 "@foo"(例如 "@foo//some:target" 的依赖项),它就应该在全局声明的 "@bar" ("@bar//some:target") 内解析该依赖项。

workspace_file

String; optional

用作此代码库的 WORKSPACE 文件。

可以指定 workspace_file 或 workspace_file_content,但不能同时指定这两者。

此属性是相对于主工作区的标签。该文件不需要命名为 WORKSPACE,但可以这样命名。(像 WORKSPACE.new-repo-name 这样的内容可能有助于将其与代码库的实际 WORKSPACE 文件区分开。)

workspace_file_content

String; optional

此代码库的 WORKSPACE 文件的内容。

可以指定 workspace_file 或 workspace_file_content,但不能同时指定这两者。