[docs][Windows] Add context and split doc into multiple files #14562

AndrewSB · 2018-02-12T18:54:16Z

@compnerd can you proof read this change?

xwu · 2018-02-12T20:18:12Z

docs/Windows.md

- Release/RelWithDebInfo modes have not been tested and may not be supported.
- Windows support for Swift is very much a work in progress and may not work on your system.
- Using the latest Visual Studio version is recommended. Swift may fail to build with older C++ compilers.
+NOTE: There is a limitation to building with MVSC: The Swift Runtime can't be


General comments:

Spelling: “separate,” not “seperate.”

Spelling: “Visual Studio,” not “VisualStudio.”

Style for written text is “Swift runtime” and “Swift standard library,” not “Swift Runtime” and “stdlib.”

troughton · 2018-02-12T20:36:23Z

docs/Windows.md

@@ -1,216 +1,29 @@
 # Getting Started with Swift on Windows

-## clang (cross-compiling)
+This document summarizes the state of Swift on Windows.


I don't think this comment adds anything to the reader.

troughton · 2018-02-12T20:36:44Z

docs/Windows.md

-export UniversalCRTSdkDir=".../Windows Kits/10"
-export VCToolsInstallDir=".../Microsoft Visual Studio/2017/Community"
-```
+Currently there are 3 supported ways to build Swift for Windows.


I think it's clearer to spell out 'three' here in full.

troughton · 2018-02-12T20:39:12Z

docs/Windows.md

-`${VCToolsInstallDir}/include`. The `ucrt.modulemap` located at
-`swift/stdlib/public/Platform/ucrt.modulemap` needs to be copied into
-`${UniversalCRTSdkDir}/Include/${UCRTVersion}/ucrt`.
+1. To cross-compile Swift for Windows from another host using `clang`, see


The idea of cross-compiling isn't particularly clear if you're not familiar with it, so it might be good to be more explicit here. Something like "to cross-compile Swift for Windows targets from a different host operating system", and maybe add a comment like "Windows Subsystem for Linux provides a convenient way to do this".

You do get into this in a bit more detail later, though, so up to you whether you agree for here.

troughton · 2018-02-12T20:39:39Z

docs/Windows.md

-```bash
--extra-cmake-options=-DSWIFT_BUILD_RUNTIME_WITH_HOST_COMPILER=FALSE,-DCMAKE_AR=<path to llvm-ar>,-DCMAKE_RANLIB=<path to llvm-ranlib>,-DSWIFT_SDKS=WINDOWS,-DSWIFT_WINDOWS_ICU_I18N_INCLUDE=<path to ICU i18n includes>,-DSWIFT_WINDOWS_ICU_UC_INCLUDE=<path to ICU UC includes>,-DSWIFT_WINDOWS_ICU_I18N_LIB=<path to ICU i18n lib>,-DSWIFT_WINDOWS_ICU_UC_LIB=<path to ICU UC lib>
-```
+1. To build on Windows using Microsoft Visual Studio Code (MVSC), see [Building


MSVC = Microsoft Visual Studio Compiler - Visual Studio Code is a different tool.

troughton · 2018-02-12T20:40:43Z

docs/Windows.md

- Windows support for Swift is very much a work in progress and may not work on your system.
- Using the latest Visual Studio version is recommended. Swift may fail to build with older C++ compilers.
+NOTE: There is a limitation to building with MVSC: The Swift Runtime can't be
+built.  So though it's possible to build the compiler and stdlib, and then


Nit: The first 'So though' should be 'Although', and there should be a comma, not a full stop, before the second 'so'.

troughton · 2018-02-12T20:43:27Z

docs/WindowsBuild.md

+1. Using Microsoft Visual Studio Code (MVSC)
+
+There is a limitation to building MVSC, the Swift Runtime can't be 
+built. So though it's possible to build the compiler and the stdlib, and use 


"There is a limitation to building MVSC, the Swift Runtime can't be built." -> "The Swift runtime can't be built using MSVC; although it's possible to build..."

troughton · 2018-02-12T20:45:13Z

docs/WindowsBuild.md

+There is a limitation to building MVSC, the Swift Runtime can't be 
+built. So though it's possible to build the compiler and the stdlib, and use 
+built products to compile a Swift program, it won't be possible to run the 
+binary without seperately obtaining the Swift Runtime. So the `clang-cl` method


Again: don't start the sentence with 'so'; if you want to do something like this, start with 'therefore' or 'as such'.

With that said, I'd move this sentence up to the start of the paragraph: "Using clang-cl is recommended over MSVC for building on Windows.", and then you go into the reasons why.

troughton · 2018-02-12T20:46:13Z

docs/WindowsBuild.md

+cmake --build "%swift_source_dir%/build/Ninja-DebugAssert/swift-windows-amd64/ninja"
+```
+
+- To create a VisualStudio project, you'll need to change the generator and, if you have a 64 bit processor, specify the generator platform. Note that you may get multiple build errors compiling the `swift` project due to an MSBuild limitation that file paths cannot exceed 260 characters. These can be ignored, as they occur after the build when writing the last build status to a file.


Nit: VisualStudio -> Visual Studio

troughton · 2018-02-12T20:47:44Z

docs/WindowsBuild.md

+
+## Clang-cl
+
+Follow the instructions for MSVC, but add the following lines to each CMake configuration command. `Clang-cl` 4.0.1 has been tested. You can remove the `SWIFT_BUILD_DYNAMIC_SDK_OVERLAY=FALSE` definition, as overlays are supported with `clang-cl`, as it supports modules. The `Z7` flag is required to produce PDB files that MSVC's `link.exe` can read, and also enables proper stack traces.


This is me editing my own change from a while back, but while you're here, could you change the last part of the sentence from ", and also enables proper stack traces." to " and enables proper stack traces." without the comma at the start?

troughton · 2018-02-12T20:49:31Z

docs/WindowsCrossCompile.md

+  -DSWIFT_SDKS=WINDOWS, \
+  -DSWIFT_WINDOWS_ICU_I18N_INCLUDE=<path to ICU i18n includes>, \
+  -DSWIFT_WINDOWS_ICU_UC_INCLUDE=<path to ICU UC includes>, \
+  -DSWIFT_WINDOWS_ICU_I18N_LIB=<path to ICU i18n lib>, \


These lines are outdated - I've been meaning to correct it for a while. The flags are now -DSWIFT_WINDOWS_ICU_I18N and -DSWIFT_WINDOWS_ICU_UC without the _LIB.

troughton · 2018-02-12T20:51:31Z

docs/WindowsSubsystemForLinux.md

@@ -0,0 +1,52 @@
+# Windows Subsystem for Linux (WSL)
+- Note that all compiled Swift binaries are only executable within Bash on Windows and are Ubuntu, not Windows, executables.


It might be useful here to clarify that we're talking about WSL in a native environment - something like "As well as being used as a cross-compile environment, Windows Subsystem for Linux can natively build and run Ubuntu executables."

troughton · 2018-02-12T20:58:22Z

I've gone through and added some minor editing and style comments. On the whole, though, thank you for doing this; it should help to make things a lot clearer.

I'll add a link here to my incomplete tutorial on how to use WSL for cross-compilation. I was hoping to finish fixing the final few build issues (e.g. around static linking) and submit that tutorial as a PR once the process was fairly smooth, but I unfortunately haven't had time yet; if any of that's useful for you to copy or adapt feel free to. If not, I'll finish it up myself once the compile issues have been completely sorted out.

AndrewSB · 2018-02-13T01:05:39Z

Thanks @xwu and @troughton 😄 I'll integrate these suggestions!

@troughton: right now I'm just working on getting builds working with clang-cl, but that doc looks really useful for cross compiling. Once it's ready, make a Pull Request targeting WindowsCrossCompile.md 👍

compnerd · 2018-02-17T17:48:58Z

docs/Windows.md

@@ -1,216 +1,32 @@
 # Getting Started with Swift on Windows

-## clang (cross-compiling)
+This document summarizes the state of Swift on Windows. One can build and run
+Swift natively, or through the Windows Subsystem for Linux.


I think that the fact that this document summarizes the state of Swift on Windows is implicit.

compnerd · 2018-02-17T17:49:57Z

docs/Windows.md

-```bash
--extra-cmake-options=-DSWIFT_BUILD_RUNTIME_WITH_HOST_COMPILER=FALSE,-DCMAKE_AR=<path to llvm-ar>,-DCMAKE_RANLIB=<path to llvm-ranlib>,-DSWIFT_SDKS=WINDOWS,-DSWIFT_WINDOWS_ICU_I18N_INCLUDE=<path to ICU i18n includes>,-DSWIFT_WINDOWS_ICU_UC_INCLUDE=<path to ICU UC includes>,-DSWIFT_WINDOWS_ICU_I18N_LIB=<path to ICU i18n lib>,-DSWIFT_WINDOWS_ICU_UC_LIB=<path to ICU UC lib>
-```
+1. To build on Windows using the Microsoft Visual Studio Compiler (MVSC), see


typo: MVSC -> MSVC

...and it stands for "Microsoft Visual C++"--not "Microsoft Visual Studio Compiler."

Sorry about that @AndrewSB - I was mistaken about the name and should’ve double checked.

compnerd · 2018-02-17T17:50:13Z

docs/Windows.md

- Release/RelWithDebInfo modes have not been tested and may not be supported.
- Windows support for Swift is very much a work in progress and may not work on your system.
- Using the latest Visual Studio version is recommended. Swift may fail to build with older C++ compilers.
+Using `clang-cl` is recommended over MVSC for building Swift on Windows.


Typo: MVSC -> MSVC

compnerd · 2018-02-17T17:50:24Z

docs/Windows.md

- Using the latest Visual Studio version is recommended. Swift may fail to build with older C++ compilers.
+Using `clang-cl` is recommended over MVSC for building Swift on Windows.
+Although it is possible to build the compiler and the standard library with
+MVSC, and use those built products to compile a Swift program, it won't be


compnerd · 2018-02-17T17:51:14Z

docs/WindowsBuild.md

+possible to run the binary without seperately obtaining the Swift runtime. On
+the other hand, `clang-cl` is able to build the runtime, which makes it
+possible to build and run all the components required for Swift natively on
+Windows.


typo: MVSC -> MSVC twice at lease

compnerd · 2018-02-17T17:52:56Z

docs/WindowsBuild.md

+- Make sure to include `Programming Languages|Visual C++` and `Windows and Web
+  Development|Universal Windows App Development|Windows SDK` in your
+  installation.
+- Windows SDK 10.0.10240 was tested. Some later versions (e.g. 10.0.14393) are


Not sure what compiler-rt has to do with this. compiler-rt definitely should be okay with 14393.

compnerd · 2018-02-17T17:55:12Z

docs/WindowsBuild.md

+- While the commands here use MSVC to build, using clang-cl is recommended (see
+  the **Clang-cl** section below).
+```cmd
+mkdir "%swift_source_dir%/build/Ninja-DebugAssert/swift-windows-amd64/ninja"


Please remove the extra ninja directory

doing this in a separate formatting PR, I have a list of 3-4 stylistic changes like this

compnerd · 2018-02-17T17:56:38Z

docs/WindowsCrossCompile.md

+## 1. Setup Visual Studio Environment Variables
+Building for Windows requires that the Visual Studio environment variables are
+setup similar to the values on Windows. The following assumes that
+`WINKIT_ROOT` points to the path where the Windows 10 SDK is available and that


WINKIT_ROOT and VC_ROOT are no longer used.

compnerd

There are a few comments strewn about

xwu

Looking good. Just a few copyedits.

xwu · 2018-02-21T01:19:48Z

docs/Windows.md

-`${VCToolsInstallDir}/include`. The `ucrt.modulemap` located at
-`swift/stdlib/public/Platform/ucrt.modulemap` needs to be copied into
-`${UniversalCRTSdkDir}/Include/${UCRTVersion}/ucrt`.
+1. To cross-compile Swift for Windows from another host Operating System (using


Sorry, minor nit: could you lowercase "Operating System" [sic]?

xwu · 2018-02-21T01:20:15Z

docs/Windows.md

- Using the latest Visual Studio version is recommended. Swift may fail to build with older C++ compilers.
+`clang-cl` is recommended over MSVC for building Swift on Windows.
+Although it is possible to build the compiler and the standard library with
+MSVC, and use those built products to compile a Swift program, it won't be


Nit: no comma after "MSVC"; you can add "to" (as in, "and to use") if you think it makes the sentence flow.

xwu · 2018-02-21T01:21:10Z

docs/Windows.md

-```
+On the [Windows Subsystem for
+Linux](https://docs.microsoft.com/en-us/windows/wsl/about), it's possible to
+build and run Swift in a Linux-like enviroment, on Windows. See [the


xwu · 2018-02-21T01:22:19Z

docs/WindowsBuild.md

+# Building Swift on Windows
+
+This document describes how to build Swift for Windows natively. See [the
+Windows doc](./Windows.md) for more about what is possible with Swift on


Nit: "Getting Started with Swift on Windows" is the name of that document, not "the Windows doc."

xwu · 2018-02-21T01:22:39Z

docs/WindowsBuild.md

+
+`clang-cl` is recommended over MSVC for building Swift on Windows.
+Although it is possible to build the compiler and the standard library with
+MSVC, and use those built products to compile a Swift program, it won't be


Ditto here about comma before "and."

xwu · 2018-02-21T01:31:40Z

docs/WindowsCrossCompile.md

+export VCToolsInstallDir=".../Microsoft Visual Studio/2017/Community"
+```
+
+## 2. Setup `visualc` and `ucrt` modules


...and here (also, sentence vs. title case).

xwu · 2018-02-21T01:33:29Z

docs/WindowsCrossCompile.md

@@ -0,0 +1,44 @@
+# Cross-compiling Swift for Windows with `clang`.


Consistency: Sentence ending in period or title case heading without period? It seems the latter choice fits with the rest of the document.

xwu · 2018-02-21T01:35:13Z

docs/WindowsSubsystemForLinux.md

+```
+
+### 3. Upgrade clang
+Install a version of clang with C++ 14 support - the default version of clang


Nit: semicolon, not dash.

xwu · 2018-02-21T01:35:28Z

docs/WindowsSubsystemForLinux.md

+```
+
+### 4. Upgrade CMake
+Install the latest version of CMake - Swift uses new CMake features such as


Ditto here about semicolon versus dash.

xwu · 2018-02-21T01:37:15Z

docs/WindowsCrossCompile.md

+
+## 3. Configure the runtime to be built with the just built clang
+Ensure that we use the tools from the just built LLVM and clang tools to build
+the Windows SDK. You will need to pass a few extra options to cmake via the


Consistency: "clang" or "Clang"? "cmake" or "CMake"?

I think the standard we should go for is clang and CMake

AndrewSB · 2018-02-21T04:33:52Z

Thanks for the proof read @xwu 👍 responded to one or two of your comments, and accepted the rest

compnerd · 2018-02-21T06:11:15Z

@swift-ci please test

compnerd · 2018-02-21T21:37:22Z

This is a pretty large improvement, I'm going to merge this, and further improvements can be follow ups I think.

xwu reviewed Feb 12, 2018

View reviewed changes

troughton reviewed Feb 12, 2018

View reviewed changes

AndrewSB force-pushed the who-needs-a-single-doc branch from b712454 to d4a9def Compare February 13, 2018 01:35

compnerd reviewed Feb 17, 2018

View reviewed changes

compnerd requested changes Feb 17, 2018

View reviewed changes

AndrewSB added 4 commits February 20, 2018 17:15

docs/Windows: Split doc into multiple files

dc10333

docs/WindowsCrossCompile: Fix ICU flags for Swift build

8d73c6d

docs/WindowsCrossCompile: Remove VS env vars that are no longer used

b9cbc63

docs/WindowsBuild: Remove incorrect comment about supported versions

9305156

AndrewSB force-pushed the who-needs-a-single-doc branch from d4a9def to 9305156 Compare February 21, 2018 01:16

AndrewSB mentioned this pull request Feb 21, 2018

docs/WindowsBuild: Reorder clang-cl & MSVC + Add MSVC Swift invocation #14764

Merged

xwu reviewed Feb 21, 2018

View reviewed changes

docs/Windows: Format and clarify documentation

6a8b1e2

AndrewSB force-pushed the who-needs-a-single-doc branch from 83d19c3 to 6a8b1e2 Compare February 21, 2018 04:33

compnerd approved these changes Feb 21, 2018

View reviewed changes

compnerd merged commit 03590d1 into swiftlang:master Feb 21, 2018

AndrewSB deleted the who-needs-a-single-doc branch July 24, 2020 06:47


		## Clang-cl

		Follow the instructions for MSVC, but add the following lines to each CMake configuration command. `Clang-cl` 4.0.1 has been tested. You can remove the `SWIFT_BUILD_DYNAMIC_SDK_OVERLAY=FALSE` definition, as overlays are supported with `clang-cl`, as it supports modules. The `Z7` flag is required to produce PDB files that MSVC's `link.exe` can read, and also enables proper stack traces.

		@@ -0,0 +1,52 @@
		# Windows Subsystem for Linux (WSL)
		- Note that all compiled Swift binaries are only executable within Bash on Windows and are Ubuntu, not Windows, executables.

		@@ -0,0 +1,44 @@
		# Cross-compiling Swift for Windows with `clang`.

[docs][Windows] Add context and split doc into multiple files #14562

[docs][Windows] Add context and split doc into multiple files #14562

Uh oh!

Conversation

AndrewSB commented Feb 12, 2018

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

troughton Feb 12, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

troughton commented Feb 12, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

AndrewSB commented Feb 13, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

compnerd left a comment

Choose a reason for hiding this comment

Uh oh!

xwu left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

xwu Feb 21, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

xwu Feb 21, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

troughton Feb 12, 2018 •

edited

Loading

troughton commented Feb 12, 2018 •

edited

Loading

AndrewSB commented Feb 13, 2018 •

edited

Loading

xwu Feb 21, 2018 •

edited

Loading

xwu Feb 21, 2018 •

edited

Loading