[PATCH v2] docs: rust: quick-start: update Ubuntu instructions

[PATCH v2] docs: rust: quick-start: update Ubuntu instructions

[Igor Korotin]

Ubuntu’s rust-1.80 and bindgen-0.65 packages don't set their tools
as defaults. They should be defined explicitly.

Signed-off-by: Igor Korotin <igor.korotin@yahoo.com>
---

Changes since v1:
 - rewrote commit message to be more concise
 - reworked instruction's steps not to make global changes
 - added overall build command for Ubuntu.
 - https://lore.kernel.org/all/20250331170118.1376899-1-igor.korotin@yahoo.com/
 
 Documentation/rust/quick-start.rst | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

diff --git a/Documentation/rust/quick-start.rst b/Documentation/rust/quick-start.rst
index 4aa50e5fcb8c..3651d726ede0 100644
--- a/Documentation/rust/quick-start.rst
+++ b/Documentation/rust/quick-start.rst
@@ -95,10 +95,25 @@ they should generally work out of the box, e.g.::
 
 	apt install rustc-1.80 rust-1.80-src bindgen-0.65 rustfmt-1.80 rust-1.80-clippy
 
+``PATH`` needs to be set when installing rust 1.80 with apt, e.g.::
+
+	PATH=/usr/lib/rust-1.80/bin:$PATH
+
+Deb package bindgen-0.65 does not set itself as a default, thus it should be set
+explicitly, e.g.::
+
+	BINDGEN=bindgen-0.65
+
 ``RUST_LIB_SRC`` needs to be set when using the versioned packages, e.g.::
 
 	RUST_LIB_SRC=/usr/src/rustc-$(rustc-1.80 --version | cut -d' ' -f2)/library
 
+The overall command should be the following::
+
+	make LLVM=1 PATH=/usr/lib/rust-1.80/bin:$PATH \
+		RUST_LIB_SRC=/usr/src/rustc-$(rustc-1.80 --version | cut -d' ' -f2)/library \
+		BINDGEN=bindgen-0.65 <target>
+
 In addition, ``bindgen-0.65`` is available in newer releases (24.04 LTS and
 24.10), but it may not be available in older ones (20.04 LTS and 22.04 LTS),
 thus ``bindgen`` may need to be built manually (please see below).
-- 
2.43.0

Re: [PATCH v2] docs: rust: quick-start: update Ubuntu instructions

[Miguel Ojeda]

On Wed, Apr 2, 2025 at 12:48 PM Igor Korotin <igor.korotin@yahoo.com> wrote:
>
> +``PATH`` needs to be set when installing rust 1.80 with apt, e.g.::
> +
> +       PATH=/usr/lib/rust-1.80/bin:$PATH

Why does it need to be set? i.e. why not `RUSTC=...` for that one too?

In other words, why are we mixing the approaches? We can explain both,
but mixing them seems confusing.

> +Deb package bindgen-0.65 does not set itself as a default, thus it should be set
> +explicitly, e.g.::
> +
> +       BINDGEN=bindgen-0.65

I don't think this example adds much, since we already show it below.

> +       make LLVM=1 PATH=/usr/lib/rust-1.80/bin:$PATH \
> +               RUST_LIB_SRC=/usr/src/rustc-$(rustc-1.80 --version | cut -d' ' -f2)/library \

Note that `RUST_LIB_SRC` (and `PATH`) are not needed there, i.e. those
two can be set as environment variables.

Perhaps we could just add something like this to the existing paragraph:

    ``RUST_LIB_SRC`` needs to be set (possibly as an environment variable) ...

Also, weren't we going to mention `RUSTDOC`, `RUSTFMT` and `CLIPPY_DRIVER`?

Thanks for the patch!

Cheers,
Miguel

Re: [PATCH v2] docs: rust: quick-start: update Ubuntu instructions

[Igor Korotin]

On 4/2/25 12:26, Miguel Ojeda wrote:
> On Wed, Apr 2, 2025 at 12:48 PM Igor Korotin <igor.korotin@yahoo.com> wrote:
>>
>> +``PATH`` needs to be set when installing rust 1.80 with apt, e.g.::
>> +
>> +       PATH=/usr/lib/rust-1.80/bin:$PATH
> 
> Why does it need to be set? i.e. why not `RUSTC=...` for that one too?
> 
> In other words, why are we mixing the approaches? We can explain both,
> but mixing them seems confusing.

I checked what happens with other tools(For example rustdoc) if I define 
only
`RUSTC=rustc-1.80`. Unsurprisingly `rustdoc` remains 1.75, which is 
installed from `rustc` package, which in its turn is dependency for the 
package `bindgen-0.65`. Though I see that this mix works fine, it seems 
a little bit weird when you have one tool of version 1.80 another 1.75, 
etc. Without a doubt one can define each tool explicitly using `RUSTC`, 
`RUSTDOC`, etc. On the other hand defining `PATH` to 
`/usr/lib/rust-1.80/bin/` automatically makes build to use rust-1.80 
tools.

>> +Deb package bindgen-0.65 does not set itself as a default, thus it should be set
>> +explicitly, e.g.::
>> +
>> +       BINDGEN=bindgen-0.65
> 
> I don't think this example adds much, since we already show it below.

This was intention to explain each additional environment part of the 
overall command.

>> +       make LLVM=1 PATH=/usr/lib/rust-1.80/bin:$PATH \
>> +               RUST_LIB_SRC=/usr/src/rustc-$(rustc-1.80 --version | cut -d' ' -f2)/library \
> 
> Note that `RUST_LIB_SRC` (and `PATH`) are not needed there, i.e. those
> two can be set as environment variables.
> 
> Perhaps we could just add something like this to the existing paragraph:
> 
>      ``RUST_LIB_SRC`` needs to be set (possibly as an environment variable) ...

By adding these as part of the overall build command, I was going by 
your earlier statement that you prefer setups that minimize global changes.

> 
> Also, weren't we going to mention `RUSTDOC`, `RUSTFMT` and `CLIPPY_DRIVER`?

This one was supposed to be covered by `PATH=/usr/lib/rust-1.80/bin:$PATH`

Thanks for the review

Best Regards
Igor

Re: [PATCH v2] docs: rust: quick-start: update Ubuntu instructions

[Igor Korotin]

On 4/2/25 12:26, Miguel Ojeda wrote:
> Also, weren't we going to mention `RUSTDOC`, `RUSTFMT` and `CLIPPY_DRIVER`?

While re-writing my changes I found out that while packages rustc, 
rustdoc and
rustfmt of version 1.80 in 22.04 and 24.04 at least create symbolic 
links to
their tools in /usr/bin/, rust-1.80-clippy does not do it. So the 
clippy-driver
is only accessible by its full path /usr/lib/rust-1.80/bin/clippy-driver.
I'm sure this quick-start.rst should be updated, because from my 
experience I know that it is painful for newcomer to configure Rust for 
kernel properly in Ubuntu 22.04/24.04. And to be honest, I see 
`PATH=/usr/lib/rust-1.80/bin:$PATH` the easiest solution. Rust packages 
in 22.04/24.04 are screwed. I checked 24.10/25.04 and these versions do 
not have such problems at all, it's just enough to use `apt rustc 
rustdoc rustfmt bindgen rust-clippy` to install rust 1.84 and bindgen 
0.71 and set `RUST_LIB_SRC` variable.

Best Regards
Igor

Re: [PATCH v2] docs: rust: quick-start: update Ubuntu instructions

[Miguel Ojeda]

On Wed, Apr 2, 2025 at 1:49 PM Igor Korotin <igor.korotin@yahoo.com> wrote:
>
> I checked what happens with other tools(For example rustdoc) if I define
> only
> `RUSTC=rustc-1.80`. Unsurprisingly `rustdoc` remains 1.75, which is
> installed from `rustc` package, which in its turn is dependency for the
> package `bindgen-0.65`. Though I see that this mix works fine, it seems
> a little bit weird when you have one tool of version 1.80 another 1.75,
> etc. Without a doubt one can define each tool explicitly using `RUSTC`,
> `RUSTDOC`, etc. On the other hand defining `PATH` to
> `/usr/lib/rust-1.80/bin/` automatically makes build to use rust-1.80
> tools.

Ah, I see -- what I meant is that it is not required to set `PATH`,
i.e. one can use the approach of setting each variable explicitly
instead (e.g. that is what I do). In fact, setting the variables is
the "most general" solution, since it allows any name for the
binaries.

That is also what I meant by "minimize global changes", i.e. instead
of touching something like `PATH` (especially if done as an env var),
we just touch those variables.

But, yeah, I understand that you are trying to simplify by setting
less variables, which is also good. That is why I mentioned that
perhaps it is best to just show the two examples, i.e. one with
`PATH`, and the other setting each variable. Then people can decide
what they prefer, and they have also the most general solution in case
something breaks with future packages etc.

But I don't want to force any particular approach -- whatever
you/others think it is easiest for newcomers is probably the best.

To be honest, I think Ubuntu's packages should not be used for normal
development at this point.

Cheers,
Miguel

Re: [PATCH v2] docs: rust: quick-start: update Ubuntu instructions

[Miguel Ojeda]

On Wed, Apr 2, 2025 at 3:52 PM Igor Korotin <igor.korotin@yahoo.com> wrote:
>
> While re-writing my changes I found out that while packages rustc,
> rustdoc and
> rustfmt of version 1.80 in 22.04 and 24.04 at least create symbolic
> links to
> their tools in /usr/bin/, rust-1.80-clippy does not do it. So the
> clippy-driver
> is only accessible by its full path /usr/lib/rust-1.80/bin/clippy-driver.
> I'm sure this quick-start.rst should be updated, because from my
> experience I know that it is painful for newcomer to configure Rust for
> kernel properly in Ubuntu 22.04/24.04. And to be honest, I see
> `PATH=/usr/lib/rust-1.80/bin:$PATH` the easiest solution. Rust packages
> in 22.04/24.04 are screwed. I checked 24.10/25.04 and these versions do
> not have such problems at all, it's just enough to use `apt rustc
> rustdoc rustfmt bindgen rust-clippy` to install rust 1.84 and bindgen
> 0.71 and set `RUST_LIB_SRC` variable.

Yeah, it is a mess. I think `rustfmt` doesn't create it either in
24.04 at least -- at least I have that one as an absolute path when I
test it.

There are also other issues even with 24.10's packages, e.g. the main
`bindgen` package did not get backports for bugs -- see the bug
reports listed in:

    https://github.com/Rust-for-Linux/linux/issues/1127

I also mentioned to the maintainers a couple other bits, e.g. the
order of installation also matters:

    https://bugs.launchpad.net/ubuntu/+source/rustc-1.80/+bug/2090791/comments/3

I am happy to link more bug reports there and/or open new ones.

The whole situation is not great, and other distributions work just
fine, so I am tempted to add a paragraph at the top recommending to
use alternative ways of installing the toolchain for Ubuntu...

Cheers,
Miguel