makefile - Sphinx 的默认 Makefile

Question

我试图理解由sphinx-quickstart自动生成的Makefile。这是:

SPHINXOPTS    =
SPHINXBUILD   = sphinx-build
SPHINXPROJ    = myproj
SOURCEDIR     = source
BUILDDIR      = build

.PHONY: help Makefile

%: Makefile
    @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

令我困惑的是:

.PHONY: help Makefile
%: Makefile

我想我明白了:

1. % 目标表示捕获任何内容(通配符)。例如，如果我输入 make html，% 将捕获 html。
2. .PHONY Makefile 表示 make 不应在其目录中查找名为 Makefile 的文件，因此不应检查文件的修改时间来确定是否运行规则。

我不明白:

为什么Makefile被列为目标%的先决条件。我的解释是:

% 捕获的目标规则应在 Makefile 更改时运行。

但这在上下文中没有任何意义。我期望的是:

当项目文档的源文件或 API 源文件发生更改时，应运行 % 捕获的目标规则。

目录结构

.
├── build
├── Makefile
├── source
└── utils

Answer 1

.PHONY: foo 的作用是 foo 永远不会被视为最新的。 (但请参阅 https://www.gnu.org/software/make/manual/html_node/Phony-Targets.html 以获取更详细的说明:主要用途是非文件名的目标)

如果您有 bar: foo，则 bar 目标的规则将始终在 make bar 上执行，因为目标依赖于 foo 但 foo 被认为永远不是最新的。这也可以通过将 bar 目标声明为 PHONY 本身来实现。

catch-all % 目标的问题在于 Makefile 所在的库包含与 Sphinx 构建器同名的库或文件。例如，假设 Makefile 所在的库中有一个 html 或 man:那么 make html 将不会执行任何操作，如果 % 没有依赖项，因为 html 是一个没有依赖项的文件或库，因此永远不会更新。

因此，% 被设置为依赖于 Makefile 伪目标，并且 Makefile 本身声明了 PHONY，因此它被认为永远不是最新的。(*) 即使目录包含文件 html 然后 make html 将被执行(并且修改构建目录中的 html 库；Makefile 库中的 html 将不会被执行已修改)。

(*) 编辑:我忘记了确切的细节:Makefile 始终被视为目标，请参阅 a surprising (?) behaviour of GNU Make when using ``%`` as target 。由于此处解释的原因， % 被设置为依赖于 Makefile，并且 Makefile 被声明为 PHONY 实际上是为了避免 make 提示循环依赖...

这个想法是 Makefile 不应该包含所有可能的构建器的硬编码列表:否则它们可能被单独声明为 PHONY 目标，但是 Sphinx 维护者将不得不担心使 Makefile 模板保持最新添加新构建器时。当项目保留相同的 Makefile 但新的 Sphinx 版本添加了新的构建器时，它也会导致问题。

如果将新构建器添加到 Sphinx，则不必修改 sphinx-quickstart 现在创建的 Makefile。当然，可以肯定 Makefile 永远不会成为构建器的名称......