Streamline Windows installer page (#846)

* Separate instructions for older installers * Settle on Python 3.9 as recommended release
swiftlang · Nov 13, 2024 · 62007cd · 62007cd
1 parent e052dc4
commit 62007cd
Show file tree

Hide file tree

Showing 5 changed files with 107 additions and 22 deletions.
diff --git a/install/windows/traditional/index.md → install/windows/_archived.md b/install/windows/traditional/index.md → install/windows/_archived.md
@@ -1,13 +1,10 @@
----
-layout: page-wide
-title: Traditional Installation
----
+## Installation of Old Swift Releases
 
 <div class="warning" markdown="1">
-The traditional installation process is required for Swift older than 5.4.2.
+This page documents the manual installation process for versions of Swift 5.9 or older. Subsequent releases have updated dependencies and a [streamlined installation process](/install/windows/manual).
 </div>
 
-Swift has been tested with [Visual Studio](https://visualstudio.microsoft.com) 2019. You will need to install Visual Studio with the following components. The installer for Swift is available in the [Download](/install/windows) section. The toolchain on Windows is typically installed to `%SystemDrive%\Library\Developer\Toolchains`.
+Older versions of Swift have been tested with [Visual Studio](https://visualstudio.microsoft.com) 2019. You will need to install Visual Studio with the following components. Older installers for Swift are available in the [Download](/download/#:~:text=Older%20Releases) section. The toolchain on Windows is typically installed to `%SystemDrive%\Library\Developer\Toolchains`.
 
 The following Visual Studio components are **required**:
 
@@ -33,7 +30,7 @@ The following additional Visual Studio component is **suggested**:
 
 After Visual Studio and the required components are installed:
 
-0. Download a latest Swift release ([{{ site.data.builds.swift_releases.last.name }}](/install/windows)) or development [snapshot](/install/windows/#development-snapshots) installer.
+0. Download the required [older Swift release installer](/download/#:~:text=Older%20Releases).
 
 0. Run the package installer.
 
@@ -58,7 +55,7 @@ copy /Y %SDKROOT%\usr\share\visualc.apinotes "%VCToolsInstallDir%\include\visual
 copy /Y %SDKROOT%\usr\share\winsdk.modulemap "%UniversalCRTSdkDir%\Include\%UCRTVersion%\um\module.modulemap"
 ~~~
 
-Because it is installing the files into the Visual Studio image, the files will need to be copied each time Visual Studio is updated.
+Because the Windows SDK is typically installed as part of Visual Studio, these files may need to be copied each time Visual Studio is updated.
 
 ### Repairing after Visual Studio Updates
 
@@ -127,3 +124,5 @@ The following commands must be run in PowerShell.
 <div class="warning" markdown="1">
   If `gpg` fails to verify and reports "BAD signature", do not run the downloaded installer. Instead, please email <swift-infrastructure@forums.swift.org> with as much detail as possible, so that we can investigate the problem.
 </div>
+
+<hr>
diff --git a/install/windows/_manual.md b/install/windows/_manual.md
@@ -0,0 +1,36 @@
+## Install Windows platform dependencies
+
+Swift depends on a number of developer tools when running on Windows, including the C++ toolchain and the Windows SDK. On Windows, typically these components are installed with [Visual Studio](https://visualstudio.microsoft.com). 
+
+The following Visual Studio components should be installed:
+
+| Name | Component ID |
+|-----------|------------------|
+| MSVC v143 - VS 2022 C++ x64/x86 build tools (Latest)[^1] | Microsoft.VisualStudio.Component.VC.Tools.x86.x64 |
+| MSVC v143 - VS 2022 C++ ARM64/ARM64EC build tools (Latest)[^1] | Microsoft.VisualStudio.Component.VC.Tools.ARM64 |
+| Windows 11 SDK (10.0.22000.0)[^2] | Microsoft.VisualStudio.Component.Windows11SDK.22000 |
+
+[^1]: At minimum, Swift requires the build tools that match your machine architecture. Installing other architectures is recommended in order to cross-compile Swift binaries to run on different machine architectures.
+
+[^2]: You may install a newer SDK instead.
+
+You should also install the following dependencies:
+
+- [Python 3.9._x_](https://www.python.org/downloads/windows/) [^3]
+- [Git for Windows](https://git-scm.com/downloads/win)
+
+[^3]: You may install the latest `.x` patch release, but ensure you use the specified `major.minor` version of Python for optimal compatibility.
+
+## Enable Developer Mode
+
+Developer Mode enables debugging and other settings that are necessary for Swift development. Please see Microsoft’s [documentation](https://docs.microsoft.com/windows/apps/get-started/enable-your-device-for-development) for instructions about how to enable developer mode.
+
+## Install Swift
+
+After the above dependencies have been installed, [download and run the installer for the latest Swift stable release ({{ site.data.builds.swift_releases.last.name }}](/install/windows)). 
+
+Alternatively, you may prefer to install a [development snapshot](/install/windows/#development-snapshots) for access to features that are actively under development. 
+
+By default, the Swift binaries are installed to `%LocalAppData%\Programs\Swift`.
+
+<hr>
diff --git a/install/windows/_traditional.md → install/windows/archived/index.md b/install/windows/_traditional.md → install/windows/archived/index.md
@@ -1,19 +1,22 @@
-## Traditional Installation
+---
+layout: page-wide
+title: Installation of Old Swift Releases
+---
 
 <div class="warning" markdown="1">
-The traditional installation process is required for Swift older than 5.4.2.
+This page documents the manual installation process for versions of Swift 5.9 or older. Subsequent releases have updated dependencies and a [streamlined installation process](/install/windows/manual).
 </div>
 
-Swift has been tested with [Visual Studio](https://visualstudio.microsoft.com) 2019. You will need to install Visual Studio with the following components. The installer for Swift is available in the [Download](/download) section. The toolchain on Windows is typically installed to `%SystemDrive%\Library\Developer\Toolchains`.
+Older versions of Swift have been tested with [Visual Studio](https://visualstudio.microsoft.com) 2019. You will need to install Visual Studio with the following components. Older installers for Swift are available in the [Download](/download/#:~:text=Older%20Releases) section. The toolchain on Windows is typically installed to `%SystemDrive%\Library\Developer\Toolchains`.
 
 The following Visual Studio components are **required**:
 
 | Component | Visual Studio ID |
 |-----------|------------------|
 | MSVC v142 - VS 2019 C++ x64/x86 build tools (Latest) | Microsoft.VisualStudio.Component.VC.Tools.x86.x64 |
-| Windows 10 SDK (10.0.17763.0)[^2] | Microsoft.VisualStudio.Component.Windows10SDK.17763 |
+| Windows 10 SDK (10.0.17763.0)[^1] | Microsoft.VisualStudio.Component.Windows10SDK.17763 |
 
-[^2]: You may install a newer SDK instead.
+[^1]: You may install a newer SDK instead.
 
 The following additional Visual Studio components are **recommended**:
 
@@ -30,7 +33,7 @@ The following additional Visual Studio component is **suggested**:
 
 After Visual Studio and the required components are installed:
 
-0. Download a latest Swift release ([{{ site.data.builds.swift_releases.last.name }}](/download/#releases)) or development [snapshot](/download/#snapshots) installer.
+0. Download the required [older Swift release installer](/download/#:~:text=Older%20Releases).
 
 0. Run the package installer.
 
@@ -55,7 +58,7 @@ copy /Y %SDKROOT%\usr\share\visualc.apinotes "%VCToolsInstallDir%\include\visual
 copy /Y %SDKROOT%\usr\share\winsdk.modulemap "%UniversalCRTSdkDir%\Include\%UCRTVersion%\um\module.modulemap"
 ~~~
 
-Because it is installing the files into the Visual Studio image, the files will need to be copied each time Visual Studio is updated.
+Because the Windows SDK is typically installed as part of Visual Studio, these files may need to be copied each time Visual Studio is updated.
 
 ### Repairing after Visual Studio Updates
 
@@ -75,7 +78,7 @@ The following commands must be run in PowerShell.
 
 0. If you are downloading Swift packages **for the first time**, import the PGP keys into your keyring:
 
-{% assign all_keys_file = 'all-keys.asc' %}   
+{% assign all_keys_file = 'all-keys.asc' %}
 
    ~~~ powershell
    $ gpg.exe —keyserver hkp://keyserver.ubuntu.com `
@@ -124,3 +127,5 @@ The following commands must be run in PowerShell.
 <div class="warning" markdown="1">
 If `gpg` fails to verify and reports "BAD signature", do not run the downloaded installer. Instead, please email <swift-infrastructure@forums.swift.org> with as much detail as possible, so that we can investigate the problem.
 </div>
+
+<hr>
diff --git a/install/windows/index.md b/install/windows/index.md
@@ -12,23 +12,23 @@ title: Install Swift
 
 <ul class="grid-level-0 grid-layout-2-column">
   <li class="grid-level-1">
-    <h3>Package Manager</h3>
+    <h3>WinGet (recommended)</h3>
     <p class="description">
-      Install Swift via Windows Package Manager (aka WinGet).
+      Install Swift via the Windows Package Manager (also known as WinGet).
     </p>
     <a href="/install/windows/winget" class="cta-secondary">Instructions</a>
   </li>
   <li class="grid-level-1">
-    <h3>Package Installer</h3>
+    <h3>Manual Installation</h3>
     <p class="description">
-      Package installers (.exe).
+      Download the Swift installer (.exe).
     </p>
     <ul class="grid-level-0 grid-layout-2-column">
       {% for arch in platform.archs %}
       <a href="https://download.swift.org/{{ tag | downcase }}/windows10{% if arch != "x86_64" %}-{{ arch }}{% endif %}/{{ tag }}/{{ tag }}-windows10{% if arch != "x86_64" %}-{{ arch }}{% endif %}.exe" class="cta-secondary">Download ({{ arch }})</a>
       {% endfor %}
     </ul>
-    <a href="/install/windows/traditional" class="cta-secondary">Instructions</a>
+    <a href="/install/windows/manual" class="cta-secondary">Instructions</a>
   </li>
   <li class="grid-level-1">
     <h3>Scoop</h3>
@@ -86,7 +86,7 @@ Swift snapshots are prebuilt binaries that are automatically created from the br
     </ul>
   </li>
 </ul>
-<a href="/install/windows/traditional/" class="cta-secondary">Instructions</a>
+<a href="/install/windows/manual/" class="cta-secondary">Instructions</a>
 <details class="download" style="margin-bottom: 0;">
   <summary>Older Snapshots (main)</summary>
   {% include install/_older_snapshots.md builds=windows_dev_builds name="windows" platform_dir="windows10" branch_dir="development" %}
@@ -95,3 +95,7 @@ Swift snapshots are prebuilt binaries that are automatically created from the br
   <summary>Older Snapshots (release/6.0)</summary>
   {% include install/_older_snapshots.md builds=windows10_6_0_builds name="windows" platform_dir="windows10" branch_dir="swift-6.0-branch" %}
 </details>
+
+## Older Releases
+
+[Older releases of Swift](/download/#:~:text=Older%20Releases) are available for installation on Windows using the manual installer, [as documented here](/install/windows/archived).
diff --git a/install/windows/manual/index.md b/install/windows/manual/index.md
@@ -0,0 +1,41 @@
+---
+layout: page-wide
+title: Manual Installation
+---
+
+## Install Windows platform dependencies
+
+Swift depends on a number of developer tools when running on Windows, including the C++ toolchain and the Windows SDK. On Windows, typically these components are installed with [Visual Studio](https://visualstudio.microsoft.com). 
+
+The following Visual Studio components should be installed:
+
+| Name | Component ID |
+|-----------|------------------|
+| MSVC v143 - VS 2022 C++ x64/x86 build tools (Latest)[^1] | Microsoft.VisualStudio.Component.VC.Tools.x86.x64 |
+| MSVC v143 - VS 2022 C++ ARM64/ARM64EC build tools (Latest)[^1] | Microsoft.VisualStudio.Component.VC.Tools.ARM64 |
+| Windows 11 SDK (10.0.22000.0)[^2] | Microsoft.VisualStudio.Component.Windows11SDK.22000 |
+
+[^1]: At minimum, Swift requires the build tools that match your machine architecture. Installing other architectures is recommended in order to cross-compile Swift binaries to run on different machine architectures.
+
+[^2]: You may install a newer SDK instead.
+
+You should also install the following dependencies:
+
+- [Python 3.9._x_](https://www.python.org/downloads/windows/) [^3]
+- [Git for Windows](https://git-scm.com/downloads/win)
+
+[^3]: You may install the latest `.x` patch release, but ensure you use the specified `major.minor` version of Python for optimal compatibility.
+
+## Enable Developer Mode
+
+Developer Mode enables debugging and other settings that are necessary for Swift development. Please see Microsoft’s [documentation](https://docs.microsoft.com/windows/apps/get-started/enable-your-device-for-development) for instructions about how to enable developer mode.
+
+## Install Swift
+
+After the above dependencies have been installed, [download and run the installer for the latest Swift stable release ({{ site.data.builds.swift_releases.last.name }}](/install/windows)). 
+
+Alternatively, you may prefer to install a [development snapshot](/install/windows/#development-snapshots) for access to features that are actively under development. 
+
+By default, the Swift binaries are installed to `%LocalAppData%\Programs\Swift`.
+
+<hr>