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

[Mauro Carvalho Chehab <mchehab+huawei@kernel.org>]

On Thu, 13 Aug 2026 17:38:59 +0800
Chen Miao <chenmiao.ku@gmail.com> wrote:

> Mauro Carvalho Chehab <mchehab+huawei@kernel.org> 于2026年8月13日周四 04:23写道：
> >
> > On Thu, 13 Aug 2026 02:23:21 +0800
> > Chen Miao <chenmiao.ku@gmail.com> 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@gmail.com>
> > > ---
> > >  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

No. I meant:

	$ make LLVM=1 menuconfig		# enable rust
	$ grep CONFIG_RUST .config		# check if it was enabled
	$ make 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



Thanks,
Mauro