本页面介绍了在 Windows 上使用 Bazel 的最佳实践。如需了解安装说明,请参阅在 Windows 上安装 Bazel。
已知问题
GitHub 上与 Windows 相关的 Bazel 问题带有“team-Windows”标签。您可以参阅此处待解决的问题。
最佳实践
避免长路径问题
有些工具(包括 MSVC 编译器)在 Windows 上具有路径长度上限。 为避免遇到此问题,您可以通过 --output_user_root 标志为 Bazel 指定短输出目录。
例如,将以下行添加到 bazelrc 文件中:
startup --output_user_root=C:/tmp
启用 8.3 文件名支持
Bazel 会尝试为长文件路径创建简称版本。但要执行此操作,您需要为具有长路径的文件所在的卷启用 8.3 文件名支持。您可以通过运行以下命令在所有卷中启用 8.3 名称创建:
fsutil 8dot3name set 0
启用符号链接支持
某些功能需要 Bazel 能够在 Windows 上创建文件符号链接,方法是启用开发者模式(在 Windows 10 版本 1703 或更高版本中)或以管理员身份运行 Bazel。这将启用以下功能:
为方便起见,请将以下代码行添加到 bazelrc 文件中:
startup --windows_enable_symlinks
build --enable_runfiles
注意:在 Windows 上创建符号链接是一项成本高昂的操作。--enable_runfiles
标志可能会创建大量文件符号链接。请仅在需要时启用此功能。
运行 Bazel:MSYS2 shell 与命令提示符与 PowerShell
建议:在命令提示符 (cmd.exe
) 或 PowerShell 中运行 Bazel。
自 2020 年 1 月 15 日起,不要从 bash
运行 Bazel,要么是通过 MSYS2 shell、Git Bash、Cygwin 或任何其他 Bash 变体运行。虽然 Bazel 可能适用于大多数用例,但有些地方会出现问题,例如使用 MSYS2 中的 Ctrl+C 中断构建。此外,如果您选择在 MSYS2 下运行,则需要停用 MSYS2 的自动路径转换,否则 MSYS 会将与 Unix 路径(如 //foo:bar
)类似的命令行参数转换为 Windows 路径。如需了解详情,请参阅此 StackOverflow 回答。
没有 Bash 使用 Bazel (MSYS2)
在不使用 Bash 的情况下使用 bazel 构建
1.0 之前的 Bazel 版本要求 Bash 构建一些规则。
从 Bazel 1.0 开始,您可以构建任何不使用 Bash 的规则,除非:
genrule
,因为 genrule 会执行 Bash 命令sh_binary
或sh_test
规则,因为这些规则本身需要 Bash- 使用
ctx.actions.run_shell()
或ctx.resolve_command()
的 Starlark 规则
不过,genrule
通常用于复制文件或编写文本文件等简单任务。您可以在 bazel-skylib 代码库中找到合适的规则,而无需使用 genrule
(具体取决于 Bash)。在 Windows 上构建应用时,这些规则不需要 Bash。
在不使用 Bash 的情况下使用 bazel 测试
1.0 之前的 Bazel 版本要求 Bash 对任何内容执行 bazel test
操作。
从 Bazel 1.0 开始,您可以不使用 Bash 来测试任何规则,以下情况除外:
- 您使用
--run_under
- 测试规则本身需要 Bash(因为它的可执行文件是 Shell 脚本)
使用 Bazel 运行,而不使用 Bash
1.0 之前的 Bazel 版本要求 Bash 对任何内容执行 bazel run
操作。
从 Bazel 1.0 开始,您可以不使用 Bash 运行任何规则,但以下情况除外:
- 您使用
--run_under
或--script_path
- 测试规则本身需要 Bash(因为它的可执行文件是 Shell 脚本)
使用 shbinary 和 sh* 规则,以及不使用 Bash 的 ctx.actions.run_shell()
您需要通过 Bash 构建和测试 sh_*
规则,以及构建和测试使用 ctx.actions.run_shell()
和 ctx.resolve_command()
的 Starlark 规则。这不仅适用于项目中的规则,还适用于项目所依赖的任何外部代码库中的规则(包括传递规则)。
未来,您可以选择使用适用于 Linux 的 Windows 子系统 (WSL) 来构建这些规则,但目前它不是 Bazel-on-Windows 子团队的优先级。
设置环境变量
您在 Windows 命令提示符 (cmd.exe
) 中设置的环境变量仅在该命令提示会话中进行设置。如果您启动新的 cmd.exe
,则需要再次设置这些变量。如需始终在 cmd.exe
启动时设置变量,可以将其添加到 Control Panel >
System Properties > Advanced > Environment Variables...
对话框中的“用户变量”或“系统变量”。
在 Windows 上构建
使用 MSVC 构建 C++
如需使用 MSVC 构建 C++ 目标,您需要:
(可选)
BAZEL_VC
和BAZEL_VC_FULL_VERSION
环境变量。Bazel 会自动检测系统上的 Visual C++ 编译器。 如需告知 Bazel 使用特定 VC 安装,您可以设置以下环境变量:
对于 Visual Studio 2017 和 2019,请设置
BAZEL_VC
。此外,您还可以设置BAZEL_VC_FULL_VERSION
。BAZEL_VC
Visual C++ Build Tools 安装目录set BAZEL_VC=C:\Program Files (x86)\Microsoft Visual Studio\2017\BuildTools\VC
BAZEL_VC_FULL_VERSION
(可选)仅适用于 Visual Studio 2017 和 2019,即 Visual C++ 构建工具的完整版本号。如果安装了多个版本,您可以通过BAZEL_VC_FULL_VERSION
选择确切的 Visual C++ 构建工具版本,否则 Bazel 将选择最新版本。set BAZEL_VC_FULL_VERSION=14.16.27023
对于 Visual Studio 2015 或更早版本,请设置
BAZEL_VC
。(不支持BAZEL_VC_FULL_VERSION
。)BAZEL_VC
Visual C++ Build Tools 安装目录set BAZEL_VC=C:\Program Files (x86)\Microsoft Visual Studio 14.0\VC
-
Windows SDK 包含构建 Windows 应用时所需的头文件和库,包括 Bazel 本身。默认情况下,将使用安装的最新 Windows SDK。您还可以通过设置
BAZEL_WINSDK_FULL_VERSION
来指定 Windows SDK 版本。您可以使用完整的 Windows 10 SDK 编号(如 10.0.10240.0),也可以指定 8.1 以使用 Windows 8.1 SDK(只有一个版本的 Windows 8.1 SDK 可用)。请确保您已安装指定的 Windows SDK。要求:支持 VC 2017 和 2019。独立的 VC 2015 Build Tools 不支持选择 Windows SDK,您需要安装完整的 Visual Studio 2015,否则
BAZEL_WINSDK_FULL_VERSION
将被忽略。set BAZEL_WINSDK_FULL_VERSION=10.0.10240.0
如果一切都已设置完毕,您现在可以构建 C++ 目标了!
尝试从我们的某个示例项目构建目标:
bazel build //examples/cpp:hello-world
bazel-bin\examples\cpp\hello-world.exe
默认情况下,构建的二进制文件以 x64 架构为目标。如需指定其他目标架构,请为目标框架设置 --cpu
build 选项:
* x64(默认):--cpu=x64_windows
或无选项
* x86:--cpu=x64_x86_windows
* ARM:--cpu=x64_arm_windows
* ARM64:--cpu=arm64_windows
例如,如需为 ARM 架构构建目标,请运行以下命令:
bazel build //examples/cpp:hello-world --cpu=x64_arm_windows
如需构建和使用动态链接库(DLL 文件),请参阅此示例。
命令行长度限制:为了防止出现 Windows 命令行长度限制问题,请通过 --features=compiler_param_file
启用编译器参数文件功能。
使用 Clang 构建 C++
从 0.29.0 开始,Bazel 支持使用 LLVM 的 MSVC 兼容编译器驱动程序 (clang-cl.exe
) 进行构建。
要求:要使用 Clang 进行构建,您必须同时安装 LLVM 和 Visual C++ 构建工具,因为尽管您使用 clang-cl.exe
作为编译器,但仍需要链接到 Visual C++ 库。
Bazel 可以自动检测系统中的 LLVM 安装,您也可以通过 BAZEL_LLVM
明确告知 Bazel 的 LLVM 的安装位置。
BAZEL_LLVM
LLVM 安装目录set BAZEL_LLVM=C:\Program Files\LLVM
在以下几种情况下,如需启用 Clang 工具链以构建 C++,
在 bazel 0.28 及更早版本中:Clang 不受支持。
如果没有
--incompatible_enable_cc_toolchain_resolution
:您可以通过构建标志--compiler=clang-cl
启用 Clang 工具链。使用
--incompatible_enable_cc_toolchain_resolution
:您必须向BUILD file
添加平台目标(例如顶级BUILD
文件):platform( name = "x64_windows-clang-cl", constraint_values = [ "@platforms//cpu:x86_64", "@platforms//os:windows", "@bazel_tools//tools/cpp:clang-cl", ], )
然后,您可以通过以下两种方法之一启用 Clang 工具链:
- 指定以下 build 标志:
--extra_toolchains=@local_config_cc//:cc-toolchain-x64_windows-clang-cl --extra_execution_platforms=//:x64_windows-clang-cl
- 在
WORKSPACE
文件中注册平台和工具链:
register_execution_platforms( ":x64_windows-clang-cl" ) register_toolchains( "@local_config_cc//:cc-toolchain-x64_windows-clang-cl", )
我们计划在未来的 Bazel 版本中默认启用 --incompatible_enable_cc_toolchain_Resolution 标志。因此,建议通过第二种方法启用 Clang 支持。
构建 Java
如需构建 Java 目标,您需要:
在 Windows 上,Bazel 会为 java_binary
规则构建两个输出文件:
- 一个
.jar
文件 .exe
文件,可以为 JVM 设置环境并运行二进制文件
尝试从我们的某个示例项目构建目标:
bazel build //examples/java-native/src/main/java/com/example/myproject:hello-world
bazel-bin\examples\java-native\src\main\java\com\example\myproject\hello-world.exe
构建 Python
如需构建 Python 目标,您需要:
在 Windows 上,Bazel 会为 py_binary
规则构建两个输出文件:
- 自解压 ZIP 文件
- 此可执行文件会启动 Python 解释器,并将自解压 ZIP 文件作为参数
您可以运行可执行文件(扩展名为 .exe
),也可以运行自解压 ZIP 文件作为参数的 Python。
尝试从我们的某个示例项目构建目标:
bazel build //examples/py_native:bin
bazel-bin\examples\py_native\bin.exe
python bazel-bin\examples\py_native\bin.zip
如果您希望详细了解 Bazel 如何在 Windows 上构建 Python 目标,请参阅此设计文档。