Re: [PATCH v3 4/6] docs: sphinx-build-wrapper: prefer gmake

On Thu, 13 Aug 2026 02:23:21 +0800
Chen Miao <[email protected]> wrote:

> Homebrew installs GNU Make as gmake on macOS, but the Sphinx build
> wrapper invokes make directly when generating Info and Rust
> documentation. This can make the dependency check succeed while those
> documentation targets still use an incompatible make implementation.
> 
> Honor MAKE when it names a compatible GNU Make. Otherwise check gmake and
> then make, selecting the first GNU Make 4.0 or newer. Use the common kdoc
> detector to keep this selection consistent with sphinx-pre-install.
> 
> Signed-off-by: Chen Miao <[email protected]>
> ---
>  tools/docs/sphinx-build-wrapper | 23 ++++++++++++++++-------
>  1 file changed, 16 insertions(+), 7 deletions(-)
> 
> diff --git a/tools/docs/sphinx-build-wrapper b/tools/docs/sphinx-build-wrapper
> index 1bb962202..15c7e0938 100755
> --- a/tools/docs/sphinx-build-wrapper
> +++ b/tools/docs/sphinx-build-wrapper
> @@ -63,6 +63,7 @@ SRC_DIR = os.path.dirname(os.path.realpath(__file__))
>  sys.path.insert(0, os.path.join(SRC_DIR, LIB_DIR))
>  
>  from kdoc.python_version import PythonVersion
> +from kdoc.gmake_detect import find_gmake
>  from kdoc.latex_fonts import LatexFontChecker
>  from jobserver import JobserverExec         # pylint: disable=C0413,C0411,E0401
>  
> @@ -97,6 +98,14 @@ class SphinxBuilder:
>      with the Kernel.
>      """
>  
> +    def get_make(self):
> +        """Select the first GNU Make 4.0 or newer in preference order."""
> +        make = find_gmake(self.env.get("MAKE"))
> +        if make:
> +            return make
> +
> +        sys.exit("GNU Make 4.0 or newer is required")
> +
>      def get_path(self, path, use_cwd=False, abs_path=False):
>          """
>          Ancillary routine to handle patches the right way, as shell does.
> @@ -569,9 +578,10 @@ class SphinxBuilder:
>          texinfo directory.
>          """
>  
> +        make = self.get_make()
>          for output_dir in output_dirs:
>              try:
> -                subprocess.run(["make", "info"], cwd=output_dir, check=True)
> +                subprocess.run([make, "info"], cwd=output_dir, check=True)
>              except subprocess.CalledProcessError as e:
>                  sys.exit(f"Error generating info docs: {e}")
>  
> @@ -787,12 +797,11 @@ class SphinxBuilder:
>  
>          if rustdoc and target in ["htmldocs", "epubdocs"]:
>              print("Building rust docs")
> -            if "MAKE" in self.env:
> -                cmd = [self.env["MAKE"]]
> -            else:
> -                cmd = ["make", "LLVM=1"]
> -
> -            cmd += [ "rustdoc"]
> +            make = self.get_make()
> +            cmd = [make]
> +            if make != self.env.get("MAKE"):
> +                cmd.append("LLVM=1")

Did you test bulding documentation with CONFIG_RUST=y?

AFAIKT, building rust docs only work with LLVM, as GCC doesn't build
Rust code yet(*). When the time comes and gcc starts supporting it,
the code would likely need to check for gcc version as well.

(*) There is an experimental Rust support on gcc under development.
    No idea about its current status. According with:

	https://docs.kernel.org/rust/quick-start.html

    "GCC also works for some configurations, but it is 
     very experimental".

Thanks,
Mauro