Re: [PATCH v6 18/23] docs: add Rust documentation

Jonathan Corbet
2022-05-09T22:33:36Z

Miguel Ojeda <ojeda@kernel.org> writes:

> Most of the documentation for Rust is written within the source code
> itself, as it is idiomatic for Rust projects. This applies to both
> the shared infrastructure at `rust/` as well as any other Rust module
> (e.g. drivers) written across the kernel.
>
> However, these documents contain general information that does not
> fit particularly well in the source code, like the Quick Start guide.
>
> It also contains an asset (SVG logo) used for the `rustdoc` target
> and a few other small changes elsewhere in the documentation folder.

Trying to take a closer look this time...

I foresee merge conflicts, but so it goes. Trying to split this apart
would not make a lot of sense.

[...]

> --- /dev/null
> +++ b/Documentation/rust/arch-support.rst
> @@ -0,0 +1,34 @@
> +Arch Support
> +============
> +
> +Currently, the Rust compiler (``rustc``) uses LLVM for code generation,
> +which limits the supported architectures that can be targeted. In addition,
> +support for building the kernel with LLVM/Clang varies (please see
> +Documentation/kbuild/llvm.rst). This support is needed for ``bindgen``
> +which uses ``libclang``.
> +
> +Below is a general summary of architectures that currently work. Level of
> +support corresponds to ``S`` values in the ``MAINTAINERS`` file.
> +
> +.. list-table::
> + :widths: 10 10 10
> + :header-rows: 1

Please use normal tables rather than list-table; this kind of thing is
really unreadable in the source form.

> + * - Architecture
> + - Level of support
> + - Constraints
> + * - ``arm``
> + - Maintained
> + - ``armv6`` and compatible only, ``RUST_OPT_LEVEL >= 2``
> + * - ``arm64``
> + - Maintained
> + - None
> + * - ``powerpc``
> + - Maintained
> + - ``ppc64le`` only, ``RUST_OPT_LEVEL < 2`` requires ``CONFIG_THREAD_SHIFT=15``
> + * - ``riscv``
> + - Maintained
> + - ``riscv64`` only
> + * - ``x86``
> + - Maintained
> + - ``x86_64`` only
> diff --git a/Documentation/rust/coding-guidelines.rst b/Documentation/rust/coding-guidelines.rst
> new file mode 100644
> index 000000000000..2a71fd68a06d
> --- /dev/null
> +++ b/Documentation/rust/coding-guidelines.rst
> @@ -0,0 +1,214 @@
> +Coding Guidelines
> +=================
> +
> +This document describes how to write Rust code in the kernel.
> +
> +
> +Style & formatting
> +------------------
> +
> +The code should be formatted using ``rustfmt``. In this way, a person
> +contributing from time to time to the kernel does not need to learn and
> +remember one more style guide. More importantly, reviewers and maintainers
> +do not need to spend time pointing out style issues anymore, and thus
> +less patch roundtrips may be needed to land a change.

I foresee disagreements over coding style conventions in the
future... I don't plan to be part of that conversation :)

> +.. note:: Conventions on comments and documentation are not checked by
> + ``rustfmt``. Thus those are still needed to be taken care of.
> +
> +The default settings of ``rustfmt`` are used. This means the idiomatic Rust
> +style is followed. For instance, 4 spaces are used for indentation rather
> +than tabs.
> +
> +It is convenient to instruct editors/IDEs to format while typing,
> +when saving or at commit time. However, if for some reason reformatting
> +the entire kernel Rust sources is needed at some point, the following can be
> +run::
> +
> + make LLVM=1 rustfmt

I will ask whether we want this, though. Why would anybody want to
mass-reformat the entire body of kernel code? This seems like something
that would generate an endless stream of "helpful" patches and a lot of
churn.

Thanks,

jon