[PATCH 0/2] docs: rust: update instructions on obtaining 'core' source

[PATCH 0/2] docs: rust: update instructions on obtaining 'core' source

[Trevor Gross]

This changes the suggested method of obtaining Rust's source to using the
tarball rather than a full clone, and adds a clarification about 'rustup
override'.

Trevor Gross (2):
  docs: rust: update instructions for obtaining 'core' source
  docs: rust: clarify what 'rustup override' does

 Documentation/rust/quick-start.rst | 19 +++++++++++--------
 1 file changed, 11 insertions(+), 8 deletions(-)

-- 
2.34.1

[PATCH 1/2] docs: rust: update instructions for obtaining 'core' source

[Trevor Gross]

The source for Rust's 'core' library is needed to build the kernel with
Rust support. This must be obtained manually when using a non-rustup
install, such as when using 'rustc' from a package manager or from a
standalone installer. Currently, the documentation suggests cloning the
'rust' repository to obtain these sources, but this is quite slow (on
the order of a few minutes).

This patch changes this documentation to suggest using the source
tarball instead, which includes only needed information (<5M) and is
significantly faster to download. This is more in line with what
'rustup' does.

Signed-off-by: Trevor Gross <tmgross@umich.edu>
---
 Documentation/rust/quick-start.rst | 15 ++++++++-------
 1 file changed, 8 insertions(+), 7 deletions(-)

diff --git a/Documentation/rust/quick-start.rst b/Documentation/rust/quick-start.rst
index a8931512ed98..bb67deb19100 100644
--- a/Documentation/rust/quick-start.rst
+++ b/Documentation/rust/quick-start.rst
@@ -56,16 +56,17 @@ If ``rustup`` is being used, run::
 The components are installed per toolchain, thus upgrading the Rust compiler
 version later on requires re-adding the component.
 
-Otherwise, if a standalone installer is used, the Rust repository may be cloned
-into the installation folder of the toolchain::
+Otherwise, if a standalone installer is used, the Rust source tree may be
+downloaded into the toolchain's installation folder::
 
-	git clone --recurse-submodules \
-		--branch $(scripts/min-tool-version.sh rustc) \
-		https://github.com/rust-lang/rust \
-		$(rustc --print sysroot)/lib/rustlib/src/rust
+	curl -L https://static.rust-lang.org/dist/rust-src-$(scripts/min-tool-version.sh rustc).tar.gz |
+		tar -xzf - -C $(rustc --print sysroot)/lib \
+		rust-src-$(scripts/min-tool-version.sh rustc)/rust-src/lib/ \
+		--strip-components=3
 
 In this case, upgrading the Rust compiler version later on requires manually
-updating this clone.
+updating the source tree (this can be done by removing ``$(rustc --print
+sysroot)/lib/rustlib/src/rust`` then rerunning the above command).
 
 
 libclang
-- 
2.34.1

[PATCH 2/2] docs: rust: clarify what 'rustup override' does

[Trevor Gross]

The behavior of 'rustup override' is not very well known. This patch is
a small edit that adds details 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 <tmgross@umich.edu>
---
 Documentation/rust/quick-start.rst | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/Documentation/rust/quick-start.rst b/Documentation/rust/quick-start.rst
index bb67deb19100..700d37dcff5c 100644
--- a/Documentation/rust/quick-start.rst
+++ b/Documentation/rust/quick-start.rst
@@ -38,7 +38,9 @@ and run::
 
 	rustup override set $(scripts/min-tool-version.sh rustc)
 
-Otherwise, fetch a standalone installer from:
+This will configure your working directory to use the correct version of
+``rustc`` without affecting your default toolchain. If you are not using
+``rustup``, fetch a standalone installer from::
 
 	https://forge.rust-lang.org/infra/other-installation-methods.html#standalone
 
-- 
2.34.1

Re: [PATCH 1/2] docs: rust: update instructions for obtaining 'core' source

[Martin Rodriguez Reboredo]

On 7/18/23 02:44, Trevor Gross wrote:
> The source for Rust's 'core' library is needed to build the kernel with
> Rust support. This must be obtained manually when using a non-rustup
> install, such as when using 'rustc' from a package manager or from a
> standalone installer. Currently, the documentation suggests cloning the
> 'rust' repository to obtain these sources, but this is quite slow (on
> the order of a few minutes).
> 
> This patch changes this documentation to suggest using the source
> tarball instead, which includes only needed information (<5M) and is
> significantly faster to download. This is more in line with what
> 'rustup' does.
> 
> Signed-off-by: Trevor Gross <tmgross@umich.edu>
> ---
> [...]
Reviewed-by: Martin Rodriguez Reboredo <yakoyoku@gmail.com>

Re: [PATCH 2/2] docs: rust: clarify what 'rustup override' does

[Martin Rodriguez Reboredo]

On 7/18/23 02:44, Trevor Gross wrote:
> The behavior of 'rustup override' is not very well known. This patch is
> a small edit that adds details 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 <tmgross@umich.edu>
> ---
> [...]
Reviewed-by: Martin Rodriguez Reboredo <yakoyoku@gmail.com>

Re: [PATCH 1/2] docs: rust: update instructions for obtaining 'core' source

[Alice Ryhl]

Trevor Gross <tmgross@umich.edu> writes:
> +	curl -L https://static.rust-lang.org/dist/rust-src-$(scripts/min-tool-version.sh rustc).tar.gz |
> +		tar -xzf - -C $(rustc --print sysroot)/lib \
> +		rust-src-$(scripts/min-tool-version.sh rustc)/rust-src/lib/ \
> +		--strip-components=3

I think this assumes that the sysroot path has no spaces. I would add
some quotes.

With that fixed, you may add
Reviewed-by: Alice Ryhl <aliceryhl@google.com>

Alice

Re: [PATCH 2/2] docs: rust: clarify what 'rustup override' does

[Alice Ryhl]

> The behavior of 'rustup override' is not very well known. This patch is
> a small edit that adds details 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 <tmgross@umich.edu>

Reviewed-by: Alice Ryhl <aliceryhl@google.com>

Re: [PATCH 1/2] docs: rust: update instructions for obtaining 'core' source

[Miguel Ojeda]

On Tue, Jul 18, 2023 at 7:50 AM Trevor Gross <tmgross@umich.edu> wrote:
>
> The source for Rust's 'core' library is needed to build the kernel with
> Rust support. This must be obtained manually when using a non-rustup
> install, such as when using 'rustc' from a package manager or from a

What does "manually" mean here? I guess "setting it up by hand", but a
distribution may provide a package for that (e.g. `rust-1.62-src` in
Ubuntu), so it is essentially the same as with `rustup` in that case
(i.e. when the distribution provides the means via the package
manager).

> standalone installer. Currently, the documentation suggests cloning the
> 'rust' repository to obtain these sources, but this is quite slow (on
> the order of a few minutes).
>
> This patch changes this documentation to suggest using the source
> tarball instead, which includes only needed information (<5M) and is
> significantly faster to download. This is more in line with what
> 'rustup' does.

If I recall correctly, the idea with the clone was to easily change
the tag when migrating to another version (assuming the base path does
not need to change across versions). But the tarball approach is
likely better anyway, especially for the majority of users.

> Signed-off-by: Trevor Gross <tmgross@umich.edu>

It may be nice to add `Link:
https://github.com/Rust-for-Linux/linux/pull/1024`, but I can do that
on my side.

In addition, commit messages should describe the changes in imperative
mood. Many commits do not follow that convention, but it is what the
kernel docs say, so we should try to adhere to it if possible.

> -Otherwise, if a standalone installer is used, the Rust repository may be cloned
> -into the installation folder of the toolchain::
> +Otherwise, if a standalone installer is used, the Rust source tree may be
> +downloaded into the toolchain's installation folder::

Is the rewording (i.e. the Saxon genitive change) expected? Not a big
deal, of course -- I am mentioning it since, in general, all changes
should be mentioned so that that they are expected, e.g. with a quick
"and improve the wording while at it".

Cheers,
Miguel