refactor(dist): clean up toolchain hierarchy, pt. 1

[rami3l]

Part of #5092.

I realized that I'm making my analysis unnecessarily difficult by using the inconsistent nomenclature, so I guess it's easier to fix it first and then consider how to restructure the code.

The main changes here are all renames:

• *ToolchainDesc to *OfficialToolchainName
• PathBasedToolchainName to ToolchainPath
• [Resolvable]LocalToolchainName to [Partial]ToolchainNameOrPath
• ResolvableToolchainName to PartialToolchainName
• *ToolchainName::resolve() to _::complete()

Rationale

The goal of the new naming system is to make every name as dumb as possible. Once you look at a type name, you shouldn't spend too much time guessing what's in it.

With it, the overall toolchain name hierarchy becomes:

type ToolchainName = OfficialToolchainName | CustomToolchainName
type ToolchainNameOrPath = ToolchainName | ToolchainPath

type PartialToolchainName = PartialOfficialToolchainName | CustomToolchainName
type PartialToolchainNameOrPath = PartialToolchainName | ToolchainPath

You may compare the above with the original naming as stated in #5092:

// A _full_ official toolchain name, or a custom toolchain name
type ToolchainName = ToolchainDesc | CustomToolchainName
// A _full_ official toolchain name, a custom toolchain name, or a path
type LocalToolchainName = ToolchainName | PathBasedToolchainName

// A partial official toolchain name, or a custom toolchain name (like 'system')
type ResolvableToolchainName = PartialToolchainDesc | CustomToolchainName
// A partial official toolchain name, or a custom toolchain name, or a path
type ResolvableLocalToolchainName = ResolvableToolchainName | PathBasedToolchainName

... and it's particularly confusing that e.g. ResolvableToolchainName contains a PartialToolchainDesc. Now we just Partial* everything.

Every PartialFoo type has a .complete() method that converts it to Foo (cannot use std conversion due to extra context being required), where Foo can be a *ToolchainName or a TargetTuple.

Future work

The types themselves could also be unfolded or partially unfolded into their references, but that will be the concern of subsequent patches.

As for #5092 (comment), my plan is to actually repurpose ToolchainDesc as the trait name for ToolchainNameOrPath, ToolchainName, and OfficialToolchainName, but that will also be in a different patch after this.

Finally, the DistributableToolchain stuff can then become:

pub(crate) struct Toolchain<'a, T = ToolchainNameOrPath> { ... }
pub(crate) type OfficialToolchain<'a> = Toolchain<'a, OfficialToolchainName>;

[rustbot]

This PR was rebased onto a different main commit. Here's a range-diff highlighting what actually changed.

Rebasing is a normal part of keeping PRs up to date, so no action is needed—this note is just to help reviewers.

[djc]

Seems like an improvement!

View changes since this review

[djc]

Nit: move this before is_empty()?

[djc]

Not sure this name feels like an improvement? It is not a Name because it is identified in a different way, so it feels like a type name suffix that is different from existing ToolchainName types is warranted.

Also not sure I love Official as a distinguishing name segment. Maybe Project, or Upstream?

[rami3l]

@djc By "official toolchains", I am referring to the toolchains such as stable-x86_64-pc-windows-msvc that are:

• Fully qualified and have a canonical string representation
• Can be uniquely identified from a string
• Have the notion of channels and are downloadable from the release server
• Come with a modifiable component list (in v2 manifest mode)

The historical context is that this was the only kind of toolchain rustup used to support, so at that moment ToolchainDesc was acceptable. Fast forward to today, I believe we can at least agree that ToolchainDesc is definitely not an accurate name any more for this type of data.

As for the Name suffix, the first two points above should make it a reasonable Name regardless of the memory layout of this type.

I do feel a bit confused about your suggestions, ProjectToolchainName sounds like it's bound to a specific project directory, and UpstreamToolchainName implies that there is a downstream (maybe you are referring to the custom toolchains because they are self-hosted builds?), so I'm not quite sure if that will lead to simplifying my understanding of the whole hierarchy.

However, it is exactly your comment that inspired me into thinking more about this, and I realized that the most important thing to me here is that: I want to later link this name with DistributableToolchain, so it's better if I mention the channel or the release server (aka the "dist server" as it's called inside the codebase). How about DistributableToolchainName or DistToolchainName or ChanneledToolchainName? I'll mirror the prefix accordingly when it comes to the toolchain layer later.

Many thanks in advance for sharing your thoughts :)