fix rustdoc build detection

Hi Jon,

For whatever weird reason, at least here sometimes rust config detection is failing, causing the logic to try building the Kernel as well, after building the docs.

After some tests, I'm opting to move the rust detection to be inside the wrapper, at it sounds to me that the building system is not evaluating well CONFIG_RUST here:

	ifeq ($(CONFIG_RUST),y)
	       RUSTDOC=--rustdoc
	endif

Another alternative would be to modify the rustdoc target inside rust Makefile to make it dependent on htmldocs, but that would require more work.

Mauro Carvalho Chehab (1):
docs: makefile: move rustdoc check to the build wrapper

 Documentation/Makefile          |  6 -----
 tools/docs/sphinx-build-wrapper | 41 +++++++++++++++++++++++++--------
 2 files changed, 32 insertions(+), 15 deletions(-)

2.51.1

The makefile logic to detect if rust is enabled is not working the way it was expected. Move it to be inside the wrapper script.

---
 Documentation/Makefile          |  6 -----
 tools/docs/sphinx-build-wrapper | 41 +++++++++++++++++++++++++--------
 2 files changed, 32 insertions(+), 15 deletions(-)

index d514ab6761dc..d4c42aa89439 100644
@@ -42,12 +42,6 @@ FONTS_CONF_DENY_VF ?= $(HOME)/deny-vf
 # User-friendly check for sphinx-build
 HAVE_SPHINX := $(shell if which $(SPHINXBUILD) >/dev/null 2>&1; then echo 1; else echo 0; fi)
 
-ifneq ($(wildcard $(srctree)/.config),)
-ifeq ($(CONFIG_RUST),y)
-	RUSTDOC=--rustdoc
-endif
-endif
-
 ifeq ($(HAVE_SPHINX),0)
 
 .DEFAULT:

2.51.1

Hmm... Could the commit explain a bit why this didn't work and why now it does?

Thanks!

Cheers,
Miguel

I don't know exactly why this was not working.

I guess one of the issues is that the "rustdoc" target becomes undefined if RUST is not enabled, e.g. rust/Makefile is lacking something like:

    ifdef CONFIG_RUST
    ...
    else
    rustdoc rustdoc-core rustdoc-macros rustdoc-compiler_builtins:
            $(warning Rust is not enabled. Can't build $<)    
    endif

But this is not enough to explain the issues I'm getting.

Maybe the other issues are cache related.

In any case, here, with Fedora 43, on some cases, when I run:

make htmldocs # or make SPHINXDIRS=xxx htmldocs

it sometimes, after building the docs, it tries to run:

make LLVM=1 rustdoc

as this is not a defined target when CONFIG_RUST is not present, this causes it to build the entire code.

Thanks,
Mauro

I would feel a lot better if we knew what the real problem is before applying fixes for it. Otherwise something seems certain to come and bite us at some point.

Thanks,

jon

Em Tue, 18 Nov 2025 09:38:15 -0700
Jonathan Corbet <[email protected]> escreveu:

Me too, but the bug is very annoying ;-)

I'll try to seek for some time to better understand it, maybe next week.

Thanks,
Mauro

Em Tue, 18 Nov 2025 20:11:52 +0100
Mauro Carvalho Chehab <[email protected]> escreveu:

Btw, at least here (Fedora 43, upgraded from 42), rustdoc doesn't build for docs-next.

Perhaps the issue could be due to some weird things with Fedora 43.

That's what happens after sphinx-build-wrapper finishes handling htmldocs (after this patch), when it runs "make LLVM=1 rustdoc":

Building rust docs
DESCEND objtool
INSTALL libsubcmd_headers
CALL scripts/checksyscalls.sh
RUSTC L rust/bindings.o
RUSTC L rust/build_error.o
RUSTC L rust/uapi.o
error: mixing -Zsanitizer will cause an ABI mismatch in crate build_error
--> rust/build_error.rs:3:1

  |
3 | //! Build-time error.
  | ^
  |

= help: the -Zsanitizer flag modifies the ABI so Rust crates compiled with different values of this flag cannot be used together safely = note: unset -Zsanitizer in this crate is incompatible with -Zsanitizer=kernel-address in dependency core
= help: set -Zsanitizer=kernel-address in this crate or unset -Zsanitizer in core
= help: if you are sure this will not cause problems, you may use -Cunsafe-allow-abi-mismatch=sanitizer to silence this error

error: mixing -Zsanitizer will cause an ABI mismatch in crate build_error
--> rust/build_error.rs:3:1

  |
3 | //! Build-time error.
  | ^
  |

= help: the -Zsanitizer flag modifies the ABI so Rust crates compiled with different values of this flag cannot be used together safely = note: unset -Zsanitizer in this crate is incompatible with -Zsanitizer=kernel-address in dependency compiler_builtins = help: set -Zsanitizer=kernel-address in this crate or unset -Zsanitizer in compiler_builtins
= help: if you are sure this will not cause problems, you may use -Cunsafe-allow-abi-mismatch=sanitizer to silence this error

error: aborting due to 2 previous errors

make[4]: *** [rust/Makefile:527: rust/build_error.o] Error 1
make[4]: ** Esperando que outros processos terminem.
make[3]: *** [Makefile:1286: prepare] Error 2
Ignored errors when building rustdoc: Command '['make', 'rustdoc']' returned non-zero exit status 2.. Is RUST enabled?

Relevant Rust configs:

$ grep RUST .config
CONFIG_RUSTC_VERSION=109100
CONFIG_RUST_IS_AVAILABLE=y
CONFIG_RUSTC_LLVM_VERSION=210103
CONFIG_RUSTC_HAS_COERCE_POINTEE=y
CONFIG_RUSTC_HAS_SPAN_FILE=y
CONFIG_RUSTC_HAS_UNNECESSARY_TRANSMUTES=y
CONFIG_RUSTC_HAS_FILE_WITH_NUL=y
CONFIG_RUSTC_HAS_FILE_AS_C_STR=y
CONFIG_RUST=y
CONFIG_RUSTC_VERSION_TEXT="rustc 1.91.0 (f8297e351 2025-10-28) (Fedora 1.91.0-1.fc43)"
# CONFIG_CPUFREQ_DT_RUST is not set
CONFIG_HAVE_RUST=y
# CONFIG_RUST_FW_LOADER_ABSTRACTIONS is not set
# CONFIG_BLK_DEV_RUST_NULL is not set
# CONFIG_RUST_PHYLIB_ABSTRACTIONS is not set
CONFIG_RADIO_TRUST=y
CONFIG_RADIO_TRUST_PORT=350
CONFIG_HID_THRUSTMASTER=y
CONFIG_THRUSTMASTER_FF=y
CONFIG_TRUSTED_KEYS=y
CONFIG_HAVE_TRUSTED_KEYS=y
CONFIG_TRUSTED_KEYS_TPM=y
CONFIG_TRUSTED_KEYS_TEE=y
CONFIG_TRUSTED_KEYS_CAAM=y
CONFIG_INTEGRITY_TRUSTED_KEYRING=y
CONFIG_IMA_SECURE_AND_OR_TRUSTED_BOOT=y
# CONFIG_RUST_BITMAP_HARDENED is not set
CONFIG_SYSTEM_TRUSTED_KEYRING=y
CONFIG_SYSTEM_TRUSTED_KEYS=""
CONFIG_SECONDARY_TRUSTED_KEYRING=y
CONFIG_SECONDARY_TRUSTED_KEYRING_SIGNED_BY_BUILTIN=y
# CONFIG_SAMPLES_RUST is not set
# CONFIG_FIND_BIT_BENCHMARK_RUST is not set
# CONFIG_RUST_DEBUG_ASSERTIONS is not set
CONFIG_RUST_OVERFLOW_CHECKS=y
# CONFIG_RUST_BUILD_ASSERT_ALLOW is not set
CONFIG_RUST_KERNEL_DOCTESTS=y

Thanks,
Mauro

That one is fixed with commit 16c43a56b79e ("rust: kbuild: treat build_error and rustdoc as kernel objects") which is in -rc5.

Cheers,
Miguel

I will try to find a moment to take a look too... This happens with only the new wrapper, right? Or is it something that happened even before? If the latter, I remember testing the logic that Carlos added a long time ago, but maybe something changed in the meantime.

Cheers,
Miguel

Em Tue, 18 Nov 2025 22:40:09 +0100
Miguel Ojeda <[email protected]> escreveu:

I'm testing here against docs/docs-next, so it is based on -rc1, so, yeah this is after the cleanups. The problem could be introduced by the Makefile cleanup, but I didn't find anything obvious but I haven't time to revisit after sending the patch, as I got sidetracked with unrelated issues (*).

I'll try testing it tomorrow against linux-next.

Thanks,
Mauro

---

(*) I was preparing a new rasdaemon release, which was launched
today.

Why? No, there is no need to build any htmldocs to build the Rust documentation, so that would be wrong.

Cheers,
Miguel

Sure, Sphinx (including kernel-doc) build and rust doca build are independent. Yet, Makefile "htmldocs" target currently does both.

It could make sense to have a separate target if one want to build them both, e.g. something like:

make rustdoc - builds just rust docs
make htmldocs - builds all non-rust docs
make allhtmldocs - makes both

On other words, we could add a rule like:

rusthtmldocs: rustdoc htmldocs

and simplify the makefile and the wrapper.

PS.: I'm using "allhtmldocs" just to make clear about what
I meant. Not sure if this would be the best name for the joint html output target.

Thanks,
Mauro

My understanding (Cc'ing Carlos) is that the idea was that htmldocs built the Rust docs if possible.

I don't mind if that is changed etc., but I think it is important to keep the rustdoc target simple and focused: it is a "basic" operation (which is also used to lint docs too), and way faster than building the HTML docs, and it doesn't depend on them.

Apologies if I put it perhaps a bit too tersely in my previous message -- everyone contributing to Rust code is supposed to rely on that target to test their commits, and needing the whole Sphinx setup would make the target way worse in practice.

Now, in the future, if we start relying on generating references for the Rust docs from the C side and things like that (which is my plan, but it is long term: first item in
https://github.com/Rust-for-Linux/linux/issues/350), we may need to rethink things a bit (i.e. we may need to run a subset of the kernel normal docs to build the Rust docs), but even then ideally we should only introduce the minimal dependency needed.

I hope that clarifies -- thanks!

Cheers,
Miguel

It is also the target I use to build rust.docs.kernel.org, for instance.

Cheers,
Miguel

Em Mon, 17 Nov 2025 12:22:48 +0100
Miguel Ojeda <[email protected]> escreveu:

Heh, the same applies to the current usage of htmldocs - specially when SPHINXDIRS is used, e.g. one doing, for instance:

make SPHINXDOCS=driver-api/<subsystem>

may not be interested on building rust docs, which, on such case, may be a lot slower than a partial build. Also, I don't think that rustdoc currently does something similar to SPHINXDOCS.

So, at least for me, it does make sense to have separate targets for Sphinx, Rust and both (*).

(*) now, how such targets would be named is a completely different
question.

Agreed.

IMO, this is a separate discussion, as you may need a different toolset.

The way I see, for issue #350 IMO the best would be to create a Sphinx extension similar to:

Documentation/sphinx/parser_yaml.py

E.g. you would create a parser_rust.py module there, which would generate ReST output from the rust code(*). Besides allowing cross references between Sphinx, C and Rust, this would also allow generating epub and pdf output.

(*) In practice, teaching rustdoc how to produce ReST output.
Alternatively, rustdoc could generate a markdown output and use a sphinx markdown extension at parser_rust.py, to convert from MD to ReST like this extension:

https://www.sphinx-doc.org/en/master/usage/markdown.html

Besides allowing cross references between Sphinx, C and Rust, a Sphinx extension would also allow generating epub and pdf output, removing all extra Makefile (or wrapper) code related to rustdoc.

-

Another alternative would be to use intersphinx, but I guess making it working would be a lot more complex - as we don't even support it yet on our current Sphinx output.

Thanks,
Mauro

If you mean building the Rust docs introduces extra work for people building the HTML docs when that happens automatically, then yeah, definitely.

Perhaps it could be skipped depending on what folders are requested.

To clarify, the idea of the "external references map file" in that issue isn't to stop using rustdoc, but rather to allow rustdoc to have (at least) the references to C items (e.g. a link to the rendered printk docs at least to the source code where it is defined). In other words, it is about allowing developrers to just write something like [printk()] and the system would figure out how to link to the right docs automatically.

We don't plan to stop using rustdoc -- its output is specialized for Rust which makes it quite nice.

rustdoc can export JSON and that should be possible to use easily from a Sphinx plugin without having to parse Rust from scratch, to at least get some degree of Sphinx support. That would be nice for the other outputs support like PDF as you mention, yeah, as well as having independent-to-the-config docs. We discussed it a few times, but it has never been a high priority, especially since rustdoc does its job quite well.

Cheers,
Miguel

Em Tue, 18 Nov 2025 23:02:35 +0100
Miguel Ojeda <[email protected]> escreveu:

Yeah, that sounds a good approach: teach rustdoc target to handle SPHINXDOCS. If it is empty (or just ".") handle the same way as today. Otherwise, do a partial doc build or skip when it doesn't make sense.

I'm not talking about stop using rustdoc. I'm talking about using it to output on a format that Sphinx can understand, and let Sphinx do the final output, solving cross-references.

There is a JSON Sphinx plugin (although I never used - no idea if it would do what it is needed):
https://sphinx-jsonschema.readthedocs.io/en/latest/

If this won't work, I guess it wouldn't be hard to use parser_yaml.py as an example to write a new plugin to handle rustdoc JSON output.

Thanks,
Mauro

By stop using rustdoc I meant its "normal" (HTML) output, i.e. the webpage with all its features and so on.

The JSON support is unstable so far:

    https://github.com/rust-lang/rust/issues/76578

And even then, I imagine it will always still require a kernel config, so that isn't an advantage either.

Thus trying to mimic what rustdoc does is probably going to be a lot of work to maintain, to likely get a worse result than what rustdoc already does.

Something that would work without a config could be way more interesting for us to integrate into Sphinx.

Thanks!

Cheers,
Miguel

Em Mon, 24 Nov 2025 02:51:40 +0100
Miguel Ojeda <[email protected]> escreveu:

I see.

From the issue timestamps, it seems that it doesn't have a high priority.

This doesn't seem to be an issue itself, as a new kernel config is easy to add.

Perhaps one solution would be to write a new output plugin to make rustdoc produce a better output format that could be easily mapped by a Sphinx plugin (like producing an output on an enriched text format like Markdown or ReST).

I can't evaluate how easy/hard would be to do that, as I'm not familiar with Rust toolset.

At Sphinx side, it won't be hard to pick references from rustdoc.

At kernel_include extension:

https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/Documentation/sphinx/kernel_include.py

I added a logic there to detect unsolved cross-references.

Currently, it just warns about unsolved references, but it won't be hard to modify a similar logic to solve it, pointing to a rustdoc reference (if those are stable enough).

Doing the reverse can be trickier, though: internally, Sphinx maps them via a C domain. The output plugin (html, pdf, ...) is what converts such reference into an html (or pdf) tag. Such mapping is version dependent.

There was a major rewrite at eh C domain on Sphinx 3.0 which changed such mapping, but other versions may have changed it as well.

Also, there is an open issue that will likely change it once fixed:

	https://github.com/sphinx-doc/sphinx/issues/7819
	https://github.com/sphinx-doc/sphinx/issues/8241

(last one closed as duplicate of #7819)

So, creating cross-references from rustdoc to Sphinx could be tricky and hard to maintain, as it may require some checks at rust/rustdoc side to verify Sphinx version.

Thanks,
Mauro

Em Mon, 24 Nov 2025 09:18:11 +0100
Mauro Carvalho Chehab <[email protected]> escreveu:

In time:

by "rust/rustdoc side" I mean the cross-reference solver that would run inside the Makefile target that will be called after building Sphinx docs.

It will likely be external tools inside the Kernel tree to identify Sphinx and docutils versions, rust/rustodoc version, and do whatever other check would be needed to detect the tags format and modify the produced html output for the hyperlinks to work.

Thanks,
Mauro

Hey there,

Thanks! I'll also take a look at this, although I fear it'll be complicated without a way to reproduce what Mauro experienced.

Thanks,

Carlos

Em Tue, 18 Nov 2025 17:23:48 -0600
Carlos Bilbao <[email protected]> escreveu:

I was able to get the scenario on linux-next. It is a little bit tricky to reproduce.

1) I did a build with:

	$ make distclean
	$ make SPHINXDIRS=peci htmldocs

rustdoc was not called.

2) copied a .config that has CONFIG_RUST there:

	$ cp config-rust .config
	$ make SPHINXDIRS=peci htmldocs

rustdoc was not called.

3) manually called rustdoc:

	$ make rustdoc

rustdoc was built.

4) now, I re-ran htmldocs:

	$ make SPHINXDIRS=peci htmldocs

rustdoc was built.

5) I replaced .config with a config without rust:

	$ make allyesconfig
	$ make SPHINXDIRS=peci htmldocs
	...
	Using alabaster theme
	Using Python kernel-doc
	  SYNC    include/config/auto.conf
	  HOSTCC  scripts/basic/fixdep
	  DESCEND objtool
	  INSTALL libsubcmd_headers
	  CC      scripts/mod/empty.o
	  CC      scripts/mod/devicetable-offsets.s
	  MKELF   scripts/mod/elfconfig.h
	  HOSTCC  scripts/mod/modpost.o
	  HOSTCC  scripts/mod/sumversion.o
	  HOSTCC  scripts/mod/symsearch.o
	  HOSTCC  scripts/mod/file2alias.o
	  HOSTLD  scripts/mod/modpost
	  CC      kernel/bounds.s
	  CC      arch/x86/kernel/asm-offsets.s
	  UPD     include/generated/asm-offsets.h
	  CC      kernel/sched/rq-offsets.s
	  CALL    scripts/checksyscalls.sh
	make[4]: *** No rule to make target 'rustdoc'.  Stop.
	make[3]: *** [Makefile:1855: rustdoc] Error 2
	Ignored errors when building rustdoc: Command '['make', 'rustdoc']' returned non-zero exit status 2.. Is RUST enabled?

There are other combinations that produce weird things.

If, instead of step (5), we do:

	$ echo >.config
	$ LANG=C make SPHINXDIRS=peci htmldocs

it will produce, after building htmldocs from Sphinx:

Using alabaster theme
Using Python kernel-doc
SYNC include/config/auto.conf
HOSTCC scripts/basic/fixdep
*
* Restart config...
*
*
* General setup
*
Compile also drivers which will not load (COMPILE_TEST) [N/y/?] (NEW)

---

My understanding is that the issue is caused because (by purpose) make htmldocs doesn't sync configuration. It doesn't need, as building docs doesn't really depend on any .config flag.

However, this check at the Makefile:

	ifneq ($(wildcard $(srctree)/.config),)
	ifeq ($(CONFIG_RUST),y)
        	RUSTDOC=--rustdoc
	endif
	endif

Uses a cached value of "CONFIG_RUST" from the last build, with may or may not be present anymore.

My patch solves this by not using the cached result, but, instead checking if CONFIG_RUST is enabled directly at the .config file.

Thanks,
Mauro