Related Windows instructions out-of-sync

[sogaiu]

Intent

Making this issue to record a current issue which even if addressed might have bits that could benefit from upkeep. I haven't thought of a good solution, but figured that spelling out some details in one place might help in maintenance and/or possibly surface / lead to some improved approach.

Observations

On the page with installation instructions there are a couple of sections that have to do with Windows:

• https://janet-lang.org/docs/index.html#Windows
• https://janet-lang.org/docs/index.html#Windows-0

The former currently has this text:

you will also need to install Visual Studio, ideally a recent release (2019 or 2017 should work well). Then, running jpm from the x64 Native Tools Command Prompt should work for a 64-bit build, and from the Developer Command Prompt should work for 32-bit builds. Using these specific command prompts for jpm simply lets jpm use the Microsoft compiler to compile native modules on install.

the latter has (elided some bits):

1. Install [Visual Studio](https://visualstudio.microsoft.com/thank-you-downloading-visual-studio/?sku=Community&rel=15#) or [Visual Studio Build Tools](https://visualstudio.microsoft.com/thank-you-downloading-visual-studio/?sku=BuildTools&rel=15#)
2. Run a Visual Studio Command Prompt (cl.exe and link.exe need to be on the PATH)
...

To install from source, first follow the steps above, then you will need to

1. Install, or otherwise add to your PATH, the [WiX 3.11 Toolset](https://github.com/wixtoolset/wix3/releases)
2. Run a Visual Studio Command Prompt (cl.exe and link.exe need to be on the PATH)
...

There are a few things that are currently out-of-sync-ish:

• the version of visual studio / build tools -- 2017 and 2019 mentioned in one place while the link in the other seems to point to an older version but goes to a generic location(?)
• the name(s) of the relevant command prompts to use -- x64 Native Command Prompt for 64-bit and Developer Command Prompt for 32-bit are mentioned in one place but not spelled out in the other

Unfortunately, the former (the version info) seems to need upkeep as MS seems to be in the habit of placing older versions behind some login (at least that's what showed up for me before when I went looking for older things -- don't know how it is now).

Perhaps the latter stuff (the names of the command prompts) doesn't change much, but one of the two sections above might be too vague / confusing. AFAIK, Visual Studio Command Prompt (cl.exe and link.exe need to be on the PATH) doesn't point at a specific enough option.

For future reference, I came across this list of some / all of the command prompt shortcuts:

• Developer Command Prompt - Sets the environment to use 32-bit, x86-native tools to build 32-bit, x86-native code.
• x86 Native Tools Command Prompt - Sets the environment to use 32-bit, x86-native tools to build 32-bit, x86-native code.
• x64 Native Tools Command Prompt - Sets the environment to use 64-bit, x64-native tools to build 64-bit, x64-native code.
• x86_x64 Cross Tools Command Prompt - Sets the environment to use 32-bit, x86-native tools to build 64-bit, x64-native code.
• x64_x86 Cross Tools Command Prompt - Sets the environment to use 64-bit, x64-native tools to build 32-bit, x86-native code.

Possible Improvement

May be it makes sense to mention the version and prompt names in one section and then have some text in the other section that makes a reference to the section with the details. I think this would reduce out-of-sync issues at the cost of extra navigation [1].

---

[1] Where is my transclusion, Mr. Nelson?