From 066b28197945a18070faf556edcaeb13a7eb949a Mon Sep 17 00:00:00 2001 From: George Kalpakas Date: Tue, 27 Aug 2019 21:53:04 +0300 Subject: [PATCH] docs(docs-infra): add note about setting up examples on Windows (#32355) Closes #32321 PR Close #32355 --- aio/README.md | 9 +++++++++ aio/tools/examples/README.md | 14 +++++++++----- 2 files changed, 18 insertions(+), 5 deletions(-) diff --git a/aio/README.md b/aio/README.md index 9a55ad0820..b3144ed8db 100644 --- a/aio/README.md +++ b/aio/README.md @@ -46,6 +46,15 @@ Here are the most important tasks you might need to use: - `yarn example-e2e --filter=foo` - limit e2e tests to those containing the word "foo" - `yarn example-e2e --setup --local` - run e2e tests with the local version of Angular contained in the "dist" folder +> **Note for Windows users** +> +> Setting up the examples involves creating some [symbolic links](https://en.wikipedia.org/wiki/Symbolic_link) (see [here](./tools/examples/README.md#symlinked-node_modules) for details). On Windows, this requires to either have [Developer Mode enabled](https://blogs.windows.com/windowsdeveloper/2016/12/02/symlinks-windows-10) (supported on Windows 10 or newer) or run the setup commands as administrator. +> +> The affected commands are: +> - `yarn setup` / `yarn setup-*` +> - `yarn build` / `yarn build-*` +> - `yarn boilerplate:add` +> - `yarn example-e2e --setup` ## Using ServiceWorker locally diff --git a/aio/tools/examples/README.md b/aio/tools/examples/README.md index 22d712698c..1a0ccfa0be 100644 --- a/aio/tools/examples/README.md +++ b/aio/tools/examples/README.md @@ -11,6 +11,10 @@ their sub-folder. Also there are a number of common boilerplate files that are n each example's project. Maintain these common boilerplate files centrally to reduce the amount of effort if one of them needs to change. +> **Note for Windows users** +> +> Setting up the examples involves creating some [symbolic links](https://en.wikipedia.org/wiki/Symbolic_link) (see [here](#symlinked-node_modules) for details). On Windows, this requires to either have [Developer Mode enabled](https://blogs.windows.com/windowsdeveloper/2016/12/02/symlinks-windows-10) (supported on Windows 10 or newer) or run the setup commands as administrator. + ## Boilerplate overview As mentioned, many of the documentation pages contain snippets extracted from real example applications. @@ -52,16 +56,16 @@ This configuration file indicates what type of boilerplate this example needs. E If the file is empty then the default type of cli is assumed. When the boilerplate tooling runs, it will copy into the example folder all of the appropriate files based on the project type. + ### A node_modules to share With all the boilerplate files in place, the only missing piece are the installed packages. For that you have a `/aio/tools/examples/shared/package.json` which contains **all** the packages needed to run all the examples through all different boilerplates. -After installing these dependencies, a `node_modules` will be created at -`/aio/tools/examples/shared/node_modules`. This folder will be **symlinked** into each example. -So it is not a copy like the other boilerplate files. This solution works in all OSes. Windows -may require admin rights. +After installing these dependencies, a `node_modules/` folder will be created at +`/aio/tools/examples/shared/node_modules/`. This folder will be **symlinked** into each example. +So it is not a copy like the other boilerplate files. ### End to end tests @@ -103,4 +107,4 @@ With every major release, we update the examples to be on the latest version. Th * In the `shared/package.json` file, bump all the `@angular/*`, `@angular-devkit/*`, `rxjs`, `typescript`, and `zone.js` package versions to the version that corresponds with the [framework version](../../../package.json). * In the `shared` folder, run `yarn` to update the dependencies for the shared `node_modules` and the `yarn.lock` file. * In the `boilerplate` folder, go through each sub-folder and update the `package.json` dependencies if one is present. -* Follow the [update guide](./shared/boilerplate/UPDATING_CLI.md) to update the common files used in the examples based on project type. \ No newline at end of file +* Follow the [update guide](./shared/boilerplate/UPDATING_CLI.md) to update the common files used in the examples based on project type.