linux-toradex.git/Documentation/rust/quick-start.rst, branch v6.11

docs: rust: remove unintended blockquote in Quick Start

2024-08-27T20:44:29+00:00

Remove indentation within the "Hacking" section of the Rust Quick Start
guide, i.e. remove a `` HTML element from the rendered
documentation.

Reported-by: Miguel Ojeda 
Closes: https://github.com/Rust-for-Linux/linux/issues/1103
Fixes: d07479b211b7 ("docs: add Rust documentation")
Signed-off-by: Jon Mulder 
Link: https://lore.kernel.org/r/20240826-pr-docs-rust-remove-quickstart-blockquote-v1-1-c51317d8d71a@gmail.com
[ Added Fixes tag, reworded slightly and matched title to a previous,
  similar commit. - Miguel ]
Signed-off-by: Miguel Ojeda

docs: rust: quick-start: add section on Linux distributions

2024-07-10T08:29:55+00:00

Now that we are starting to support several Rust compiler and `bindgen`
versions, there is a good chance some Linux distributions work out of
the box.

Thus, provide some instructions on how to set the toolchain up for a
few major Linux distributions. This simplifies the setup users need to
build the kernel.

In addition, add an introduction to the document so that it is easier
to understand its structure and move the LLVM+Rust kernel.org toolchains
paragraph there (removing "depending on the Linux version"). We may want
to reorganize the document or split it in the future, but I wanted to
focus this commit on the new information added about each particular
distribution.

Finally, remove the `rustup`'s components mention in `changes.rst` since
users do not need it if they install the toolchain via the distributions
(and anyway it was too detailed for that main document).

Cc: Jan Alexander Steffens 
Cc: Johannes Löthberg 
Cc: Fabian Grünbichler 
Cc: Josh Stone 
Cc: Randy Barlow 
Cc: Anna (navi) Figueiredo Gomes 
Cc: Matoro Mahri 
Cc: Ryan Scheel 
Cc: figsoda 
Cc: Jörg Thalheim 
Cc: Theodore Ni <43ngvg@masqt.com>
Cc: Winter 
Cc: William Brown 
Cc: Xiaoguang Wang 
Cc: Andrea Righi 
Cc: Zixing Liu 
Cc: Nathan Chancellor 
Tested-by: Benno Lossin 
Tested-by: Andreas Hindborg 
Link: https://lore.kernel.org/r/20240709160615.998336-14-ojeda@kernel.org
Signed-off-by: Miguel Ojeda

rust: start supporting several `bindgen` versions

2024-07-10T08:28:52+00:00

With both the workaround for `bindgen` 0.69.0 and the warning about
0.66.0 and 0.66.1 in place, start supporting several `bindgen` versions,
like it was done for the Rust compiler in a previous patch.

All other versions, including the latest 0.69.4, build without errors.

The `bindgen` project, like Rust, has also agreed to have the kernel
in their CI [1] -- thanks! This should help both projects: `bindgen`
will be able to detect early issues like those mentioned above, and the
kernel will be very likely build with new releases (at least for the
basic configuration being tested).

Link: https://github.com/rust-lang/rust-bindgen/pull/2851 [1]
Tested-by: Benno Lossin 
Tested-by: Andreas Hindborg 
Link: https://lore.kernel.org/r/20240709160615.998336-10-ojeda@kernel.org
Signed-off-by: Miguel Ojeda

rust: avoid assuming a particular `bindgen` build

2024-07-10T08:28:52+00:00

`bindgen`'s logic to find `libclang` (via `clang-sys`) may change over
time, and depends on how it was built (e.g. Linux distributions may decide
to build it differently, and we are going to provide documentation on
installing it via distributions later in this series).

Therefore, clarify that `bindgen` may be built in several ways and
simplify the documentation by only mentioning the most prominent
environment variable (`LIBCLANG_PATH`) as an example on how to tweak the
search of the library at runtime (i.e. when `bindgen` is built as our
documentation explains). This also avoids duplicating the documentation,
like `bindgen` itself does (i.e. it refers to `clang-sys`).

Similarly, replace the test we had for this (which used the real program)
with a mocked one, to avoid depending on the particular build as well.

Tested-by: Benno Lossin 
Tested-by: Andreas Hindborg 
Link: https://lore.kernel.org/r/20240709160615.998336-8-ojeda@kernel.org
Signed-off-by: Miguel Ojeda

rust: start supporting several compiler versions

2024-07-10T08:28:52+00:00

It is time to start supporting several Rust compiler versions and thus
establish a minimum Rust version.

We may still want to upgrade the minimum sometimes in the beginning since
there may be important features coming into the language that improve
how we write code (e.g. field projections), which may or may not make
sense to support conditionally.

We will start with a window of two stable releases, and widen it over
time. Thus this patch does not move the current minimum (1.78.0), but
instead adds support for the recently released 1.79.0.

This should already be enough for kernel developers in distributions that
provide recent Rust compiler versions routinely, such as Arch Linux,
Debian Unstable (outside the freeze period), Fedora Linux, Gentoo
Linux (especially the testing channel), Nix (unstable) and openSUSE
Tumbleweed. See the documentation patch about it later in this series.

In addition, Rust for Linux is now being built-tested in Rust's pre-merge
CI [1]. That is, every change that is attempting to land into the Rust
compiler is tested against the kernel, and it is merged only if it passes
-- thanks to the Rust project for that!

Thus, with the pre-merge CI in place, both projects hope to avoid
unintentional changes to Rust that break the kernel. This means that,
in general, apart from intentional changes on their side (that we will
need to workaround conditionally on our side), the upcoming Rust compiler
versions should generally work.

For instance, currently, the beta (1.80.0) and nightly (1.81.0) branches
work as well.

Of course, the Rust for Linux CI job in the Rust toolchain may still need
to be temporarily disabled for different reasons, but the intention is
to help bring Rust for Linux into stable Rust.

Link: https://github.com/rust-lang/rust/pull/125209 [1]
Reviewed-by: Finn Behrens 
Tested-by: Benno Lossin 
Tested-by: Andreas Hindborg 
Link: https://lore.kernel.org/r/20240709160615.998336-7-ojeda@kernel.org
Signed-off-by: Miguel Ojeda

kbuild: rust: remove now-unneeded `rusttest` custom sysroot handling

2024-07-08T20:39:39+00:00

Since we dropped our custom `alloc` in commit 9d0441bab775 ("rust: alloc:
remove our fork of the `alloc` crate"), there is no need anymore to keep
the custom sysroot hack.

Thus delete it, which makes the target way simpler and faster too.

This also means we are not using Cargo for anything at the moment,
and that no download is required anymore, so update the main `Makefile`
and the documentation accordingly.

Link: https://lore.kernel.org/r/20240528163502.411600-1-ojeda@kernel.org
Signed-off-by: Miguel Ojeda

docs: rust: introduce the new kernel.org LLVM+Rust toolchains

2024-07-08T20:39:29+00:00

These combined LLVM+Rust toolchains are now available, thanks to Nathan
Chancellor (ClangBuiltLinux).

Thus introduce them in the Rust Quick Start guide.

Signed-off-by: Nathan Chancellor 
Link: https://lore.kernel.org/r/20240517170615.377786-1-ojeda@kernel.org
Co-developed-by: Miguel Ojeda 
Signed-off-by: Miguel Ojeda

docs: rust: Clarify that 'rustup override' applies to build directory

2023-12-21T21:47:40+00:00

'rustup override' is required to be set for the build directory and not
necessarily the kernel source tree (unless the build directory is its
subdir).

Clarify the same in the Quick Start guide.

Signed-off-by: Viresh Kumar 
Reviewed-by: Benno Lossin 
Reviewed-by: Alice Ryhl 
Originally-pointed-out-by: Masahiro Yamada 
Link: https://github.com/Rust-for-Linux/linux/commit/f2238e7
Link: https://lore.kernel.org/r/e2b943eca92abebbf035447b3569f09a7176c770.1702366951.git.viresh.kumar@linaro.org
[ Reworded and fixed quotes for `--path` and `set`. ]
Signed-off-by: Miguel Ojeda

docs: rust: remove `CC=clang` mentions

2023-12-21T21:47:09+00:00

Nowadays all architectures except s390 recommend using `LLVM=1` instead of
`CC=clang`, and since commit a3c6bfba4429 ("Documentation/llvm: refresh
docs") the Kbuild LLVM documentation makes `LLVM=1` the way to go:

    We want to encourage the use of ``LLVM=1`` rather than just
    ``CC=clang``. Make that suggestion "above the fold" and "front and
    center" in our docs.

In particular, that commit removes the examples with `CC=clang`.

Thus do the same in the Rust Quick Start guide, i.e. remove the `CC=clang`
mentions, especially since the architectures that have had their Rust
support upstreamed (or soon to be upstreamed) are all `LLVM=1` ones.
And perhaps by the time Rust is supported for s390 (or new architectures),
it may have moved to `LLVM=1` anyway. Otherwise, this can be added back
if needed (or perhaps an extra link to Documentation/kbuild/llvm.rst).

This should also help avoiding potential confusion around `CC=clang` [1].

Link: https://lore.kernel.org/rust-for-linux/6df6e8e5-8d5b-4d3d-91b5-bc0e90c424ea@nvidia.com/ [1]
Reviewed-by: Ariel Miculas 
Reviewed-by: Nathan Chancellor 
Reviewed-by: Alice Ryhl 
Reviewed-by: Benno Lossin 
Reviewed-by: Justin Stitt 
Reviewed-by: John Hubbard 
Reviewed-by: Martin Rodriguez Reboredo 
Link: https://lore.kernel.org/r/20231215124751.175191-1-ojeda@kernel.org
Signed-off-by: Miguel Ojeda

docs: rust: clarify what 'rustup override' does

2023-08-20T22:36:41+00:00

The behavior of 'rustup override' is not very well known. Add a small
note about what it does, so users have a better understanding of how it
affects their system toolchain (i.e., it does not affect system
toolchain and only sets a directory-specific override).

Signed-off-by: Trevor Gross 
Reviewed-by: Martin Rodriguez Reboredo 
Reviewed-by: Alice Ryhl 
Link: https://lore.kernel.org/r/20230803060437.12157-3-tmgross@umich.edu
[ Undid the `:` to `::` change. ]
Signed-off-by: Miguel Ojeda