diff --git a/site/docs/bazel-and-java.md b/site/docs/bazel-and-java.md index d6160b84dbd2bc..eda5292c1da421 100644 --- a/site/docs/bazel-and-java.md +++ b/site/docs/bazel-and-java.md @@ -57,7 +57,7 @@ Follow these guidelines when creating your BUILD files: * Tests should be in a matching directory under `src/test` and depend on this library. -## Java and new rules +## Creating new rules for advanced Java builds **Note**: Creating new rules is for advanced build and test scenarios. You do not need it when getting started with Bazel. diff --git a/site/docs/bazel-and-javascript.md b/site/docs/bazel-and-javascript.md index 4baeca3fde490f..4f9e6a7d725a32 100644 --- a/site/docs/bazel-and-javascript.md +++ b/site/docs/bazel-and-javascript.md @@ -9,8 +9,6 @@ This page contains resources that help you use Bazel with JavaScript projects. It links to build rules and other information specific to building JavaScript with Bazel. -## Working with Bazel - The following resources will help you work with Bazel on JavaScript projects: * [Building JavaScript/TypeScript with Bazel](build-javascript.html) diff --git a/site/docs/bazel-container.md b/site/docs/bazel-container.md index 77f6723d6c0d43..e4fe88509ebcf4 100644 --- a/site/docs/bazel-container.md +++ b/site/docs/bazel-container.md @@ -1,9 +1,9 @@ --- layout: documentation -title: Bazel Container +title: Bazel container --- -# Getting started with Bazel Docker Container +# Getting Started with Bazel Docker Container In this guide, we will explore the contents of the Bazel container, build the [abseil-cpp](https://github.com/abseil/abseil-cpp) project using Bazel inside diff --git a/site/docs/bazel-overview.md b/site/docs/bazel-overview.md index ce4e156207606b..57360fc48be5c1 100644 --- a/site/docs/bazel-overview.md +++ b/site/docs/bazel-overview.md @@ -1,9 +1,9 @@ --- layout: documentation -title: Bazel overview +title: Bazel Overview --- -# Bazel overview +# Bazel Overview Bazel is an open-source build and test tool similar to Make, Maven, and Gradle. It uses a human-readable, high-level build language. Bazel supports projects in @@ -11,7 +11,7 @@ multiple languages and builds outputs for multiple platforms. Bazel supports large codebases across multiple repositories, and large numbers of users. -## Why should I use Bazel? +## Benefits Bazel offers the following advantages: @@ -41,7 +41,7 @@ Bazel offers the following advantages: framework. -## How do I use Bazel? +## Using Bazel To build or test a project with Bazel, you typically do the following: @@ -75,7 +75,7 @@ In addition to building, you can also use Bazel to run to trace dependencies in your code. -## How does Bazel work? +## Bazel build process When running a build or a test, Bazel does the following: @@ -96,7 +96,7 @@ correctness, you can set up Bazel to run builds and tests and maximizing [reproducibility](guide.html#correctness). -### What is the action graph? +### Action graph The action graph represents the build artifacts, the relationships between them, and the build actions that Bazel will perform. Thanks to this graph, Bazel can @@ -106,7 +106,7 @@ know what build work has previously been done. The graph also enables you to easily [trace dependencies](query-how-to.html) in your code. -## How do I get started? +## Getting started tutorials To get started with Bazel, see [Getting Started](getting-started.html) or jump directly to the Bazel tutorials: diff --git a/site/docs/bazel-vision.md b/site/docs/bazel-vision.md index 7a3d4f71540a63..e658831fdb38ba 100644 --- a/site/docs/bazel-vision.md +++ b/site/docs/bazel-vision.md @@ -3,7 +3,7 @@ layout: documentation title: Bazel vision --- -# Bazel vision +# Bazel Vision

Any software developer can efficiently build, test, and package any project, of any size or complexity, with tooling that's easy to adopt and @@ -74,7 +74,7 @@ available that integrate with the workflows and conventions of that community. Bazel is committed to be extensible and open, and to support good rulesets for any language. -### So what is a good ruleset? +### Requirements of a good ruleset 1. The rules need to support efficient **building and testing** for the language, including code coverage. diff --git a/site/docs/best-practices.md b/site/docs/best-practices.md index d3d233e37cd5f7..0f6198cceee6ba 100644 --- a/site/docs/best-practices.md +++ b/site/docs/best-practices.md @@ -3,7 +3,7 @@ layout: documentation title: Best practices --- -# Best practices for Bazel +# Best Practices This document assumes that you are familiar with Bazel and provides advice on structuring your projects to take full advantage of Bazel's features. @@ -32,9 +32,9 @@ should be tagged as specifically as possible (e.g., "`requires-osx`"). This tagg targets to be filtered at a more fine-grained level than the "manual" tag and allows someone inspecting the BUILD file to understand what a target's restrictions are. -## Third party dependencies +## Third-party dependencies -You may declare third party dependencies: +You may declare third-party dependencies: * Either declare them as remote repositories in the WORKSPACE file. * Or put them in a directory called `third_party/` under your workspace directory. @@ -58,7 +58,7 @@ dependency issues: if one library depends on `guava-19.0` and one depends on `gu could end up with a library that tries to depend on two different versions. If you created a misleading alias to point both targets to one guava library, then the BUILD files are misleading. -## `.bazelrc` +## Using the `.bazelrc` file For project-specific options, use the configuration file your `/.bazelrc` (see [bazelrc format](guide.html#bazelrc)). diff --git a/site/docs/build-event-protocol.md b/site/docs/build-event-protocol.md index 5f0ec454369f83..3262d59bbf0dd8 100644 --- a/site/docs/build-event-protocol.md +++ b/site/docs/build-event-protocol.md @@ -1,9 +1,9 @@ --- layout: documentation -title: Build event protocol +title: Build Event Protocol --- -# Build event protocol +# Build Event Protocol The [Build Event Protocol](https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/buildeventstream/proto/build_event_stream.proto) @@ -18,8 +18,6 @@ results, build progress, the build configuration and much more. The Build Event Protocol is intended to be consumed programmatically and makes parsing Bazel’s command line output a thing of the past. -## Overview - The Build Event Protocol represents information about a build as events. A build event is a protocol buffer message consisting of a build event identifier, a set of child event identifiers, and a payload. @@ -44,7 +42,7 @@ encoded as a protocol buffer message specific to that event. Note, that the payload might not be the expected type, but could be an `Aborted` message e.g. if the build aborted prematurely. -### Build event graph +### Build Event graph All build events form a directed acyclic graph through their parent and child relationship. Every build event except for the initial build event has one or @@ -53,7 +51,7 @@ necessarily be posted before it. When a build is complete (succeeded or failed) all announced events will have been posted. In case of a Bazel crash or a failed network transport, some announced build events may never be posted. -## The Build Event Protocol by example +## Build Event Protocol example The full specification of the Build Event Protocol can be found in its protocol buffer definition and describing it here is beyond the scope of this document. @@ -147,9 +145,9 @@ built. } ``` -## Consuming the Build Event Protocol +## Consuming Build Event Protocol -### Consume in a binary format +### Consume in binary format To consume the Build Event Protocol in a binary format: @@ -164,17 +162,17 @@ method. 2. Then, write a program that extracts the relevant information from the serialized protocol buffer message. -### Consume in text formats +### Consume in text or JSON formats -The following Bazel command line flags will output the Build Event Protocol in a -human-readable formats: +The following Bazel command line flags will output the Build Event Protocol in +human-readable formats, such as text and JSON: ``` --build_event_text_file --build_event_json_file ``` -## The Build Event Service +## Build Event Service The [Build Event Service](https://github.com/googleapis/googleapis/blob/master/google/devtools/build/v1/publish_build_event.proto) diff --git a/site/docs/build-javascript.md b/site/docs/build-javascript.md index f5dc71ddb33a26..db83dfb0f6d0fe 100644 --- a/site/docs/build-javascript.md +++ b/site/docs/build-javascript.md @@ -31,13 +31,13 @@ Started"](getting-started.html) material before proceeding. To set up your environment for building JavaScript outputs with Bazel, do the following: -### Step 1: Installing Bazel +### Installing Bazel You can either [Install Bazel](install.html) following the same steps that you would for backend development, or you can install NodeJS with npm and run `npm install -g @bazel/bazel`. -### Step 2: Installing iBazel +### Installing iBazel iBazel, or iterative Bazel, is a "watchdog" version of Bazel that automatically runs whenever your source files change. Use it to auto-run your tests and @@ -61,7 +61,7 @@ yarn global add @bazel/ibazel To use `ibazel`, simply replace `bazel` with `ibazel` in your Bazel commands. -### Step 3: Configuring the `bazel.rc` file +### Configuring the `bazel.rc` file Any Bazel build flag or option that can be placed on the command line can also be set in the project's [`bazel.rc` file](guide.html#bazelrc)