Re: [PATCH v1 2/2] docs: sphinx-pre-install: check GNU Make version

On Sun,  9 Aug 2026 18:19:21 +0800
Chen Miao <[email protected]> wrote:

> The kernel documentation build requires GNU Make 4.0 or newer, but the
> Sphinx dependency checker only verifies that a make executable exists.
> This lets incompatible make implementations pass the check and fail
> later during the build.
> 
> Check the GNU Make version on all supported systems. If make is missing
> or too old, report it as a missing dependency. Also accept a compatible
> gmake command, which is how Homebrew provides GNU Make on macOS.
> 
> Document the requirement and the macOS gmake fallback.
> 
> Signed-off-by: Chen Miao <[email protected]>
> ---
>  Documentation/doc-guide/sphinx.rst            |  4 +-
>  .../translations/zh_CN/doc-guide/sphinx.rst   |  2 +
>  Documentation/translations/zh_CN/how-to.rst   |  3 +-
>  tools/docs/sphinx-pre-install                 | 52 ++++++++++++++++++-
>  4 files changed, 58 insertions(+), 3 deletions(-)
> 
> 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)

I would invert the check: test first for "gmake", and then for "make".

Lots of Linux distros have an alias for gmake, like on Fedora:

	lrwxrwxrwx 1 root root        4 Apr 24 21:33 /usr/bin/gmake -> make
	-rwxr-xr-x 1 root root   287384 Apr 24 21:33 /usr/bin/make

Yet, I would do it on a different way:

	make = self.which("gmake")
	if not make:
		make = self.which("make")

	version = self.get_make_version(make)

This should simplify the code a little bit.

> +
> +        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

With that, you probably can remove most of the above.

Btw, you likely need to teach tools/docs/sphinx-build-wrapper
to also consider gmake binary, as it can run make internally
to generate info and Rust docs.

Thanks,
Mauro