PSA: Rust documentation is now optional and opt-in when installing via rustup

[tyoc213]

Whether they are installed by default or not, it seems like component selection should be part of the install process.

Maybe some like rustup install stable with docs for it to be a one liner.

Also it would be a NTH that rustup update does print from what to what are you updating

rustup update
info: syncing channel updates for 'stable-x86_64-pc-windows-msvc'
info: downloading component 'rustc'
 26.7 MiB /  26.7 MiB (100 %)   1.2 MiB/s ETA:   0 s
info: downloading component 'rust-std'
 33.5 MiB /  33.5 MiB (100 %)   1.2 MiB/s ETA:   0 s
info: downloading component 'rust-docs'
  6.7 MiB /   6.7 MiB (100 %)   1.2 MiB/s ETA:   0 s
info: downloading component 'cargo'
  2.5 MiB /   2.5 MiB (100 %)   1.2 MiB/s ETA:   0 s

6.7MiB is only 9.2% of the total.

[skade]

We could extract it on the first "rustup docs" call.

[CryZe]

I can confirm. On a network drive extracting the docs alone takes 20 minutes!

[cgag]

Would much much rather opt-out. I'm probably not going to bother opting in, and I'm probably going to regret it at some point. If I the docs annoyed me, I'd cancel and figure out how to opt out.

[tyoc213]

I did put the numbers because the OP said this docs have significant download size rustc and rustlib have significant download size, not the docs... thought

I can confirm. On a network drive extracting the docs alone takes 20 minutes!

Thought having SSD that means almost nothing ...

We could extract it on the first "rustup doc" call.

N1, I was thinking in downloading them as md files (the download size would be less than HTML I think) then converting them to html would be best in this call, thought with the current HTML download perhaps it is not possible.

---

Maybe when installing, updating or something, there could be a message you have this opt-in and opt out features: doc.

So the people know that there are or are not docs installed. (Well, for starters, I didnt even know I did have the docs installed or that I can access them trought that command).

---

Another thing I will like to know if there is no doc installed, what will do rustup doc do?

[gibfahn]

+1 for a way to have docs automatically installed. I'll never remember to install the docs until I need them, by which point it will be too late.

I personally think that it's a pretty neat feature for Rust to have the specific docs for the version of rust you're using just a rustup doc away. I understand that some/many people may not need them, but a permanent opt-in for getting docs would be very useful.

[retep998]

I'd very strongly prefer for docs to be installed by default but with an opt out. They're so incredibly useful, especially when you don't have internet (at which point if you forgot to install them, then you're screwed).

[elahn]

Whether they are installed by default or not, it seems like component selection should be part of the install process.

Another consideration is that right now there is no way to define optional, opt-out, components. It will take more work in various places to make that possible.

I'm happy to help with that, is there an issue or RFC that defines the ideal work flow?

I'd like it to present options while downloading/installing the required components.

• If I haven't opted out by the time that's done, install docs.
• Leave options for rust-src and racer/RLS on the screen
• Command line options for automated installs.

[tyoc213]

Also remember that cargo registry will take more space that the install https://github.com/rust-lang/cargo/issues/3323 and you will not have a chance to opt in or out of that AFAIK (I for example dont know how much space it has right now on my SSD).

[kornel]

I don't mind having one copy of the docs, but having a separate copy for each of stable, beta and nightly is too much. Nightlies are updated frequently, so their docs also use most bandwidth.

Maybe install stable docs by default, and beta/nightly as opt-in?

[lilred]

I'd like to register my support for "optional, opt-in" docs. Over the past few weeks I've been intensely annoyed by both the install times and disk usage.

I think a happy medium could be to download the compressed docs, and only decompress them on rustup component add rust-docs. This is kind of a best-of-both-worlds scenario: the main argument against opt-in appears to be that you usually want to opt in at times you don't have an internet connection, but here you wouldn't need one.

(Also: currently, rustup fails on my machine on the installing rust-docs step. How can I access a version of rustup that has this change?)

[chriskrycho]

This last suggestion is exactly what I was going to suggest on bumping into the thread: always download, but don't uncompress unless explicitly requested. That way if you need them and are offline, you can still get them. (Probably needs to be documented in rustup in a helpful way.)

[tcf]

Unless I'm mistaken, due to the opt-in change, rustup doc fail without any error message when the doc isn't installed. Wouldn't it be more user friendly to show a message like this?

The documentation is not currently installed; you can install it by running rustup component add rust-docs.

[brson]

@tcf Yes, that would be better.

The point that docs are a only small part of the download time is well taken.

I'm still undecided about what to do here but it seems like it's going to be a combination of multiple things. Here's what I'm inclined to do:

• Modify the mainifests (rust-buildbot) so that rust-docs are required again.
• Optimize rustup's installation routine so it isn't moving around so much data. There's a lot of temporary files involved and a lot of improvements possible. The actual on-disk installation can go a lot faster.
• Teach rustup and the rust-buildbot manifest generator about optional but installed by default components
• Modify the manifests so that rust-docs is optional but installed by default
• Add a --minimal flag to rust-init that gives you a working rustc+cargo but no optional components, for use by e.g. automation.
• Add command-line and interactive component selection to rust-init.

Thanks for your patience.

[tyoc213]

I would love to add another thing to opt in, that is sources :), I mean for racer and (maybe for others?) you need to have the source code, but for example I have not updated the source sisnce some time now, even that I have done some rustup update so it will be nice if also this is included in some way easely identifiable by racer and maybe other programs when running rustup update.

[matklad]

it will be nice if also this is included in some way easely identifiable by racer and maybe other programs when running rustup update

I think that any program which needs sources can execute rustup component add. For example, IntelliJ-Rust does this and it works great. The situation with docs is different: the need for them can arise suddenly when the internet is down.

[wscott]

Here is what I get when I run rustup on an account that has never seen it before:

# curl https://sh.rustup.rs -sSf | sh
info: downloading installer

Welcome to Rust!

This will download and install the official compiler for the Rust programming 
language, and its package manager, Cargo.

It will add the cargo, rustc, rustup and other commands to Cargo's bin 
directory, located at:

  /root/.cargo/bin

This path will then be added to your PATH environment variable by modifying the
profile file located at:

  /root/.profile

You can uninstall at any time with rustup self uninstall and these changes will
be reverted.

Current installation options:

   default host triple: x86_64-unknown-linux-gnu
     default toolchain: stable
  modify PATH variable: yes

1) Proceed with installation (default)
2) Customize installation
3) Cancel installation

If 'include offline documentation' and 'include rust source code for IDEs' were listed as optional variables you can tweak (with whatever defaults), then people would be less likely to be surprised by them.

(yeah, I piped random crud from the web to root's account. It was a temp container.)

[emk]

We use Rustup to build Rust programs inside Docker images, and we definitely do not want documentation to be saved into the image. At the very least, there should be a flag to disable download of the documentation during initial install.

[Pod]

New rust user here. I ran curl ... | sh. Followed the instructions. Then ran rustup --help to check out what this new command does. I'm greeted with the rustup options and this bit of text.

rustup installs The Rust Programming Language from the official
release channels, enabling you to easily switch between stable, beta,
and nightly compilers and keep them updated. It makes cross-compiling
simpler with binary builds of the standard library for common platforms.

If you are new to Rust consider running rustup doc --book
to learn Rust.

So guess what command try next? I'm then greeted with a nice error message from firefox telling me some random path doesn't exist.

It's not a great introduction to new users.

ps: As a suggestion, I think rustup should check if the rust-docs component is installed before trying to have my browser open it, and if it's not installed then tell the user the appropriate command to install it. (e.g. I got the command from the top of this thread, via google. I took a quick look at rustup --help but didn't see an obvious install command, and as I'm new to rust and it's lingo I didn't realise you consider the documentation to be part of a toolchain's components.)

[sourcefrog]

ps: As a suggestion, I think rustup should check if the rust-docs component is installed before trying to have my browser open it, and if it's not installed then tell the user the appropriate command to install it. (

Great suggestion! Can you file a bug if there is not already one?