[PATCH] rust: kbuild: clean output before running `rustdoc`

[PATCH] rust: kbuild: clean output before running `rustdoc`

[Miguel Ojeda]

`rustdoc` can get confused when generating documentation into a folder
that contains generated files from other `rustdoc` versions.

For instance, running something like:

    rustup default 1.78.0
    make LLVM=1 rustdoc
    rustup default 1.88.0
    make LLVM=1 rustdoc

may generate errors like:

    error: couldn't generate documentation: invalid template: last line expected to start with a comment
      |
      = note: failed to create or modify "./Documentation/output/rust/rustdoc/src-files.js"

Thus just always clean the output folder before generating the
documentation -- we are anyway regenerating it every time the `rustdoc`
target gets called, at least for the time being.

Cc: stable@vger.kernel.org # Needed in 6.12.y and later (Rust is pinned in older LTSs).
Reported-by: Daniel Almeida <daniel.almeida@collabora.com>
Closes: https://rust-for-linux.zulipchat.com/#narrow/channel/288089/topic/x/near/527201113
Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
---
 rust/Makefile | 10 +++++++---
 1 file changed, 7 insertions(+), 3 deletions(-)

diff --git a/rust/Makefile b/rust/Makefile
index 115b63b7d1e3..771246bc7ae6 100644
--- a/rust/Makefile
+++ b/rust/Makefile
@@ -103,14 +103,14 @@ rustdoc: rustdoc-core rustdoc-macros rustdoc-compiler_builtins \
 rustdoc-macros: private rustdoc_host = yes
 rustdoc-macros: private rustc_target_flags = --crate-type proc-macro \
     --extern proc_macro
-rustdoc-macros: $(src)/macros/lib.rs FORCE
+rustdoc-macros: $(src)/macros/lib.rs rustdoc-clean FORCE
 	+$(call if_changed,rustdoc)
 
 # Starting with Rust 1.82.0, skipping `-Wrustdoc::unescaped_backticks` should
 # not be needed -- see https://github.com/rust-lang/rust/pull/128307.
 rustdoc-core: private skip_flags = --edition=2021 -Wrustdoc::unescaped_backticks
 rustdoc-core: private rustc_target_flags = --edition=$(core-edition) $(core-cfgs)
-rustdoc-core: $(RUST_LIB_SRC)/core/src/lib.rs FORCE
+rustdoc-core: $(RUST_LIB_SRC)/core/src/lib.rs rustdoc-clean FORCE
 	+$(call if_changed,rustdoc)
 
 rustdoc-compiler_builtins: $(src)/compiler_builtins.rs rustdoc-core FORCE
@@ -122,7 +122,8 @@ rustdoc-ffi: $(src)/ffi.rs rustdoc-core FORCE
 rustdoc-pin_init_internal: private rustdoc_host = yes
 rustdoc-pin_init_internal: private rustc_target_flags = --cfg kernel \
     --extern proc_macro --crate-type proc-macro
-rustdoc-pin_init_internal: $(src)/pin-init/internal/src/lib.rs FORCE
+rustdoc-pin_init_internal: $(src)/pin-init/internal/src/lib.rs \
+    rustdoc-clean FORCE
 	+$(call if_changed,rustdoc)
 
 rustdoc-pin_init: private rustdoc_host = yes
@@ -140,6 +141,9 @@ rustdoc-kernel: $(src)/kernel/lib.rs rustdoc-core rustdoc-ffi rustdoc-macros \
     $(obj)/bindings.o FORCE
 	+$(call if_changed,rustdoc)
 
+rustdoc-clean: FORCE
+	$(Q)rm -rf $(rustdoc_output)
+
 quiet_cmd_rustc_test_library = $(RUSTC_OR_CLIPPY_QUIET) TL $<
       cmd_rustc_test_library = \
 	OBJTREE=$(abspath $(objtree)) \

base-commit: 89be9a83ccf1f88522317ce02f854f30d6115c41
-- 
2.50.1

Re: [PATCH] rust: kbuild: clean output before running `rustdoc`

[Tamir Duberstein]

On Sat, Jul 26, 2025 at 9:35 AM Miguel Ojeda <ojeda@kernel.org> wrote:
>
> `rustdoc` can get confused when generating documentation into a folder
> that contains generated files from other `rustdoc` versions.
>
> For instance, running something like:
>
>     rustup default 1.78.0
>     make LLVM=1 rustdoc
>     rustup default 1.88.0
>     make LLVM=1 rustdoc
>
> may generate errors like:
>
>     error: couldn't generate documentation: invalid template: last line expected to start with a comment
>       |
>       = note: failed to create or modify "./Documentation/output/rust/rustdoc/src-files.js"
>
> Thus just always clean the output folder before generating the
> documentation -- we are anyway regenerating it every time the `rustdoc`
> target gets called, at least for the time being.
>
> Cc: stable@vger.kernel.org # Needed in 6.12.y and later (Rust is pinned in older LTSs).
> Reported-by: Daniel Almeida <daniel.almeida@collabora.com>
> Closes: https://rust-for-linux.zulipchat.com/#narrow/channel/288089/topic/x/near/527201113
> Signed-off-by: Miguel Ojeda <ojeda@kernel.org>

I've seen this as well.

Reviewed-by: Tamir Duberstein <tamird@kernel.org>


> ---
>  rust/Makefile | 10 +++++++---
>  1 file changed, 7 insertions(+), 3 deletions(-)
>
> diff --git a/rust/Makefile b/rust/Makefile
> index 115b63b7d1e3..771246bc7ae6 100644
> --- a/rust/Makefile
> +++ b/rust/Makefile
> @@ -103,14 +103,14 @@ rustdoc: rustdoc-core rustdoc-macros rustdoc-compiler_builtins \
>  rustdoc-macros: private rustdoc_host = yes
>  rustdoc-macros: private rustc_target_flags = --crate-type proc-macro \
>      --extern proc_macro
> -rustdoc-macros: $(src)/macros/lib.rs FORCE
> +rustdoc-macros: $(src)/macros/lib.rs rustdoc-clean FORCE
>         +$(call if_changed,rustdoc)
>
>  # Starting with Rust 1.82.0, skipping `-Wrustdoc::unescaped_backticks` should
>  # not be needed -- see https://github.com/rust-lang/rust/pull/128307.
>  rustdoc-core: private skip_flags = --edition=2021 -Wrustdoc::unescaped_backticks
>  rustdoc-core: private rustc_target_flags = --edition=$(core-edition) $(core-cfgs)
> -rustdoc-core: $(RUST_LIB_SRC)/core/src/lib.rs FORCE
> +rustdoc-core: $(RUST_LIB_SRC)/core/src/lib.rs rustdoc-clean FORCE
>         +$(call if_changed,rustdoc)
>
>  rustdoc-compiler_builtins: $(src)/compiler_builtins.rs rustdoc-core FORCE
> @@ -122,7 +122,8 @@ rustdoc-ffi: $(src)/ffi.rs rustdoc-core FORCE
>  rustdoc-pin_init_internal: private rustdoc_host = yes
>  rustdoc-pin_init_internal: private rustc_target_flags = --cfg kernel \
>      --extern proc_macro --crate-type proc-macro
> -rustdoc-pin_init_internal: $(src)/pin-init/internal/src/lib.rs FORCE
> +rustdoc-pin_init_internal: $(src)/pin-init/internal/src/lib.rs \
> +    rustdoc-clean FORCE
>         +$(call if_changed,rustdoc)
>
>  rustdoc-pin_init: private rustdoc_host = yes
> @@ -140,6 +141,9 @@ rustdoc-kernel: $(src)/kernel/lib.rs rustdoc-core rustdoc-ffi rustdoc-macros \
>      $(obj)/bindings.o FORCE
>         +$(call if_changed,rustdoc)
>
> +rustdoc-clean: FORCE
> +       $(Q)rm -rf $(rustdoc_output)
> +
>  quiet_cmd_rustc_test_library = $(RUSTC_OR_CLIPPY_QUIET) TL $<
>        cmd_rustc_test_library = \
>         OBJTREE=$(abspath $(objtree)) \
>
> base-commit: 89be9a83ccf1f88522317ce02f854f30d6115c41
> --
> 2.50.1
>
>

Re: [PATCH] rust: kbuild: clean output before running `rustdoc`

[Miguel Ojeda]

On Sat, Jul 26, 2025 at 3:34 PM Miguel Ojeda <ojeda@kernel.org> wrote:
>
> `rustdoc` can get confused when generating documentation into a folder
> that contains generated files from other `rustdoc` versions.
>
> For instance, running something like:
>
>     rustup default 1.78.0
>     make LLVM=1 rustdoc
>     rustup default 1.88.0
>     make LLVM=1 rustdoc
>
> may generate errors like:
>
>     error: couldn't generate documentation: invalid template: last line expected to start with a comment
>       |
>       = note: failed to create or modify "./Documentation/output/rust/rustdoc/src-files.js"
>
> Thus just always clean the output folder before generating the
> documentation -- we are anyway regenerating it every time the `rustdoc`
> target gets called, at least for the time being.
>
> Cc: stable@vger.kernel.org # Needed in 6.12.y and later (Rust is pinned in older LTSs).
> Reported-by: Daniel Almeida <daniel.almeida@collabora.com>
> Closes: https://rust-for-linux.zulipchat.com/#narrow/channel/288089/topic/x/near/527201113
> Signed-off-by: Miguel Ojeda <ojeda@kernel.org>

Applied to `rust-fixes` -- thanks everyone!

Cheers,
Miguel