diff --git a/Documentation/doc-guide/sphinx.rst b/Documentation/doc-guide/sphinx.rst
index 62aca56b8..d9b9e025f 100644
--- a/Documentation/doc-guide/sphinx.rst
+++ b/Documentation/doc-guide/sphinx.rst
@@ -136,7 +136,9 @@ commands are printed without ``sudo``. The PDF dependencies are provided by
the ``mactex`` cask; use ``--no-pdf`` when only building HTML documentation.
The default virtualenv mode is recommended on macOS because PyYAML is
installed from ``Documentation/sphinx/requirements.txt`` rather than from a
-Homebrew formula.
+Homebrew formula. The script also checks for GNU Make 4.0 or newer; when
+Homebrew provides it as ``gmake``, use ``gmake htmldocs`` instead of
+``make htmldocs``.
Installing Sphinx Minimal Version
---------------------------------
diff --git a/Documentation/translations/zh_CN/doc-guide/sphinx.rst b/Documentation/translations/zh_CN/doc-guide/sphinx.rst
index 154142318..93f27d35a 100644
--- a/Documentation/translations/zh_CN/doc-guide/sphinx.rst
+++ b/Documentation/translations/zh_CN/doc-guide/sphinx.rst
@@ -114,6 +114,8 @@ PDF和LaTeX构建
``sudo``。PDF 依赖通过 ``mactex`` cask 提供;如果只构建 HTML 文档,请使用
``--no-pdf``。macOS 用户建议使用默认的 Python 虚拟环境,因为 PyYAML 会从
``Documentation/sphinx/requirements.txt`` 安装,而不是通过 Homebrew 安装。
+脚本还会检查 GNU Make 4.0 或更高版本;如果 Homebrew 将其安装为 ``gmake``,
+请使用 ``gmake htmldocs``,而不是 ``make htmldocs``。
Sphinx构建
==========
diff --git a/Documentation/translations/zh_CN/how-to.rst b/Documentation/translations/zh_CN/how-to.rst
index e8c91d81a..84f277124 100644
--- a/Documentation/translations/zh_CN/how-to.rst
+++ b/Documentation/translations/zh_CN/how-to.rst
@@ -106,7 +106,8 @@ Linux 发行版和简单地使用 Linux 命令行,那么可以迅速开始了
sudo。PDF 构建所需的 MacTeX 通过 Homebrew cask 安装;如果只构建 HTML 文档,
可以执行 ``./tools/docs/sphinx-pre-install --no-pdf``。macOS 用户建议使用默认
的 Python 虚拟环境,因为 PyYAML 会从 ``Documentation/sphinx/requirements.txt``
-安装,而不是通过 Homebrew 安装。
+安装,而不是通过 Homebrew 安装。脚本还会检查 GNU Make 4.0 或更高版本;如果
+Homebrew 将其安装为 ``gmake``,请使用 ``gmake htmldocs``,而不是 ``make htmldocs``。
如果您处于一个多用户环境中,为了避免对其他人造成影响,建议您配置单用户
sphinx 虚拟环境,即只需要执行::
diff --git a/tools/docs/sphinx-pre-install b/tools/docs/sphinx-pre-install
index 51a296cc7..079655078 100755
--- a/tools/docs/sphinx-pre-install
+++ b/tools/docs/sphinx-pre-install
@@ -40,6 +40,7 @@ from kdoc.python_version import PythonVersion
RECOMMENDED_VERSION = PythonVersion("3.4.3").version
MIN_PYTHON_VERSION = PythonVersion("3.7").version
+MIN_MAKE_VERSION = PythonVersion("4.0").version
class DepManager:@@ -308,6 +309,55 @@ class MissingCheckers(AncillaryMethods):
return None
+ def get_make_version(self, cmd):
+ """Get the GNU Make version, or None if cmd is not GNU Make."""
+ if not cmd:
+ return None
+
+ try:
+ result = self.run(
+ [cmd, "--version"],
+ capture_output=True,
+ text=True,
+ check=True,
+ )
+ except (subprocess.CalledProcessError, FileNotFoundError):
+ return None
+
+ match = re.search(
+ r"^GNU Make\s+([0-9]+(?:\.[0-9]+)*)", result.stdout, re.MULTILINE
+ )
+ if not match:
+ return None
+
+ return PythonVersion.parse_version(match.group(1))
+
+ def check_make(self):
+ """Check for GNU Make 4.0 or newer."""
+ make = self.which("make")
+ version = self.get_make_version(make)
+
+ if version and version >= MIN_MAKE_VERSION:
+ return
+
+ # macOS commonly has an incompatible /usr/bin/make, while Homebrew
+ # installs GNU Make as gmake. Also accept gmake on other systems when
+ # it is the only compatible command available.
+ gmake = self.which("gmake")
+ gmake_version = self.get_make_version(gmake)
+ if gmake_version and gmake_version >= MIN_MAKE_VERSION:
+ make_name = os.path.basename(make) if make else "make"
+ gmake_name = os.path.basename(gmake)
+ make_ver = PythonVersion.ver_str(version) if version else "unknown"
+ gmake_ver = PythonVersion.ver_str(gmake_version)
+ print(
+ f"Note: {make_name} ({make_ver}) does not meet the GNU Make "
+ f"requirement; use {gmake_name} ({gmake_ver}) instead."
+ )
+ return
+
+ self.deps.add_package("make", DepManager.SYSTEM_MANDATORY)
+
def check_perl_module(self, prog, dtype):
"""
Does perl have a dependency? Is it available?@@ -1535,7 +1585,7 @@ class SphinxDependencyChecker(MissingCheckers):
# Check for needed programs/tools
self.check_perl_module("Pod::Usage", DepManager.SYSTEM_MANDATORY)
- self.check_program("make", DepManager.SYSTEM_MANDATORY)
+ self.check_make()
self.check_program("which", DepManager.SYSTEM_MANDATORY)
self.check_program("dot", DepManager.SYSTEM_OPTIONAL)--
2.50.1 (Apple Git-155)