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

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

[Igor Korotin]

Split installation instructions for Ubuntu into 2 different sections:
- For Ubuntu 25.04 and 24.10: these releases provide easy-to-install
  Rust packages.
- For Ubuntu 24.10 and below: these releases provide rust-1.80 and
  bindgen-0.65, which do not set their tools as defaults. The instructions
  for these versions have been updated to configure Rust tools properly.

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

Changes since v2:
 - rewrote commit message to reflect the latest changes
 - split Installation section for Ubuntu distro into two sections for specific
   versions
 - https://lore.kernel.org/rust-for-linux/20250402104759.1764282-1-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/rust-for-linux/20250331170118.1376899-1-igor.korotin@yahoo.com/

 Documentation/rust/quick-start.rst | 53 +++++++++++++++++++++++++++---
 1 file changed, 48 insertions(+), 5 deletions(-)

diff --git a/Documentation/rust/quick-start.rst b/Documentation/rust/quick-start.rst
index 4aa50e5fcb8c..3fc4492c9ee7 100644
--- a/Documentation/rust/quick-start.rst
+++ b/Documentation/rust/quick-start.rst
@@ -87,18 +87,61 @@ they should generally work out of the box, e.g.::
 	zypper install rust rust1.79-src rust-bindgen clang
 
 
-Ubuntu
-******
+Ubuntu 25.04 and 24.10
+**********************
 
-Ubuntu LTS and non-LTS (interim) releases provide recent Rust releases and thus
-they should generally work out of the box, e.g.::
+The latest Ubuntu releases provide recent Rust releases and thus 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
+	apt install rustc rust-src bindgen rustfmt rust-clippy
+
+``RUST_LIB_SRC`` needs to be set when using the versioned packages, e.g.::
+
+	RUST_LIB_SRC=/usr/src/rustc-$(rustc --version | cut -d' ' -f2)/library
+
+For convenience, ``RUST_LIB_SRC`` can be exported to the global environment.
+
+In addition, for Ubuntu 24.10 non-LTS only, ``bindgen`` is version 0.66.1. 
+This version contains a bug https://github.com/rust-lang/rust-bindgen/pull/2567
+``bindgen-0.65`` should be installed instead, e.g.:: 
+
+	`apt install bindgen-0.65`
+
+In this case ``bindgen-0.65`` should be used explicitly, e.g.::
+
+	make LLVM=1 BINDGEN=bindgen-0.65 
+
+
+Ubuntu 24.04 LTS, 23.10 non-LTS or older
+****************************************
+
+Though Ubuntu 24.04 LTS and older versions still provide recent Rust
+releases, they require some additional configuration to be set, e.g.::
+
+	apt install rustc-1.80 rust-1.80-src bindgen-0.65 rustfmt-1.80 \
+		rust-1.80-clippy
+	ln -s /usr/lib/rust-1.80/bin/clippy-driver /usr/bin/clippy-driver-1.80
+
+None of these packages set their tools as defaults; therefore should be 
+specified explicitly, e.g.::
+
+	make LLVM=1 RUSTC=rustc-1.80 RUSTDOC=rustdoc-1.80 RUSTFMT=rustfmt-1.80 \
+		CLIPPY_DRIVER=clippy-driver-1.80 BINDGEN=bindgen-0.65
+
+or alternatively, modify the ``PATH`` variable to place the Rust 1.80 binaries
+first and set bindgen as the default, e.g.::
+
+	PATH=/usr/lib/rust-1.80/bin:$PATH
+	update-alternatives --install /usr/bin/bindgen bindgen \
+		/usr/bin/bindgen-0.65 100
+	update-alternatives --set bindgen /usr/bin/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
 
+For convenience, ``RUST_LIB_SRC`` can be exported to the global environment.
+
 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 v3] docs: rust: quick-start: update Ubuntu instructions

[Miguel Ojeda]

On Wed, Apr 2, 2025 at 6:01 PM Igor Korotin <igor.korotin@yahoo.com> wrote:
>
> Split installation instructions for Ubuntu into 2 different sections:
> - For Ubuntu 25.04 and 24.10: these releases provide easy-to-install
>   Rust packages.
> - For Ubuntu 24.10 and below: these releases provide rust-1.80 and
>   bindgen-0.65, which do not set their tools as defaults. The instructions
>   for these versions have been updated to configure Rust tools properly.
>
> Signed-off-by: Igor Korotin <igor.korotin@yahoo.com>

This looks much better, thank you! I fixed a few things and re-checked
the instructions. Please double-check if you are OK with the changes.

I dropped the 24.10 content, because there is still a bug with it
(https://bugs.launchpad.net/ubuntu/+source/rust-bindgen-cli/+bug/2086639,
https://github.com/rust-lang/rust-bindgen/pull/2824), which is
different from the 0.66.1 one that you mention, and anyway 24.10 just
has one month left of life anyway, which will be over by the time the
next kernel gets released.

I considered dropping 20.04 LTS (i.e. mentioning just 24.04 LTS and
22.04 LTS explicitly), since it is out of standard support and does
not even appear in the package listings anymore... Anyway, we can do
that another time.

Applied to `rust-next` -- thanks!

    [ Dropped 24.10 -- it is soon out of support and their `bindgen` issue
      (reported as issue #2086639) was never patched anyway. Removed trailing
      spaces. Split into subheaders. Added `rustfmt` link. Removed spurious
      backquotes. Reworded contents slightly. - Miguel ]

Cheers,
Miguel