diff --git a/site/assets/bep-graph.png b/site/assets/bep-graph.png index 27b5a8674c0b4f..82da671549db5a 100644 Binary files a/site/assets/bep-graph.png and b/site/assets/bep-graph.png differ diff --git a/site/assets/namedsetoffiles-bep-graph.png b/site/assets/namedsetoffiles-bep-graph.png new file mode 100644 index 00000000000000..ea1e10cc82039c Binary files /dev/null and b/site/assets/namedsetoffiles-bep-graph.png differ diff --git a/site/docs/bep-examples.md b/site/docs/bep-examples.md index e3f5093e0ff72f..b92e6e68bfb812 100644 --- a/site/docs/bep-examples.md +++ b/site/docs/bep-examples.md @@ -14,14 +14,9 @@ Consider a simple Bazel workspace that consists of two empty shell scripts `foo.sh` and `foo_test.sh` and the following BUILD file: ```bash -sh_binary( - name = "foo", - srcs = ["foo.sh"], -) - sh_library( name = "foo_lib", - data = [":foo"], + srcs = ["foo.sh"], ) sh_test( @@ -53,11 +48,11 @@ build was invoked through the `bazel test` command and announces child events: 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. Note that the `TargetConfigured` event declares the -`Configuration` event as a child event, even though `Configuration` has been -posted before the `TargetConfigured` event. +into which specific targets the `...` pattern expanded to: +`//foo:foo_lib` and `//foo:foo_test`. It does so by declaring two +`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 `TargetConfigured` event. Besides the parent and child relationship, events may also refer to each other using their build event identifiers. For example, in the above graph the @@ -74,10 +69,10 @@ the number of files. A `NamedSetOfFiles` event may also not have all its files embedded, but instead refer to other `NamedSetOfFiles` events through their build event identifiers. -Below is an instance of the `TargetComplete` event for the `//:foo_lib` target -from the above graph, printed in protocol buffer’s JSON representation. The -build event identifier contains the target as an opaque string and refers to the -`Configuration` event using its build event identifier. The event does not +Below is an instance of the `TargetComplete` event for the `//foo:foo_lib` +target from the above graph, printed in protocol buffer’s JSON representation. +The build event identifier contains the target as an opaque string and refers to +the `Configuration` event using its build event identifier. The event does not announce any child events. The payload contains information about whether the target was built successfully, the set of output files, and the kind of target built. @@ -86,7 +81,7 @@ built. { "id": { "targetCompleted": { - "label": "//:foo_lib", + "label": "//foo:foo_lib", "configuration": { "id": "544e39a7f0abdb3efdd29d675a48bc6a" } @@ -124,7 +119,7 @@ the BEP: { "id": { "targetCompleted": { - "label": "//:foo_lib", + "label": "//foo:foo_lib", "configuration": { "id": "544e39a7f0abdb3efdd29d675a48bc6a" }, @@ -158,6 +153,8 @@ Consumers must take care to avoid quadratic algorithms when processing such events, requiring hundreds of millions operations in a traversal with quadratic complexity. +![namedsetoffiles-bep-graph](/assets/namedsetoffiles-bep-graph.png) + A `NamedSetOfFiles` event always appears in the BEP stream *before* a `TargetComplete` or `NamedSetOfFiles` event that references it. This is the inverse of the "parent-child" event relationship, where all but the first event diff --git a/site/docs/build-event-protocol.md b/site/docs/build-event-protocol.md index 407674964a3d61..4736f93b83a2e4 100644 --- a/site/docs/build-event-protocol.md +++ b/site/docs/build-event-protocol.md @@ -52,6 +52,20 @@ 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 event graph's structure reflects the lifecycle of a command. Every BEP +graph has the following characteristic shape: + +1. The root event is always a [`BuildStarted`](bep-glossary.md#buildstarted) + event. All other events are its descendants. +1. Immediate children of the BuildStarted event contain metadata about the + command. +1. Events containing data produced by the command, such as files built and test + results, appear before the [`BuildFinished`](bep-glossary.md#buildfinished) + event. +1. The [`BuildFinished`](bep-glossary.md#buildfinished) event *may* be followed + by events containing summary information about the build (for example, metric + or profiling data). + ## Consuming Build Event Protocol ### Consume in binary format @@ -88,8 +102,9 @@ Protocol is a generic [gRPC](https://www.grpc.io) service for publishing build e Service protocol is independent of the BEP and treats BEP events as opaque bytes. Bazel ships with a gRPC client implementation of the Build Event Service protocol that publishes 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. +events to using the `--bes_backend=HOST:PORT` flag. If your backend uses gRPC, +you must prefix the address with the appropriate scheme: `grpc://` for plaintext +gRPC and `grpcs://` for gRPC with TLS enabled. 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 @@ -140,4 +155,3 @@ from the cache. See [GitHub issue 3689](https://github.com/bazelbuild/bazel/issues/3689) for more details. -