Update WindowsBuild.md

- remove numbers on steps, they get out of sync and auto-numbering headers doesn't work
- correct some header titles
- re-render the tree to be ascii pretty
- split out "one-time setup" from "getting started"
- fix invocation of cmake for toolchain
- fix libdispatch build rules
- convert libdispatch build rules to be copy-paste friendly
- add libdispatch test instructions

Author: compnerd

docs/WindowsBuild.md

@@ -2,13 +2,11 @@
 
 Visual Studio 2017 or newer is needed to build swift on Windows.
 
-## 1. Install dependencies
+## Install dependencies
 - Install the latest version of [Visual Studio](https://www.visualstudio.com/downloads/)
-- Make sure to include "Programming Languages|Visual C++" and "Windows and Web
-  Development|Universal Windows App Development|Windows SDK" in your
-  installation.
+- Make sure to include "Programming Languages|Visual C++" and "Windows and Web Development|Universal Windows App Development|Windows SDK" in your installation.
 
-## 1. Clone the repositories
+## Clone the repositories
 1. Clone `apple/llvm-project` into a directory for the toolchain
 1. Clone `apple/swift-cmark`, `apple/swift`, `apple/swift-corelibs-libdispatch`, `apple/swift-corelibs-foundation`, `apple/swift-corelibs-xctest`, `apple/swift-llbuild`, `apple/swift-package-manager` into the toolchain directory
 1. Clone `compnerd/windows-swift` as a peer of the toolchain directory
@@ -34,19 +32,24 @@ git clone -c core.autocrlf=input https://github.com/apple/swift-package-manager
 git clone https://github.com/compnerd/windows-swift windows-swift
 ```
 
-## 1. Acquire ICU, SQLite3, curl, libxml2
+## Acquire ICU, SQLite3, curl, libxml2, zlib
 1. Go to https://dev.azure.com/compnerd/windows-swift and scroll down to "Dependencies" where you'll see bots (hopefully green) for icu, SQLite, curl, and libxml2. Download each of the zip files and copy their contents into S:/Library. The directory structure should resemble:
 
 ```
-S:/Library/
-          /icu-64/usr
-          /libcurl-development/usr
-          /libxml2-development/usr
-          /sqlite-3.28.0/usr
-          /zlib-1.2.11/usr
+/Library
+  ┝ icu-64
+  │   ┕ usr/...
+  ├ libcurl-development
+  │   ┕ usr/...
+  ├ libxml2-development
+  │   ┕ usr/...
+  ├ sqlite-3.28.0
+  │   ┕ usr/...
+  ┕ zlib-1.2.11
+      ┕ usr/...
 ```
 
-## 1. Get ready
+## Get ready
 - From within a **NATIVE developer** command prompt (not PowerShell nor cmd, but the [Visual Studio Developer Command Prompt](https://msdn.microsoft.com/en-us/library/f35ctcxw.aspx)), execute the following command if you have an x64 PC (The Native Developer command prompt is situated at "C:\ProgramData\Microsoft\Windows\Start Menu\Programs\Visual Studio 2019\Visual Studio Tools\VC\x64 Native Tools Command Prompt for VS 2019.lnk").
 
 Run this as administrator the first time, for setting up the symlinks below. 
@@ -62,6 +65,7 @@ VsDevCmd -arch=x86
   (`Debug`, `RelWithDebInfoAssert` or `Release`) to avoid conflicts between the debug and 
   non-debug version of the MSCRT library.
 
+## One-time Setup (re-run on Visual Studio upgrades)
 - Set up the `ucrt`, `visualc`, and `WinSDK` modules by copying  `ucrt.modulemap` located at
   `swift/stdlib/public/Platform/ucrt.modulemap` into
   `${UniversalCRTSdkDir}/Include/${UCRTVersion}/ucrt` as `module.modulemap`, copying `visualc.modulemap` located at `swift/stdlib/public/Platform/visualc.modulemap` into `${VCToolsInstallDir}/include` as `module.modulemap`, and copying `winsdk.modulemap` located at `swift/stdlib/public/Platform/winsdk.modulemap` into `${UniversalCRTSdkDir}/Include/${UCRTVersion}/um` and setup the `visualc.apinotes` located at `swift/stdlib/public/Platform/visualc.apinotes` into `${VCToolsInstallDir}/include` as `visualc.apinotes`
@@ -75,12 +79,12 @@ mklink "%VCToolsInstallDir%\include\visualc.apinotes" S:\swift\stdlib\public\Pla
 
 Warning: Creating the above links usually requires administrator privileges. The quick and easy way to do this is to open a second developer prompt by right clicking whatever shortcut you used to open the first one, choosing Run As Administrator, and pasting the above commands into the resulting window. You can then close the privileged prompt; this is the only step which requires elevation.
 
-## 1. Build toolchain
+## Build the toolchain
 - This must be done from within a developer command prompt. Make sure that the build type for LLVM/Clang is compatible with the build type for Swift. That is, either build everything `Debug` or some variant of `Release` (e.g. `Release`, `RelWithDebInfo`).
 
 ```cmd
 md "S:\b\toolchain"
-cmake -B "S:\b\toolchain" -G Ninja -C S:\windows-swift\cmake\caches\Windows-x86_64.cmake -C S:\windows-swift\cmake\caches\org.compnerd.dt.cmake -DLLVM_ENABLE_ASSERTIONS=YES -DLLVM_ENABLE_PROJECTS="clang;clang-tools-extra;cmark;swift;lldb" -DLLVM_EXTERNAL_PROJECTS="cmark;swift" -DSWIFT_PATH_TO_LIBDISPATCH_SOURCE=S:\llvm-project\swift-corelibs-libdispatch -DLLVM_ENABLE_PDB=YES -DLLDB_DISABLE_PYTHON=YES -DSWIFT_WINDOWS_x86_64_ICU_UC_INCLUDE="S:/Library/icu-64/usr/include" -DSWIFT_WINDOWS_x86_64_ICU_UC="S:/Library/icu-64/usr/lib/icuuc64.lib" -DSWIFT_WINDOWS_x86_64_ICU_I18N_INCLUDE="S:/Library/icu-64/usr/include" -DSWIFT_WINDOWS_x86_64_ICU_I18N="S:/Library/icu-64/usr/lib/icuin64.lib" -DCMAKE_INSTALL_PREFIX="C:\Library\Developer\Toolchains\unknown-Asserts-development.xctoolchain\usr" -DPYTHON_EXECUTABLE=C:\Python27\python.exe
+cmake -B "S:\b\toolchain" -G Ninja -S S:\toolchain\llvm -C S:\windows-swift\cmake\caches\Windows-x86_64.cmake -C S:\windows-swift\cmake\caches\org.compnerd.dt.cmake -DLLVM_ENABLE_ASSERTIONS=YES -DLLVM_ENABLE_PROJECTS="clang;clang-tools-extra;cmark;swift;lldb;lld" -DLLVM_EXTERNAL_PROJECTS="cmark;swift" -DSWIFT_PATH_TO_LIBDISPATCH_SOURCE=S:\llvm-project\swift-corelibs-libdispatch -DLLVM_ENABLE_PDB=YES -DLLDB_DISABLE_PYTHON=YES -DSWIFT_WINDOWS_x86_64_ICU_UC_INCLUDE="S:/Library/icu-64/usr/include" -DSWIFT_WINDOWS_x86_64_ICU_UC="S:/Library/icu-64/usr/lib/icuuc64.lib" -DSWIFT_WINDOWS_x86_64_ICU_I18N_INCLUDE="S:/Library/icu-64/usr/include" -DSWIFT_WINDOWS_x86_64_ICU_I18N="S:/Library/icu-64/usr/lib/icuin64.lib" -DCMAKE_INSTALL_PREFIX="C:\Library\Developer\Toolchains\unknown-Asserts-development.xctoolchain\usr" -DPYTHON_EXECUTABLE=C:\Python27\python.exe -DSWIFT_BUILD_DYNAMIC_STDLIB=YES -DSWIFT_BUILD_DYNAMIC_SDK_OVERLAY=YES
 ninja -C S:\b\toolchain
 ```
 
@@ -90,7 +94,7 @@ ninja -C S:\b\toolchain
 path S:\b\toolchain\bin;%PATH%
 ```
 
-## 1. Running tests on Windows
+## Running tests on Windows
 
 Running the testsuite on Windows has additional external dependencies.
 
@@ -99,28 +103,25 @@ path S:\Library\icu-64\usr\bin;S:\b\toolchain\bin;S:\b\toolchain\libdispatch-pre
 ninja -C S:\b\toolchain check-swift
 ```
 
-## 1. Build swift-corelibs-libdispatch
+## Build swift-corelibs-libdispatch
 
 ```cmd
-md "S:\b\libdispatch"
-cd "S:\b\libdispatch"
-cmake -G Ninja^
-  -DCMAKE_BUILD_TYPE=RelWithDebInfo^
-  -DCMAKE_C_COMPILER=clang-cl^
-  -DCMAKE_CXX_COMPILER=clang-cl^
-  -DCMAKE_SWIFT_COMPILER=S:\b\toolchain\bin\swiftc.exe^
-  -DENABLE_SWIFT=ON^
-  -DENABLE_TESTING=OFF^
-  S:\toolchain\swift-corelibs-libdispatch
-ninja
+cmake -B S:\b\libdispatch -G Ninja -S S:\toolchain\swift-corelibs-libdispatch -DCMAKE_BUILD_TYPE=RelWithDebInfo -DCMAKE_C_COMPILER=clang-cl -DCMAKE_CXX_COMPILER=clang-cl -DCMAKE_Swift_COMPILER=S:\b\toolchain\bin\swiftc.exe -DENABLE_SWIFT=YES
+ninja -C S:\b\libdispatch
 ```
 
 - Add libdispatch to your path:
 ```cmd
 path S:\b\libdispatch;S:\b\libdispatch\src;%PATH%
 ```
 
-## 1. Build swift-corelibs-foundation
+## Test swift-corelibs-libdispatch
+
+```cmd
+ninja -C S:\b\libdispatch check
+```
+
+## Build swift-corelibs-foundation
 
 ```cmd
 md "S:\b\foundation"
@@ -146,7 +147,7 @@ ninja
 path S:\b\foundation;%PATH%
 ```
 
-## 1. Build swift-corelibs-xctest
+## Build swift-corelibs-xctest
 
 ```cmd
 md "S:\b\xctest"
@@ -169,13 +170,13 @@ ninja
 path S:\b\xctest;%PATH%
 ```
 
-## 1. Test XCTest
+## Test XCTest
 
 ```cmd
 ninja -C S:\b\xctest check-xctest
 ```
 
-## 1. Rebuild Foundation
+## Rebuild Foundation
 
 ```cmd
 cd "S:\b\foundation
@@ -196,14 +197,14 @@ cmake -G Ninja^
 ninja
 ```
 
-## 1. Test Foundation
+## Test Foundation
 
 ```cmd
 cmake --build S:\b\foundation
 ninja -C S:\b\foundation test 
 ```
 
-## 1. Build llbuild
+## Build llbuild
 
 ```cmd
 md S:\b\llbuild
@@ -228,15 +229,15 @@ ninja
 path S:\b\llbuild\bin;%PATH%
 ```
 
-## 1. Build swift-package-manager
+## Build swift-package-manager
 
 ```cmd
 md S:\b\spm
 cd S:\b\spm
 C:\Python27\python.exe S:\swift-package-manager\Utilities\bootstrap --foundation S:\b\foundation --libdispatch-build-dir S:\b\libdispatch --libdispatch-source-dir S:\swift-corelibs-libdispatch --llbuild-build-dir S:\b\llbuild --llbuild-source-dir S:\llbuild --sqlite-build-dir S:\b\sqlite --sqlite-source-dir S:\sqlite-amalgamation-3270200
 ```
 
-## 1. Install Swift on Windows
+## Install Swift on Windows
 
 - Run ninja install: