Docs for Windows/MSVC toolchain: which workloads/components to install?

Describe the problem you are trying to solve

I'm trying to use a Visual Studio installer without GUI via command line parameters (in fact, from the chocolatey package), but there are so many options within Build Tools workload to choose from, none of which exactly match what rustup docs suggest (namely, "C++ tools").

I surely don't want to install everything, as there are some clearly unrelated things such as "Node.js build tools" or UWP, and also, as unfortunate as it is, my disk space is finite.

For example, the "Windows 10 SDK" requirement is simple. Just a search for "Windows 10 SDK" shows up 10 matches of the page. All of them are versioned as Microsoft.VisualStudio.Component.Windows10SDK.<numbers>, and actually searching for only Microsoft.VisualStudio.Component.Windows10SDK shows an exact match which is named differently as a "Windows Universal C Runtime" and is slightly outdated compared to half of explicitly versioned SDKs. Turned out, exact match is not what we need; see comments below.

Weirdly enough, "C++ tools" has no direct hits. But there's a "Desktop development with C++" workload (ID: Microsoft.VisualStudio.Workload.VCTools), and it still includes a lot of rubbish. ~~My best guess is Microsoft.VisualStudio.Component.VC.CoreBuildTools named "C++ Build Tools core features" and probably Microsoft.Component.MSBuild just for completeness, but I'm not sure.~~ Turned out, it's neither of them; see comments below.

Describe the solution you'd like

It would be nice to know which exact workloads/components Rust's MSVC toolchain really requires, preferably by their IDs. Maybe it would be a list of mutually exclusive equivalent components.

Notes

Windows 10, rustup v1.24.3, latest stable Rust v1.53.0.

My default toolchain is stable-x86_64-pc-windows-gnu, it works alright. Wanted to try stable-x86_64-pc-windows-msvc for a change.

Rustup documentation page in question: https://rust-lang.github.io/rustup/installation/other.html#msvc.

Related StackOverflow questions:

https://stackoverflow.com/questions/63390924/rust-link-exe-not-found

So far it looks like a was wrong about so many things in this life. *.VC.CoreBuildTools does not provide a linker (link.exe), and that version-less "Windows 10 SDK" stuff is just a C runtime without any notion of C++. What's with the naming, Microsoft? What's worse, Visual studio installer GUI just doesn't want you to know what exactly are you about to install: it will only show you the name but not the ID of components. But at least it has an option to export/import configuration, so let's dig into that.

First, I removed everything installed except the installer itself, exported config via this command (plus some awkward GUI interaction):

C:\Program Files (x86)\Microsoft Visual Studio\Installer> .\vs_installer.exe modify --installPath "C:\Program Files (x86)\Microsoft Visual Studio\2019\BuildTools"

and got this output in exported file:

{
  "version": "1.0",
  "components": [
    "Microsoft.VisualStudio.Component.Roslyn.Compiler",
    "Microsoft.Component.MSBuild",
    "Microsoft.VisualStudio.Component.CoreBuildTools",
    "Microsoft.VisualStudio.Workload.MSBuildTools"
  ]
}

so that's an empty, "bare" setup.

This is the list of components I tried next. Interestingly, both are marked as "Recommended" (not "Required") on a "Desktop development with C++" workload's list.

ID	Name	Version
`Microsoft.VisualStudio.Component.VC.Tools.x86.x64`	MSVC v142 - VS 2019 C++ x64/x86 build tools (Latest)	16.10.31205.252
`Microsoft.VisualStudio.Component.Windows10SDK.19041`	Windows 10 SDK (10.0.19041.0)	16.10.31205.252

Since VS Installer was already installed (sorry for tautology), I could use chocolatey's package install arguments anymore. So instead I used vs_installer.exe to modify existing stuff. Somehow, I didn't get a dedicated vs_buildtools.exe mentioned on the official documentation page, so I was forced to specify an --installPath manually — it wasn't needed for the initial installation though.

C:\Program Files (x86)\Microsoft Visual Studio\Installer> .\vs_installer.exe modify `
  --installPath "C:\Program Files (x86)\Microsoft Visual Studio\2019\BuildTools" `
  --add Microsoft.VisualStudio.Component.Windows10SDK.19041 `
  --add Microsoft.VisualStudio.Component.VC.Tools.x86.x64 `
  --passive

Which I should have been done from the beginning with the following:

C:\> choco install visualstudio2019buildtools --package-parameters "
  --add Microsoft.VisualStudio.Component.VC.Tools.x86.x64 
  --add Microsoft.VisualStudio.Component.Windows10SDK.19041
"

Half an hour and 4.5 GB later, I had a chance to export my current config. Here it is for anyone who wants to conveniently import it. Works with rust as usual, without the need to source any the build tools environment bat scripts. I intentionally stripped it down from "bare setup" to just the two components above, because (quoted) "This operation is additive and it won't remove any workload or component if they aren't present in the file".

Export

C:\Program Files (x86)\Microsoft Visual Studio\Installer> .\vs_installer.exe export `
  --installPath "C:\Program Files (x86)\Microsoft Visual Studio\2019\BuildTools" `
  --config $home\Documents\vsconfig-rust-msvc.json `
  --passive

Config itself (GitHub does not support json attachments in comments):

{
  "version": "1.0",
  "components": [
    "Microsoft.VisualStudio.Component.VC.Tools.x86.x64",
    "Microsoft.VisualStudio.Component.Windows10SDK.19041"
  ]
}

Import

C:\Program Files (x86)\Microsoft Visual Studio\Installer> .\vs_installer.exe modify `
  --installPath "C:\Program Files (x86)\Microsoft Visual Studio\2019\BuildTools" `
  --config $home\Downloads\vsconfig-rust-msvc.json `
  --passive

Wow this is a lot, thank you for doing that investigation. We want to give the shortest possible suggestions in our documentation so if there's any chance you can boil things down to a pithy small instruction sequence then that would be appreciated. @rbtcollins you're most likely to be able to judge whether or not things make sense, my Windows install is very very crusty / non-traditional these days.

So yeah, npm does some chocolatey thing that works well, copying that is where I'd probably start.

I'd also start by syncing with the main rustc docs, since we're downstream - an installer, not the owner of the toolchain definitions themselves.

I'll try to summarize my findings in a short concise bunch of if-else branches. But tomorrow. Sorry, not in the best shape right now.

So yeah, npm does some chocolatey thing that works well, copying that is where I'd probably start.

For those who haven't tried npm on Windows+chocolatey, can you please elaborate what do you mean?

We want to give the shortest possible suggestions in our documentation so if there's any chance you can boil things down to a pithy small instruction sequence then that would be appreciated.

I won't promise to give exhaustive instructions on my first attempt, but let me try. It's gonna be a bunch of if-else blocks.

https://drive.google.com/file/d/1mMEHAdlxCIWaRjPXOpAKu9No837v0soV/view?usp=sharing

Rendered: MSVC targets.pdf

Ping. Is this triaged / prioritized yet?

Hi @ratijas and thank you for your efforts on that diagram. Wow it looks complex and likely to need some maintenance since it includes versions of tools such as SDK 19041 or v142 of C++ tools. I think we'd need to make it a little more generic which, sadly, means we probably can't put the JSON together easily for our users.

I think we could convert a lot of that diagram into text instructions which could go nicely into our documentation though, so that's really good. The file in question which will have to contain that is https://github.com/rust-lang/rustup/blob/master/doc/src/installation/windows.md where currently we say:

rustup/doc/src/installation/windows.md

Lines 12 to 16 in 6d24d2f

    
           When targeting the MSVC ABI, Rust additionally requires an [installation of 
        
           Visual Studio 2013 (or later) or the Visual C++ Build Tools 2019][vs] so 
        
           `rustc` can use its linker. For Visual Studio, make sure to check the "C++ 
        
           tools" and "Windows 10 SDK" option. No additional software installation is 
        
           necessary for basic use of the GNU build.

Where the vs link is

https://github.com/rust-lang/rustup/blob/master/doc/src/installation/windows.md?plain=1#L69

We could expand that up into some more detailed instructions.

Wow it looks complex and likely to need some maintenance since it includes versions of tools such as SDK 19041 or v142 of C++ tools. I think we'd need to make it a little more generic which, sadly, means we probably can't put the JSON together easily for our users.

Unfortunately, that's because the process is really complex indeed. There's no single straightforward way which would work for everyone (e.g. steps are different depending on whether VS is already installed or not). That's why I suggest giving users some ideas where to start — but — if they know they need something more specific for their use case, thats means they are power users, and they probably don't need our advices anyway. Currently it only targets power users.

I genuinely lack techincal writing soft skills to finish this work. But if anything, I'd imagine installation page be like:

"Hi there! Dealing with MS Visual Studio might a bit complex, but don't get scared, and let us walk you through this process." And then present either plain text or interactive selection with some step-by-step instructions for each combination.

and likely to need some maintenance since it includes versions of tools such as SDK 19041 or v142 of C++ tools.

About maintenance in particular. Just like currently Cargo somehow finds MSVC build tools by looking at hardcoded paths (i can't find any other explanation), this would also need to be verified and updated for each VS version to come. I doubt that the next VS would be fully compatible with previous one anyway.

I think that diagram reflects many ways people can end up with the result; but we don't need to encode that to get either instructions or automation in place. By analogy, it is like describing every possible package manager: apt || rpm || dpkg || deselect || nix || yum || zypper || yast etc.

But we don't, and wouldn't: we describe using abstractions like 'using your package manager install the c library development headers'.

The vast majority of Windows developers install the necessary tools in a straight forward manner today. We should make it better by having the instructions be up to date with the latest changes from MS; and I would like us to actually invest in an automated solution.

As I said, NPM has an automated solution for the same problem; looking at that is what I think we should do.

By analogy, it is like describing every possible package manager: apt || rpm || dpkg || deselect || nix || yum || zypper || yast etc.

Except, in case of Linux package managers we can afford to expect users to know what they are doing. In Windows land this is often not the case, because nobody — literally nobody in the world understands how any of that works. During University years, I tried to bring Rust to some courses' team projects — and I tell you what: it was a pain to get people started on Windows.

As I said, NPM has an automated solution for the same problem; looking at that is what I think we should do.

Can you please describe in short what it does?

When you install npm on windows, you get the ms build tools automatically installed if you select the check box. I've mentioned twice that go and look at it is the needed action: If I knew exactly what it did, I wouldn't describe it as go and look at it, but instead would describe what it does.

@rbtcollins Thanks! I felt like it was important to write down here what are the effects of npm installer, and as a user (outsider) what did you like so much about it. So that even if I will try to install npm in Windows per your suggestion, I'd know specifically what to look for, long before digging into its implementation details. Honestly it's was a surprise for me that node has ecosystem for native addons.

It isn't a matter of trying the npm installer; it is a matter of reading the source code.

I feel like this is stalling for hilarious reason that no one wants to deal with npm installer :-\

Including me, that is.

We're a volunteer project; bugs move forward when volunteers volunteer time.

My time is currently going to fixing the problem with locked files during updates, and general project overheads.

If/when this bug becomes top of the pile for me, I will download the NPM source and figure out what exactly they do. If you want this to move forward, you can do that.

If you don't, thats fine too.

Today, I experienced similar issues as the original poster of this issue:
With the instructions provided by rustup-init.exe, I didn't really succeed with getting a Rust-compliant Visual C++ toolchain to work on my machine. I downloaded "Microsoft Build Tools for C++", selected the latest Windows 10 SDK, the latest English language pack, and the latest Visual C++ compiler, but with no effect. Eventually, I selected the "workload" for C++ desktop development.

I did take a look at the Node.js MSI installer. An automatic installation of the necessary Microsoft build tools seems to involve an installation of Chocolateley:

Further, they state that there are manual instructions that can be found here: https://github.com/nodejs/node-gyp#on-windows
Interestingly, these instructions also say that one should go with the C++ desktop workload:

Install tools and configuration manually:
Install Visual C++ Build Environment: Visual Studio Build Tools (using "Visual C++ build tools" workload) or Visual Studio Community (using the "Desktop development with C++" workload)
Launch cmd, npm config set msvs_version 2017

And even Microsoft recommends to install the C++ workload, toghether with two other workloads:
https://docs.microsoft.com/en-us/windows/dev-environment/rust/setup

Further, in the build instructions for Node.js, they talk about a Boxstarter script which - again - makes use of Chocolateley to automatically setup a Visual C++ environment:
https://github.com/nodejs/node/blob/main/BUILDING.md#option-2-automated-install-with-boxstarter

I am not sure, whether a fully automated installation of Rust that involves an installation of Chocolatey, is desirable for everyone. If somebody already has Chocolatey up and running on his machine, he / she can make use of the same Chocolatey packages as the Node community. But users who just want to with the VS Build Tools installer, should be told to simply go with the "Desktop development with C++" workload. Currently, this seems to be the most simple and most reliable way to go.

The specific workload name (and whether or not it installs the required components) has changed over time and with different installers. The docs should indeed by updated with the most useful and up to date information. Note though that non-English users may also need to install the English language pack. In short, this just needs someone to create a PR updating the docs.

Note that the next version of rustup will offer to auto-install if no Visual Studio is installed:

It's not however fully automatic due to feedback we got about licensing concerns,

I was going to prepare a pull request. But it seems as though, somebody else has already updated self_update.rs in master with respect to the necessary "Desktop development with C++" workload. However, I am not sure, whether the new instructions for users who want to select the individual componenty manually are going to work. I will give them a try, tomorrow.

I built "rustup-init.exe" from master and tested it on a Windows 10 machine that has never been exposed to Microsoft's build tools. The new instructions seem to work fine, now (even for the individual selection of components). In my opinion, this issue is no longer needed.

Hey I'm late to the discussion. I feel the same way about MS not so being friendly to developers but if someone has this problem in the future, try this:

The goal is to install "minimal" dependency/components without an full VS IDE installed ("minimal" here is relative. With a few clicks you can balance the "components just enough to make rustinit happy" and the effort you need to hack into VS install CLI). I've tried back and forth in "Individual Components" a few times to install a few seemingly required components but no luck..

Download the build tools here: https://visualstudio.microsoft.com/downloads/#build-tools-for-visual-studio-2022
Select the workload of "Desktop Development with C++" workload but on the right side, only keep these two optional boxes:

Select the workload of "Desktop Development with C++" workload but on the right side, only keep these two optional boxes …

Is there any way to reduce the minimal installation even further by selecting the "Individual components" tab (instead of "Workloads") and selecting just the linker and whatever? I wasn't expecting to have to have to install loads of Microsoft cruft just to program in Rust, so the more I can trim this down to only what is necessary, the better.

Another thing: the most recent VS Build Tools installer has a version of "Windows 11 SDK" selected by default instead of "Windows 10 SDK", even though I'm running on Windows 10. Should I go with the Windows 11 SDK—does that include support for Windows 10 as well?

It seems to me that this has been fixed.

https://github.com/rust-lang/rustup/blob/81a71647f4615d85267325b8dd8019a37e01f9fd/doc/user-guide/src/installation/windows-msvc.md now contains a rather detailed list of steps to follow if you'd like to install VS C++ build tools manually.

Please feel free to reopen if you believe that is not the case.

	When targeting the MSVC ABI, Rust additionally requires an [installation of
	Visual Studio 2013 (or later) or the Visual C++ Build Tools 2019][vs] so
	`rustc` can use its linker. For Visual Studio, make sure to check the "C++
	tools" and "Windows 10 SDK" option. No additional software installation is
	necessary for basic use of the GNU build.