在 Windows 上编写规则

本页面重点介绍如何编写与 Windows 兼容的规则、编写可移植规则的常见问题以及一些解决方案。

路径

问题:

  • 长度限制:路径长度上限为 259 个字符。

    虽然 Windows 还支持更长的路径(最多 32767 个字符),但许多程序在构建时会使用此上限。

    请注意您在 Action 中运行的程序。

  • 工作目录:也不得超过 259 个字符。

    进程无法 cd 到长度超过 259 个字符的目录。

  • 区分大小写:Windows 路径不区分大小写,Unix 路径则区分大小写。

    为操作创建命令行时,请注意这一点。

  • 路径分隔符:是反斜杠 (\`), not forward slash (/`)。

    Bazel 会以 Unix 样式存储带有 / 分隔符的路径。虽然某些 Windows 程序支持 Unix 样式的路径,但其他程序不支持。cmd.exe 中的某些内置命令支持这些命令,有些则不支持。

    为操作创建命令行和环境变量时,最好始终使用 \` separators on Windows: replace/with

  • 绝对路径:不能以正斜线 (/) 开头。

    Windows 上的绝对路径以盘符开头,例如 C:\foo\bar.txt。没有单个文件系统根目录。

    如果您的规则检查路径是否为绝对路径,请注意这一点。应避免使用绝对路径,因为它们通常是不可移植的。

解决方案:

  • 确保路径简短

    避免使用较长的目录名称、深层嵌套的目录结构、较长的文件名、较长的工作区名称以及较长的目标名称。

    所有这些元素都可能会成为操作输入文件的路径组成部分,并且可能会超出路径长度限制。

  • 使用简短的输出根目录

    使用 --output_user_root=<path> 标志为 Bazel 输出指定短路径。一个好主意是创建一个仅用于 Bazel 输出(例如 D:\`), and adding this line to your.bazelrc` 文件)的驱动器(或虚拟盘):

    build --output_user_root=D:/
    

    build --output_user_root=C:/_bzl
    
  • 使用路口。

    大体上说[1],交叉点是目录符号链接。交叉路口易于创建,可以指向(同一台计算机上)具有长路径的目录。如果构建操作创建一个路径较短但目标很长的连接,则具有短路径限制的工具可以访问该连接目录中的文件。

    .bat 文件或 cmd.exe 中,您可以创建如下所示的联结:

    mklink /J c:\path\to\junction c:\path\to\very\long\target\path
    

    [1]:严格来说,Junction 不是符号链接,但出于构建操作的目的,您可以将 Junction 视为目录符号链接。

  • 将 actions / envvars 中路径中的 / 替换为“`”。

    为操作创建命令行或环境变量时,请将路径设置为 Windows 样式。例如:

    def as_path(p, is_windows):
        if is_windows:
            return p.replace("/", "\\")
        else:
            return p
    

环境变量

问题:

  • 区分大小写:Windows 环境变量名称不区分大小写。

    例如,在 Java 中,System.getenv("SystemRoot")System.getenv("SYSTEMROOT") 会产生相同的结果。(这同样适用于其他语言。)

  • 重复性:操作应使用尽可能少的自定义环境变量。

    环境变量是操作的缓存键的一部分。如果操作使用经常更改的环境变量或用户自定义的环境变量,则规则的缓存性会降低。

解决方案:

  • 只能使用大写的环境变量名称

    这适用于 Windows、macOS 和 Linux。

  • 尽量减少操作环境。

    使用 ctx.actions.run 时,请将环境设置为 ctx.configuration.default_shell_env。如果操作需要更多环境变量,请将它们全部放入字典中,然后将其传递给操作。例如:

    load("@bazel_skylib//lib:dicts.bzl", "dicts")
    
    def _make_env(ctx, output_file, is_windows):
        out_path = output_file.path
        if is_windows:
            out_path = out_path.replace("/", "\\")
        return dicts.add(ctx.configuration.default_shell_env, {"MY_OUTPUT": out_path})
    

Action

问题:

  • 可执行输出:每个可执行文件都必须具有可执行文件扩展名。

    最常见的扩展程序是 .exe(二进制文件)和 .bat(批处理脚本)。

    请注意,shell 脚本 (.sh) 无法在 Windows 上执行;您不能将其指定为 ctx.actions.runexecutable。文件也没有 +x 权限,因此您无法像在 Linux 上那样执行任意文件。

  • Bash 命令:出于可移植性考虑,请避免直接在操作中运行 Bash 命令。

    Bash 广泛用于类似 Unix 的系统,但通常无法在 Windows 上使用。Bazel 本身对 Bash (MSYS2) 的依赖越来越少,因此将来用户不太可能将 MSYS2 与 Bazel 一起安装。为了使规则更易于在 Windows 上使用,请避免在操作中运行 Bash 命令。

  • 行尾:Windows 使用 CRLF (\r\n),类似于 Unix 的系统使用 LF (\n)。

    在比较文本文件时,请注意这一点。注意您的 Git 设置,尤其是在签出或提交时行尾。(请参阅 Git 的 core.autocrlf 设置。)

解决方案:

  • 使用无 Bash 专用规则。

    native.genrule() 是 Bash 命令的封装容器,通常用于解决复制文件或编写文本文件等简单问题。您可以避免依赖 Bash(甚至重复创建):查看 bazel-skylib 是否有专门制定的规则来满足您的需求。在 Windows 上构建/测试时,它们都不依赖于 Bash。

    构建规则示例:

    • copy_file()源代码文档):将文件复制到其他位置,可选择使其可执行

    • write_file()源代码文档):写入一个以所需行结尾(autounixwindows)的文本文件,可以选择使其可执行(如果是脚本)

    • run_binary()源代码文档):运行具有指定输入和预期输出的二进制文件(或 *_binary 规则)作为构建操作(这是 ctx.actions.run 的构建规则封装容器)

    • native_binary()源代码文档):将原生二进制文件封装在 *_binary 规则中,您可以 bazel run 或者在 run_binary()tool 属性或 native.genrule()tools 属性中使用该规则

    测试规则示例:

    • diff_test()来源文档):用于比较两个文件内容的测试

    • native_test()源代码文档):将原生二进制文件封装在 *_test 规则中,您可以 bazel test

  • 在 Windows 上,不妨考虑使用 .bat 脚本来处理一些无关紧要的事情。

    您可以使用 .bat 脚本而不是 .sh 脚本解决琐碎的任务。

    例如,如果您需要一个不执行任何操作的脚本、输出消息或退出显示固定错误代码的脚本,那么一个简单的 .bat 文件就足够了。如果您的规则返回 DefaultInfo() 提供程序,则 executable 字段可能会引用 Windows 上的该 .bat 文件。

    由于文件扩展名在 macOS 和 Linux 上无关紧要,因此您可以随时使用 .bat 作为扩展名,即使对于 shell 脚本也是如此。

    请注意,无法执行空的 .bat 文件。如果您需要一个空脚本,请在其中输入一个空格。

  • 有原则地使用 Bash

    在 Starlark 构建和测试规则中,使用 ctx.actions.run_shell 将 Bash 脚本和 Bash 命令作为操作运行。

    在 Starlark 宏中,将 Bash 脚本和命令封装在 native.sh_binary()native.genrule() 中。Bazel 将检查 Bash 是否可用,并通过 Bash 运行脚本或命令。

    在 Starlark 代码库规则中,请尝试完全避免使用 Bash。目前,Bazel 没有提供在代码库规则中原则性地运行 Bash 命令的方法。

删除文件

问题:

  • 文件在打开时无法删除。

    默认情况下,无法删除打开的文件,尝试删除会导致“访问遭拒”错误。如果您无法删除某个文件,可能是因为正在运行的进程仍使其保持打开状态。

  • 无法删除正在运行的进程的工作目录。

    进程的工作目录有一个打开的句柄,在进程终止之前,无法删除该目录。

解决方案:

  • 在代码中,尝试快速关闭文件。

    在 Java 中使用 try-with-resources。在 Python 中,使用 with open(...) as f:。原则上,应尽快尝试关闭句柄。