Sublime Text 构建系统 - 学习整理

Sublime Text 提供构建系统（Build Systems），构建系统可以调用外部程序来处理文件。也就是说，它可以调用一些脚本，或是编译器、解释器等。因此，构建系统的一个的常用示例就是编译。在本文，我们将重点放在构建系统本身上，构建系统的一些使用示例将在其他的文章中详细介绍。

注意，本文章默认在 Windows 系统下使用 Sublime Text，在 Mac 和 Linux 下的情况也类似，因此本文不加讨论。当前的 Sublime Text 版本为 Sublime Text 4（及以上）。

什么是构建系统

我们在广义上使用“构建”这个词，它不是指编译。一个构建系统不一定就要生成一个已编译的可执行文件——它可以简单地格式化代码，运行一个解释器，等等。实际上，构建系统所做的主要就是调用一个外部程序。

构建系统是一个 JSON 文件，扩展名为 .sublime-build。可以通过 Tools | Build System | New Build System... 来创建一个新的构建系统。自定义的 .sublime-build 文件需要放在用户目录的 AppData\Roaming\Sublime Text\Packages 或其子目录下。

简单的构建系统只需要一个 .sublime-build 文件。

更高级的构建系统可能由以下三部分组成：

• 一个 .sublime-build 文件（JSON 格式的配置数据）；
• 可选的，一个自定义的驱动构建过程的 Sublime Text 命令（Python 代码）；
• 可选的，外部可执行文件（脚本或二进制文件）。

本文只介绍 .sublime-build 文件的内容，不涉及额外编写 Python 代码与外部可执行文件。

构建系统的使用

运行构建系统

构建系统可以通过以下方法之一运行：

• 通过快捷键 Ctrl+B；
• 通过快捷键 F7；
• 通过菜单 Tools | Build。

选择构建系统

默认情况下，Sublime Text 使用自动选择构建系统。当用户调用构建系统时，将使用当前文件的语法和文件名来选择适当的构建系统。如果有多个构建系统与当前文件类型匹配，则会提示用户选择他们希望使用的构建系统。一旦选择了构建系统，Sublime Text 会记住它，直到用户改变他们的选择。

要改变构建系统，可使用快捷键 Ctrl+Shift+B 或菜单 Tools | Build With。

结果导航

当构建系统向结果视图（下方的输出窗口）输出文本时，可以捕获结果数据以启用结果导航。结果也通常意味着报错信息。结果导航通常用于跳转到错误的位置。导航可以通过以下方式进行：

• 下一个结果：快捷键 F4 或菜单 Tools | Build Results | Next Result；
• 下一个结果：快捷键 Shift+F4 或菜单 Tools | Build Results | Previous Result。

取消构建

一个正在进行的构建可以i通过快捷键 Ctrl+Break 或菜单 Tools | Cancel Build 来取消。

自定义构建

我们可以在 Sublime Text 安装目录的 Packages 文件夹（不是在用户目录下的 Packages 文件夹）下看到很多 .sublime-package 文件，这些是 Sublime Text 的包文件，其中每个包可视为 Zip 压缩包。我们将其中一个复制出来重命名为 .zip 后缀之后，可以看到里面有很多文件，其中就大概率有 .sublime-build 这个文件。一般而言，包名就是某个语法的名字，而其中的 .sublime-build 一般就是针对这个语法而设计的构建系统。

例如，我们把 Python.sublime-package 这个文件复制出来，重命名为 Python.zip。打开压缩包，我们可以看到其中的 .sublime-build 文件，文件内容如下：

Python.sublime-package

{
	"cmd": ["python3", "-u", "$file"],
	"file_regex": "^[ ]*File \"(...*?)\", line ([0-9]*)",
	"selector": "source.python",

	"env": {"PYTHONIOENCODING": "utf-8"},

	"windows": {
		"cmd": ["py", "-u", "$file"],
	},

	"variants":
	[
		{
			"name": "Syntax Check",
			"cmd": ["python3", "-m", "py_compile", "$file"],

			"windows": {
				"cmd": ["py", "-m", "py_compile", "$file"],
			}
		}
	]
}

如果我们暂时忽略 Syntax Check 的变体，该构建系统能实现的就是：当运行构建时，调用 Python 解释器来执行当前的 Python 文件。输出结果在编辑器内部下方的输出窗口里。

然而，如果程序需要读取键盘输入，而输出窗口上是无法将输入送给程序的，这就导致不能输入。因此，我们可以看到 Sublime Text 自身带有的 .sublime-build 文件未必就能满足我们的需求。我们很可能都需要自定义构建系统。

接下来，我们就来解释构建系统的运行过程以及 .sublime-build 文件中的每个选项都是什么意思。

构建系统的运行过程

当在 Sublime Text 中运行默认的构建任务时，Sublime Text 命令（默认为 exec，但它可以被覆盖成其他的）首先会接收到 .sublime-build 文件中指定的配置数据（也就是某些选项），然后开始构建文件。通常，它调用一个外部程序。

如上所说，默认情况下，构建系统使用由 Packages/Default/exec.py 实现的 exec 命令。该命令只是将配置数据转发到外部程序并异步运行。使用 .sublime-build 文件中的 target 选项，可以覆盖 exec 命令，将命令指定为 target 选项的值。

选项

所有构建系统都可以在 .sublime-build 文件中使用以下选项：

• "selector" （string）
  一个选择器，用于匹配应该启用此构建系统的语法。当 Tools | Build System | Automatic 设置为 true 时使用。Sublime Text 使用这个选择器为活动视图找到合适的构建系统。
• "file_patterns" （array of strings）
  表示应该启用构建系统的文件名模式。
• "keyfiles" （array of strings）
  文件名，如果存在于其中一个打开的文件夹中，将导致启用构建系统。
• "variants" （array of objects）
  从顶层构建系统继承选项的附属构建系统，是选项的字典列表。每个 "variant" 都需要指定一个 "name" 键，并且可以覆盖或向顶层构建系统添加选项。使用 "variants" 可以在同一个 .sublime-build 文件中指定多个构建系统任务。
• "cancel" （string，array of strings）
  字符串命令名或字符串选项数组。如果指定了字符串，则将使用指定的命令取消构建；如果是字符串选项数组，则 "target" 将被调用，并且这些选项将被添加进去。这只需要在使用自定义 "target" 时指定。
• "target" （string）
  调用构建系统时要运行的命令。默认为 exec。这个命令接收 .sublime-build 文件中指定的所有目标命令参数。请注意，如果你选择覆盖构建系统的默认命令，你可以向 .sublime-build 文件添加任意数量的额外选项。exec 的默认值允许使用 “exec 目标选项”（下一部分）中指定的附加选项。如果指定了 exec 以外的值，则 “exec 目标选项” 中的任何选项都不会执行任何操作。
• "windows" （object）
  在 Windows 机器上执行构建系统时使用的选项，接受一个包含选项的字典。用于操作系统有选择地应用选项。特定于操作系统的值会覆盖默认值。
• "osx" （object）
  在 Mac 机器上执行构建系统时使用的选项，接受一个包含选项的字典。用于操作系统有选择地应用选项。特定于操作系统的值会覆盖默认值。
• "linux" （object）
  在 Linux 机器上执行构建系统时使用的选项，接受一个包含选项的字典。用于操作系统有选择地应用选项。特定于操作系统的值会覆盖默认值。

以上这些是所有构建系统都能理解的标准选项列表。这些选项在 Sublime Text 内部使用，target 指定的命令不接收这些选项中的任何一个。

exec 目标选项

大多数构建系统都使用默认 target（即 exec）。它提供了以下选项来控制要执行什么程序，以及如何显示结果。下面的所有选项都与 exec 命令相关，如果更改了 target，则不再依赖这些选项。

• "cmd" （array of strings）
  如果 "shell_cmd" 为空则需要。会被 "shell_cmd" 覆盖。包含要运行的可执行文件及其所需参数的数组。如果不指定绝对路径，则将在 PATH 中搜索外部程序。不支持管道和重定向等 shell 构造。可以使用变量。
• "shell_cmd" （string）
  如果 "cmd" 为空则需要。如果存在 "cmd" 则会将其覆盖。为要执行的 shell 命令。不像 "cmd" 选项，它允许管道和重定向。可以使用变量。在 Mac 和 Linux 机器上使用 bash，在 Windows 上使用 cmd.exe。
• "working_dir" （string）
  执行 "cmd" 或 "shell_cmd" 的目录。可以使用变量。也就是说在执行 "cmd" 或 "shell_cmd" 前，会先从当前目录改变到 "working_dir"，然后执行 "cmd" 或 "shell_cmd" ，之后再返回原目录。
• "file_regex" （string）
  一个 perl 风格的正则表达式，用于从结果视图中捕获最多四个错误信息字段，即：文件名、行号、列号和错误消息。使用组来捕获此信息，文件名字段和行号字段是必需的，也就是说，该正则表达式应该捕获2、3或4个组。
• "line_regex" （string）
  一个 perl 风格的正则表达式，用于从结果视图中捕获最多三个错误信息字段，即：行号、列号和错误消息。使用组来捕获此信息，行号字段是必需的，也就是说，该正则表达式应该捕获1、2或3个组。这个正则表达式只在某些结果严格包含行号，或行号和列号，或带有消息的行号和列号时才需要。当进行这样的匹配时，如果 "file_regex" 不匹配，但 "line_regex" 存在并且匹配当前行，则向后遍历缓冲区，直到找到匹配 "file_regex" 的行，并使用这两个匹配来确定要访问的文件和行。
• "encoding" （string）
  构建系统输出的编码。使用 Python 编解码器名称（见 https://docs.python.org/3.3/library/codecs.html#id3）。默认为“utf-8”。
• "env" （object）
  运行 "cmd" 或 "shell_cmd" 时要使用的环境变量值。使用此选项可以在不修改系统设置的情况下添加或修改环境变量。
• "quiet" （boolean）
  减少关于构建系统调用的输出量。
• "word\_wrap" （boolean）
  在构建系统输出面板中打开换行。
• "syntax" （string）
  用于突出显示构建系统输出面板的语法文件。

自定义目标选项

当实现一个命令作为构建系统的 target 时，该命令的关键字参数可以通过 .sublime-build 文件中的选项使用。但是，某些参数名不可行，因为它们与内置的构建系统功能冲突。以下名称将不会作为参数传递给命令（这也适用于其他情况，例如在 "cancel"，"windows"，"osx" 和 "linux" 选项中指定的选项）："cancel"、"file_patterns"、"keyfile"、"keyfiles"、"windows"、"osx"、"linux"、"save_untitled_files"、"selector"、"target"、"variants"。

变量

下面的变量将在 "cmd" ，"shell_cmd" 或 "working_dir" 选项中指定的任意字符串中展开。

如果字面量 $ 需要在这些选项中指定，那么它必须用 \ 转义。又因为 JSON 也使用反斜杠来转义，因此 $ 将需要写成 \\$。变量的 $ 后面的内容可以用 {} 来包裹。

变量	描述
$packages	文件夹的路径。
$platform	Sublime Text 运行的平台："windows"，"osx" 或 "linux"。
$file	活动视图中文件的完整路径（包括文件夹）。
$file_path	活动视图中文件所在文件夹的路径。
$file_name	活动视图中文件的文件名（无文件夹路径）。
$file_base_name	活动视图中文件的文件名（不包括扩展名）。
$file_extension	活动视图中文件的文件名的扩展名。
$folder	在侧栏中打开的第一个文件夹的完整路径。
$project	当前项目文件的完整路径。
$project_path	当前项目文件所在文件夹的路径。
$project_name	当前项目文件的文件名（无文件夹路径）。
$project_base_name	当前项目文件的文件名（不包括扩展名）。
$project_extension	当前项目文件的扩展名。

详细实例请参看下述文章：

Sublime Text 配置 C/C++ 编译环境与中文乱码的解决

Sublime Text 配置 Python 环境

参考文档：

1. https://www.sublimetext.com/docs/build_systems.html
2. https://docs.sublimetext.io/guide/usage/build-systems.html
3. https://sublime-text-unofficial-documentation.readthedocs.io/en/latest/reference/build_systems.html