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

[Chen Miao]

Mauro Carvalho Chehab <mchehab+huawei@xxxxxxxxxx> 于2026年8月13日周四 04:23写道：
>
> On Thu, 13 Aug 2026 02:23:21 +0800
> Chen Miao <chenmiao.ku@xxxxxxxxx> 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 <chenmiao.ku@xxxxxxxxx>
> > ---
> >  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
>
Yes, I tested it on macOS with CONFIG_RUST=y using:

    make LLVM=1 SPHINXDIRS=rust htmldocs

The Rust documentation path was selected and the wrapper invoked rustdoc with
the LLVM build configuration.

The initial build exposed a few macOS host-build portability issues unrelated
to this series, including the lack of ELF headers required by host tools and
GNU sed-specific uses in Rust-related build rules. After fixing those issues
locally, the rustdoc build and the Sphinx HTML documentation build completed
successfully.

Those fixes are outside the scope of this series. If macOS host-build support
is useful, I can send them as a separate patch series.

Thanks,
Chen Miao