Skip to content

Commit 1aac244

Browse files
dgp1130dgp1130
committed
docs(@angular/cli): Adds developer documentation.
I wrote down my understanding of the best ways to build/run/test/debug this repository. A couple other random things included here: * Removed an extraneous `debugger;` statement which I kept hitting. * Removed the `watch` scripts which are no longer used and don't need to be supported. * Removed `yarn test-cli-e2e`, as it alters the $PATH and can use the wrong `ng` instance.
1 parent c5671e0 commit 1aac244

File tree

5 files changed

+200
-7
lines changed

5 files changed

+200
-7
lines changed

‎README.md

+100-2
Original file line numberDiff line numberDiff line change
@@ -44,16 +44,114 @@ analyze your code.
4444
# Getting Started - Local Development
4545

4646
## Installation
47+
4748
To get started locally, follow these instructions:
4849

4950
1. If you haven't done it already, [make a fork of this repo](https://github.com/angular/angular-cli/fork).
5051
1. Clone to your local computer using `git`.
5152
1. Make sure that you have Node 10.13 or later installed. See instructions [here](https://nodejs.org/en/download/).
5253
1. Make sure that you have `yarn` installed; see instructions [here](https://yarnpkg.com/lang/en/docs/install/).
53-
1. Run `yarn` (no arguments) from the root of your clone of this project.
54-
1. Run `yarn link` to add all custom scripts we use to your global install.
54+
1. Run `yarn` (no arguments) from the root of your clone of this project to install dependencies.
55+
56+
## Building and Installing the CLI
57+
58+
To make a local build:
59+
60+
```shell
61+
yarn build --local
62+
```
63+
64+
This generates a number of tarballs in the `dist/` directory. To actually use
65+
the locally built tools, switch to another repository reproducing the specific
66+
issue you want to fix (or just generate a local repo with `ng new`). Then
67+
install the locally built packages:
68+
69+
```shell
70+
cd "${EXAMPLE_ANGULAR_PROJECT_REPO}"
71+
npm install -D ${CLI_REPO}/dist/*.tgz
72+
```
73+
74+
Builds of this example project will use tooling created from the previous local
75+
build and include any local changes. When using the CLI, it will automatically
76+
check for a local install and use that if present. This means you can just run:
77+
78+
```shell
79+
npm install -g @angular/cli
80+
```
81+
82+
to get a global install of the latest CLI release. Then running any `ng` command
83+
in the example project will automatically find and use the local build of the
84+
CLI.
85+
86+
Note: If you are testing `ng update`, be aware that installing all the tarballs
87+
will also update the framework (`@angular/core`) to the latest version. In this
88+
case, simply install the CLI alone with
89+
`npm install -D ${CLI_REPO}/dist/_angular_cli.tgz`, that way the rest of the
90+
project remains to be upgraded with `ng update`.
91+
92+
## Debugging
93+
94+
To debug an invocation of the CLI, [build and install the CLI for an example
95+
project](#building-and-installing-the-cli), then run the desired `ng` command
96+
as:
97+
98+
```shell
99+
node --inspect-brk node_modules/.bin/ng ...
100+
```
101+
102+
This will trigger a breakpoint as the CLI starts up. You can connect to this
103+
using the supported mechanisms for your IDE, but the simplest option is to open
104+
Chrome to [chrome://inspect](chrome://inspect) and then click on the `inspect`
105+
link for the `node_modules/.bin/ng` Node target.
106+
107+
Unfortunately, the CLI dynamically `require()`'s other files mid-execution, so
108+
the debugger is not aware of all the source code files before hand. As a result,
109+
it is tough to put breakpoints on files before the CLI loads them. The easiest
110+
workaround is to use the `debugger;` statement to stop execution in the file you
111+
are interested in, and then you should be able to step around and set breakpoints
112+
as expected.
113+
114+
## Testing
115+
116+
There are three different test suites which can be run locally:
117+
118+
* Unit tests
119+
* Run: `yarn test --full`
120+
* Debug: `yarn debug:test --full`
121+
* Large tests
122+
* Run: `yarn test-large --full`
123+
* Debug: `yarn debug:test-large --full`
124+
* End to end tests
125+
* Run: `node tests/legacy-cli/run_e2e.js`
126+
* Run subset of tests: `node tests/legacy-cli/run_e2e.js tests/legacy-cli/e2e/tests/i18n/ivy-localize-*`
127+
128+
When running the debug commands, Node will stop and wait for a debugger to
129+
attach. You can attach your IDE to the debugger to stop on breakpoints and step through the code. Also see [IDE Specific Usage](#ide-specific-usage) for a
130+
simpler debug story.
131+
132+
When debugging a specific test, change `describe()` or `it()` to `fdescribe()`
133+
and `fit()` to focus execution to just that one test. This will keep the output clean and speed up execution by not running irrelevant tests.
134+
135+
## IDE Specific Usage
136+
137+
Some additional tips for developing in specific IDEs.
138+
139+
### Intellij IDEA / WebStorm
140+
141+
To load the project in Intellij products, simply `Open` the repository folder.
142+
Do **not** `Import Project`, because that will overwrite the existing
143+
configuration.
144+
145+
Once opened, the editor should automatically detect run configurations in the
146+
workspace. Use the drop down to choose which one to run and then click the `Run`
147+
button to start it. When executing a debug target, make sure to click the
148+
`Debug` icon to automatically attach the debugger (if you click `Run`, Node will
149+
wait forever for a debugger to attach).
150+
151+
![Intellij IDEA run configurations](docs/images/run-configurations.png)
55152

56153
## Creating New Packages
154+
57155
Adding a package to this repository means running two separate commands:
58156

59157
1. `schematics devkit:package PACKAGE_NAME`. This will update the `.monorepo` file, and create the

‎docs/images/run-configurations.png

27.4 KB
Loading

‎package.json

-2
Original file line numberDiff line numberDiff line change
@@ -33,8 +33,6 @@
3333
"templates": "node ./bin/devkit-admin templates",
3434
"test": "node ./bin/devkit-admin test",
3535
"test-large": "node ./bin/devkit-admin test --large --spec-reporter",
36-
"test-cli-e2e": "node ./tests/legacy-cli/run_e2e",
37-
"test:watch": "nodemon --watch packages -e ts ./bin/devkit-admin test",
3836
"validate": "node ./bin/devkit-admin validate",
3937
"validate-commits": "./bin/devkit-admin validate-commits",
4038
"preinstall": "node ./tools/yarn/check-yarn.js",

‎scripts/templates/readme.ejs

+100-2
Original file line numberDiff line numberDiff line change
@@ -52,16 +52,114 @@ analyze your code.
5252
# Getting Started - Local Development
5353

5454
## Installation
55+
5556
To get started locally, follow these instructions:
5657

5758
1. If you haven't done it already, [make a fork of this repo](https://github.com/angular/angular-cli/fork).
5859
1. Clone to your local computer using `git`.
5960
1. Make sure that you have Node 10.13 or later installed. See instructions [here](https://nodejs.org/en/download/).
6061
1. Make sure that you have `yarn` installed; see instructions [here](https://yarnpkg.com/lang/en/docs/install/).
61-
1. Run `yarn` (no arguments) from the root of your clone of this project.
62-
1. Run `yarn link` to add all custom scripts we use to your global install.
62+
1. Run `yarn` (no arguments) from the root of your clone of this project to install dependencies.
63+
64+
## Building and Installing the CLI
65+
66+
To make a local build:
67+
68+
```shell
69+
yarn build --local
70+
```
71+
72+
This generates a number of tarballs in the `dist/` directory. To actually use
73+
the locally built tools, switch to another repository reproducing the specific
74+
issue you want to fix (or just generate a local repo with `ng new`). Then
75+
install the locally built packages:
76+
77+
```shell
78+
cd "${EXAMPLE_ANGULAR_PROJECT_REPO}"
79+
npm install -D ${CLI_REPO}/dist/*.tgz
80+
```
81+
82+
Builds of this example project will use tooling created from the previous local
83+
build and include any local changes. When using the CLI, it will automatically
84+
check for a local install and use that if present. This means you can just run:
85+
86+
```shell
87+
npm install -g @angular/cli
88+
```
89+
90+
to get a global install of the latest CLI release. Then running any `ng` command
91+
in the example project will automatically find and use the local build of the
92+
CLI.
93+
94+
Note: If you are testing `ng update`, be aware that installing all the tarballs
95+
will also update the framework (`@angular/core`) to the latest version. In this
96+
case, simply install the CLI alone with
97+
`npm install -D ${CLI_REPO}/dist/_angular_cli.tgz`, that way the rest of the
98+
project remains to be upgraded with `ng update`.
99+
100+
## Debugging
101+
102+
To debug an invocation of the CLI, [build and install the CLI for an example
103+
project](#building-and-installing-the-cli), then run the desired `ng` command
104+
as:
105+
106+
```shell
107+
node --inspect-brk node_modules/.bin/ng ...
108+
```
109+
110+
This will trigger a breakpoint as the CLI starts up. You can connect to this
111+
using the supported mechanisms for your IDE, but the simplest option is to open
112+
Chrome to [chrome://inspect](chrome://inspect) and then click on the `inspect`
113+
link for the `node_modules/.bin/ng` Node target.
114+
115+
Unfortunately, the CLI dynamically `require()`'s other files mid-execution, so
116+
the debugger is not aware of all the source code files before hand. As a result,
117+
it is tough to put breakpoints on files before the CLI loads them. The easiest
118+
workaround is to use the `debugger;` statement to stop execution in the file you
119+
are interested in, and then you should be able to step around and set breakpoints
120+
as expected.
121+
122+
## Testing
123+
124+
There are three different test suites which can be run locally:
125+
126+
* Unit tests
127+
* Run: `yarn test --full`
128+
* Debug: `yarn debug:test --full`
129+
* Large tests
130+
* Run: `yarn test-large --full`
131+
* Debug: `yarn debug:test-large --full`
132+
* End to end tests
133+
* Run: `node tests/legacy-cli/run_e2e.js`
134+
* Run subset of tests: `node tests/legacy-cli/run_e2e.js tests/legacy-cli/e2e/tests/i18n/ivy-localize-*`
135+
136+
When running the debug commands, Node will stop and wait for a debugger to
137+
attach. You can attach your IDE to the debugger to stop on breakpoints and step through the code. Also see [IDE Specific Usage](#ide-specific-usage) for a
138+
simpler debug story.
139+
140+
When debugging a specific test, change `describe()` or `it()` to `fdescribe()`
141+
and `fit()` to focus execution to just that one test. This will keep the output clean and speed up execution by not running irrelevant tests.
142+
143+
## IDE Specific Usage
144+
145+
Some additional tips for developing in specific IDEs.
146+
147+
### Intellij IDEA / WebStorm
148+
149+
To load the project in Intellij products, simply `Open` the repository folder.
150+
Do **not** `Import Project`, because that will overwrite the existing
151+
configuration.
152+
153+
Once opened, the editor should automatically detect run configurations in the
154+
workspace. Use the drop down to choose which one to run and then click the `Run`
155+
button to start it. When executing a debug target, make sure to click the
156+
`Debug` icon to automatically attach the debugger (if you click `Run`, Node will
157+
wait forever for a debugger to attach).
158+
159+
![Intellij IDEA run configurations](docs/images/run-configurations.png)
63160

64161
## Creating New Packages
162+
65163
Adding a package to this repository means running two separate commands:
66164

67165
1. `schematics devkit:package PACKAGE_NAME`. This will update the `.monorepo` file, and create the

‎tests/angular_devkit/schematics/tools/file-system-engine-host/extra-properties/factory.ts

-1
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,6 @@ import { SchematicContext, Tree } from '@angular-devkit/schematics';
1010

1111
export default function(options: {}) {
1212
return (tree: Tree, context: SchematicContext) => {
13-
debugger;
1413
// We pass information back to the test.
1514
tree.create(
1615
(context.schematic.description as any).extra, // tslint:disable-line:no-any

0 commit comments

Comments
 (0)