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

Mauro Carvalho Chehab <[email protected]> 于2026年8月10日周一 01:18写道：
>
> 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.
>
Yes, I overlooked that. I'll fix it in the next revision.
>
> > +
> > +        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
>
I'll add a separate patch in the next series to handle
tools/docs/sphinx-build-wrapper.

Thanks,
Chen Miao