Fix formatting for BEP documentation
The link format used in this doc doesn't work with our site renderer.
See https://docs.bazel.build/versions/0.29.1/build-event-protocol.html to see what links are broken.
Closes #9433.
Change-Id: I8f9dd447020cbc56367bed774d84ea2edb4bbd79
PiperOrigin-RevId: 271035642
diff --git a/site/docs/build-event-protocol.md b/site/docs/build-event-protocol.md
index 251d539..4166946 100644
--- a/site/docs/build-event-protocol.md
+++ b/site/docs/build-event-protocol.md
@@ -5,15 +5,18 @@
# Build Event Protocol
-The [Build Event Protocol] allows third party programs to gain insight into a
-Bazel invocation. For example, you could use the Build Event Protocol to gather
-information for an IDE plugin or a dashboard that displays build results.
+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)
+allows third party programs to gain insight into a Bazel invocation. For
+example, you could use the Build Event Protocol to gather information for an IDE
+plugin or a dashboard that displays build results.
-The protocol is a set of [protocol buffer] messages with some semantics defined
-on top of it. It includes information about build and test 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.
+The protocol is a set of [protocol
+buffer](https://developers.google.com/protocol-buffers/) messages with some
+semantics defined on top of it. It includes information about build and test
+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.
## Contents
@@ -29,19 +32,24 @@
## Build Event Protocol Overview
-The [Build Event Protocol] represents information about a build as events. A
+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.
* __Build Event Identifier:__ Depending on the kind of build event, it might be
-an [opaque string] or [structured information] revealing more about the build
-event. A build event identifier is unique within a build.
+an [opaque
+string](https://github.com/bazelbuild/bazel/blob/16a107d/src/main/java/com/google/devtools/build/lib/buildeventstream/proto/build_event_stream.proto#L91)
+or [structured
+information](https://github.com/bazelbuild/bazel/blob/16a107d/src/main/java/com/google/devtools/build/lib/buildeventstream/proto/build_event_stream.proto#L123)
+revealing more about the build event. A build event identifier is unique within
+a build.
* __Children:__ A build event may announce other build events, by including
-their build event identifiers in its [children field]. For example, the
-`PatternExpanded` build event announces the targets it expands to as children.
-The protocol guarantees that all events, except for the first event, are
-announced by a previous event.
+their build event identifiers in its [children
+field](https://github.com/bazelbuild/bazel/blob/16a107d/src/main/java/com/google/devtools/build/lib/buildeventstream/proto/build_event_stream.proto#L469).
+For example, the `PatternExpanded` build event announces the targets it expands
+to as children. The protocol guarantees that all events, except for the first
+event, are announced by a previous event.
* __Payload:__ The payload contains structured information about a build event,
encoded as a protocol buffer message specific to that event. Note, that the
@@ -49,6 +57,7 @@
if the build aborted prematurely.
### 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
more parent events. Please note that not all parent events of a child event must
@@ -57,10 +66,11 @@
network transport, some announced build events may never be posted.
## The Build Event Protocol by 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. However, it might be helpful to build up some intuition before looking
-at the specification.
+
+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.
+However, it might be helpful to build up some intuition before looking at the
+specification.
Consider a simple Bazel workspace that consists of two empty shell scripts
`foo.sh` and `foo_test.sh` and the following BUILD file:
@@ -88,16 +98,16 @@
aforementioned parent and child relationship. Note that some build events and
most fields have been omitted for brevity.
-![bep-graph]
+
Initially, a `BuildStarted` event is published. The event informs us that the
build was invoked through the `bazel test` command and it also announces five
child events: `OptionsParsed`, `WorkspaceStatus`, `CommandLine`,
`PatternExpanded` and `Progress`. The first three events provide information
about how Bazel was invoked. The `PatternExpanded` build event provides insight
-into which specific targets the `...` pattern expanded to: `//:foo`, `//:foo_lib`
-and `//:foo_test`. It does so by declaring three `TargetConfigured` events as
-children.
+into which specific targets the `...` pattern expanded to: `//:foo`,
+`//:foo_lib` and `//:foo_test`. It does so by declaring three `TargetConfigured`
+events as children.
Note that the `TargetConfigured` event declares the `Configuration` event as a
child event, even though `Configuration` has been posted before the
@@ -160,7 +170,8 @@
serialized protocol buffer messages with each message being length delimited.
Each message is prefixed with its length encoded as a variable length integer.
This format can be read using the protocol buffer library’s
-[parseDelimitedFrom(InputStream)] method.
+[`parseDelimitedFrom(InputStream)`](https://developers.google.com/protocol-buffers/docs/reference/java/com/google/protobuf/AbstractParser#parseDelimitedFrom-java.io.InputStream-)
+method.
2. Then, write a program that extracts the relevant information from the
serialized protocol buffer message.
@@ -177,21 +188,23 @@
## The Build Event Service
-The [Build Event Service] Protocol is a generic [gRPC] service for transmitting
-build events. The Build Event Service protocol is independent of the Build Event
+The [Build Event
+Service](https://github.com/googleapis/googleapis/blob/master/google/devtools/build/v1/publish_build_event.proto)
+Protocol is a generic [gRPC](https://www.grpc.io) service for transmitting build
+events. The Build Event Service protocol is independent of the Build Event
Protocol and treats the Build Event Protocol events as opaque bytes. Bazel ships
with a gRPC client implementation of the Build Event Service protocol that
transmits Build Event Protocol events. One can specify the endpoint to send the
events to using the `--bes_backend=HOST:PORT flag`. Bazel’s implementation also
supports TLS which can be enabled by specifying the `--tls_enabled flag`.
-There is currently an experimental open source implementation of the [Build Event
-Service](https://github.com/buildbarn/bb-event-service/) in Go as part of the
-Buildbarn suite of Remote Execution tools and services.
+There is currently an experimental open source implementation of the [Build
+Event Service](https://github.com/buildbarn/bb-event-service/) in Go as part of
+the Buildbarn suite of Remote Execution tools and services.
### Build Event Service Flags
-Bazel has several flags related to the [Build Event Service] protocol, including:
+Bazel has several flags related to the Build Event Service protocol, including:
* `--bes_backend`
* `--[no]bes_best_effort`
@@ -205,10 +218,10 @@
### Authentication and Security
-Bazel’s [Build Event Service] implementation also supports authentication and
-TLS. These settings can be controlled using the below flags. Please note that
-these flags are also used for Bazel’s Remote Execution. This implies that the
-Build Event Service and Remote Execution Endpoints need to share the same
+Bazel’s Build Event Service implementation also supports authentication and TLS.
+These settings can be controlled using the below flags. Please note that these
+flags are also used for Bazel’s Remote Execution. This implies that the Build
+Event Service and Remote Execution Endpoints need to share the same
authentication and TLS infrastructure.
* `--[no]google_default_credentials`
@@ -224,38 +237,12 @@
The BEP typically contains many references to log files (test.log, test.xml,
etc. ) stored on the machine where Bazel is running. A remote BES server
-typically can't access these files as they are on different machines. A way
-to work around this issue is to use Bazel with [remote caching]. Bazel will
-upload all output files to the remote cache (including files referenced in
-the BEP) and the BES server can then fetch the referenced files from the
-cache.
+typically can't access these files as they are on different machines. A way to
+work around this issue is to use Bazel with [remote
+caching](https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/remote/README.md).
+Bazel will upload all output files to the remote cache (including files
+referenced in the BEP) and the BES server can then fetch the referenced files
+from the cache.
-See [GitHub issue 3689] for more details.
-
-[remote caching]: https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/remote/README.md
-
-[GitHub issue 3689]: https://github.com/bazelbuild/bazel/issues/3689
-
-[Build Event Protocol]:
-https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/buildeventstream/proto/build_event_stream.proto
-
-[Build Event Service]:
-https://github.com/googleapis/googleapis/blob/master/google/devtools/build/v1/publish_build_event.proto
-
-[gRPC]: https://www.grpc.io
-
-[protocol buffer]: https://developers.google.com/protocol-buffers/
-
-[bep-graph]: /assets/bep-graph.svg
-
-[parseDelimitedFrom(InputStream)]:
-https://developers.google.com/protocol-buffers/docs/reference/java/com/google/protobuf/AbstractParser#parseDelimitedFrom-java.io.InputStream-
-
-[opaque string]:
-https://github.com/bazelbuild/bazel/blob/16a107d/src/main/java/com/google/devtools/build/lib/buildeventstream/proto/build_event_stream.proto#L91
-
-[structured information]:
-https://github.com/bazelbuild/bazel/blob/16a107d/src/main/java/com/google/devtools/build/lib/buildeventstream/proto/build_event_stream.proto#L123
-
-[children field]:
-https://github.com/bazelbuild/bazel/blob/16a107d/src/main/java/com/google/devtools/build/lib/buildeventstream/proto/build_event_stream.proto#L469
+See [GitHub issue 3689](https://github.com/bazelbuild/bazel/issues/3689) for
+more details.
