From d50ec0f3782fcf8bb2ba2bf85006264a4d49ef62 Mon Sep 17 00:00:00 2001 From: Gaurav Munjal Date: Tue, 2 Oct 2018 15:39:42 -0400 Subject: [PATCH 1/3] Port over Windows support --- guides/basic-use/index.md | 3 +- guides/reference/windows.md | 84 ++++++++++++++++++++++++++++++++++++- 2 files changed, 85 insertions(+), 2 deletions(-) diff --git a/guides/basic-use/index.md b/guides/basic-use/index.md index 4b035ac..f838ffc 100644 --- a/guides/basic-use/index.md +++ b/guides/basic-use/index.md @@ -34,7 +34,8 @@ If Watchman is not installed, a notice is displayed when invoking various comman ### Installing for Windows - +Windows Vista and newer Windows versions are fully supported, although there are steps you can take to improve your experience. +You can find more information about this in our section on [Windows support](../reference/windows) ## Getting help diff --git a/guides/reference/windows.md b/guides/reference/windows.md index f6ce261..1c34f0b 100644 --- a/guides/reference/windows.md +++ b/guides/reference/windows.md @@ -1 +1,83 @@ - \ No newline at end of file +Windows Vista and newer windows versions are fully supported. + +To get started ensure the following dependencies are installed: + +* Node.js - [https://nodejs.org/en/](https://nodejs.org/en/) +* Git - [https://git-scm.com/](https://git-scm.com/) +* Phantom.js - [http://phantomjs.org/](http://phantomjs.org/) + +### Performance + +Although supported, Windows performance, at least by default, isn't as good as +on Linux or MacOS. On a positive note, this story continues to improve. Both +Microsoft, and the Ember CLI team continue to work to improve these developer +ergonomics. + +#### What causes the build slowdown? + +The two primary reasons are: + +* Lack of enabled-by-default symlinks +* Generally slower FS operations on NTFS + +#### For the best possible Windows experience + +* Windows 10, insiders release with development mode enabled. Symlinks are enabled + by default) [Details from + Microsoft](https://blogs.windows.com/buildingapps/2016/12/02/symlinks-windows-10/) +* or, Windows Subsystem Linux [Installation + Guide](https://msdn.microsoft.com/en-us/commandline/wsl/install_guide) + +#### Improving your Windows experience + +Ensure Search and Defender ignore your project's `tmp` directory: + +```bash +npm install --save-dev ember-cli-windows-addon +``` + +Then, to start the automatic configuration, run: + +```bash +ember windows +``` + +[Read more about this from the Microsoft DX Open Source team](http://felixrieseberg.com/improved-ember-cli-performance-with-windows/) + +### Enabling symlinks + +To create symlinks the account running Ember CLI must have the +`SeCreateSymbolicLinkPrivilege`. Users in the Administrators group have this +permission already. However, if UAC (User Access Control) is enabled, users in +the Administrators group must run their shell using Run As Administrator +because UAC strips away certain permissions from the Administrators +group, +including `SeCreateSymbolicLinkPrivilege`. + +![Run As Administrator]({{ site.url }}/assets/images/common-issues/run-as-admin.png) + +If the user account is not part of the Administrators group you will need to +add the `SeCreateSymbolicLinkPrivilege` to allow the creation of symlinks. To +do this open the `Local Security Policy` by typing Local Security Policy in the +Windows `Run` Box. + +Under `Local Policies` -> `User Rights Assignment` find the `Create symbolic +links` policy and double click it to add a new user or group. Once your user or +group has been added, your user should be able to create symlinks. Keep in mind +if your user is part of the Administrators group and UAC is enabled you will +still need to start your shell using `Run as Administrator`. + +![Enabling Symlinks]({{ site.url }}/assets/images/common-issues/enabling-symlinks.png) + +### Issues With npm: `EEXISTS`, Path too Long, etc + +There were always two major issues with running Node.js on Windows: first and +foremost, the operating system maintains a maximum length for path names, which +clashes with Node's traditional way of nesting modules in `node_modules`. The +second issue was a bit more subtle: The npm installer had a set of steps it +executed for each package and it would immediately start executing them as soon +as it decided to act on a package resulting in hard-to-debug race conditions. + +`npm` 3 is a nearly complete rewrite of `npm`, fixing both issues. Windows users of +Ember Cli might want to make the switch to `npm` 3 to benefit from its +flat module installation (solving most issues involving long path names) as well +as its multi-stage installer. From b992eb258071cfab71fbf7e102f7686367b6ea6a Mon Sep 17 00:00:00 2001 From: Gaurav Munjal Date: Wed, 3 Oct 2018 09:37:55 -0400 Subject: [PATCH 2/3] Updates based on comments --- guides/reference/windows.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/guides/reference/windows.md b/guides/reference/windows.md index 1c34f0b..5ee129e 100644 --- a/guides/reference/windows.md +++ b/guides/reference/windows.md @@ -1,16 +1,16 @@ -Windows Vista and newer windows versions are fully supported. +Windows Vista and newer Windows versions are fully supported. To get started ensure the following dependencies are installed: * Node.js - [https://nodejs.org/en/](https://nodejs.org/en/) * Git - [https://git-scm.com/](https://git-scm.com/) -* Phantom.js - [http://phantomjs.org/](http://phantomjs.org/) +* Chrome - [https://www.google.com/chrome/](https://www.google.com/chrome/) ### Performance Although supported, Windows performance, at least by default, isn't as good as on Linux or MacOS. On a positive note, this story continues to improve. Both -Microsoft, and the Ember CLI team continue to work to improve these developer +Microsoft, and the Ember CLI team continue to work on improving these developer ergonomics. #### What causes the build slowdown? From 7c04949a1b6182b07e3b9bc6629084e844440b29 Mon Sep 17 00:00:00 2001 From: Gaurav Munjal Date: Wed, 3 Oct 2018 10:09:28 -0400 Subject: [PATCH 3/3] Update based on Chris Krycho's comments. --- guides/reference/windows.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/guides/reference/windows.md b/guides/reference/windows.md index 5ee129e..397812b 100644 --- a/guides/reference/windows.md +++ b/guides/reference/windows.md @@ -22,10 +22,7 @@ The two primary reasons are: #### For the best possible Windows experience -* Windows 10, insiders release with development mode enabled. Symlinks are enabled - by default) [Details from - Microsoft](https://blogs.windows.com/buildingapps/2016/12/02/symlinks-windows-10/) -* or, Windows Subsystem Linux [Installation +* Use Windows Subsystem Linux [Installation Guide](https://msdn.microsoft.com/en-us/commandline/wsl/install_guide) #### Improving your Windows experience @@ -33,15 +30,18 @@ The two primary reasons are: Ensure Search and Defender ignore your project's `tmp` directory: ```bash -npm install --save-dev ember-cli-windows-addon +npm install -g ember-cli-windows ``` Then, to start the automatic configuration, run: ```bash -ember windows +ember-cli-windows ``` +*Make sure you use an elevated PowerShell.* +If there was an error, try executing Set-ExecutionPolicy Unrestricted -scope Process first. + [Read more about this from the Microsoft DX Open Source team](http://felixrieseberg.com/improved-ember-cli-performance-with-windows/) ### Enabling symlinks