docs: Remove Bazel builder from @angular/bazel (#37190)
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
Matias Niemelä
parent
df082307b9
commit
9791c9ecaf
|
|
@ -1,122 +0,0 @@
|
|||
# Building with Bazel
|
||||
|
||||
This guide explains how to build and test Angular apps with Bazel.
|
||||
|
||||
|
||||
<div class="alert is-helpful">
|
||||
|
||||
This guide assumes you are already familiar with developing and building Angular applications using the [CLI](cli).
|
||||
|
||||
It describes features which are part of Angular Labs, and are not considered a stable, supported API.
|
||||
|
||||
</div>
|
||||
|
||||
## Using Bazel with the Angular CLI
|
||||
|
||||
The `@angular/bazel` package provides a builder that allows Angular CLI to use Bazel as the build tool.
|
||||
|
||||
To opt-in an existing application, run
|
||||
|
||||
```sh
|
||||
ng add @angular/bazel
|
||||
```
|
||||
|
||||
To use Bazel in a new application, first install `@angular/bazel` globally
|
||||
|
||||
```sh
|
||||
npm install -g @angular/bazel
|
||||
```
|
||||
|
||||
then create the new application with
|
||||
|
||||
```sh
|
||||
ng new --collection=@angular/bazel
|
||||
```
|
||||
|
||||
Now when you use Angular CLI build commands such as `ng build` and `ng serve`,
|
||||
Bazel is used behind the scenes.
|
||||
Outputs from Bazel appear in the `dist/bin` folder.
|
||||
|
||||
> The command-line output includes extra logging from Bazel.
|
||||
> We plan to reduce this in the future.
|
||||
|
||||
### Removing Bazel
|
||||
|
||||
If you need to opt-out from using Bazel, you can restore the backup files:
|
||||
|
||||
- `/angular.json.bak` replaces `/angular.json`
|
||||
|
||||
## Advanced configuration
|
||||
|
||||
<div class="alert is-helpful">
|
||||
|
||||
Editing the Bazel configuration may prevent you opting out of Bazel.
|
||||
Custom behaviors driven by Bazel won't be available in other Builders.
|
||||
|
||||
This section assumes you are familiar with [Bazel](https://docs.bazel.build).
|
||||
|
||||
</div>
|
||||
|
||||
You can manually adjust the Bazel configuration to:
|
||||
|
||||
* customize the build steps
|
||||
* parallellize the build for scale and incrementality
|
||||
|
||||
Create the initial Bazel configuration files by running the following command:
|
||||
|
||||
```sh
|
||||
ng build --leaveBazelFilesOnDisk
|
||||
```
|
||||
|
||||
Now you'll find new files in the Angular workspace:
|
||||
|
||||
* `/WORKSPACE` tells Bazel how to download external dependencies.
|
||||
* `/BUILD.bazel` and `/src/BUILD.bazel` tell Bazel about your source code.
|
||||
|
||||
You can find a full-featured example with custom Bazel configurations at https://github.com/bazelbuild/rules_nodejs/tree/master/examples/angular.
|
||||
|
||||
Documentation for using Bazel for frontend projects is linked from https://docs.bazel.build/versions/master/bazel-and-javascript.html.
|
||||
|
||||
|
||||
|
||||
## Running Bazel directly
|
||||
|
||||
In some cases you'll want to bypass the Angular CLI builder, and run the Bazel CLI directly.
|
||||
The Bazel tool is managed by the `@bazel/bazelisk` package (similar to how Node.js can be managed by `nvm`).
|
||||
You can install it globally to get the `bazelisk` command in your path, or use `$(npm bin)/bazelisk` in place of bazelisk below.
|
||||
|
||||
The common commands in Bazel are:
|
||||
|
||||
* `bazelisk build [targets]`: Compile the default output artifacts of the given targets.
|
||||
* `bazelisk test [targets]`: For whichever `*_test` targets are found in the patterns, run the tests.
|
||||
* `bazelisk run [target]`: Compile the program represented by target, and then run it.
|
||||
|
||||
To repeat the command any time the inputs change (watch mode), replace `bazelisk` with `ibazel` in these commands.
|
||||
|
||||
The output locations are printed in the output.
|
||||
|
||||
Full documentation for the Bazel CLI is at https://docs.bazel.build/versions/master/command-line-reference.html.
|
||||
|
||||
|
||||
## Querying the build graph
|
||||
|
||||
Because Bazel constructs a graph out of your targets, you can find lots of useful information.
|
||||
|
||||
Using the graphviz optional dependency, you'll have a program `dot`, which you can use with `bazel query`:
|
||||
|
||||
```bash
|
||||
$ bazel query --output=graph ... | dot -Tpng > graph.png
|
||||
```
|
||||
|
||||
See https://docs.bazel.build/versions/master/query-how-to.html for more details on `bazel query`.
|
||||
|
||||
|
||||
## Customizing `BUILD.bazel` files
|
||||
|
||||
"Rules" are like plugins for Bazel. Many rule sets are available. This guide documents the ones maintained by the Angular team at Google.
|
||||
|
||||
Rules are used in `BUILD.bazel` files, which are markers for the packages in your workspace. Each `BUILD.bazel` file declares a separate package to Bazel, though you can have more coarse-grained distributions so that the packages you publish (for example, to `npm`) can be made up of many Bazel packages.
|
||||
|
||||
In the `BUILD.bazel` file, each rule must first be imported, using the `load` statement. Then the rule is called with some attributes, and the result of calling the rule is that you've declared to Bazel how it can derive some outputs given some inputs and dependencies. Then later, when you run a `bazel` command line, Bazel loads all the rules you've declared to determine an absolute ordering of what needs to be run. Note that only the rules needed to produce the requested output will actually be executed.
|
||||
|
||||
A list of common rules for frontend development is documented in the README at https://github.com/bazelbuild/rules_nodejs/.
|
||||
|
|
@ -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`.
|
||||
|
|
|
|||
Loading…
Reference in New Issue