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

[Chen Miao]

Mauro Carvalho Chehab <mchehab+huawei@xxxxxxxxxx> 于2026年8月14日周五 05:36写道：
>
> On Thu, 13 Aug 2026 17:38:59 +0800
> Chen Miao <chenmiao.ku@xxxxxxxxx> wrote:
>
> > 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
>
> No. I meant:
>
>         $ make LLVM=1 menuconfig                # enable rust
>         $ grep CONFIG_RUST .config              # check if it was enabled
>         $ make SPHINXDIRS=rust htmldocs
>
Thanks for clarifying. I retested with CONFIG_RUST=y and then ran:

    make SPHINXDIRS=rust htmldocs

Indeed, there is an issue: the wrapper invokes `make rustdoc` without
`LLVM=1`, so the Rust documentation is not generated. I will update this
and retest in v4.

Thanks,
Chen Miao
>
> >
> > 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