cargdev/angular
1
0
Fork 0
Code Issues 10 Pull Requests Actions Packages Projects Releases Wiki Activity

docs: Remove Bazel builder from @angular/bazel (#37190)

Browse Source 
This commit adds a deprecation doc for Bazel builder in
`@angular/bazel` and removes the corresponding guide in angular.io.

PR Close #37190
This commit is contained in:
Keen Yee Liau
2020-05-18 14:33:11 -07:00
committed by Matias Niemelä
parent 270da1f69f
commit 83ab99c746
2 changed files with 26 additions and 238 deletions
Download Patch File Download Diff File Expand all files Collapse all files

142
packages/bazel/src/schematics/README.md
View File

@ -1,136 +1,46 @@
# Schematics for Bazel
## WARNING
Bazel builder for Angular CLI has been deprecated.
Schematics in `@angular/bazel` is still highly experimental as of January 2019,
please use with caution. For feedbacks and comments, please open an issue on
GitHub and ping [@mgechev](https://github.com/mgechev) or
[@kyliau](https://github.com/kyliau).
The schematics for Bazel builder have been in Angular Labs for some time,
but over the course of its evaluation the Angular team has found that they did
not meet our expectation of providing a smooth experience to get users onboard.
## Requirements
There are multiple factors:
To create a new Angular project that builds with Bazel + CLI, the following
packages have to be installed.
1. Bazel ecosystem for Javascript is still evolving at a rapid pace.
2. The introduction of Ivy compiler enables new ways to use Bazel in a faster
and more efficient manner.
3. Feature parity with Angular CLI is difficult to achieve.
| Package | Minimum Version
|----------------|-----------------
| @angular/cli | v8.0.x
| @angular/bazel | v8.0.x
For users who are currently using Bazel builder, there are a few migration
options.
The `@angular/bazel` package contains schematics to generate necessary Bazel
build files.
## View Engine
If the packages are not on your system yet, install them with the following
commands:
If your application is using View Engine, you could leave the Bazel files
in your workspace, and manage them manually.
```
yarn global add @angular/cli@next @angular/bazel@next
ng build --leaveBazelFilesOnDisk
```
It is very *important* to meet the minimum version requirement of `@angular/cli`
because Bazel schematics rely on some of the new APIs that are missing in older
versions of the CLI. Invoking `@angular/bazel` schematics with an older version
of CLI would very likely result in unexpected errors.
## Ivy
<details>
<summary>
More details
</summary>
Bazel schematics rely on the new
<a href="https://github.com/angular/angular-cli/commit/a0ac4b0e3dd60c75e1edafd6bb8cced47d10a8d3">
<code>ScopedTree</code></a> in <code>@angular-devkit/schematics</code>.
There is currently no way for a schematic to mandate a minimum
"schematic runtime" version. The version of <code>@angular-devkit/schematics</code>
that is installed with the CLI is used to run the schematic even though a different
version is used in the schematic itself.
</details>
## Create a Bazel-managed Angular project
Create a new project using `@angular/bazel` schematics for `ng new`.
If your application is using Ivy, you should also leave the Bazel files on disk.
```
$ ng new demo --collection=@angular/bazel --defaults
ng build --leaveBazelFilesOnDisk
```
In addition to the regular files generated by CLI, the following files that are
specific to a Bazel workspace are also created.
Once that is done, switch to using the latest [`ng_ts_library`](https://github.com/bazelbuild/rules_nodejs/blob/master/examples/angular/tools/angular_ts_library.bzl) rule.
This new rule leverages ngtsc plugin supported by `ts_library`, and it is much
faster.
```
...
CREATE demo/BUILD.bazel (190 bytes)
CREATE demo/WORKSPACE (2951 bytes)
CREATE demo/.bazelignore (18 bytes)
CREATE demo/.bazelrc (828 bytes)
CREATE demo/e2e/BUILD.bazel (1230 bytes)
CREATE demo/e2e/protractor.on-prepare.js (1101 bytes)
CREATE demo/src/BUILD.bazel (2626 bytes)
CREATE demo/src/initialize_testbed.ts (432 bytes)
CREATE demo/src/main.dev.ts (185 bytes)
CREATE demo/src/main.prod.ts (249 bytes)
```
For the latest recommendations, please refer to the canonical Angular Bazel [repo](https://github.com/bazelbuild/rules_nodejs/tree/master/examples/angular).
Note that in a Bazel-managed project, there is a Bazel WORKSPACE file and a few BUILD.bazel files.
There are also some files specific to a Bazel-managed project, namely `main.dev.ts` and `main.prod.ts`.
This is because all Angular projects built with Bazel must be AOT only.
In a Bazel project, `main.ts` generated by CLI is not used.
## Angular CLI
By default, `ng new` for Bazel does not perform `yarn install`.
This is because the `node_modules` are managed by Bazel and it is Bazel's
responsibility to perform the install.
Next, let's try to build the project using Bazel.
All existing `ng` commands would work as before.
```
cd demo
# The following yarn step is needed so that `ng build` works correctly.
# Alternatively, you can skip this step if you choose to not use `ng` commands.
# In which case, you'd execute `yarn bazel build //src:bundle`. This is
# equivalent to running `ng build`.
yarn
ng build
ng serve
```
If you encounter a warning about version mismatch, update `ANGULAR_VERSION` in
the WORKSPACE file to match the version of `@angular/bazel` installed from NPM.
Bring up the dev server using `ibazel run` command.
```
yarn ibazel run //src:devserver
```
Make some changes to the code, and verify that the dev server automatically refreshes.
## Development notes
To test any local changes, run
```shell
bazel build //packages/bazel:npm_package
```
then `cd` to the npm package in the `dist` folder and run `yarn link`.
Next run `yarn link` again in the directory where the `ng` command is invoked.
Make sure the `ng` command is local, and not the global installation.
## Generate .d.ts file from JSON schema
The script to generate `.d.ts` file is located in the
[Angular CLI](https://github.com/angular/angular-cli) repo. Make sure
the CLI repository is checked out on your local machine.
Then, in the CLI repository, run the following command
```shell
bazel run //tools:quicktype_runner -- \
~/Documents/GitHub/angular/packages/bazel/src/schematics/ng-new/schema.json \
~/Documents/GitHub/angular/packages/bazel/src/schematics/ng-new/schema.d.ts
```
## TODOs
1. Make the `ts_json_schema` rule re-usable and portable.
2. Add comments in BUILD files. See discussion [here](https://github.com/angular/angular/pull/26971#discussion_r231325683).
If you'd like to revert to the default Angular CLI builder, you could restore
the original Angular config from backup by replacing `angular.json` with
`angular.json.bak`.