Re: [PATCH v5 0/2] docs: Integrate rustdoc into Rust documentation

[Miguel Ojeda]

On Tue, Jan 3, 2023 at 12:54 AM Jonathan Corbet <corbet@xxxxxxx> wrote:
>
> - It forces the generation of a kernel configuration, something that the
>   docs build has never done until now.  What are our changes of
>   eliminating that?

We could workaround it by providing a fixed, preset config that does
not interfere with the usual `.config`.

We would still need to compile some things like we normally would do,
though (see next point).

> - It did a bunch of other building, starting with objtool - again, never
>   needed for the docs build before.

Yeah, rustdoc, like the compiler, requires dependencies to be
available to understand the code. Thus some things need to be
compiled, like for the normal build.

This is definitely different than the current docs, of course, which
is why I raised these questions back then.

> In the end, it died with:
>
> > BINDGEN rust/bindings/bindings_generated.rs
> > Failed to run rustfmt: No such file or directory (os error 2) (non-fatal, continuing)

This one is unrelated -- it happens when rustfmt is not installed, so
that those interested in only building (but not developing) the kernel
can avoid it. We could hide the message, though for developers it is
useful to know.

This is one instance where knowing in the build system whether the
user intends to developer the kernel or not could be useful (e.g. we
could hide it for some of the distribution/packaging targets); but I
would prefer to simply make rustfmt mandatory, since in principle
there could be a rustfmt bug that makes a behavioral change, and it
would simplify things (it comes with the compiler anyway).

> >   BINDGEN rust/bindings/bindings_helpers_generated.rs
> > error: Found argument '--blacklist-type' which wasn't expected, or isn't valid in this context
> >
> >       Did you mean '--blocklist-type'?
>
> Perhaps this is because I ignored the warnings about my Rust toolchain
> being too new? (Rust 1.65.0, bindgen 0.63.0).  I get that only one

Yeah, that is due to bindgen 0.63.0 removing [1] some flags deprecated
[2] in 0.58.0.

[1] https://github.com/rust-lang/rust-bindgen/blob/v0.63.0/CHANGELOG.md#removed-1
[2] https://github.com/rust-lang/rust-bindgen/blob/v0.58.0/CHANGELOG.md#deprecated-1

> version is really supported, but it would be nice to fail a bit more
> gracefully if at all possible.

Do you mean failing in the `scripts/rust_is_available.sh` step instead
of warning? We could also add versioning information to that script,
so that it knows more about which versions work etc., but I guess at
that point it would be best to simply start supporting several
versions, which may be a bit too early to split CI runs on that since
it would require some degree of testing.

Cheers,
Miguel