From 7c479f073eb46d8d2116ec4ddc2af49bd36edf3d Mon Sep 17 00:00:00 2001
From: Alex Eagle <eagle@post.harvard.edu>
Date: Tue, 11 Jul 2017 14:48:50 -0500
Subject: [PATCH] docs: document using Bazel (#17701)

---
 docs/BAZEL.md | 52 +++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 52 insertions(+)
 create mode 100644 docs/BAZEL.md

diff --git a/docs/BAZEL.md b/docs/BAZEL.md
new file mode 100644
index 0000000000..f8a3396db5
--- /dev/null
+++ b/docs/BAZEL.md
@@ -0,0 +1,52 @@
+# Building Angular with Bazel
+
+Note: this doc is for developing Angular, it is _not_ public
+documentation for building an Angular application with Bazel.
+
+The Bazel build tool (http://bazel.build) provides fast, reliable
+incremental builds. We plan to migrate Angular's build scripts to
+Bazel.
+
+## Installation
+
+Install Bazel from the distribution, see [install] instructions.
+On Mac, just `brew install bazel`.
+
+Bazel will install a hermetic version of Node, npm, and Yarn when
+you run the first build.
+
+[install]: https://bazel.build/versions/master/docs/install.html
+
+## Configuration
+
+The `WORKSPACE` file indicates that our root directory is a
+Bazel project. It contains the version of the Bazel rules we
+use to execute build steps, from `io_bazel_rules_typescript`.
+The sources on [GitHub] are published from Google's internal
+repository (google3).
+
+That repository defines dependencies on specific versions of
+all the tools. You can run the tools Bazel installed, for
+example rather than `npm install` (which depends on whatever
+version you have installed on your machine), you can
+`bazel run @io_bazel_rules_typescript_node//:bin/npm install`.
+
+Bazel accepts a lot of options. We check in some options in the
+`.bazelrc` file. See the [bazelrc doc]. For example, if you don't
+want Bazel to create several symlinks in your project directory
+(`bazel-*`) you can add the line `build --symlink_prefix=/` to your
+`.bazelrc` file.
+
+[GitHub]: https://github.com/bazelbuild/rules_typescript
+[bazelrc doc]: https://bazel.build/versions/master/docs/bazel-user-manual.html#bazelrc
+
+## Building Angular
+
+- Build a package: `bazel build packages/core`
+- Build all packages: `bazel build packages/...`
+
+You can use [ibazel] to get a "watch mode" that continuously
+keeps the outputs up-to-date as you save sources. Note this is
+new as of May 2017 and not very stable yet.
+
+[ibazel]: https://github.com/bazelbuild/bazel-watcher