Document `settings.toml`

[eirnym]

Problem you are trying to solve

Current state of settings.toml documentation contains only location of documentation leaving other features to be discovered using reverse engineering

Solution you'd like

I'd like to have an actual list of options there to configure. Could be built automatically or manually.

Notes

No response

[ChrisDenton]

Currently the documentation says;

The schema for this file is not part of the public interface for rustup - the rustup CLI should be used to query and set settings.

That is, rustup set should always be used for editing the settings file.

So the ask here is not just to document it, but also commit to stabilizing it.

[eirnym]

I understand. Documentation is build for specific version anyway, so I don't expect it to never change. Many applications tells that explicitly and nobody is offended.

[djc]

Why do you want this? What problem are you trying to solve?

[eirnym]

I'd like to read documentation without opening source code. Other parts of documentation give hits of options which are in configuration file, so this would make documentation consistent as well.

[ChrisDenton]

I think the question being asked is why do you need to write the configuration file manually instead of using rustup to set the options?

[djc]

settings.toml is less like a configuration file and more like an internal persistence mechanism that happens to be human-readable.

[eirnym]

I'd like to manage all my configuration including persistence and version tracking.

[djc]

That doesn't answer this question:

Why do you want this? What problem are you trying to solve?

[rami3l]

That doesn't answer this question:

Why do you want this? What problem are you trying to solve?

@djc @ChrisDenton There are people who would like to use an "immutable" system such as NixOS and Guix, and the basis of this idea is to make everything persistent. (I belong to this group as well as I use NixOS on my servers, but my desktops remain mutable.) In this case, a comprehensive documentation for the config file makes it easier to generate a config file via e.g. Nix, bypassing rustup's set commands completely.

However, I don't think rustup is made with such use cases in mind in the first place: being a toolchain multiplexer, it's inherently relying on a mutable global state (the active toolchain). So I think a reasonable stance to take on our end would be that, anyone is free to make rustup work with their "immutable" setup, but we will not provide any stability guarantees for settings.toml or whatsoever.