Skip to content

Commit 40fb1a1

Browse files
alan-agius4dgp1130
alan-agius4
authored and
dgp1130
committed
docs: move developer guide into a seperate file
Currently, the `readme.md` also contains information on how to build and test the CLI which isn't useful to most users. With this change we move this information into a seperate document.
1 parent c47195a commit 40fb1a1

File tree

3 files changed

+123
-244
lines changed

3 files changed

+123
-244
lines changed

‎README.md

-122
Original file line numberDiff line numberDiff line change
@@ -41,128 +41,6 @@ Angular DevKit.
4141
DevKit's goal is to provide a large set of libraries that can be used to manage, develop, deploy and
4242
analyze your code.
4343

44-
# Getting Started - Local Development
45-
46-
## Installation
47-
48-
To get started locally, follow these instructions:
49-
50-
1. If you haven't done it already, [make a fork of this repo](https://github.com/angular/angular-cli/fork).
51-
1. Clone to your local computer using `git`.
52-
1. Make sure that you have Node 12.14 or 14.0 installed. See instructions [here](https://nodejs.org/en/download/).
53-
1. Make sure that you have `yarn` installed; see instructions [here](https://yarnpkg.com/lang/en/docs/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 two different test suites which can be run locally:
117-
118-
### Unit tests
119-
* Run all tests: `yarn bazel test //packages/...`
120-
* Run a subset of the tests, use the full Bazel target example: `yarn bazel test //packages/schematics/angular:angular_test`
121-
* For a complete list of test targets use the following Bazel query: `yarn bazel query "tests(//packages/...)"`
122-
123-
You can find more info about debugging [tests with Bazel in the docs.](https://github.com/angular/angular-cli/blob/master/docs/process/bazel.md#debugging-jasmine_node_test)
124-
125-
### End to end tests
126-
* Run: `node tests/legacy-cli/run_e2e.js`
127-
* Run a subset of the tests: `node tests/legacy-cli/run_e2e.js tests/legacy-cli/e2e/tests/i18n/ivy-localize-*`
128-
129-
When running the debug commands, Node will stop and wait for a debugger to attach.
130-
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
131-
simpler debug story.
132-
133-
When debugging a specific test, change `describe()` or `it()` to `fdescribe()`
134-
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.
135-
136-
## IDE Specific Usage
137-
138-
Some additional tips for developing in specific IDEs.
139-
140-
### Intellij IDEA / WebStorm
141-
142-
To load the project in Intellij products, simply `Open` the repository folder.
143-
Do **not** `Import Project`, because that will overwrite the existing
144-
configuration.
145-
146-
Once opened, the editor should automatically detect run configurations in the
147-
workspace. Use the drop down to choose which one to run and then click the `Run`
148-
button to start it. When executing a debug target, make sure to click the
149-
`Debug` icon to automatically attach the debugger (if you click `Run`, Node will
150-
wait forever for a debugger to attach).
151-
152-
![Intellij IDEA run configurations](docs/images/run-configurations.png)
153-
154-
## Creating New Packages
155-
156-
Adding a package to this repository means running two separate commands:
157-
158-
1. `schematics devkit:package PACKAGE_NAME`. This will update the `.monorepo` file, and create the
159-
base files for the new package (package.json, src/index, etc).
160-
1. `devkit-admin templates`. This will update the README and all other template files that might
161-
have changed when adding a new package.
162-
163-
For private packages, you will need to add a `"private": true` key to your package.json manually.
164-
This will require re-running the template admin script.
165-
16644
# Packages
16745

16846
This is a monorepo which contains many tools and packages:

‎docs/DEVELOPER.md

+123
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,123 @@
1+
# Building and Testing Angular CLI
2+
3+
## Installation
4+
5+
To get started locally, follow these instructions:
6+
7+
1. If you haven't done it already, [make a fork of this repo](https://github.com/angular/angular-cli/fork).
8+
1. Clone to your local computer using `git`.
9+
1. Make sure that you have Node `v12.20`, `v14.15`, or `v16.10` installed. See instructions [here](https://nodejs.org/en/download/).
10+
1. Make sure that you have `yarn` installed; see instructions [here](https://yarnpkg.com/lang/en/docs/install/).
11+
1. Run `yarn` (no arguments) from the root of your clone of this project to install dependencies.
12+
13+
## Building and Installing the CLI
14+
15+
To make a local build:
16+
17+
```shell
18+
yarn build --local
19+
```
20+
21+
This generates a number of tarballs in the `dist/` directory. To actually use
22+
the locally built tools, switch to another repository reproducing the specific
23+
issue you want to fix (or just generate a local repo with `ng new`). Then
24+
install the locally built packages:
25+
26+
```shell
27+
cd "${EXAMPLE_ANGULAR_PROJECT_REPO}"
28+
npm install -D ${CLI_REPO}/dist/*.tgz
29+
```
30+
31+
Builds of this example project will use tooling created from the previous local
32+
build and include any local changes. When using the CLI, it will automatically
33+
check for a local install and use that if present. This means you can just run:
34+
35+
```shell
36+
npm install -g @angular/cli
37+
```
38+
39+
to get a global install of the latest CLI release. Then running any `ng` command
40+
in the example project will automatically find and use the local build of the
41+
CLI.
42+
43+
Note: If you are testing `ng update`, be aware that installing all the tarballs
44+
will also update the framework (`@angular/core`) to the latest version. In this
45+
case, simply install the CLI alone with
46+
`npm install -D ${CLI_REPO}/dist/_angular_cli.tgz`, that way the rest of the
47+
project remains to be upgraded with `ng update`.
48+
49+
## Debugging
50+
51+
To debug an invocation of the CLI, [build and install the CLI for an example
52+
project](#building-and-installing-the-cli), then run the desired `ng` command
53+
as:
54+
55+
```shell
56+
node --inspect-brk node_modules/.bin/ng ...
57+
```
58+
59+
This will trigger a breakpoint as the CLI starts up. You can connect to this
60+
using the supported mechanisms for your IDE, but the simplest option is to open
61+
Chrome to [chrome://inspect](chrome://inspect) and then click on the `inspect`
62+
link for the `node_modules/.bin/ng` Node target.
63+
64+
Unfortunately, the CLI dynamically `require()`'s other files mid-execution, so
65+
the debugger is not aware of all the source code files before hand. As a result,
66+
it is tough to put breakpoints on files before the CLI loads them. The easiest
67+
workaround is to use the `debugger;` statement to stop execution in the file you
68+
are interested in, and then you should be able to step around and set breakpoints
69+
as expected.
70+
71+
## Testing
72+
73+
There are two different test suites which can be run locally:
74+
75+
### Unit tests
76+
77+
- Run all tests: `yarn bazel test //packages/...`
78+
- Run a subset of the tests, use the full Bazel target example: `yarn bazel test //packages/schematics/angular:angular_test`
79+
- For a complete list of test targets use the following Bazel query: `yarn bazel query "tests(//packages/...)"`
80+
81+
You can find more info about debugging [tests with Bazel in the docs.](https://github.com/angular/angular-cli/blob/master/docs/process/bazel.md#debugging-jasmine_node_test)
82+
83+
### End to end tests
84+
85+
- Run: `node tests/legacy-cli/run_e2e.js`
86+
- Run a subset of the tests: `node tests/legacy-cli/run_e2e.js tests/legacy-cli/e2e/tests/i18n/ivy-localize-*`
87+
88+
When running the debug commands, Node will stop and wait for a debugger to attach.
89+
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
90+
simpler debug story.
91+
92+
When debugging a specific test, change `describe()` or `it()` to `fdescribe()`
93+
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.
94+
95+
## IDE Specific Usage
96+
97+
Some additional tips for developing in specific IDEs.
98+
99+
### Intellij IDEA / WebStorm
100+
101+
To load the project in Intellij products, simply `Open` the repository folder.
102+
Do **not** `Import Project`, because that will overwrite the existing
103+
configuration.
104+
105+
Once opened, the editor should automatically detect run configurations in the
106+
workspace. Use the drop down to choose which one to run and then click the `Run`
107+
button to start it. When executing a debug target, make sure to click the
108+
`Debug` icon to automatically attach the debugger (if you click `Run`, Node will
109+
wait forever for a debugger to attach).
110+
111+
![Intellij IDEA run configurations](images/run-configurations.png)
112+
113+
## Creating New Packages
114+
115+
Adding a package to this repository means running two separate commands:
116+
117+
1. `schematics devkit:package PACKAGE_NAME`. This will update the `.monorepo` file, and create the
118+
base files for the new package (package.json, src/index, etc).
119+
1. `devkit-admin templates`. This will update the README and all other template files that might
120+
have changed when adding a new package.
121+
122+
For private packages, you will need to add a `"private": true` key to your package.json manually.
123+
This will require re-running the template admin script.

‎scripts/templates/readme.ejs

-122
Original file line numberDiff line numberDiff line change
@@ -49,128 +49,6 @@ Angular DevKit.
4949
DevKit's goal is to provide a large set of libraries that can be used to manage, develop, deploy and
5050
analyze your code.
5151

52-
# Getting Started - Local Development
53-
54-
## Installation
55-
56-
To get started locally, follow these instructions:
57-
58-
1. If you haven't done it already, [make a fork of this repo](https://github.com/angular/angular-cli/fork).
59-
1. Clone to your local computer using `git`.
60-
1. Make sure that you have Node 12.14 or 14.0 installed. See instructions [here](https://nodejs.org/en/download/).
61-
1. Make sure that you have `yarn` installed; see instructions [here](https://yarnpkg.com/lang/en/docs/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 two different test suites which can be run locally:
125-
126-
### Unit tests
127-
* Run all tests: `yarn bazel test //packages/...`
128-
* Run a subset of the tests, use the full Bazel target example: `yarn bazel test //packages/schematics/angular:angular_test`
129-
* For a complete list of test targets use the following Bazel query: `yarn bazel query "tests(//packages/...)"`
130-
131-
You can find more info about debugging [tests with Bazel in the docs.](https://github.com/angular/angular-cli/blob/master/docs/process/bazel.md#debugging-jasmine_node_test)
132-
133-
### End to end tests
134-
* Run: `node tests/legacy-cli/run_e2e.js`
135-
* Run a subset of the tests: `node tests/legacy-cli/run_e2e.js tests/legacy-cli/e2e/tests/i18n/ivy-localize-*`
136-
137-
When running the debug commands, Node will stop and wait for a debugger to attach.
138-
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
139-
simpler debug story.
140-
141-
When debugging a specific test, change `describe()` or `it()` to `fdescribe()`
142-
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.
143-
144-
## IDE Specific Usage
145-
146-
Some additional tips for developing in specific IDEs.
147-
148-
### Intellij IDEA / WebStorm
149-
150-
To load the project in Intellij products, simply `Open` the repository folder.
151-
Do **not** `Import Project`, because that will overwrite the existing
152-
configuration.
153-
154-
Once opened, the editor should automatically detect run configurations in the
155-
workspace. Use the drop down to choose which one to run and then click the `Run`
156-
button to start it. When executing a debug target, make sure to click the
157-
`Debug` icon to automatically attach the debugger (if you click `Run`, Node will
158-
wait forever for a debugger to attach).
159-
160-
![Intellij IDEA run configurations](docs/images/run-configurations.png)
161-
162-
## Creating New Packages
163-
164-
Adding a package to this repository means running two separate commands:
165-
166-
1. `schematics devkit:package PACKAGE_NAME`. This will update the `.monorepo` file, and create the
167-
base files for the new package (package.json, src/index, etc).
168-
1. `devkit-admin templates`. This will update the README and all other template files that might
169-
have changed when adding a new package.
170-
171-
For private packages, you will need to add a `"private": true` key to your package.json manually.
172-
This will require re-running the template admin script.
173-
17452
# Packages
17553

17654
This is a monorepo which contains many tools and packages:

0 commit comments

Comments
 (0)