Delete obsolete documentation files.
The new versions live under site/en/
PiperOrigin-RevId: 429528903
diff --git a/BUILD b/BUILD
index 8bc5528..b977f61 100644
--- a/BUILD
+++ b/BUILD
@@ -24,6 +24,7 @@
"//examples:srcs",
"//scripts:srcs",
"//site:srcs",
+ "//site/en:srcs",
"//src:srcs",
"//tools:srcs",
"//third_party:srcs",
diff --git a/site/docs/aquery.html b/site/docs/aquery.html
deleted file mode 100644
index 5b453fe..0000000
--- a/site/docs/aquery.html
+++ /dev/null
@@ -1,460 +0,0 @@
----
-layout: documentation
-title: Aquery (action graph query)
----
-
-<div style="background-color: #EFCBCB; color: #AE2B2B; border: 1px solid #AE2B2B; border-radius: 5px; border-left: 10px solid #AE2B2B; padding: 0.5em;">
-<b>IMPORTANT:</b> The Bazel docs have moved! Please update your bookmark to <a href="https://bazel.build/docs/aquery" style="color: #0000EE;">https://bazel.build/docs/aquery</a>
-<p/>
-You can <a href="https://blog.bazel.build/2022/02/17/Launching-new-Bazel-site.html" style="color: #0000EE;">read about</a> the migration, and let us <a href="https://forms.gle/onkAkr2ZwBmcbWXj7" style="color: #0000EE;">know what you think</a>.
-</div>
-
-<h1>Action Graph Query (aquery)</h1>
-
-
-<p>
- The <code>aquery</code> command allows you to query for actions in your build graph.
- It operates on the post-analysis Configured Target Graph and exposes
- information about <b>Actions, Artifacts and their relationships.</b>
-</p>
-
-<p>
- <code>aquery</code> is useful when you are interested in the properties of the Actions/Artifacts
- generated from the Configured Target Graph. For example, the actual commands run
- and their inputs/outputs/mnemonics.
-</p>
-
-<p>
- The tool accepts several command-line <a href="#aquery-options">options</a>.
- Notably, the aquery command runs on top of a regular Bazel build and inherits
- the set of options available during a build.
-</p>
-
-<p>
- It supports the same set of functions that is also available to traditional
- <code>query</code> but <code>siblings</code>, <code>buildfiles</code> and
- <code>tests</code>.
-</p>
-
-<p>An example <code>aquery</code> output (without specific details):</p>
-
-<pre>
-$ bazel aquery 'deps(//some:label)'
-action 'Writing file some_file_name'
- Mnemonic: ...
- Target: ...
- Configuration: ...
- ActionKey: ...
- Inputs: [...]
- Outputs: [...]
-</pre>
-
-<h2 id='basic-syntax'>Basic syntax</h2>
-
-<p>A simple example of the syntax for <code>aquery</code> is as follows:</p>
-
-<p><code>bazel aquery "aquery_function(function(//target))"</code></p>
-
-<p>The query expression (in quotes) consists of the following:
-
-<ul>
- <li>
- <code>aquery_function(...)</code>: functions specific to <code>aquery</code>.
- More details <a href="#functions">below</a>.
- </li>
- <li>
- <code>function(...)</code>: the standard <a href="query.html#functions">functions</a>
- as traditional <code>query</code>.
- </li>
- <li>
- <code>//target</code> is the label to the interested target.
- </li>
-</ul>
-
-<pre>
-# aquery examples:
-# Get the action graph generated while building //src/target_a
-$ bazel aquery '//src/target_a'
-
-# Get the action graph generated while building all dependencies of //src/target_a
-$ bazel aquery 'deps(//src/target_a)'
-
-# Get the action graph generated while building all dependencies of //src/target_a
-# whose inputs filenames match the regex ".*cpp".
-$ bazel aquery 'inputs(".*cpp", deps(//src/target_a))'
-</pre>
-
-<h2 id='functions'>Using aquery functions</h2>
-
-<p>There are three <code>aquery</code> functions:</p>
-<ul>
- <li><code>inputs</code>: filter actions by inputs.</li>
- <li><code>outputs</code>: filter actions by outputs</li>
- <li><code>mnemonic</code>: filter actions by mnemonic</li>
-</ul>
-
-<p><code>expr ::= inputs(word, expr)</code></p>
-
-<p>
- The <code>inputs</code> operator returns the actions generated from building <code>expr</code>,
- whose input filenames match the regex provided by <code>word</code>.
-</p>
-
-<p><code>$ bazel aquery 'inputs(".*cpp", deps(//src/target_a))'</code></p>
-
-<p><code>outputs</code> and <code>mnemonic</code> functions share a similar syntax.</p>
-
-<p>You can also combine functions to achieve the AND operation. For example:</p>
-<pre>
- $ bazel aquery 'mnemonic("Cpp.*", (inputs(".*cpp", inputs("foo.*", //src/target_a))))'
-</pre>
-<p>
- The above command would find all actions involved in building <code>//src/target_a</code>,
- whose mnemonics match <code>"Cpp.*"</code> and inputs match the patterns
- <code>".*cpp"</code> and <code>"foo.*"</code>.
-</p>
-
-<h3>Important: aquery functions can't be nested inside non-aquery functions</h3>
-<ul>
- <li>Conceptually this makes sense since the output of aquery functions is Actions,
- not Configured Targets.</li>
- <li>
- An example of the syntax error produced:
- <pre>
- $ bazel aquery 'deps(inputs(".*cpp", //src/target_a))'
- ERROR: aquery filter functions (inputs, outputs, mnemonic) produce actions,
- and therefore can't be the input of other function types: deps
- deps(inputs(".*cpp", //src/target_a))
- </pre>
- </li>
-</ul>
-
-<h2 id='options'>Options</h2>
-
-<h3>Build options</h3>
-
-<p>
- <code>aquery</code> runs on top of a regular Bazel build and thus inherits the set of
- <a href="command-line-reference.html#build-options">options</a>
- available during a build.
-</p>
-
-<h3 id="aquery-options">Aquery options</h3>
-
-<h4><code class='flag'>--output=(text|summary|proto|jsonproto|textproto), default=text</code></h4>
-
-<p>
- The <code>text</code> (default) and summary output formats are human-readable,
- select <code>proto</code>, <code>textproto</code>, or <code>jsonproto</code> for a
- machine-readable format.
- The proto message for the machine-readable formats is <code>analysis.ActionGraphContainer</code>.
-</p>
-
-<h4><code class='flag'>--include_commandline, default=true</code></h4>
-
-<p>
- Includes the content of the action command lines in the output (potentially large).
-</p>
-
-<h4><code class='flag'>--include_artifacts, default=true</code></h4>
-
-<p>
- Includes names of the action inputs and outputs in the output (potentially large).
-</p>
-
-<h4><code class='flag'>--include_aspects, default=true</code></h4>
-
-<p>
- Whether to include Aspect-generated actions in the output.
-</p>
-
-<h4><code class='flag'>--include_param_files, default=false</code></h4>
-
-<p>
- Include the content of the param files used in the command (potentially large).
- Warning: Enabling this flag will automatically enable the <code>--include_commandline</code> flag.
-</p>
-
-<h4><code class='flag'>--skyframe_state, default=false</code></h4>
-
-<p>
- Without performing extra analysis, dump the Action Graph from Skyframe.
- Note: Specifying a target with <code>--skyframe_state</code> is currently not supported.
- This flag is only available with <code>--output=proto</code> or <code>--output=textproto</code>.
-</p>
-
-<h2 id='misc'>Other tools and features</h2>
-
-<h3 id="skyframe-state">Querying against the state of Skyframe</h3>
-
-<p>
- <a href="https://bazel.build/designs/skyframe.html">Skyframe</a> is the evaluation and
- incrementality model of Bazel. On each instance of Bazel server, Skyframe stores the dependency graph
- constructed from the previous runs of the <a href="guide.html#analysis-phase">Analysis phase</a>.
-</p>
-
-<p>
- In some cases, it is useful to query the Action Graph on Skyframe.
- An example use case would be:
-</p>
-
-<ol>
- <li>Run <code>bazel build //target_a</code></li>
- <li>Run <code>bazel build //target_b</code></li>
- <li>File <code>foo.out</code> was generated.</li>
-</ol>
-
-<p>
- <i>As a Bazel user, I want to determine if <code>foo.out</code> was generated from building
- <code>//target_a</code> or <code>//target_b</code></i>.
-</p>
-
-<p>
- One could run <code>bazel aquery 'outputs("foo.out", //target_a)'</code> and
- <code>bazel aquery 'outputs("foo.out", //target_b)'</code> to figure out the action responsible
- for creating <code>foo.out</code>, and in turn the target. However, the number of different
- targets previously built can be larger than 2, which makes running multiple <code>aquery</code>
- commands a hassle.
-</p>
-
-<p>As an alternative, the <code>--skyframe_state</code> flag can be used:</p>
-
-<pre>
- # List all actions on Skyframe's action graph
- $ bazel aquery --output=proto --skyframe_state
-
- # or
-
- # List all actions on Skyframe's action graph, whose output matches "foo.out"
- $ bazel aquery --output=proto --skyframe_state 'outputs("foo.out")'
-</pre>
-
-<p>
- With <code>--skyframe_state</code> mode, <code>aquery</code> takes the content of the Action Graph
- that Skyframe keeps on the instance of Bazel, (optionally) performs filtering on it and
- outputs the content, without re-running the analysis phase.
-</p>
-
-<h4>Special considerations</h4>
-
-<h5>Output format</h5>
-
-<p><code>--skyframe_state</code> is currently only available for <code>--output=proto</code>
- and <code>--output=textproto</code></p>
-
-<h5>Non-inclusion of target labels in the query expression</h5>
-
-<p>
- Currently, <code>--skyframe_state</code> queries the whole action graph that exists on Skyframe,
- regardless of the targets. Having the target label specified in the query together with
- <code>--skyframe_state</code> is considered a syntax error:
-</p>
-
-<pre>
- # WRONG: Target Included
- $ bazel aquery --output=proto --skyframe_state <b>//target_a</b>
- ERROR: Error while parsing '//target_a)': Specifying build target(s) [//target_a] with --skyframe_state is currently not supported.
-
- # WRONG: Target Included
- $ bazel aquery --output=proto --skyframe_state 'inputs(".*.java", <b>//target_a</b>)'
- ERROR: Error while parsing '//target_a)': Specifying build target(s) [//target_a] with --skyframe_state is currently not supported.
-
- # CORRECT: Without Target
- $ bazel aquery --output=proto --skyframe_state
- $ bazel aquery --output=proto --skyframe_state 'inputs(".*.java")'
-</pre>
-
-<h3 id="diff-tool">Comparing aquery outputs</h3>
-
-<p>
- You can compare the outputs of two different aquery invocations using the <code>aquery_differ</code> tool.
- For instance: when you make some changes to your rule definition and want to verify that the
- command lines being run did not change. <code>aquery_differ</code> is the tool for that.
-</p>
-
-<p>
- The tool is available in the <a href="https://github.com/bazelbuild/bazel/tree/master/tools/aquery_differ">bazelbuild/bazel</a> repository.
- To use it, clone the repository to your local machine. An example usage:
-</p>
-
-
-<pre>
- $ bazel run //tools/aquery_differ -- \
- --before=/path/to/before.proto \
- --after=/path/to/after.proto \
- --input_type=proto \
- --attrs=cmdline \
- --attrs=inputs
-</pre>
-
-
-<p>
- The above command returns the difference between the <code>before</code> and <code>after</code> aquery outputs:
- which actions were present in one but not the other, which actions have different
- command line/inputs in each aquery output, ...). The result of running the above command would be:
-</p>
-
-<pre>
- Aquery output 'after' change contains an action that generates the following outputs that aquery output 'before' change doesn't:
- ...
- /list of output files/
- ...
-
- [cmdline]
- Difference in the action that generates the following output(s):
- /path/to/abc.out
- --- /path/to/before.proto
- +++ /path/to/after.proto
- @@ -1,3 +1,3 @@
- ...
- /cmdline diff, in unified diff format/
- ...
-</pre>
-
-<h4>Command options</h4>
-<p><code class='flag'>--before, --after</code>: The aquery output files to be compared</p>
-<p>
- <code class='flag'>--input_type=(proto|text_proto), default=proto</code>: the format of the input
- files. Support is provided for <code>proto</code> and <code>textproto</code> aquery output.
-</p>
-<p>
- <code class='flag'>--attrs=(cmdline|inputs), default=cmdline</code>: the attributes of actions
- to be compared.
-</p>
-
-<h3 id="aspect-on-aspect">Aspect-on-aspect</h3>
-
-<p>
- It is possible for <a href="https://docs.bazel.build/versions/main/skylark/aspects.html">Aspects</a>
- to be applied on top of each other. The aquery output of the action generated by these Aspects would
- then include the <i>Aspect path</i>, which is the sequence of Aspects applied to the target which generated the action.
-</p>
-
-<p>An example of Aspect-on-Aspect:</p>
-
-<pre>
- t0
- ^
- | <- a1
- t1
- ^
- | <- a2
- t2
-</pre>
-
-<p>
- Let t<sub>i</sub> be a target of rule r<sub>i</sub>, which applies an Aspect a<sub>i</sub>
- to its dependencies.
-</p>
-
-<p>Assume that a2 generates an action X when applied to target t0. The text output of
- <code>bazel aquery --include_aspects 'deps(//t2)'</code> for action X would be:</p>
-
-<pre>
- action ...
- Mnemonic: ...
- Target: //my_pkg:t0
- Configuration: ...
- AspectDescriptors: [//my_pkg:rule.bzl%<b>a2</b>(foo=...)
- -> //my_pkg:rule.bzl%<b>a1</b>(bar=...)]
- ...
-</pre>
-
-<p>
- This means that action <code>X</code> was generated by Aspect <code>a2</code> applied onto
- <code>a1(t0)</code>, where <code>a1(t0)</code> is the result of Aspect <code>a1</code> applied
- onto target <code>t0</code>.
-</p>
-
-<p>Each <code>AspectDescriptor</code> has the following format:</p>
-
-<pre>
- AspectClass([param=value,...])
-</pre>
-
-<p>
- <code>AspectClass</code> could be the name of the Aspect class (for native Aspects) or
- <code>bzl_file%aspect_name</code> (for Starlark Aspects). <code>AspectDescriptor</code> are
- sorted in topological order of the
- <a href="https://docs.bazel.build/versions/main/skylark/aspects.html#aspect-basics">dependency graph</a>.
-</p>
-
-<h3 id="linking-json-profile">Linking with the JSON profile</h3>
-<p>
- While aquery provides information about the actions being run in a build (why they're being run,
- their inputs/outputs), the <a href="https://docs.bazel.build/versions/main/skylark/performance.html#performance-profiling">JSON profile</a>
- tells us the timing and duration of their execution.
- It is possible to combine these 2 sets of information via a common denominator: an action's primary output.
-</p>
-
-<p>
- To include actions' outputs in the JSON profile, generate the profile with
- <code>--experimental_include_primary_output --noexperimental_slim_json_profile</code>.
- Slim profiles are incompatible with the inclusion of primary outputs. An action's primary output
- is included by default by aquery.
-</p>
-
-<p>
- We don't currently provide a canonical tool to combine these 2 data sources, but you should be
- able to build your own script with the above information.
-</p>
-
-<h2 id='known-issues'>Known issues</h2>
-
-<h3 id='shared-actions'>Handling shared actions</h3>
-
-<p>
- Sometimes actions are
- <a href="https://source.bazel.build/bazel/+/master:src/main/java/com/google/devtools/build/lib/actions/Actions.java;l=59;drc=146d51aa1ec9dcb721a7483479ef0b1ac21d39f1">shared</a>
- between configured targets.
-
- In the execution phase, those shared actions are
- <a href="https://source.bazel.build/bazel/+/master:src/main/java/com/google/devtools/build/lib/actions/Actions.java;l=241;drc=003b8734036a07b496012730964ac220f486b61f">simply considered as one</a> and only executed once.
- However, aquery operates on the pre-execution, post-analysis action graph, and hence treats these
- like separate actions whose output Artifacts have the exact same <code>execPath</code>. As a result,
- equivalent Artifacts appear duplicated.
-</p>
-<p>
- The list of aquery issues/planned features can be found on
- <a href="https://github.com/bazelbuild/bazel/labels/team-Performance">GitHub</a>.
-</p>
-<h2 id='faqs'>FAQs</h2>
-
-<h3 id='action-key'>The ActionKey remains the same even though the content of an input file changed.</h3>
-
-
-<p>
- In the context of aquery, the <code>ActionKey</code> refers to the <code>String</code> gotten from
- <code><a href="https://cs.opensource.google/bazel/bazel/+/master:src/main/java/com/google/devtools/build/lib/actions/ActionAnalysisMetadata.java;l=89;drc=8b856f5484f0117b2aebc302f849c2a15f273310">ActionAnalysisMetadata#getKey</a></code>:
-</p>
-
-<pre>
- Returns a string encoding all of the significant behaviour of this Action that might affect the
- output. The general contract of <code>getKey</code> is this: if the work to be performed by the
- execution of this action changes, the key must change.
-
- ...
-
- Examples of changes that should affect the key are:
-
- - Changes to the BUILD file that materially affect the rule which gave rise to this Action.
- - Changes to the command-line options, environment, or other global configuration resources
- which affect the behaviour of this kind of Action (other than changes to the names of the
- input/output files, which are handled externally).
- - An upgrade to the build tools which changes the program logic of this kind of Action
- (typically this is achieved by incorporating a UUID into the key, which is changed each
- time the program logic of this action changes).
- Note the following exception: for actions that discover inputs, the key must change if any
- input names change or else action validation may falsely validate.
-</pre>
-
-<p>
- This excludes the changes to the content of the input files, and is not to be confused with
- <code><a href="https://cs.opensource.google/bazel/bazel/+/master:src/main/java/com/google/devtools/build/lib/remote/common/RemoteCacheClient.java;l=38;drc=21577f202eb90ce94a337ebd2ede824d609537b6">RemoteCacheClient#ActionKey</a></code>.
-</p>
-
-<h2 id='updates'>Updates</h2>
-
-<p>
- For any issues/feature requests, please file an issue <a href="https://github.com/bazelbuild/bazel/issues/new">here</a>.
-</p>
diff --git a/site/docs/bep-examples.md b/site/docs/bep-examples.md
deleted file mode 100644
index ee4fbeb..0000000
--- a/site/docs/bep-examples.md
+++ /dev/null
@@ -1,213 +0,0 @@
----
-layout: documentation
-title: Build Event Protocol Examples
----
-
-<div style="background-color: #EFCBCB; color: #AE2B2B; border: 1px solid #AE2B2B; border-radius: 5px; border-left: 10px solid #AE2B2B; padding: 0.5em;">
-<b>IMPORTANT:</b> The Bazel docs have moved! Please update your bookmark to <a href="https://bazel.build/docs/bep-examples" style="color: #0000EE;">https://bazel.build/docs/bep-examples</a>
-<p/>
-You can <a href="https://blog.bazel.build/2022/02/17/Launching-new-Bazel-site.html" style="color: #0000EE;">read about</a> the migration, and let us <a href="https://forms.gle/onkAkr2ZwBmcbWXj7" style="color: #0000EE;">know what you think</a>.
-</div>
-
-
-# Build Event Protocol Examples
-
-
-The full specification of the Build Event Protocol can be found in its protocol
-buffer definition. 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:
-
-```bash
-sh_library(
- name = "foo_lib",
- srcs = ["foo.sh"],
-)
-
-sh_test(
- name = "foo_test",
- srcs = ["foo_test.sh"],
- deps = [":foo_lib"],
-)
-```
-
-When running `bazel test ...` on this project the build graph of the generated
-build events will resemble the graph below. The arrows indicate the
-aforementioned parent and child relationship. Note that some build events and
-most fields have been omitted for brevity.
-
-
-
-Initially, a `BuildStarted` event is published. The event informs us that the
-build was invoked through the `bazel test` command and announces child events:
-
-* `OptionsParsed`
-* `WorkspaceStatus`
-* `CommandLine`
-* `UnstructuredCommandLine`
-* `BuildMetadata`
-* `BuildFinished`
-* `PatternExpanded`
-* `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: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
-`TargetComplete` event refers to the `NamedSetOfFiles` event in its `fileSets`
-field.
-
-Build events that refer to files (i.e. outputs) usually don’t embed the file
-names and paths in the event. Instead, they contain the build event identifier
-of a `NamedSetOfFiles` event, which will then contain the actual file names and
-paths. The `NamedSetOfFiles` event allows a set of files to be reported once and
-referred to by many targets. This structure is necessary because otherwise in
-some cases the Build Event Protocol output size would grow quadratically with
-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: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.
-
-```json
-{
- "id": {
- "targetCompleted": {
- "label": "//foo:foo_lib",
- "configuration": {
- "id": "544e39a7f0abdb3efdd29d675a48bc6a"
- }
- }
- },
- "completed": {
- "success": true,
- "outputGroup": [{
- "name": "default",
- "fileSets": [{
- "id": "0"
- }]
- }],
- "targetKind": "sh_library rule"
- }
-}
-```
-
-## Aspect Results in BEP
-
-Ordinary builds evaluate actions associated with `(target, configuration)`
-pairs. When building with [aspects](skylark/aspects.html) enabled, Bazel
-additionally evaluates targets associated with `(target, configuration,
-aspect)` triples, for each target affected by a given enabled aspect.
-
-Evaluation results for aspects are available in BEP despite the absence of
-aspect-specific event types. For each `(target, configuration)` pair with an
-applicable aspect, Bazel publishes an additional `TargetConfigured` and
-`TargetComplete` event bearing the result from applying the aspect to the
-target. For example, if `//:foo_lib` is built with
-`--aspects=aspects/myaspect.bzl%custom_aspect`, this event would also appear in
-the BEP:
-
-```json
-{
- "id": {
- "targetCompleted": {
- "label": "//foo:foo_lib",
- "configuration": {
- "id": "544e39a7f0abdb3efdd29d675a48bc6a"
- },
- "aspect": "aspects/myaspect.bzl%custom_aspect"
- }
- },
- "completed": {
- "success": true,
- "outputGroup": [{
- "name": "default",
- "fileSets": [{
- "id": "1"
- }]
- }]
- }
-}
-```
-
-Note that the only difference between the IDs is the presence of the `aspect`
-field. A tool that does not check the `aspect` ID field and accumulates output
-files by target may conflate target outputs with aspect outputs.
-
-## Consuming `NamedSetOfFiles`
-
-Determining the artifacts produced by a given target (or aspect) is a common
-BEP use-case that can be done efficiently with some preparation. This section
-discusses the recursive, shared structure offered by the `NamedSetOfFiles`
-event, which matches the structure of a Starlark [Depset](skylark/depsets.html).
-Consumers must take care to avoid quadratic algorithms when processing
-`NamedSetOfFiles` events because large builds can contain tens of thousands of
-such events, requiring hundreds of millions operations in a traversal with
-quadratic complexity.
-
-
-
-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
-appears after at least one event announcing it. A `NamedSetOfFiles` event is
-announced by a `Progress` event with no semantics.
-
-Given these ordering and sharing constraints, a typical consumer must buffer all
-`NamedSetOfFiles` events until the BEP stream is exhausted. The following JSON
-event stream and Python code demonstrate how to populate a map from
-target/aspect to built artifacts in the "default" output group, and how to
-process the outputs for a subset of built targets/aspects:
-
-<p>
- <button class="btn btn-primary" type="button" data-toggle="collapse"
- data-target="#collapseNamedSetJson" aria-expanded="false"
- aria-controls="collapseNamedSetJson">
- Show/Hide BEP JSON
- </button>
-</p>
-{: .collapse #collapseNamedSetJson}
-
-```python
-named_sets = {} # type: dict[str, NamedSetOfFiles]
-outputs = {} # type: dict[str, dict[str, set[str]]]
-
-for event in stream:
- kind = event.id.WhichOneof("id")
- if kind == "named_set":
- named_sets[event.id.named_set.id] = event.named_set_of_files
- elif kind == "target_completed":
- tc = event.id.target_completed
- target_id = (tc.label, tc.configuration.id, tc.aspect)
- outputs[target_id] = {}
- for group in event.completed.output_group:
- outputs[target_id][group.name] = {fs.id for fs in group.file_sets}
-
-for result_id in relevant_subset(outputs.keys()):
- visit = outputs[result_id].get("default", [])
- seen_sets = set(visit)
- while visit:
- set_name = visit.pop()
- s = named_sets[set_name]
- for f in s.files:
- process_file(result_id, f)
- for fs in s.file_sets:
- if fs.id not in seen_sets:
- visit.add(fs.id)
- seen_sets.add(fs.id)
-```
diff --git a/site/docs/bep-glossary.md b/site/docs/bep-glossary.md
deleted file mode 100644
index 35c18a8..0000000
--- a/site/docs/bep-glossary.md
+++ /dev/null
@@ -1,508 +0,0 @@
----
-layout: documentation
-title: Build Event Protocol Glossary
----
-
-<div style="background-color: #EFCBCB; color: #AE2B2B; border: 1px solid #AE2B2B; border-radius: 5px; border-left: 10px solid #AE2B2B; padding: 0.5em;">
-<b>IMPORTANT:</b> The Bazel docs have moved! Please update your bookmark to <a href="https://bazel.build/docs/bep-glossary" style="color: #0000EE;">https://bazel.build/docs/bep-glossary</a>
-<p/>
-You can <a href="https://blog.bazel.build/2022/02/17/Launching-new-Bazel-site.html" style="color: #0000EE;">read about</a> the migration, and let us <a href="https://forms.gle/onkAkr2ZwBmcbWXj7" style="color: #0000EE;">know what you think</a>.
-</div>
-
-
-# Build Event Protocol Glossary
-
-
-Each BEP event type has its own semantics, minimally documented in
-[build\_event\_stream.proto](https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/buildeventstream/proto/build_event_stream.proto).
-The following glossary describes each event type.
-
-## Aborted
-
-Unlike other events, `Aborted` does not have a corresponding ID type, because
-the `Aborted` event *replaces* events of other types. This event indicates that
-the build terminated early and the event ID it appears under was not produced
-normally. `Aborted` contains an enum and human-friendly description to explain
-why the build did not complete.
-
-For example, if a build is evaluating a target when the user interrupts Bazel,
-BEP contains an event like the following:
-
-<p>
- <button class="btn btn-primary" type="button" data-toggle="collapse"
- data-target="#collapseAbortedJson" aria-expanded="false"
- aria-controls="collapseAbortedJson">
- Show/Hide BEP JSON
- </button>
-</p>
-
-```json
-{
- "id": {
- "targetCompleted": {
- "label": "//:foo",
- "configuration": {
- "id": "544e39a7f0abdb3efdd29d675a48bc6a"
- }
- }
- },
- "aborted": {
- "reason": "USER_INTERRUPTED"
- }
-}
-```
-{: .collapse #collapseAbortedJson}
-
-## ActionExecuted
-
-Provides details about the execution of a specific
-[Action](https://docs.bazel.build/skylark/lib/actions.html) in a build. By default, this event is
-included in the BEP only for failed actions, to support identifying the root cause
-of build failures. Users may set the `--build_event_publish_all_actions` flag
-to include all `ActionExecuted` events.
-
-## BuildFinished
-
-A single `BuildFinished` event is sent after the command is complete and
-includes the exit code for the command. This event provides authoritative
-success/failure information.
-
-## BuildMetadata
-
-Contains the parsed contents of the `--build_metadata` flag. This event exists
-to support Bazel integration with other tooling by plumbing external data (e.g.
-identifiers).
-
-## BuildMetrics
-
-A single `BuildMetrics` event is sent at the end of every command and includes
-counters/gauges useful for quantifying the build tool's behavior during the
-command. These metrics indicate work actually done and does not count cached
-work that is reused.
-
-Note that `memory_metrics` may not be populated if there was no Java garbage
-collection during the command's execution. Users may set the
-`--memory_profile=/dev/null` option which forces the garbage collector to run at
-the end of the command to populate `memory_metrics`.
-
-<p>
- <button class="btn btn-primary" type="button" data-toggle="collapse"
- data-target="#collapseBuildMetricsJson" aria-expanded="false"
- aria-controls="collapseBuildMetricsJson">
- Show/Hide BEP JSON
- </button>
-</p>
-
-```json
-{
- "id": {
- "buildMetrics": {}
- },
- "buildMetrics": {
- "actionSummary": {
- "actionsExecuted": "1"
- },
- "memoryMetrics": {},
- "targetMetrics": {
- "targetsLoaded": "9",
- "targetsConfigured": "19"
- },
- "packageMetrics": {
- "packagesLoaded": "5"
- },
- "timingMetrics": {
- "cpuTimeInMs": "1590",
- "wallTimeInMs": "359"
- }
- }
-}
-```
-{: .collapse #collapseBuildMetricsJson}
-
-## BuildStarted
-
-The first event in a BEP stream, `BuildStarted` includes metadata describing the
-command before any meaningful work begins.
-
-## BuildToolLogs
-
-A single `BuildToolLogs` event is sent at the end of a command, including URIs
-of files generated by the build tool that may aid in understanding or debugging
-build tool behavior. Some information may be included inline.
-
-<p>
- <button class="btn btn-primary" type="button" data-toggle="collapse"
- data-target="#collapseBuildToolLogsJson" aria-expanded="false"
- aria-controls="collapseBuildToolLogsJson">
- Show/Hide BEP JSON
- </button>
-</p>
-
-```json
-{
- "id": {
- "buildToolLogs": {}
- },
- "lastMessage": true,
- "buildToolLogs": {
- "log": [
- {
- "name": "elapsed time",
- "contents": "MC4xMjEwMDA="
- },
- {
- "name": "process stats",
- "contents": "MSBwcm9jZXNzOiAxIGludGVybmFsLg=="
- },
- {
- "name": "command.profile.gz",
- "uri": "file:///tmp/.cache/bazel/_bazel_foo/cde87985ad0bfef34eacae575224b8d1/command.profile.gz"
- }
- ]
- }
-}
-```
-{: .collapse #collapseBuildToolLogsJson}
-
-## CommandLine
-
-The BEP contains multiple `CommandLine` events containing representations of all
-command-line arguments (including options and uninterpreted arguments).
-Each `CommandLine` event has a label in its `StructuredCommandLineId` that
-indicates which representation it conveys; three such events appear in the BEP:
-
-* `"original"`: Reconstructed commandline as Bazel received it from the Bazel
- client, without startup options sourced from .rc files.
-* `"canonical"`: The effective commandline with .rc files expanded and
- invocation policy applied.
-* `"tool"`: Populated from the `--experimental_tool_command_line` option. This
- is useful to convey the command-line of a tool wrapping Bazel through the BEP.
- This could be a base64-encoded `CommandLine` binary protocol buffer messsage
- which is used directly, or a string which is parsed but not interpreted (as
- the tool's options may differ from Bazel's).
-
-## Configuration
-
-A `Configuration` event is sent for every [`configuration`](https://docs.bazel.build/skylark/config.html)
-used in the top-level targets in a build. At least one configuration event is
-always be present. The `id` is reused by the `TargetConfigured` and
-`TargetComplete` event IDs and is necessary to disambiguate those events in
-multi-configuration builds.
-
-<p>
- <button class="btn btn-primary" type="button" data-toggle="collapse"
- data-target="#collapseConfigurationJson" aria-expanded="false"
- aria-controls="collapseConfigurationJson">
- Show/Hide BEP JSON
- </button>
-</p>
-
-```json
-{
- "id": {
- "configuration": {
- "id": "a5d130b0966b4a9ca2d32725aa5baf40e215bcfc4d5cdcdc60f5cc5b4918903b"
- }
- },
- "configuration": {
- "mnemonic": "k8-fastbuild",
- "platformName": "k8",
- "cpu": "k8",
- "makeVariable": {
- "COMPILATION_MODE": "fastbuild",
- "TARGET_CPU": "k8",
- "GENDIR": "bazel-out/k8-fastbuild/bin",
- "BINDIR": "bazel-out/k8-fastbuild/bin"
- }
- }
-}
-```
-{: .collapse #collapseConfigurationJson}
-
-## ConvenienceSymlinksIdentified
-
-**Experimental.** If the `--experimental_convenience_symlinks_bep_event`
-option is set, a single `ConvenienceSymlinksIdentified` event is produced by
-`build` commands to indicate how symlinks in the workspace should be managed.
-This enables building tools that invoke Bazel remotely then arrange the local
-workspace as if Bazel had been run locally.
-
-<p>
- <button class="btn btn-primary" type="button" data-toggle="collapse"
- data-target="#collapseConvenienceSymlinksIdentifiedJson"
- aria-expanded="false"
- aria-controls="collapseConvenienceSymlinksIdentifiedJson">
- Show/Hide BEP JSON
- </button>
-</p>
-
-```json
-{
- "id": {
- "convenienceSymlinksIdentified":{}
- },
- "convenienceSymlinksIdentified": {
- "convenienceSymlinks": [
- {
- "path": "bazel-bin",
- "action": "CREATE",
- "target": "execroot/google3/bazel-out/k8-fastbuild/bin"
- },
- {
- "path": "bazel-genfiles",
- "action": "CREATE",
- "target": "execroot/google3/bazel-out/k8-fastbuild/genfiles"
- },
- {
- "path": "bazel-out",
- "action": "CREATE",
- "target": "execroot/google3/bazel-out"
- }
- ]
- }
-}
-```
-{: .collapse #collapseConvenienceSymlinksIdentifiedJson}
-
-## Fetch
-
-Indicates that a Fetch operation occurred as a part of the command execution.
-Unlike other events, if a cached fetch result is re-used, this event does not
-appear in the BEP stream.
-
-## NamedSetOfFiles
-
-`NamedSetOfFiles` events report a structure matching a
-[`depset`](https://docs.bazel.build/skylark/depsets.html) of files produced during command evaluation.
-Transitively included depsets are identified by `NamedSetOfFilesId`.
-
-For more information on interpreting a stream's `NamedSetOfFiles` events, see the
-[BEP examples page](bep-examples.html#consuming-namedsetoffiles).
-
-## OptionsParsed
-
-A single `OptionsParsed` event lists all options applied to the command,
-separating startup options from command options. It also includes the
-[InvocationPolicy](https://docs.bazel.build/command-line-reference.html#flag--invocation_policy), if any.
-
-<p>
- <button class="btn btn-primary" type="button" data-toggle="collapse"
- data-target="#collapseOptionsParsedJson" aria-expanded="false"
- aria-controls="collapseOptionsParsedJson">
- Show/Hide BEP JSON
- </button>
-</p>
-
-```json
-{
- "id": {
- "optionsParsed": {}
- },
- "optionsParsed": {
- "startupOptions": [
- "--max_idle_secs=10800",
- "--noshutdown_on_low_sys_mem",
- "--connect_timeout_secs=30",
- "--output_user_root=/tmp/.cache/bazel/_bazel_foo",
- "--output_base=/tmp/.cache/bazel/_bazel_foo/a61fd0fbee3f9d6c1e30d54b68655d35",
- "--deep_execroot",
- "--expand_configs_in_place",
- "--idle_server_tasks",
- "--write_command_log",
- "--nowatchfs",
- "--nofatal_event_bus_exceptions",
- "--nowindows_enable_symlinks",
- "--noclient_debug",
- ],
- "cmdLine": [
- "--enable_platform_specific_config",
- "--build_event_json_file=/tmp/bep.json"
- ],
- "explicitCmdLine": [
- "--build_event_json_file=/tmp/bep.json"
- ],
- "invocationPolicy": {}
- }
-}
-```
-{: .collapse #collapseOptionsParsedJson}
-
-## PatternExpanded
-
-`PatternExpanded` events indicate the set of all targets that match the patterns
-supplied on the commandline. For successful commands, a single event is present
-with all patterns in the `PatternExpandedId` and all targets in the
-`PatternExpanded` event's *children*. If the pattern expands to any
-`test_suite`s the set of test targets included by the `test_suite`. For each
-pattern that fails to resolve, BEP contains an additional [`Aborted`](#aborted)
-event with a `PatternExpandedId` identifying the pattern.
-
-<p>
- <button class="btn btn-primary" type="button" data-toggle="collapse"
- data-target="#collapsePatternExpandedJson" aria-expanded="false"
- aria-controls="collapsePatternExpandedJson">
- Show/Hide BEP JSON
- </button>
-</p>
-
-```json
-{
- "id": {
- "pattern": {
- "pattern":["//base:all"]
- }
- },
- "children": [
- {"targetConfigured":{"label":"//base:foo"}},
- {"targetConfigured":{"label":"//base:foobar"}}
- ],
- "expanded": {
- "testSuiteExpansions": {
- "suiteLabel": "//base:suite",
- "testLabels": "//base:foo_test"
- }
- }
-}
-```
-{: .collapse #collapsePatternExpandedJson}
-
-## Progress
-
-Progress events contain the standard output and standard error produced by Bazel
-during command execution. These events are also auto-generated as needed to
-announce events that have not been announced by a logical "parent" event (in
-particular, [NamedSetOfFiles](#namedsetoffiles).)
-
-## TargetComplete
-
-For each `(target, configuration, aspect)` combination that completes the
-execution phase, a `TargetComplete` event is included in BEP. The event contains
-the target's success/failure and the target's requested output groups.
-
-<p>
- <button class="btn btn-primary" type="button" data-toggle="collapse"
- data-target="#collapseTargetCompleteJson" aria-expanded="false"
- aria-controls="collapseTargetCompleteJson">
- Show/Hide BEP JSON
- </button>
-</p>
-
-```json
-{
- "id": {
- "targetCompleted": {
- "label": "//examples/py:bep",
- "configuration": {
- "id": "a5d130b0966b4a9ca2d32725aa5baf40e215bcfc4d5cdcdc60f5cc5b4918903b"
- }
- }
- },
- "completed": {
- "success": true,
- "outputGroup": [
- {
- "name": "default",
- "fileSets": [
- {
- "id": "0"
- }
- ]
- }
- ]
- }
-}
-```
-{: .collapse #collapseTargetCompleteJson}
-
-## TargetConfigured
-
-For each Target that completes the analysis phase, a `TargetConfigured` event is
-included in BEP. This is the authoritative source for a target's "rule kind"
-attribute. The configuration(s) applied to the target appear in the announced
-*children* of the event.
-
-For example, building with the `--experimental_multi_cpu` options may produce
-the following `TargetConfigured` event for a single target with two
-configurations:
-
-<p>
- <button class="btn btn-primary" type="button" data-toggle="collapse"
- data-target="#collapseTargetConfiguredJson" aria-expanded="false"
- aria-controls="collapseTargetConfiguredJson">
- Show/Hide BEP JSON
- </button>
-</p>
-
-```json
-{
- "id": {
- "targetConfigured": {
- "label": "//starlark_configurations/multi_arch_binary:foo"
- }
- },
- "children": [
- {
- "targetCompleted": {
- "label": "//starlark_configurations/multi_arch_binary:foo",
- "configuration": {
- "id": "c62b30c8ab7b9fc51a05848af9276529842a11a7655c71327ade26d7c894c818"
- }
- }
- },
- {
- "targetCompleted": {
- "label": "//starlark_configurations/multi_arch_binary:foo",
- "configuration": {
- "id": "eae0379b65abce68d54e0924c0ebcbf3d3df26c6e84ef7b2be51e8dc5b513c99"
- }
- }
- }
- ],
- "configured": {
- "targetKind": "foo_binary rule"
- }
-}
-```
-{: .collapse #collapseTargetConfiguredJson}
-
-## TargetSummary
-
-For each `(target, configuration)` pair that is executed, a `TargetSummary`
-event is included with an aggregate success result encompassing the configured
-target's execution and all aspects applied to that configured target.
-
-## TestResult
-
-If testing is requested, a `TestResult` event is sent for each test attempt,
-shard, and run per test. This allows BEP consumers to identify precisely which
-test actions failed their tests and identify the test outputs (e.g. logs,
-test.xml files) for each test action.
-
-## TestSummary
-
-If testing is requested, a `TestSummary` event is sent for each test `(target,
-configuration)`, containing information necessary to interpret the test's
-results. The number of attempts, shards and runs per test are included to enable
-BEP consumers to differentiate artifacts across these dimensions. The attempts
-and runs per test are considered while producing the aggregate `TestStatus` to
-differentiate `FLAKY` tests from `FAILED` tests.
-
-## UnstructuredCommandLine
-
-Unlike [CommandLine](#commandline), this event carries the unparsed commandline
-flags in string form as encountered by the build tool after expanding all
-[`.bazelrc`](guide.html#bazelrc-the-bazel-configuration-file) files and
-considering the `--config` flag.
-
-The `UnstructuredCommandLine` event may be relied upon to precisely reproduce a
-given command execution.
-
-## WorkspaceConfig
-
-A single `WorkspaceConfig` event contains configuration information regarding the
-workspace, such as the execution root.
-
-## WorkspaceStatus
-
-A single `WorkspaceStatus` event contains the result of the [workspace status
-command](user-manual.html#workspace_status).
diff --git a/site/docs/build-event-protocol.md b/site/docs/build-event-protocol.md
deleted file mode 100644
index 95b90bd..0000000
--- a/site/docs/build-event-protocol.md
+++ /dev/null
@@ -1,160 +0,0 @@
----
-layout: documentation
-title: Build Event Protocol
----
-
-<div style="background-color: #EFCBCB; color: #AE2B2B; border: 1px solid #AE2B2B; border-radius: 5px; border-left: 10px solid #AE2B2B; padding: 0.5em;">
-<b>IMPORTANT:</b> The Bazel docs have moved! Please update your bookmark to <a href="https://bazel.build/docs/build-event-protocol" style="color: #0000EE;">https://bazel.build/docs/build-event-protocol</a>
-<p/>
-You can <a href="https://blog.bazel.build/2022/02/17/Launching-new-Bazel-site.html" style="color: #0000EE;">read about</a> the migration, and let us <a href="https://forms.gle/onkAkr2ZwBmcbWXj7" style="color: #0000EE;">know what you think</a>.
-</div>
-
-
-# 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)
-(BEP) allows third-party programs to gain insight into a Bazel invocation. For
-example, you could use the BEP to gather information for an IDE
-plugin or a dashboard that displays build results.
-
-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 BEP is
-intended to be consumed programmatically and makes parsing Bazel’s
-command line output a thing of the past.
-
-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](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](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
-payload might not be the expected type, but could be an `Aborted` message e.g.
-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
-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
-
-To consume the BEP in a binary format:
-
-1. Have Bazel serialize the protocol buffer messages to a file by specifying the
-option `--build_event_binary_file=/path/to/file`. The file will contain
-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)`](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.
-
-### Consume in text or JSON formats
-
-The following Bazel command line flags will output the BEP in
-human-readable formats, such as text and JSON:
-
-```
---build_event_text_file
---build_event_json_file
-```
-
-## Build Event Service
-
-
-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 publishing build events. The Build Event
-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. 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.
-
-### Build Event Service flags
-
-Bazel has several flags related to the Build Event Service protocol, including:
-
-* `--bes_backend`
-* `--[no]bes_best_effort`
-* `--[no]bes_lifecycle_events`
-* `--bes_results_url`
-* `--bes_timeout`
-* `--project_id`
-
-For a description of each of these flags, see the
-[Command-Line Reference](command-line-reference.html).
-
-### 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
-authentication and TLS infrastructure.
-
-* `--[no]google_default_credentials`
-* `--google_credentials`
-* `--google_auth_scopes`
-* `--tls_certificate`
-* `--[no]tls_enabled`
-
-For a description of each of these flags, see the
-[Command-Line Reference](command-line-reference.html).
-
-### Build Event Service and remote caching
-
-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](remote-caching.html).
-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](https://github.com/bazelbuild/bazel/issues/3689) for
-more details.
-
diff --git a/site/docs/build-ref.html b/site/docs/build-ref.html
deleted file mode 100644
index 7072ff0..0000000
--- a/site/docs/build-ref.html
+++ /dev/null
@@ -1,1000 +0,0 @@
----
-layout: documentation
-title: Concepts and terminology
-category: getting-started
----
-
-<div style="background-color: #EFCBCB; color: #AE2B2B; border: 1px solid #AE2B2B; border-radius: 5px; border-left: 10px solid #AE2B2B; padding: 0.5em;">
-<b>IMPORTANT:</b> The Bazel docs have moved! Please update your bookmark to <a href="https://bazel.build/concepts/build-ref" style="color: #0000EE;">https://bazel.build/concepts/build-ref</a>
-<p/>
-You can <a href="https://blog.bazel.build/2022/02/17/Launching-new-Bazel-site.html" style="color: #0000EE;">read about</a> the migration, and let us <a href="https://forms.gle/onkAkr2ZwBmcbWXj7" style="color: #0000EE;">know what you think</a>.
-</div>
-
-<h1>Concepts and Terminology</h1>
-<p>
- This page provides an overview of the source tree layout and the
- terminology used in Bazel.
-</p>
-<h2 id="intro">Introduction</h2>
-
-<p>Bazel builds software from source code organized in a directory called
- a workspace. Source files in the workspace are organized in a nested
- hierarchy of packages, where each package is a directory that contains a set
- of related source files and one BUILD file. The BUILD file specifies what
- software outputs can be built from the source.
-</p>
-<h2 id="packages_targets">Workspaces, repositories, packages, and targets</h2>
-<h3 id="workspace">Workspace</h3>
-
-<p>A <em>workspace</em> is a directory on your filesystem that contains the
- source files for the software you want to build. Each workspace directory has
- a text file named <code>WORKSPACE</code> which may be empty, or may contain
- references to <a href="external.html">external dependencies</a>
- required to build the outputs.</p>
-
-<p>Directories containing a file called
- <code>WORKSPACE</code> are considered the root of a workspace.
- Therefore, Bazel ignores any directory trees in a workspace rooted
- at a subdirectory containing a <code>WORKSPACE</code> file (as they form
- another workspace).</p>
-
-<p>Bazel also supports <code>WORKSPACE.bazel</code> file as an alias of <code>WORKSPACE</code> file.
- If both files exist, <code>WORKSPACE.bazel</code> will take the priority.</p>
-
-<h3 id="repositories">Repositories</h3>
-<p>Code is organized in <em>repositories</em>. The directory containing
- the <code>WORKSPACE</code> file is the root of the main repository, also
- called <code>@</code>. Other, (external) repositories
- are defined in the <code>WORKSPACE</code> file using workspace rules.
-
-<p>The workspace rules bundled with Bazel are documented in the
- <a href="be/workspace.html">Workspace Rules</a> section in the
- <a href="be/overview.html">Build Encyclopedia</a> and the documentation on
- <a href="repo/index.html">embedded Starlark repository rules</a>.</p>
-
-<p>As external repositories are repositories themselves, they often contain
- a <code>WORKSPACE</code> file as well. However, these additional
- <code>WORKSPACE</code> files are ignored by Bazel. In particular,
- repositories depended upon transitively are not added automatically.</p>
-
-<h3 id="packages">Packages</h3>
-<p>
- The primary unit of code organization in a repository is
- the <i>package</i>. A package is a collection of related files and a
- specification of the dependencies among them.
-</p>
-
-<p>
- A package is defined as a directory containing a file
- named <code>BUILD</code> or <code>BUILD.bazel</code>,
- residing beneath the top-level directory in the
- workspace. A package includes all files in its directory, plus all
- subdirectories beneath it, except those which themselves contain a BUILD
- file.
-</p>
-
-<p>
- For example, in the following directory tree
- there are two packages, <code>my/app</code>,
- and the subpackage <code>my/app/tests</code>.
- Note that <code>my/app/data</code> is not a package, but a directory
- belonging to package <code>my/app</code>.
-</p>
-
-<pre>
-src/my/app/BUILD
-src/my/app/app.cc
-src/my/app/data/input.txt
-src/my/app/tests/BUILD
-src/my/app/tests/test.cc
-</pre>
-<h3 id="targets">Targets</h3>
-
-<p>
- A package is a container. The elements of a package are called
- <i>targets</i>. Most targets are one of two principal kinds, <i>files</i>
- and <i>rules</i>. Additionally, there is another kind of target,
- <a href="be/functions.html#package_group">package groups</a>,
- but they are far less numerous.
-</p>
-
-<p>
- Files are further divided into two kinds.
- <i>Source files</i> are usually written by the efforts of people,
- and checked in to the repository.
- <i>Generated files</i>, sometimes called derived files or output files,
- are not checked in, but are generated by the build tool from source
- files according to specific rules.
-</p>
-
-<p>
- The second kind of target is the <i>rule</i>. A rule specifies the
- relationship between a set of input and a set of output files,
- including the necessary steps to derive the outputs from the inputs.
- The outputs of a rule are always generated files. The inputs to a
- rule may be source files, but they may be generated files also;
- consequently, outputs of one rule may be the inputs to another,
- allowing long chains of rules to be constructed.
-</p>
-
-<p>
- Whether the input to a rule is a source file or a generated file is
- in most cases immaterial; what matters is only the contents of that
- file. This fact makes it easy to replace a complex source file with
- a generated file produced by a rule, such as happens when the burden
- of manually maintaining a highly structured file becomes too
- tiresome, and someone writes a program to derive it. No change is
- required to the consumers of that file. Conversely, a generated
- file may easily be replaced by a source file with only local
- changes.
-</p>
-
-<p>
- The inputs to a rule may also include <i>other rules</i>. The
- precise meaning of such relationships is often quite complex and
- language- or rule-dependent, but intuitively it is simple: a C++
- library rule A might have another C++ library rule B for an input.
- The effect of this dependency is that B's header files are
- available to A during compilation, B's symbols are available to A
- during linking, and B's runtime data is available to A during
- execution.
-</p>
-
-<p>
- An invariant of all rules is that the files generated by a rule
- always belong to the same package as the rule itself; it is not
- possible to generate files into another package. It is not uncommon
- for a rule's inputs to come from another package, though.
-</p>
-
-<p>
- Package groups are sets of packages whose purpose is to limit accessibility
- of certain rules. Package groups are defined by the
- <code>package_group</code> function. They have three properties: the list of
- packages they contain, their name, and other package groups they include. The only allowed ways to refer to them
- are from the <code>visibility</code> attribute of rules or from the
- <code>default_visibility</code> attribute of the <code>package</code>
- function; they do not generate or consume files. For more information, refer
- to the <a
- href='be/functions.html#package_group'><code>package_group</code>
- documentation</a>.
-</p>
-
-
-<h3 id="labels">Labels</h3>
-
-<p>
- All targets belong to exactly one package. The name of a target is
- called its <em>label</em>. Every label uniquely identifies a target. A
- typical label in canonical form looks like:
-</p>
-
-
-<pre>
-@myrepo//my/app/main:app_binary
-</pre>
-
-<p>
- The first part of the label is the repository name, <code>@myrepo//</code>.
- In the typical case that a label refers to the same repository from which
- it is used, the repository identifier may be abbreviated as <code>//</code>.
- So, inside <code>@myrepo</code> this label is usually written as
-</p>
-
-<pre>
-//my/app/main:app_binary
-</pre>
-
-<p>
-
- The second part of the label is the un-qualified package name
- <code>my/app/main</code>, the path to the package
- relative to the repository root. Together, the repository name and the
- un-qualified package name form the fully-qualified package name
- <code>@myrepo//my/app/main</code>. When the label refers to the same
- package it is used in, the package name (and optionally, the colon)
- may be omitted. So, inside <code>@myrepo//my/app/main</code>,
- this label may be written either of the following ways:
-
-</p>
-
-<pre>
-app_binary
-:app_binary
-</pre>
-
-<p>
- It is a matter of convention that the colon is omitted for files,
- but retained for rules, but it is not otherwise significant.
-</p>
-
-<p>
- The part of the label after
- the colon, <code>app_binary</code> is the un-qualified target name.
- When it matches the last component of the package path, it, and
- the colon, may be omitted. So, these two labels are
- equivalent:
-</p>
-
-<pre>
-//my/app/lib
-//my/app/lib:lib
-</pre>
-
-<p>
- The name of a file target in a subdirectory of the
- package is the file's path relative to the package
- root (the directory containing the <code>BUILD</code> file).
- So, this file is in the <code>my/app/main/testdata</code>
- subdirectory of the repository:
-</p>
-
-<pre>
-//my/app/main:testdata/input.txt
-</pre>
-
-<p>
- Don't confuse labels like <code>//my/app</code> with package names. Labels
- always start with a repository identifier (often abbreviated <code>//</code>)
- but package names never do. Thus, <code>my/app</code> is the package
- containing <code>//my/app/lib</code> (a.k.a.
- <code>//my/app/lib:lib</code>).
-
- (A common misconception is that <code>//my/app</code> refers
- to a package, or to <em>all</em> the targets in a package; neither
- is true. Remember, it is equivalent to <code>//my/app:app</code>, so it names
- the <code>app</code> target in the <code>my/app</code> package of the current repository).
-</p>
-
-<p>
- Relative labels cannot be used to refer to targets in other
- packages; the repository identifier and package name must
- always be specified in this case. For example, if the source
- tree contains both the package
- <code>my/app</code> and the package
- <code>my/app/testdata</code> (i.e., each of these two
- directories has its own BUILD file). The latter package contains a
- file named <code>testdepot.zip</code>. Here are two ways (one
- wrong, one correct) to refer to this file within
- <code>//my/app:BUILD</code>:
-</p>
-
-<pre>
-<span class="discouraged">testdata/testdepot.zip</span> # Wrong: testdata is a different package.
-//my/app/testdata:testdepot.zip # Right.
-</pre>
-
-<p>
- Labels starting with <code>@//</code> are references to the main
- repository, which will still work even from external repositories.
- Therefore <code>@//a/b/c</code> is different from
- <code>//a/b/c</code> when referenced from an external repository.
- The former refers back to the main repository, while the latter
- looks for <code>//a/b/c</code> in the external repository itself.
- This is especially relevant when writing rules in the main
- repository that refer to targets in the main repository, and will be
- used from external repositories.
-</p>
-
-<p>
-For information about the different ways you can refer to targets, see
-<a href="guide.md#specifying-targets-to-build">target patterns</a>.
-</p>
-
-
-<h3 id="lexi">Lexical specification of a label</h3>
-
-<p>
- Label syntax discourages use of metacharacters that have special meaning to the shell. This helps
- to avoid inadvertent quoting problems, and makes it easier to construct tools and scripts that
- manipulate labels, such as the <a href='query.html'>Bazel Query Language</a>.
-
- The precise details of allowed target names are below.
-</p>
-
-<h4 id="name">Target names, <code>//<package name>:<b>target-name</b></code></h4>
-
-<p><code>target-name</code> is the name of the target within the package.
- The name of a rule is the value of the <code>name</code>
- attribute in the rule's declaration in a BUILD file; the name
- of a file is its pathname relative to the directory containing
- the BUILD file.
- Target names must be composed entirely of
- characters drawn from the set <code>a</code>–<code>z</code>,
- <code>A</code>–<code>Z</code>, <code>0</code>–<code>9</code>,
- and the punctuation symbols <code>!%-@^_` "#$&'()*-+,;<=>?[]{|}~/.</code>.
- Do not use <code>..</code> to refer to files in other packages; use
- <code>//<var>packagename</var>:<var>filename</var></code> instead.
- Filenames must be relative pathnames in normal form, which means
- they must neither start nor end with a slash
- (e.g. <code>/foo</code> and <code>foo/</code> are forbidden) nor
- contain multiple consecutive slashes as path separators
- (e.g. <code>foo//bar</code>). Similarly, up-level references
- (<code>..</code>) and current-directory references
- (<code>./</code>) are forbidden.
-</p>
-
-<p>While it is common to use <code>/</code> in the name of a file
- target, it is recommended that you avoid the use of <code>/</code> in the
- names of rules. Especially when the shorthand form of a label is
- used, it may confuse the reader. The
- label <code>//foo/bar/wiz</code> is always a shorthand
- for <code>//foo/bar/wiz:wiz</code>, even if there is no such package
- <code>foo/bar/wiz</code>; it never refers to <code>//foo:bar/wiz</code>,
- even if that target exists.</p>
-
-<p>However, there are some situations where use of a slash is
- convenient, or sometimes even necessary. For example, the name of
- certain rules must match their principal source file, which may
- reside in a subdirectory of the package.</p>
-
-<h4>Package names, <code>//<b>package-name</b>:<target name></code></h4>
-<p>
- The name of a package is the name of the directory containing its
-
- BUILD file, relative to the top-level directory of the containing
- repository. For example: <code>my/app</code>.
-
- Package names must be composed entirely of characters drawn from
- the set <code>A</code>-<code>Z</code>, <code>a</code>–<code>z</code>,
- <code>0</code>–<code>9</code>, '<code>/</code>', '<code>-</code>',
- '<code>.</code>', and '<code>_</code>', and cannot start with
- a slash.
-<p>
- For a language with a directory structure that is significant
- to its module system (e.g. Java), it is important to choose directory names
- that are valid identifiers in the language.
-</p>
-
-<p>
- Although Bazel supports targets in the workspace's root package
- (e.g. <code>//:foo</code>), it's best to leave that package empty
- so all meaningful packages have descriptive names.
-</p>
-<p>
- Package names may not contain the substring <code>//</code>, nor
- end with a slash.
-</p>
-
-<h3 id="rules">Rules</h3>
-
-<p>
- A rule specifies the relationship between inputs and outputs, and the
- steps to build the outputs. Rules can be of one of many different
- kinds or <i>classes</i>, which produce compiled
- executables and libraries, test executables and other supported
- outputs as described in the
- <a href="be/overview.html">Build Encyclopedia</a>.
-</p>
-
-<p>
- Every rule has a name, specified by the <code>name</code> attribute,
- of type string. The name must be a syntactically valid target name,
- as specified <a href='#name'>above</a>. In some cases, the name is
- somewhat arbitrary, and more interesting are the names of the files
- generated by the rule, and this is true of genrules. For more information, see
- <a href="be/general.html#genrule">
- General Rules: genrule</a>.
-
- In other cases, the name is significant: for <code>*_binary</code>
- and <code>*_test</code> rules, for example, the rule name determines
- the name of the executable produced by the build.
-</p>
-
-<pre>
-cc_binary(
- name = "my_app",
- srcs = ["my_app.cc"],
- deps = [
- "//absl/base",
- "//absl/strings",
- ],
-)
-</pre>
-
-<p>
- Every rule has a set of <i>attributes</i>; the applicable attributes
- for a given rule, and the significance and semantics of each
- attribute are a function of the rule's class; see
- the <a href='be/overview.html'>Build
- Encyclopedia</a> for a list of rules and their
- corresponding attributes. Each attribute has a name and a
- type. Some of the common types an attribute can have are integer,
- label, list of labels, string, list of strings, output label,
- list of output labels. Not all attributes need to be specified in
- every rule. Attributes thus form a dictionary from keys (names) to
- optional, typed values.
-</p>
-
-<p>
- The <code>srcs</code> attribute present in many rules has type "list
- of labels"; its value, if present, is a list of labels, each being
- the name of a target that is an input to this rule.
-</p>
-
-<p>
- This directed acyclic graph over targets is called the
- "target graph" or "build dependency graph", and is the domain over
- which the <a href='query.html'>Bazel Query tool</a> operates.
-</p>
-
-
-<h2 id="BUILD_files">BUILD files</h2>
-
-<p>
- The previous section described packages, targets and labels, and the
- build dependency graph abstractly. This section describes the
- concrete syntax used to define a package.
-</p>
-
-<p>
- By definition, every package contains a BUILD file, which is a short
- program.
- BUILD files are evaluated using an imperative language,
- <a href="https://github.com/bazelbuild/starlark/">Starlark</a>.
-
- They are interpreted as a sequential list of statements.
-</p>
-
-<p>
- In general, order does matter: variables must be defined before they are used, for
- example. However, most BUILD files consist only of declarations of
- build rules, and the relative order of these statements is
- immaterial; all that matters is <em>which</em> rules were declared,
- and with what values, by the time package evaluation completes.
-
- When a build rule function, such as <code>cc_library</code>, is
- executed, it creates a new target in the graph. This target can later be
- referred using a label.
-
- So, in simple BUILD files, rule declarations can be re-ordered
- freely without changing the behavior.
-</p>
-
-
-<p>
- To encourage a clean separation between code and data, BUILD files cannot
- contain function definitions, <code>for</code> statements or
- <code>if</code> statements (but list comprehensions and <code>if</code>
- expressions are allowed). Functions can be declared in <code>.bzl</code>
- files instead. Additionally, <code>*args</code> and <code>**kwargs</code>
- arguments are not allowed in BUILD files; instead list all the arguments
- explicitly.
-</p>
-
-<p>
- Crucially, programs in Starlark are unable to perform
- arbitrary I/O. This invariant makes the
- interpretation of BUILD files hermetic, i.e. dependent only on a
- known set of inputs, which is essential for ensuring that builds are
- reproducible.
-</p>
-
-<p>
- BUILD files should be written using only ASCII characters,
- although technically they are interpreted using the Latin-1
- character set.
-</p>
-
-<p>
- Since BUILD files need to be updated whenever the dependencies of the
- underlying code change, they are typically maintained by multiple
- people on a team. BUILD file authors are encouraged to use comments
- liberally to document the role of each build target, whether or not it
- is intended for public use, and to document the role of the package
- itself.
-</p>
-
-<h3 id="load">Loading an extension</h3>
-
-Bazel extensions are files ending in <code>.bzl</code>. Use
-the <code>load</code> statement to import a symbol from an extension.
-
-<pre>
-load("//foo/bar:file.bzl", "some_library")
-</pre>
-
-This code will load the file <code>foo/bar/file.bzl</code> and add the
-<code>some_library</code> symbol to the environment. This can be used to load
-new rules, functions or constants (e.g. a string, a list, etc.). Multiple
-symbols can be imported by using additional arguments to the call
-to <code>load</code>. Arguments must be string literals (no variable)
-and <code>load</code> statements must appear at top-level, i.e. they cannot be
-in a function body.
-
-The first argument of <code>load</code> is a <a href="#labels">label</a>
-identifying a <code>.bzl</code> file. If it is a relative label, it is resolved
-with respect to the package (not directory) containing the current
-<code>bzl</code> file. Relative labels in <code>load</code> statements should
-use a leading <code>:</code>.
-
-<code>load</code> also supports aliases, i.e. you can assign different names to
-the imported symbols.
-
-<pre>
-load("//foo/bar:file.bzl", library_alias = "some_library")
-</pre>
-
-You can define multiple aliases within one <code>load</code> statement.
-Moreover, the argument list can contain both aliases and regular symbol names.
-The following example is perfectly legal (please note when to use quotation
-marks).
-
-<pre>
-load(":my_rules.bzl", "some_rule", nice_alias = "some_other_rule")
-</pre>
-
-In a <code>.bzl</code> file, symbols starting with <code>_</code> are not
-exported and cannot be loaded from another file. Visibility doesn't affect
-loading (yet): you don't need to use <code>exports_files</code> to make
-a <code>.bzl</code> file visible.
-
-<h2 id="funcs">Types of build rules</h2>
-
-<p>
- The majority of build rules come in families, grouped together by
- language. For example, <code>cc_binary</code>, <code>cc_library</code>
- and <code>cc_test</code> are the build rules for C++ binaries,
- libraries, and tests, respectively. Other languages use the same
- naming scheme, with a different prefix, e.g. <code>java_*</code> for
- Java. Some of these functions are documented in the
- <a href="be/overview.html">Build Encyclopedia</a>, but it is possible
- for anyone to create new rules.
-</p>
-
-<ul>
- <li><p><code>*_binary</code>
- rules build executable programs in a given language. After a
- build, the executable will reside in the build tool's binary
- output tree at the corresponding name for the rule's label,
- so <code>//my:program</code> would appear at
- (e.g.) <code>$(BINDIR)/my/program</code>. </p>
-
- <p>In some languages, such rules also create a runfiles directory
-
- containing all the files mentioned in a <code>data</code>
- attribute belonging to the rule, or any rule in its transitive
- closure of dependencies; this set of files is gathered together in
- one place for ease of deployment to production.</p>
- </li>
-
- <li><p><code>*_test</code>
- rules are a specialization of a <code>*_binary</code> rule, used for automated
- testing. Tests are simply programs that return zero on success.
-
- </p>
-
- <p>
- Like binaries, tests also have runfiles trees, and the files
- beneath it are the only files that a test may legitimately open
- at runtime. For example, a program <code>cc_test(name='x',
- data=['//foo:bar'])</code> may open and
-
- read <code>$TEST_SRCDIR/workspace/foo/bar</code> during execution.
- (Each programming language has its own utility function for
- accessing the value of <code>$TEST_SRCDIR</code>, but they are all
- equivalent to using the environment variable directly.)
- Failure to observe the rule will cause the test to fail when it is
- executed on a remote testing host.
-
- </p>
- </li>
-
- <li><code>*_library</code>
- rules specify separately-compiled modules in the given
- programming language. Libraries can depend on other libraries,
- and binaries and tests can depend on libraries, with the expected
- separate-compilation behavior.
- </li>
-</ul>
-
-<h2 id="dependencies">Dependencies</h2>
-
-<p>
- A target <code>A</code> <i>depends upon</i> a target
- <code>B</code> if <code>B</code> is needed by <code>A</code> at
- build or execution time. The <i>depends upon</i> relation induces a
- <a href="https://en.wikipedia.org/wiki/Directed_acyclic_graph">Directed
- Acyclic Graph</a> (DAG) over targets, and it is called a
- <em>dependency graph</em>.
-
- A target's <em>direct</em> dependencies are those other targets
- reachable by a path of length 1 in the dependency graph. A target's
- <em>transitive</em> dependencies are those targets upon which it
- depends via a path of any length through the graph.
-</p>
-
-<p>
- In fact, in the context of builds, there are two dependency graphs,
- the graph of <em>actual dependencies</em> and the graph of
- <em>declared dependencies</em>. Most of the time, the two graphs
- are so similar that this distinction need not be made, but it is
- useful for the discussion below.
-</p>
-
-<h3 id="actual_and_declared_dependencies">Actual and declared dependencies</h3>
-
-<p>
- A target <code>X</code> is <i>actually dependent</i> on target
- <code>Y</code> if and only if <code>Y</code> must be present, built
- and up-to-date in order for <code>X</code> to be built correctly.
- "Built" could mean generated, processed, compiled, linked,
- archived, compressed, executed, or any of the other kinds of tasks
- that routinely occur during a build.
-</p>
-
-<p>
- A target <code>X</code> has a <i>declared dependency</i> on target
- <code>Y</code> if and only if there is a dependency edge from <code>X</code>
- to <code>Y</code> in the package of <code>X</code>.
-</p>
-
-<p>
- For correct builds, the graph of actual dependencies <i>A</i> must
- be a subgraph of the graph of declared dependencies <i>D</i>. That
- is, every pair of directly-connected nodes <code>x --> y</code>
- in <i>A</i> must also be directly connected in <i>D</i>. It can be said that
- <i>D</i> is an <em>overapproximation</em> of <i>A</i>.
-</p>
-
-<p>
- It is important that it is not too much of an overapproximation,
- though, since redundant declared dependencies can make builds slower and
- binaries larger.
-</p>
-
-<p>
- What this means for BUILD file writers is that every rule must
- explicitly declare all of its actual direct dependencies to the
- build system, and no more.
-
- Failure to observe this principle causes undefined behavior: the
- build may fail, but worse, the build may depend on some prior
- operations, or upon transitive declared dependencies the target
- happens to have. The build tool attempts aggressively to check for
- missing dependencies and report errors, but it is not possible for
- this checking to be complete in all cases.
-</p>
-
-<p>
-
- You need not (and should not) attempt to list everything indirectly imported,
- even if it is "needed" by A at execution time.
-</p>
-
-<p>
- During a build of target <code>X</code>, the build tool inspects the
- entire transitive closure of dependencies of <code>X</code> to ensure that
- any changes in those targets are reflected in the final result,
- rebuilding intermediates as needed.
-</p>
-
-<p>
- The transitive nature of dependencies leads to a common mistake.
- Through careless programming, code in one file may use code provided
- by an <em>indirect</em> dependency, i.e. a transitive but not direct
- edge in the declared dependency graph. Indirect dependencies do not
- appear in the BUILD file. Since the rule doesn't
- directly depend on the provider, there is no way to track changes,
- as shown in the following example timeline:
-</p>
-
-<div class="greenbox">
-<p><b>1. At first, everything works</b></p>
-
-<p>The code in package <code>a</code> uses code in package <code>b</code>.
-The code in package <code>b</code> uses code in package <code>c</code>,
-and thus <code>a</code> transitively depends on <code>c</code>.</p>
-
-<div style="float:left; width: 49%; margin-top: -20px;">
-<p><code>a/BUILD</code></p>
-<pre class="code">
-<b>rule(
- name = "a",
- srcs = "a.in",
- deps = "//b:b",
-)</b>
-</pre>
-<p><code>a/a.in</code></p>
-<pre class="code">
-<b>import b;
-b.foo();</b>
-</pre>
-</div>
-<div style="float:right; width: 49%; margin-top: -20px; ">
-<p><code>b/BUILD</code></p>
-<pre class="code">
-<b>rule(
- name = "b",
- srcs = "b.in",
- deps = "//c:c",
-)</b>
-</pre>
-<p><code>b/b.in</code></p>
-<pre class="code">
-<b>import c;
-function foo() {
- c.bar();
-}</b>
-</pre>
-</div>
-<table style='margin: auto; width: 100%'><tr>
-<td style='padding: 10px; text-align: center'>
-<!-- digraph G {
- graph [size="4,4"];
- node [shape=circle];
- rankdir="LR";
- a -> b -> c;
-} -->
-<img src="images/a_b_c.svg" alt="a_b_c.svg" style="margin-left=10;" />
-<p><i>Declared dependency graph</i></p>
-</td>
-<td style='padding: 10px; text-align: center'>
-<!-- digraph G {
- graph [size="4,4"];
- node [shape=circle];
- rankdir="LR";
- a -> b -> c;
-} -->
-<img src="images/a_b_c.svg" alt="a_b_c.svg" style="margin-left=10;" />
-<p><i>Actual dependency graph</i></p>
-</td>
-</tr></table>
-The declared dependencies overapproximate the actual dependencies.
-All is well.
-</div>
-
-<div class="greenbox">
-<p><b>2. A latent hazard is introduced.</b></p>
-<p>
- Someone carelessly adds code to <code>a</code> that creates a direct
- actual dependency on <code>c</code>, but forgets to declare it in
- the build file <code>a/BUILD</code>.
-</p>
-<div style="float:left; width: 49%; margin-top: -20px; ">
-<p><code>a/a.in</code></p>
-<pre class="code">
-import b;
-<b>import c;</b>
-b.foo();
-<b>c.garply();</b>
-</pre>
-</div>
-
-<table style='margin: auto; width: 100%'><tr>
-<td style='padding: 10px; text-align: center'>
-<!-- digraph G {
- graph [size="4,4"];
- node [shape=circle];
- rankdir="LR";
- a -> b -> c;
-} -->
-<img src="images/a_b_c.svg" alt="a_b_c.svg" style="margin-left=10;" />
-<p><i>Declared dependency graph</i></p>
-</td>
-<td style='padding: 10; text-align: center'>
-<!-- digraph G {
- graph [size="4,4"];
- node [shape=circle];
- rankdir="LR";
- a -> b -> c;
- a -> c [constraint=false];
-} -->
-<img src="images/a_b_c_ac.svg" alt="a_b_c_ac.svg" style="margin-left=10;" />
-<p><i>Actual dependency graph</i></p>
-</td>
-</tr></table>
-The declared dependencies no longer overapproximate the actual
-dependencies. This may build ok, because the transitive closures of
-the two graphs are equal, but masks a problem: <code>a</code> has an
-actual but undeclared dependency on <code>c</code>.
-</div>
-
-<div class="greenbox">
-<p><b>3. The hazard is revealed</b> </p>
-<p>
- Someone refactors <code>b</code> so that it no longer depends on
- <code>c</code>, inadvertently breaking <code>a</code> through no
- fault of their own.
-</p>
-<div style="float:right; width: 49%; margin-top: -20px; ">
-<p><code>b/BUILD</code></p>
-<pre class="code">
-rule(
- name = "b",
- srcs = "b.in",
- <b>deps = "//d:d"</b>,
-)
-</pre>
-<p><code>b/b.in</code></p>
-<pre class="code">
-<b>import d;</b>
-function foo() {
- <b>d.baz();</b>
-}
-</pre>
-</div>
-<table style='margin: auto; width: 100%'><tr>
-<td style='padding: 10px; text-align: center'>
-<!-- digraph G {
- graph [size="4,4"];
- node [shape=circle];
- rankdir="LR";
- a -> b;
- b -> c [style=invis];
-} -->
-<img src="images/ab_c.svg" alt="ab_c.svg" style="margin-left=10;" />
-<p><i>Declared dependency graph</i></p>
-</td>
-<td style='padding: 10; text-align: center'>
-<!-- digraph G {
- graph [size="4,4"];
- node [shape=circle];
- rankdir="LR";
- a -> b;
- b -> c [style=invis];
- a -> c [constraint=false];
-} -->
-<img src="images/a_b_a_c.svg" alt="a_b_a_c.svg" style="margin-left=10;" />
-<p><i>Actual dependency graph</i></p>
-</td>
-</tr></table>
-<p>
- The declared dependency graph is now an underapproximation of the
- actual dependencies, even when transitively closed; the build is
- likely to fail.
-
- The problem could have been averted by ensuring that the actual
- dependency from <code>a</code> to <code>c</code> introduced in Step
- 2 was properly declared in the BUILD file.
-</div>
-
-<h3 id="types_of_dependencies">Types of dependencies</h3>
-
-<p>
- Most build rules have three attributes for specifying different kinds
- of generic dependencies: <code>srcs</code>, <code>deps</code> and
- <code>data</code>. These are explained below. See also
- <a href='be/common-definitions.html'>Attributes common
- to all rules</a> in the Build Encyclopedia.
-</p>
-
-<p>
- Many rules also have additional attributes for rule-specific kinds
- of dependency, e.g. <code>compiler</code>, <code>resources</code>,
- etc. These are detailed in the Build Encyclopedia.
-</p>
-
-<h4 id="srcs"><code>srcs</code> dependencies</h4>
-<p>
- Files consumed directly by the rule or rules that output source files.
-</p>
-
-<h4 id="deps"><code>deps</code> dependencies</h4>
-<p>
- Rule pointing to separately-compiled modules providing header files,
- symbols, libraries, data, etc.
-</p>
-
-<h4 id="data"><code>data</code> dependencies</h4>
-<p>A build target might need some data files to run correctly. These
- data files aren't source code: they don't affect how the target is
- built. For example, a unit test might compare a function's output
- to the contents of a file. When you build the unit test you
- don't need the file, but you do need it when you run the test. The
- same applies to tools that are launched during execution.
-
-<p>The build system runs tests in an isolated directory where only files
- listed as "data" are available. Thus, if a binary/library/test
- needs some files to run, specify them (or a build rule containing
- them) in data. For example:
-</p>
-
-<pre>
-# I need a config file from a directory named env:
-java_binary(
- name = "setenv",
- ...
- data = [":env/default_env.txt"],
-)
-
-# I need test data from another directory
-sh_test(
- name = "regtest",
- srcs = ["regtest.sh"],
- data = [
- "//data:file1.txt",
- "//data:file2.txt",
- ...
- ],
-)
-</pre>
-
-<p>These files are available using the relative path
-<code>path/to/data/file</code>. In tests, it is also possible to refer to
-them by joining the paths of the test's source directory and the workspace-relative
-path, e.g.
-
-<code>${TEST_SRCDIR}/workspace/path/to/data/file</code>.
- <h3 id="label_directory">Using labels to reference directories</h3>
-
- <p>As you look over our <code>BUILD</code> files, you might notice
- that some <code>data</code> labels refer to directories.
- These labels end with <code>/.</code> or <code>/</code> like so:
-
-<pre>
-<span style="text-decoration: line-through">data = ["//data/regression:unittest/."]</span> # don't use this
-</pre>
-<p>
-or like so:
-</p>
-<pre>
-<span style="text-decoration: line-through">data = ["testdata/."]</span> # don't use this
-</pre>
-
-<p>
-or like so:
-</p>
-
-<pre>
-<span style="text-decoration: line-through">data = ["testdata/"]</span> # don't use this
-</pre>
- <p>This seems convenient, particularly for tests (since it allows a test to
- use all the data files in the directory).
- </p>
-
- <p>But try not to do this. In order to ensure correct incremental rebuilds (and
- re-execution of tests) after a change, the build system must be
- aware of the complete set of files that are inputs to the build (or
- test). When you specify a directory, the build system will perform
- a rebuild only when the directory itself changes (due to addition or
- deletion of files), but won't be able to detect edits to individual
- files as those changes do not affect the enclosing directory.
- Rather than specifying directories as inputs to the build system,
- you should enumerate the set of files contained within them, either
- explicitly or using the
- <a href='be/functions.html#glob'><code>glob()</code></a> function.
- (Use <code>**</code> to force the <a href='be/functions.html#glob'>
- <code>glob()</code></a> to be recursive.)
- </p>
-
-<pre>
-data = glob(["testdata/**"]) # use this instead
-</pre>
-
- <p>Unfortunately, there are some scenarios where directory labels must be used.
- For example, if the <code>testdata</code> directory contains files whose
- names do not conform to the <a href='#lexi'>label syntax</a>, then explicit
- enumeration of files, or use of the
- <a href='be/functions.html#glob'><code>glob()</code></a> function will
- produce an invalid labels error. You must use directory labels in this case,
- but beware of the concomitant risk of incorrect rebuilds described above.
- </p>
-
- <p>If you must use directory labels, keep in mind that you can't refer to the parent
- package with a relative "<code>../</code>" path; instead, use an absolute path like
- "<code>//data/regression:unittest/.</code>".
- </p>
-
- <p>Note that directory labels are only valid for data dependencies. If you try to use
- a directory as a label in an argument other than <code>data</code>, it
- will fail and you will get a (probably cryptic) error message.
- </p>
-
- <p>
- Any external rule, such as a test, that needs to use multiple files must explicitly
- declare its dependence on all of them. You can use <code>filegroup()</code> to group files
- together in the BUILD file:
- </p>
-
- <pre>
- filegroup(
- name = 'my_data',
- srcs = glob(['my_unittest_data/*'])
- )
- </pre>
-
- <p>
- You can then reference the label <code>my_data</code> as the data dependency in your test.
- </p>
-
diff --git a/site/docs/configurable-attributes.md b/site/docs/configurable-attributes.md
deleted file mode 100644
index 442b179..0000000
--- a/site/docs/configurable-attributes.md
+++ /dev/null
@@ -1,1007 +0,0 @@
----
-layout: documentation
-title: Configurable build attributes
-category: getting-started
----
-
-<div style="background-color: #EFCBCB; color: #AE2B2B; border: 1px solid #AE2B2B; border-radius: 5px; border-left: 10px solid #AE2B2B; padding: 0.5em;">
-<b>IMPORTANT:</b> The Bazel docs have moved! Please update your bookmark to <a href="https://bazel.build/docs/configurable-attributes" style="color: #0000EE;">https://bazel.build/docs/configurable-attributes</a>
-<p/>
-You can <a href="https://blog.bazel.build/2022/02/17/Launching-new-Bazel-site.html" style="color: #0000EE;">read about</a> the migration, and let us <a href="https://forms.gle/onkAkr2ZwBmcbWXj7" style="color: #0000EE;">know what you think</a>.
-</div>
-
-
-# Configurable Build Attributes
-
-**_Configurable attributes_**, commonly known as [`select()`](
-be/functions.html#select), is a Bazel feature that lets users toggle the values
-of build rule attributes at the command line.
-
-This can be used, for example, for a multiplatform library that automatically
-chooses the appropriate implementation for the architecture, or for a
-feature-configurable binary that can be customized at build time.
-
-## Example
-
-```python
-# myapp/BUILD
-
-cc_binary(
- name = "mybinary",
- srcs = ["main.cc"],
- deps = select({
- ":arm_build": [":arm_lib"],
- ":x86_debug_build": [":x86_dev_lib"],
- "//conditions:default": [":generic_lib"],
- }),
-)
-
-config_setting(
- name = "arm_build",
- values = {"cpu": "arm"},
-)
-
-config_setting(
- name = "x86_debug_build",
- values = {
- "cpu": "x86",
- "compilation_mode": "dbg",
- },
-)
-```
-
-This declares a `cc_binary` that "chooses" its deps based on the flags at the
-command line. Specficially, `deps` becomes:
-
-<table>
- <tr style="background: #E9E9E9; font-weight: bold">
- <td>Command</td>
- <td>deps =</td>
- </tr>
- <tr>
- <td><code>bazel build //myapp:mybinary --cpu=arm</code></td>
- <td><code>[":arm_lib"]</code></td>
- </tr>
- <tr>
- <td><code>bazel build //myapp:mybinary -c dbg --cpu=x86</code></td>
- <td><code>[":x86_dev_lib"]</code></td>
- </tr>
- <tr>
- <td><code>bazel build //myapp:mybinary --cpu=ppc</code></td>
- <td><code>[":generic_lib"]</code></td>
- </tr>
- <tr>
- <td><code>bazel build //myapp:mybinary -c dbg --cpu=ppc</code></td>
- <td><code>[":generic_lib"]</code></td>
- </tr>
-</table>
-
-`select()` serves as a placeholder for a value that will be chosen based on
-*configuration conditions*, which are labels referencing [`config_setting`](be/general.html#config_setting)
-targets. By using `select()` in a configurable attribute, the attribute
-effectively adopts different values when different conditions hold.
-
-Matches must be unambiguous: either exactly one condition must match or, if
-multiple conditions match, one's `values` must be a strict superset of all
-others'. For example, `values = {"cpu": "x86", "compilation_mode": "dbg"}` is an
-unambiguous specialization of `values = {"cpu": "x86"}`. The built-in condition
-[`//conditions:default`](#the-default-condition) automatically matches when
-nothing else does.
-
-While this example uses `deps`, `select()` works just as well on `srcs`,
-`resources`, `cmd`, and most other attributes. Only a small number of attributes
-are *non-configurable*, and these are clearly annotated. For example,
-`config_setting`'s own
-[`values`](be/general.html#config_setting.values) attribute is non-configurable.
-
-## `select()` and dependencies
-
-Certain attributes change the build parameters for all transitive dependencies
-under a target. For example, `genrule`'s `tools` changes `--cpu` to the CPU of
-the machine running Bazel (which, thanks to cross-compilation, may be different
-than the CPU the target is built for). This is known as a
-[configuration transition](https://docs.bazel.build/versions/main/glossary.html#transition).
-
-Given
-
-```python
-#myapp/BUILD
-
-config_setting(
- name = "arm_cpu",
- values = {"cpu": "arm"},
-)
-
-config_setting(
- name = "x86_cpu",
- values = {"cpu": "x86"},
-)
-
-genrule(
- name = "my_genrule",
- srcs = select({
- ":arm_cpu": ["g_arm.src"],
- ":x86_cpu": ["g_x86.src"],
- }),
- tools = select({
- ":arm_cpu": [":tool1"],
- ":x86_cpu": [":tool2"],
- }),
-)
-
-cc_binary(
- name = "tool1",
- srcs = select({
- ":arm_cpu": ["armtool.cc"],
- ":x86_cpu": ["x86tool.cc"],
- }),
-)
-```
-
-running
-
-```sh
-$ bazel build //myapp:my_genrule --cpu=arm
-```
-
-on an `x86` developer machine binds the build to `g_arm.src`, `tool1`, and
-`x86tool.cc`. Both of the `select`s attached to `my_genrule` use `my_genrule`'s
-build parameters, which include `--cpu=arm`. The `tools` attribute changes
-`--cpu` to `x86` for `tool1` and its transitive dependencies. The `select` on
-`tool1` uses `tool1`'s build parameters, which include `--cpu=x86`.
-
-## Configuration conditions
-
-Each key in a configurable attribute is a label reference to a
-[`config_setting`](be/general.html#config_setting) or
-[`constraint_value`](be/platform.html#constraint_value).
-
-`config_setting` is just a collection of
-expected command line flag settings. By encapsulating these in a target, it's
-easy to maintain "standard" conditions users can reference from multiple places.
-
-`constraint_value` provides support for [multi-platform behavior](#platforms).
-
-
-### Built-in flags
-
-Flags like `--cpu` are built into Bazel: the build tool natively understands
-them for all builds in all projects. These are specified with
-[`config_setting`](be/general.html#config_setting)'s
-[`values`](be/general.html#config_setting.values) attribute:
-
-```python
-config_setting(
- name = "meaningful_condition_name",
- values = {
- "flag1": "value1",
- "flag2": "value2",
- ...
- },
-)
-```
-
-`flagN` is a flag name (without `--`, so `"cpu"` instead of `"--cpu"`). `valueN`
-is the expected value for that flag. `:meaningful_condition_name` matches if
-*every* entry in `values` matches. Order is irrelevant.
-
-`valueN` is parsed as if it was set on the command line. This means:
-
-* `values = { "compilation_mode": "opt" }` matches `bazel build -c opt`
-* `values = { "force_pic": "true" }` matches `bazel build --force_pic=1`
-* `values = { "force_pic": "0" }` matches `bazel build --noforce_pic`
-
-`config_setting` only supports flags that affect target behavior. For example,
-[`--show_progress`](user-manual.html#flag--show_progress) isn't allowed because
-it only affects how Bazel reports progress to the user. Targets can't use that
-flag to construct their results. The exact set of supported flags isn't
-documented. In practice, most flags that "make sense" work.
-
-### Custom flags
-
-You can model your own project-specific flags with
-[Starlark build
-settings][BuildSettings]. Unlike built-in flags, these are defined as build
-targets, so Bazel references them with target labels.
-
-These are triggered with [`config_setting`](be/general.html#config_setting)'s
-[`flag_values`](be/general.html#config_setting.flag_values)
-attribute:
-
-```python
-config_setting(
- name = "meaningful_condition_name",
- flag_values = {
- "//myflags:flag1": "value1",
- "//myflags:flag2": "value2",
- ...
- },
-)
-```
-
-Behavior is the same as for [built-in flags](#built-in-flags). See [here](https://github.com/bazelbuild/examples/tree/HEAD/rules/starlark_configurations/select_on_build_setting)
-for a working example.
-
-[`--define`](command-line-reference.html#flag--define)
-is an alternative legacy syntax for custom flags (for example
-`--define foo=bar`). This can be expressed either in the
-[values](be/general.html#config_setting.values) attribute
-(`values = {"define": "foo=bar"}`) or the
-[define_values](be/general.html#config_setting.define_values) attribute
-(`define_values = {"foo": "bar"}`). `--define` is only supported for backwards
-compatibility. Prefer Starlark build settings whenever possible.
-
-`values`, `flag_values`, and `define_values` evaluate independently. The
-`config_setting` matches if all values across all of them match.
-
-## The default condition
-
-The built-in condition `//conditions:default` matches when no other condition
-matches.
-
-Because of the "exactly one match" rule, a configurable attribute with no match
-and no default condition emits a `"no matching conditions"` error. This can
-protect against silent failures from unexpected settings:
-
-```python
-# myapp/BUILD
-
-config_setting(
- name = "x86_cpu",
- values = {"cpu": "x86"},
-)
-
-cc_library(
- name = "x86_only_lib",
- srcs = select({
- ":x86_cpu": ["lib.cc"],
- }),
-)
-```
-
-```sh
-$ bazel build //myapp:x86_only_lib --cpu=arm
-ERROR: Configurable attribute "srcs" doesn't match this configuration (would
-a default condition help?).
-Conditions checked:
- //myapp:x86_cpu
-```
-
-For even clearer errors, you can set custom messages with `select()`'s
-[`no_match_error`](#custom-error-messages) attribute.
-
-## Platforms
-
-While the ability to specify multiple flags on the command line provides
-flexibility, it can also be burdensome to individually set each one every time
-you want to build a target.
- [Platforms](platforms.html)
-let you consolidate these into simple bundles.
-
-```python
-# myapp/BUILD
-
-sh_binary(
- name = "my_rocks",
- srcs = select({
- ":basalt": ["pyroxene.sh"],
- ":marble": ["calcite.sh"],
- "//conditions:default": ["feldspar.sh"],
- }),
-)
-
-config_setting(
- name = "basalt",
- constraint_values = [
- ":black",
- ":igneous",
- ],
-)
-
-config_setting(
- name = "marble",
- constraint_values = [
- ":white",
- ":metamorphic",
- ],
-)
-
-# constraint_setting acts as an enum type, and constraint_value as an enum value.
-constraint_setting(name = "color")
-constraint_value(name = "black", constraint_setting = "color")
-constraint_value(name = "white", constraint_setting = "color")
-constraint_setting(name = "texture")
-constraint_value(name = "smooth", constraint_setting = "texture")
-constraint_setting(name = "type")
-constraint_value(name = "igneous", constraint_setting = "type")
-constraint_value(name = "metamorphic", constraint_setting = "type")
-
-platform(
- name = "basalt_platform",
- constraint_values = [
- ":black",
- ":igneous",
- ],
-)
-
-platform(
- name = "marble_platform",
- constraint_values = [
- ":white",
- ":smooth",
- ":metamorphic",
- ],
-)
-```
-
-The platform can be specified on the command line. It activates the
-`config_setting`s that contain a subset of the platform's `constraint_values`,
-allowing those `config_setting`s to match in `select()` expressions.
-
-For example, in order to set the `srcs` attribute of `my_rocks` to `calcite.sh`,
-you can simply run
-
-```sh
-bazel build //my_app:my_rocks --platforms=//myapp:marble_platform
-```
-
-Without platforms, this might look something like
-
-```sh
-bazel build //my_app:my_rocks --define color=white --define texture=smooth --define type=metamorphic
-```
-
-`select()` can also directly read `constraint_value`s:
-
-```python
-constraint_setting(name = "type")
-constraint_value(name = "igneous", constraint_setting = "type")
-constraint_value(name = "metamorphic", constraint_setting = "type")
-sh_binary(
- name = "my_rocks",
- srcs = select({
- ":igneous": ["igneous.sh"],
- ":metamorphic" ["metamorphic.sh"],
- }),
-)
-```
-
-This saves the need for boilerplate `config_setting`s when you only need to
-check against single values.
-
-Platforms are still under development. See the
-[documentation](platforms-intro.html) for details.
-
-## Combining `select()`s
-
-`select` can appear multiple times in the same attribute:
-
-```python
-sh_binary(
- name = "my_target",
- srcs = ["always_include.sh"] +
- select({
- ":armeabi_mode": ["armeabi_src.sh"],
- ":x86_mode": ["x86_src.sh"],
- }) +
- select({
- ":opt_mode": ["opt_extras.sh"],
- ":dbg_mode": ["dbg_extras.sh"],
- }),
-)
-```
-
-`select` cannot appear inside another `select`. If you need to nest `selects`
-and your attribute takes other targets as values, use an intermediate target:
-
-```python
-sh_binary(
- name = "my_target",
- srcs = ["always_include.sh"],
- deps = select({
- ":armeabi_mode": [":armeabi_lib"],
- ...
- }),
-)
-
-sh_library(
- name = "armeabi_lib",
- srcs = select({
- ":opt_mode": ["armeabi_with_opt.sh"],
- ...
- }),
-)
-```
-
-If you need a `select` to match when multiple conditions match, consider [AND
-chaining](#and-chaining).
-
-## OR chaining
-
-Consider the following:
-
-```python
-sh_binary(
- name = "my_target",
- srcs = ["always_include.sh"],
- deps = select({
- ":config1": [":standard_lib"],
- ":config2": [":standard_lib"],
- ":config3": [":standard_lib"],
- ":config4": [":special_lib"],
- }),
-)
-```
-
-Most conditions evaluate to the same dep. But this syntax is hard to read and
-maintain. It would be nice to not have to repeat `[":standard_lib"]` multiple
-times.
-
-One option is to predefine the value as a BUILD variable:
-
-```python
-STANDARD_DEP = [":standard_lib"]
-
-sh_binary(
- name = "my_target",
- srcs = ["always_include.sh"],
- deps = select({
- ":config1": STANDARD_DEP,
- ":config2": STANDARD_DEP,
- ":config3": STANDARD_DEP,
- ":config4": [":special_lib"],
- }),
-)
-```
-
-This makes it easier to manage the dependency. But it still causes unnecessary
-duplication.
-
-For more direct support, use one of the following:
-
-### <a name="selects-with-or"></a>`selects.with_or`
-
-The
-[with_or](https://github.com/bazelbuild/bazel-skylib/blob/main/docs/selects_doc.md#selectswith_or)
-macro in [Skylib](https://github.com/bazelbuild/bazel-skylib)'s
-[`selects`](https://github.com/bazelbuild/bazel-skylib/blob/main/docs/selects_doc.md)
-module supports `OR`ing conditions directly inside a `select`:
-
-```python
-load("@bazel_skylib//lib:selects.bzl", "selects")
-```
-
-```python
-sh_binary(
- name = "my_target",
- srcs = ["always_include.sh"],
- deps = selects.with_or({
- (":config1", ":config2", ":config3"): [":standard_lib"],
- ":config4": [":special_lib"],
- }),
-)
-```
-
-### <a name="selects-config-setting-or-group"></a>`selects.config_setting_group`
-
-
-The
-[config_setting_group](https://github.com/bazelbuild/bazel-skylib/blob/main/docs/selects_doc.md#selectsconfig_setting_group)
-macro in [Skylib](https://github.com/bazelbuild/bazel-skylib)'s
-[`selects`](https://github.com/bazelbuild/bazel-skylib/blob/main/docs/selects_doc.md)
-module supports `OR`ing multiple `config_setting`s:
-
-```python
-load("@bazel_skylib//lib:selects.bzl", "selects")
-```
-
-
-```python
-config_setting(
- name = "config1",
- values = {"cpu": "arm"},
-)
-config_setting(
- name = "config2",
- values = {"compilation_mode": "dbg"},
-)
-selects.config_setting_group(
- name = "config1_or_2",
- match_any = [":config1", ":config2"],
-)
-sh_binary(
- name = "my_target",
- srcs = ["always_include.sh"],
- deps = select({
- ":config1_or_2": [":standard_lib"],
- "//conditions:default": [":other_lib"],
- }),
-)
-```
-
-Unlike `selects.with_or`, different targets can share `:config1_or_2` across
-different attributes.
-
-It's an error for multiple conditions to match unless one is an unambiguous
-"specialization" of the others. See [here](#example) for details.
-
-## AND chaining
-
-If you need a `select` branch to match when multiple conditions match, use the
-[Skylib](https://github.com/bazelbuild/bazel-skylib) macro
-[config_setting_group](https://github.com/bazelbuild/bazel-skylib/blob/main/docs/selects_doc.md#selectsconfig_setting_group):
-
-```python
-config_setting(
- name = "config1",
- values = {"cpu": "arm"},
-)
-config_setting(
- name = "config2",
- values = {"compilation_mode": "dbg"},
-)
-selects.config_setting_group(
- name = "config1_and_2",
- match_all = [":config1", ":config2"],
-)
-sh_binary(
- name = "my_target",
- srcs = ["always_include.sh"],
- deps = select({
- ":config1_and_2": [":standard_lib"],
- "//conditions:default": [":other_lib"],
- }),
-)
-```
-
-Unlike OR chaining, existing `config_setting`s can't be directly `AND`ed
-inside a `select`. You have to explicitly wrap them in a `config_setting_group`.
-
-## Custom error messages
-
-By default, when no condition matches, the target the `select()` is attached to
-fails with the error:
-
-```sh
-ERROR: Configurable attribute "deps" doesn't match this configuration (would
-a default condition help?).
-Conditions checked:
- //tools/cc_target_os:darwin
- //tools/cc_target_os:android
-```
-
-This can be customized with the [`no_match_error`](be/functions.html#select)
-attribute:
-
-```python
-cc_library(
- name = "my_lib",
- deps = select(
- {
- "//tools/cc_target_os:android": [":android_deps"],
- "//tools/cc_target_os:windows": [":windows_deps"],
- },
- no_match_error = "Please build with an Android or Windows toolchain",
- ),
-)
-```
-
-```sh
-$ bazel build //myapp:my_lib
-ERROR: Configurable attribute "deps" doesn't match this configuration: Please
-build with an Android or Windows toolchain
-```
-
-## <a name="rules"></a>Rules compatibility
-Rule implementations receive the *resolved values* of configurable
-attributes. For example, given:
-
-```python
-# myapp/BUILD
-
-some_rule(
- name = "my_target",
- some_attr = select({
- ":foo_mode": [":foo"],
- ":bar_mode": [":bar"],
- }),
-)
-```
-
-```sh
-$ bazel build //myapp/my_target --define mode=foo
-```
-
-Rule implementation code sees `ctx.attr.some_attr` as `[":foo"]`.
-
-Macros can accept `select()` clauses and pass them through to native
-rules. But *they cannot directly manipulate them*. For example, there's no way
-for a macro to convert
-
-```python
-select({"foo": "val"}, ...)
-```
-
-to
-
-```python
-select({"foo": "val_with_suffix"}, ...)
-```
-
-This is for two reasons.
-
-First, macros that need to know which path a `select` will choose *cannot work*
-because macros are evaluated in Bazel's [loading phase](guide.html#loading-phase),
-which occurs before flag values are known.
-This is a core Bazel design restriction that's unlikely to change any time soon.
-
-Second, macros that just need to iterate over *all* `select` paths, while
-technically feasible, lack a coherent UI. Further design is necessary to change
-this.
-
-## <a name="query"></a>Bazel query and cquery
-Bazel [`query`](query-how-to.html) operates over Bazel's
-[loading phase](https://docs.bazel.build/versions/main/glossary.html#loading-phase).
-This means it doesn't know what command line flags a target uses since those
-flags aren't evaluated until later in the build (in the
-[analysis phase](https://docs.bazel.build/versions/main/glossary.html#analysis-phase)).
-So it can't determine which `select()` branches are chosen.
-
-Bazel [`cquery`](cquery.html) operates after Bazel's analysis phase, so it has
-all this information and can accurately resolve `select()`s.
-
-Consider:
-
-```python
-load("@bazel_skylib//rules:common_settings.bzl", "string_flag")
-```
-```python
-# myapp/BUILD
-
-string_flag(
- name = "dog_type",
- build_setting_default = "cat"
-)
-
-cc_library(
- name = "my_lib",
- deps = select({
- ":long": [":foo_dep"],
- ":short": [":bar_dep"],
- }),
-)
-
-config_setting(
- name = "long",
- flag_values = {":dog_type": "dachshund"},
-)
-
-config_setting(
- name = "short",
- flag_values = {":dog_type": "pug"},
-)
-```
-
-`query` overapproximates `:my_lib`'s dependencies:
-
-```sh
-$ bazel query 'deps(//myapp:my_lib)'
-//myapp:my_lib
-//myapp:foo_dep
-//myapp:bar_dep
-```
-
-while `cquery` shows its exact dependencies:
-
-```sh
-$ bazel cquery 'deps(//myapp:my_lib)' --//myapp:dog_type=pug
-//myapp:my_lib
-//myapp:bar_dep
-```
-
-## FAQ
-
-### <a name="macros-select"></a>Why doesn't select() work in macros?
-select() *does* work in rules! See [Rules compatibility](#rules) for
-details.
-
-The key issue this question usually means is that select() doesn't work in
-*macros*. These are different than *rules*. See the
-documentation on [rules](skylark/rules.html) and [macros](skylark/macros.html)
-to understand the difference.
-Here's an end-to-end example:
-
-Define a rule and macro:
-
-```python
-# myapp/defs.bzl
-
-# Rule implementation: when an attribute is read, all select()s have already
-# been resolved. So it looks like a plain old attribute just like any other.
-def _impl(ctx):
- name = ctx.attr.name
- allcaps = ctx.attr.my_config_string.upper() # This works fine on all values.
- print("My name is " + name + " with custom message: " + allcaps)
-
-# Rule declaration:
-my_custom_bazel_rule = rule(
- implementation = _impl,
- attrs = {"my_config_string": attr.string()},
-)
-
-# Macro declaration:
-def my_custom_bazel_macro(name, my_config_string):
- allcaps = my_config_string.upper() # This line won't work with select(s).
- print("My name is " + name + " with custom message: " + allcaps)
-```
-
-Instantiate the rule and macro:
-
-```python
-# myapp/BUILD
-
-load("//myapp:defs.bzl", "my_custom_bazel_rule")
-load("//myapp:defs.bzl", "my_custom_bazel_macro")
-
-my_custom_bazel_rule(
- name = "happy_rule",
- my_config_string = select({
- "//tools/target_cpu:x86": "first string",
- "//tools/target_cpu:ppc": "second string",
- }),
-)
-
-my_custom_bazel_macro(
- name = "happy_macro",
- my_config_string = "fixed string",
-)
-
-my_custom_bazel_macro(
- name = "sad_macro",
- my_config_string = select({
- "//tools/target_cpu:x86": "first string",
- "//tools/target_cpu:ppc": "other string",
- }),
-)
-```
-
-Building fails because `sad_macro` can't process the `select()`:
-
-```sh
-$ bazel build //myapp:all
-ERROR: /myworkspace/myapp/BUILD:17:1: Traceback
- (most recent call last):
-File "/myworkspace/myapp/BUILD", line 17
-my_custom_bazel_macro(name = "sad_macro", my_config_stri..."}))
-File "/myworkspace/myapp/defs.bzl", line 4, in
- my_custom_bazel_macro
-my_config_string.upper()
-type 'select' has no method upper().
-ERROR: error loading package 'myapp': Package 'myapp' contains errors.
-```
-
-Building succeeds when you comment out `sad_macro`:
-
-```sh
-# Comment out sad_macro so it doesn't mess up the build.
-$ bazel build //myapp:all
-DEBUG: /myworkspace/myapp/defs.bzl:5:3: My name is happy_macro with custom message: FIXED STRING.
-DEBUG: /myworkspace/myapp/hi.bzl:15:3: My name is happy_rule with custom message: FIRST STRING.
-```
-
-This is impossible to change because *by definition* macros are evaluated before
-Bazel reads the build's command line flags. That means there isn't enough
-information to evaluate select()s.
-
-Macros can, however, pass `select()`s as opaque blobs to rules:
-
-```python
-# myapp/defs.bzl
-
-def my_custom_bazel_macro(name, my_config_string):
- print("Invoking macro " + name)
- my_custom_bazel_rule(
- name = name + "_as_target",
- my_config_string = my_config_string,
- )
-```
-
-```sh
-$ bazel build //myapp:sad_macro_less_sad
-DEBUG: /myworkspace/myapp/defs.bzl:23:3: Invoking macro sad_macro_less_sad.
-DEBUG: /myworkspace/myapp/defs.bzl:15:3: My name is sad_macro_less_sad with custom message: FIRST STRING.
-```
-
-### <a name="boolean-select"></a>Why does select() always return true?
-Because *macros* (but not rules) by definition
-[can't evaluate `select()`s](#macros-select), any attempt to do so
-usually produces an error:
-
-```sh
-ERROR: /myworkspace/myapp/BUILD:17:1: Traceback
- (most recent call last):
-File "/myworkspace/myapp/BUILD", line 17
-my_custom_bazel_macro(name = "sad_macro", my_config_stri..."}))
-File "/myworkspace/myapp/defs.bzl", line 4, in
- my_custom_bazel_macro
-my_config_string.upper()
-type 'select' has no method upper().
-```
-
-Booleans are a special case that fail silently, so you should be particularly
-vigilant with them:
-
-```sh
-$ cat myapp/defs.bzl
-def my_boolean_macro(boolval):
- print("TRUE" if boolval else "FALSE")
-
-$ cat myapp/BUILD
-load("//myapp:defs.bzl", "my_boolean_macro")
-my_boolean_macro(
- boolval = select({
- "//tools/target_cpu:x86": True,
- "//tools/target_cpu:ppc": False,
- }),
-)
-
-$ bazel build //myapp:all --cpu=x86
-DEBUG: /myworkspace/myapp/defs.bzl:4:3: TRUE.
-$ bazel build //mypro:all --cpu=ppc
-DEBUG: /myworkspace/myapp/defs.bzl:4:3: TRUE.
-```
-
-This happens because macros don't understand the contents of `select()`.
-So what they're really evaluting is the `select()` object itself. According to
-[Pythonic](https://docs.python.org/release/2.5.2/lib/truth.html) design
-standards, all objects aside from a very small number of exceptions
-automatically return true.
-### <a name="inspectable-select"></a>Can I read select() like a dict?
-Macros [can't](#macros-select) evaluate select(s) because macros evaluate before
-Bazel knows what the build's command line parameters are. Can they at least read
-the `select()`'s dictionary to, for example, add a suffix to each value?
-
-Conceptually this is possible, but it isn't yet a Bazel feature.
-What you *can* do today is prepare a straight dictionary, then feed it into a
-`select()`:
-
-```sh
-$ cat myapp/defs.bzl
-def selecty_genrule(name, select_cmd):
- for key in select_cmd.keys():
- select_cmd[key] += " WITH SUFFIX"
- native.genrule(
- name = name,
- outs = [name + ".out"],
- srcs = [],
- cmd = "echo " + select(select_cmd + {"//conditions:default": "default"})
- + " > $@"
- )
-
-$ cat myapp/BUILD
-selecty_genrule(
- name = "selecty",
- select_cmd = {
- "//tools/target_cpu:x86": "x86 mode",
- },
-)
-
-$ bazel build //testapp:selecty --cpu=x86 && cat bazel-genfiles/testapp/selecty.out
-x86 mode WITH SUFFIX
-```
-
-If you'd like to support both `select()` and native types, you can do this:
-
-```sh
-$ cat myapp/defs.bzl
-def selecty_genrule(name, select_cmd):
- cmd_suffix = ""
- if type(select_cmd) == "string":
- cmd_suffix = select_cmd + " WITH SUFFIX"
- elif type(select_cmd) == "dict":
- for key in select_cmd.keys():
- select_cmd[key] += " WITH SUFFIX"
- cmd_suffix = select(select_cmd + {"//conditions:default": "default"})
-
- native.genrule(
- name = name,
- outs = [name + ".out"],
- srcs = [],
- cmd = "echo " + cmd_suffix + "> $@",
- )
-```
-
-### <a name="bind-select"></a>Why doesn't select() work with bind()?
-
-Because [`bind()`](be/workspace.html#bind) is a WORKSPACE rule, not a BUILD rule.
-
-Workspace rules do not have a specific configuration, and aren't evaluated in
-the same way as BUILD rules. Therefore, a `select()` in a `bind()` can't
-actually evaluate to any specific branch.
-
-Instead, you should use [`alias()`](be/general.html#alias), with a `select()` in
-the `actual` attribute, to perform this type of run-time determination. This
-works correctly, since `alias()` is a BUILD rule, and is evaluated with a
-specific configuration.
-
-You can even have a `bind()` target point to an `alias()`, if needed.
-
-```sh
-$ cat WORKSPACE
-workspace(name = "myapp")
-bind(name = "openssl", actual = "//:ssl")
-http_archive(name = "alternative", ...)
-http_archive(name = "boringssl", ...)
-
-$ cat BUILD
-config_setting(
- name = "alt_ssl",
- define_values = {
- "ssl_library": "alternative",
- },
-)
-
-alias(
- name = "ssl",
- actual = select({
- "//:alt_ssl": "@alternative//:ssl",
- "//conditions:default": "@boringssl//:ssl",
- }),
-)
-```
-
-With this setup, you can pass `--define ssl_library=alternative`, and any target
-that depends on either `//:ssl` or `//external:ssl` will see the alternative
-located at `@alternative//:ssl`.
-
-### Why doesn't my select() choose what I expect?
-If `//myapp:foo` has a `select()` that doesn't choose the condition you expect,
-use [cquery](cquery.html) and `bazel config` to debug:
-
-If `//myapp:foo` is the top-level target you're building, run:
-
-```sh
-$ bazel cquery //myapp:foo <desired build flags>
-//myapp:foo (12e23b9a2b534a)
-```
-
-If you're building some other target `//bar` that depends on
-//myapp:foo somewhere in its subgraph, run:
-
-```sh
-$ bazel cquery 'somepath(//bar, //myapp:foo)' <desired build flags>
-//bar:bar (3ag3193fee94a2)
-//bar:intermediate_dep (12e23b9a2b534a)
-//myapp:foo (12e23b9a2b534a)
-```
-
-The `(12e23b9a2b534a)` next to `//myapp:foo` is a *hash* of the
-configuration that resolves `//myapp:foo`'s `select()`. You can inspect its
-values with `bazel config`:
-
-```sh
-$ bazel config 12e23b9a2b534a
-BuildConfigurationValue 12e23b9a2b534a
-Fragment com.google.devtools.build.lib.analysis.config.CoreOptions {
- cpu: darwin
- compilation_mode: fastbuild
- ...
-}
-Fragment com.google.devtools.build.lib.rules.cpp.CppOptions {
- linkopt: [-Dfoo=bar]
- ...
-}
-...
-```
-
-Then compare this output against the settings expected by each `config_setting`.
-
-`//myapp:foo` may exist in different configurations in the same build. See the
-[cquery docs](cquery.html) for guidance on using `somepath` to get the right
-one.
-
-Caution: To prevent restarting the Bazel server, invoke `bazel config` with the
-same command line flags as the `bazel cquery`. The `config` command relies on
-the configuration nodes from the still-running server of the previous command.
-
-[BuildSettings]: skylark/config.html#user-defined-build-settings
diff --git a/site/docs/cquery.html b/site/docs/cquery.html
deleted file mode 100644
index bad6cac..0000000
--- a/site/docs/cquery.html
+++ /dev/null
@@ -1,789 +0,0 @@
----
-layout: documentation
-title: Cquery (configurable query)
----
-
-<div style="background-color: #EFCBCB; color: #AE2B2B; border: 1px solid #AE2B2B; border-radius: 5px; border-left: 10px solid #AE2B2B; padding: 0.5em;">
-<b>IMPORTANT:</b> The Bazel docs have moved! Please update your bookmark to <a href="https://bazel.build/docs/cquery" style="color: #0000EE;">https://bazel.build/docs/cquery</a>
-<p/>
-You can <a href="https://blog.bazel.build/2022/02/17/Launching-new-Bazel-site.html" style="color: #0000EE;">read about</a> the migration, and let us <a href="https://forms.gle/onkAkr2ZwBmcbWXj7" style="color: #0000EE;">know what you think</a>.
-</div>
-
-<h1> Configurable Query (cquery)</h1>
-
-
-<p>
- <code>cquery</code> is a variant
- of <a href="query.html"><code>query</code></a> that correctly handles
- <a href="configurable-attributes.md"><code>select()</code></a> and build
- options' effects on the build graph.
-</p>
-
-<p>
- It achieves this by running over the results of Bazel's
- <a href="https://docs.bazel.build/versions/main/skylark/concepts.html#evaluation-model">analysis
- phase</a>, which integrates these effects. <code>query</code>, by constrast,
- runs over the results of Bazel's loading phase, before options are evaluated.
-</p>
-
-<p>
- For example:
-</p>
-
-<pre>
-$ cat > tree/BUILD <<EOF
-sh_library(
- name = "ash",
- deps = select({
- ":excelsior": [":manna-ash"],
- ":americana": [":white-ash"],
- "//conditions:default": [":common-ash"],
- }),
-)
-sh_library(name = "manna-ash")
-sh_library(name = "white-ash")
-sh_library(name = "common-ash")
-config_setting(
- name = "excelsior",
- values = {"define": "species=excelsior"},
-)
-config_setting(
- name = "americana",
- values = {"define": "species=americana"},
-)
-EOF
-</pre>
-
-<pre>
-# Traditional query: query doesn't know which select() branch you will choose,
-# so it conservatively lists all possible choices, including all used config_settings.
-$ bazel query "deps(//tree:ash)" --noimplicit_deps
-//tree:americana
-//tree:ash
-//tree:common-ash
-//tree:excelsior
-//tree:manna-ash
-//tree:white-ash
-
-# cquery: cquery lets you set build options at the command line and chooses
-# the exact dependencies that implies (and also the config_setting targets).
-$ bazel cquery "deps(//tree:ash)" --define species=excelsior --noimplicit_deps
-//tree:ash (9f87702)
-//tree:manna-ash (9f87702)
-//tree:americana (9f87702)
-//tree:excelsior (9f87702)
-</pre>
-
-<p>
- Each result includes a <a href="#configurations">unique identifier</a> <code>(9f87702)</code> of
- the <a href="https://docs.bazel.build/glossary.html#configuration">configuration</a> the target is
- built with.
-</p>
-
-<p>
- Since <code>cquery</code> runs over the configured target graph. it doesn't
- have insight into artifacts like build actions nor access to
- <code><a href="be/general.html#test_suite">test_suite</a></code>
- rules as they are not configured targets. For the former,
- see <code><a href="aquery.html">aquery</a></code>.
-</p>
-
-<h2 id='basic-syntax'>Basic syntax</h2>
-
-<p>A simple <code>cquery</code> call looks like:</p>
-
-<p><code>bazel cquery "function(//target)"</code></p>
-
-<p>The query expression <code>"function(//target)"</code> consists of the following:
-
-<ul>
- <li>
- <b><code>function(...)</code></b> is the function to run on the target. <code>cquery</code>
- supports most
- of <code>query</code>'s <a href="query.html#functions">functions</a>, plus a
- few new ones.
- </li>
- <li><b><code>//target</code></b> is the expression fed to the function. In this example, the
- expression is a simple target. But the query language also allows nesting of functions.
- See the <a href="query-how-to.html">Query How-To</a> for examples.
- </li>
-</ul>
-
-<p>
- <code>cquery</code> requires a target to run through the
- <a href="https://docs.bazel.build/versions/main/skylark/concepts.html#evaluation-model">loading
- and analysis</a>
- phases. Unless otherwise specified, <code>cquery</code> parses the target(s)
- listed in the query
- expression. See <a href="#universe_scope-comma-separated-list"><code>--universe_scope</code></a>
- for querying dependencies of top-level build targets.
-</p>
-
-<h2 id='configurations'>Configurations</h2>
-
-<p>
- The line:
-</p>
-
-<pre>
-//tree:ash (9f87702)
-</pre>
-
-<p>
- means <code>//tree:ash</code> was built in a configuration with ID <code>9f87702</code>. For most
- targets, this is an opaque hash of the build option values defining the configuration.
-</p>
-
-<p>
- To see the configuration's complete contents, run:
-</p>
-
-<pre>
-$ bazel config 9f87702
-</pre>
-
-<p>
- The host configuration uses the special ID <code>(HOST)</code>. Non-generated source files, like
- those commonly found in <code>srcs</code>, use the special ID <code>(null)</code> (because they
- don't need to be configured).
-</p>
-
-<p>
- <code>9f87702</code> is a prefix of the complete ID. This is because complete IDs are
- SHA-256 hashes, which are long and hard to follow. <code>cquery</code> understands any valid
- prefix of a complete ID, similar to
- <a href="https://git-scm.com/book/en/v2/Git-Tools-Revision-Selection#_revision_selection">Git short hashes</a>.
- To see complete IDs, run <code>$ bazel config</code>.
-</p>
-
-<h2 id='target-pattern-evaluation'>Target pattern evaluation</h2>
-
-<p>
- <code>//foo</code> has a different meaning for <code>cquery</code> than
- for <code>query</code>. This is because <code>cquery</code>
- evaluates <i>configured</i> targets and the build graph may have multiple
- configured versions of <code>//foo</code>.
-</p>
-
-<p>
- For <code>cquery</code>, a target pattern in the query expression evaluates
- to every configured target with a label that matches that pattern. Output is
- deterministic, but <code>cquery</code> makes no ordering guarantee beyond the
- <a href="query.html#graph-order">core query ordering contract</a>.
-</p>
-
-<p>
- This produces subtler results for query expressions than with <code>query</code>.
- For example, the following can produce multiple results:
-
- <pre>
-# Analyzes //foo in the target configuration, but also analyzes
-# //genrule_with_foo_as_tool which depends on a host-configured
-# //foo. So there are two configured target instances of //foo in
-# the build graph.
-$ bazel cquery //foo --universe_scope=//foo,//genrule_with_foo_as_tool
-//foo (9f87702)
-//foo (HOST)
- </pre>
-
-</p>
-
-<p>
- If you want to precisely declare which instance to query over, use
- the <a href="#config"><code>config</code></a> function.
-</p>
-
-
-<p>
- See <code>query</code>'s <a href="query.html#target-patterns">target pattern
- documentation</a> for more information on target patterns.
-</p>
-
-<h2 id='functions'>Functions</h2>
-
-<p>
- Of the <a href="query.html#functions" title="list of query functions">set of functions</a>
- supported by <code>query</code>, <code>cquery</code> supports
- all
- but <a href="query.html#visible"><code>visible</code></a>,
- <a href="query.html#siblings"><code>siblings</code></a>,
- <a href="query.html#buildfiles"><code>buildfiles</code></a>,
- and <a href="query.html#tests"><code>tests</code></a>.
-</p>
-
-<p>
- <code>cquery</code> also introduces the following new functions:
-</p>
-
-<h3 id="config">config</h3>
-
-<p><code>expr ::= config(expr, word)</code></p>
-
-<p>
- The <code>config</code> operator attempts to find the configured target for
- the label denoted by the first argument and configuration specified by the
- second argument.
-</p>
-
-<p>
- Valid values for the second argument
- are <code>target</code>, <code>host</code>, <code>null</code>, or a
- <a href="#configurations">custom configuration hash</a>. Hashes can be retrieved from <code>$
- bazel config</code> or a prevous <code>cquery</code>'s output.
-</p>
-
-<p>
- Examples:
-</p>
-
-<pre>
-$ bazel cquery "config(//bar, host)" --universe_scope=//foo
-</pre>
-
-<pre>
-$ bazel cquery "deps(//foo)"
-//bar (HOST)
-//baz (3732cc8)
-
-$ bazel cquery "config(//baz, 3732cc8)"
-</pre>
-
-<p>
- If not all results of the first argument can be found in the specified
- configuration, only those that can be found are returned. If no results
- can be found in the specified configuration, the query fails.
-</p>
-
-<h2 id='options'>Options</h2>
-
-<h3>Build options</h3>
-
-<p>
- <code>cquery</code> runs over a regular Bazel build and thus inherits the
- set of
-
- <a href="command-line-reference.html#build-options">options</a>
- available during a build.
-</p>
-
-<h3> Using cquery options</h3>
-
-<h4 id="universe_scope-comma-separated-list"><code>--universe_scope</code> (comma-separated list)</h4>
-
-<p>
- Often, the dependencies of configured targets go through
- <a href="https://docs.bazel.build/versions/main/skylark/rules.html#configurations">transitions</a>,
- which causes their configuration to differ from their dependent. This flag allows you to query
- a target as if it were built as a dependency or a transitive dependency of another target. For
- example:
-</p>
-
-<pre>
-# x/BUILD
-genrule(
- name = "my_gen",
- srcs = ["x.in"],
- outs = ["x.cc"],
- cmd = "$(locations :tool) $< >$@",
- tools = [":tool"],
-)
-cc_library(
- name = "tool",
-)
-</pre>
-
-<p>
- Genrules configure their tools in the
- <a href="https://docs.bazel.build/versions/main/skylark/rules.html#configurations">host configuration</a>
- so the following queries would produce the following outputs:
-</p>
-
-<table class="table table-condensed table-bordered table-params">
- <thead>
- <tr>
- <th>Query</th>
- <th>Target Built</th>
- <th>Output</th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td>bazel cquery "//x:tool"</td>
- <td>//x:tool</td>
- <td>//x:tool(targetconfig)</td>
- </tr>
- <tr>
- <td>bazel cquery "//x:tool" --universe_scope="//x:my_gen"</td>
- <td>//x:my_gen</td>
- <td>//x:tool(hostconfig)</td>
- </tr>
- </tbody>
-</table>
-
-<p>
- If this flag is set, its contents are built. <em>If it's not set, all targets
- mentioned in the query expression are built</em> instead. The transitive closure of the
- built targets are used as the universe of the query. Either way, the targets to
- be built must be buildable at the top level (that is, compatible with top-level
- options). <code>cquery</code> returns results in the transitive closure of these
- top-level targets.
-</p>
-
-<p>
- Even if it's possible to build all targets in a query expression at the top
- level, it may be beneficial to not do so. For example, explicitly setting
- <code>--universe_scope</code> could prevent building targets multiple times in
- configurations you don't care about. It could also help specify which configuration version of a
- target you're looking for (since it's not currently possible
- to fully specify this any other way). You should set this flag
- if your query expression is more complex than <code>deps(//foo)</code>.
-</p>
-
-<h4><code>--implicit_deps</code> (boolean, default=True)</h4>
-
-<p>
- Setting this flag to false filters out all results that aren't explicitly set in
- the BUILD file and instead set elsewhere by Bazel. This includes filtering resolved
- toolchains.
-</p>
-
-<h4><code>--tool_deps</code> (boolean, default=True)</h4>
-
-<p>
- Setting this flag to false filters out all configured targets for which the
- path from the queried target to them crosses a transition between the target
- configuration and the
- <a href="https://docs.bazel.build/versions/main/skylark/rules.html#configurations">non-target configurations</a>.
- If the queried target is in the target configuration, setting <code>--notool_deps</code> will
- only return targets that also are in the target configuration. If the queried
- target is in a non-target configuration, setting <code>--notool_deps</code> will only return
- targets also in non-target configurations. This setting generally does not affect filtering
- of resolved toolchains.
-</p>
-
-<h4><code>--include_aspects</code> (boolean, default=True)</h4>
-
-<p>
- <a href="https://docs.bazel.build/versions/main/skylark/aspects.html">Aspects</a> can add
- additional dependencies to a build. By default, <code>cquery</code> doesn't follow aspects because
- they make the queryable graph bigger, which uses more memory. But following them produces more
- accurate results.
-</p>
-
-<p>
- If you're not worried about the memory impact of large queries, enable this flag by default in
- your bazelrc.
-</p>
-
-<p>
- If you query with aspects disabled, you can experience a problem where target X fails while
- building target Y but <code>cquery somepath(Y, X)</code> and <code>cquery deps(Y) | grep 'X'
- </code> return no results because the dependency occurs through an aspect.
-</p>
-
-<h2 id='output-formats'>Output formats</h2>
-
-<p> By default, cquery outputs results in a dependency-ordered list of label and configuration pairs.
-There are other options for exposing the results as well. </p>
-
-<h3> Transitions </h3>
-
-<pre>
---transitions=lite
---transitions=full
-</pre>
-
-<p>
- Configuration <a href="https://docs.bazel.build/versions/main/skylark/rules.html#configurations">transitions</a>
- are used to build targets underneath the top level targets in different configurations than the top
- level targets.
-</p>
-
-<p>
- For example, a target might impose a transition to the host configuration on all
- dependencies in its <code>tools</code> attribute. These are known as attribute
- transitions. Rules can also impose transitions on their own configurations,
- known as rule class transitions. This output format outputs information about
- these transitions such as what type they are and the effect they have on build
- options.
-</p>
-
-<p>This output format is triggered by the <code>--transitions</code> flag which by default is set to
- <code>NONE</code>. It can be set to <code>FULL</code> or <code>LITE</code> mode. <code>FULL</code>
- mode outputs information about rule class transitions and attribute transitions including a detailed
- diff of the options before and after the transition. <code>LITE</code> mode outputs the same information
- without the options diff.
-</p>
-
-<h3>Protocol message output</h3>
-
-<pre>
---output=proto
-</pre>
-
-<p>
- This option causes the resulting targets to be printed in a binary protocol
- buffer form. The definition of the protocol buffer can be found at
-
- <a href="https://github.com/bazelbuild/bazel/blob/master/src/main/protobuf/analysis.proto">src/main/protobuf/analysis.proto</a>.
-<h4>--[no]proto:include_configurations</h4>
-
-<p>
- By default, cquery results return configuration information as part of each
- configured target. If you'd like to omit this information and get proto output
- that is formatted exactly like query's proto output, set this flag to false
-
- .
-
-
-<p>
- See <a href="query.html#output-proto">query's proto output documentation</a>
- for more proto output-related options.
-</p>
-
-<p>
- <b>Note</b>: while selects are resolved both at the top level of returned
- targets and within attributes, all possible inputs for selects are still
- included as <code>rule_input</code> fields.
-</p>
-
-<h3>Graph output</h3>
-
-<pre>
---output=graph
-</pre>
-
-<p>
- This option generates output as a Graphviz-compatible .dot file. See <code>query</code>'s
- <a href="query.html#output-graph">graph output documentation</a> for details. <code>cquery</code>
- also supports
-
- <a href="query.html#graph-node_limit-n"><code>--graph:node_limit</code></a> and
- <a href="query.html#no-graph-factored"><code>--graph:factored</code></a>.
-
-</p>
-
-<h3>Defining the output format using Starlark</h3>
-
-<pre>
---output=starlark
-</pre>
-
-<p>
- This output format calls a
- <a href="https://docs.bazel.build/versions/main/skylark/language.html">Starlark</a>
- function for each configured target in the query result, and prints the value returned by the
- call. The <code>--starlark:file</code> flag specifies the location of a Starlark file that
- defines a function named <code>format</code> with a single parameter, <code>target</code>. This
- function is called for each
- <a href="https://docs.bazel.build/versions/main/skylark/lib/Target.html">Target</a> in the
- query result. Alternatively, for convenience, you may specify just the body of a function
- declared as <code>def format(target): return expr</code> by using the
- <code>--starlark:expr</code> flag.
-
-<h4>'cquery' Starlark dialect</h4>
-<p>
- The cquery Starlark environment differs from a BUILD or .bzl file. It includes all core Starlark
- <a href="https://github.com/bazelbuild/starlark/blob/master/spec.md#built-in-constants-and-functions">
- built-in constants and functions</a>, plus a few cquery-specific ones described below,
- but not (for example) <code>glob</code>, <code>native</code>, or <code>rule</code>, and it does
- not support load statements.
-</p>
-<h5 id='build_options'>build_options(target)</h5>
-<p>
- <code>build_options(target)</code> returns a map whose keys are build option identifiers (see
- <a href="https://docs.bazel.build/versions/main/skylark/config.html">Configurations</a>)
- and whose values are their Starlark values. Build options whose values are not legal Starlark
- values are omitted from this map.
-</p><p>
- If the target is an input file, <code>build_options(target)</code> returns None, as input file
- targets have a null configuration.
-</p>
-<h5 id='providers'>providers(target)</h5>
-<p>
- <code>providers(target)</code> returns a map whose keys are names of
- <a href="https://docs.bazel.build/versions/main/skylark/rules.html#providers">providers</a>
- (for example, <code>"DefaultInfo"</code>) and whose values are their Starlark values. Providers
- whose values are not legal Starlark values are omitted from this map.
-</p>
-
-<h4>Examples</h4>
-
-<p>
-Print a space-separated list of the base names of all files produced by <code>//foo</code>:
-</p>
-<pre>
- bazel cquery //foo --output=starlark \
- --starlark:expr="' '.join([f.basename for f in target.files.to_list()])"
-</pre>
-<p>
-Print a space-separated list of the paths of all files produced by <b>rule</b> targets in
-<code>//bar</code> and its subpackages:
-</p>
-<pre>
- bazel cquery 'kind(rule, //bar/...)' --output=starlark \
- --starlark:expr="' '.join([f.path for f in target.files.to_list()])"
-</pre>
-<p>
-Print a list of the mnemonics of all actions registered by <code>//foo</code>.
-</p>
-<pre>
- bazel cquery //foo --output=starlark \
- --starlark:expr="[a.mnemonic for a in target.actions]"
-</pre>
-<p>
-Print a list of compilation outputs registered by a <code>cc_library</code> <code>//baz</code>.
-</p>
-<pre>
- bazel cquery //baz --output=starlark \
- --starlark:expr="[f.path for f in target.output_groups.compilation_outputs.to_list()]"
-</pre>
-<p>
-Print the value of the command line option <code>--javacopt</code> when building <code>//foo</code>.
-</p>
-<pre>
- bazel cquery //foo --output=starlark \
- --starlark:expr="build_options(target)['//command_line_option:javacopt']"
-</pre>
-<p>
- Print the label of each target with exactly one output. This example uses Starlark functions
- defined in a file.
-</p>
-<pre>
- $ cat example.cquery
-
- def has_one_output(target):
- return len(target.files.to_list()) == 1
-
- def format(target):
- if has_one_output(target):
- return target.label
- else:
- return ""
-
-
- $ bazel cquery //baz --output=starlark --starlark:file=example.cquery
-</pre>
-<p>
- Print the label of each target which is strictly Python 3. This example uses Starlark functions
- defined in a file.
-</p>
-<pre>
- $ cat example.cquery
-
- def format(target):
- p = providers(target)
- py_info = p.get("PyInfo")
- if py_info and py_info.has_py3_only_sources:
- return target.label
- else:
- return ""
-
-
- $ bazel cquery //baz --output=starlark --starlark:file=example.cquery
-</pre>
-
-<p>
- Extract a value from a user defined Provider.
-</p>
-<pre>
- $ cat some_package/my_rule.bzl
-
- MyRuleInfo = provider(fields={"color": "the name of a color"})
-
- def _my_rule_impl(ctx):
- ...
- return [MyRuleInfo(color="red")]
-
- my_rule = rule(
- implementation = _my_rule_impl,
- attrs = {...},
- )
-
- $ cat example.cquery
-
- def format(target):
- p = providers(target)
- my_rule_info = p.get("//some_package:my_rule.bzl%MyRuleInfo'")
- if my_rule_info:
- return my_rule_info.color
- return ""
-
-
- $ bazel cquery //baz --output=starlark --starlark:file=example.cquery
-</pre>
-
-
-<h2 id='compare'>cquery vs. query</h2>
-
-<p>
- <code>cquery</code> and <code>query</code> complement each other and excel in
- different niches. Consider the following to decide which is right for you:
-
- <ul>
- <li>
- <code>cquery</code> follows specific <code>select()</code> branches to
- model the exact graph you build. <code>query</code> doesn't know which
- branch the build chooses, so overapproximates by including all branches.
- </li>
- <li>
- <code>cquery</code>'s precision requires building more of the graph than
- <code>query</code> does. Specifically, <code>cquery</code>
- evaluates <i>configured targets</i> while <code>query</code> only
- evaluates <i>targets</i>. This takes more time and uses more memory.
- </li>
- <li>
- <code>cquery</code>'s intepretation of
- the <a href="query.html#concepts">query language</a> introduces ambiguity
- that <code>query</code> avoids. For example,
- if <code>"//foo"</code> exists in two configurations, which one
- should <code>cquery "deps(//foo)"</code> use?
- The <code><a href="#config">config</a></code></code> function can help with
- this.
- </li>
- <li>
- As a newer tool, <code>cquery</code> lacks support for certain use
- cases. See <a href="#known-issues">Known issues</a> for details.
- </li>
- </ul>
-</p>
-
-<h2 id='known-issues'>Known issues</h2>
-
-<ul>
- <li>
- <strong>All targets that <code>cquery</code> "builds" must have the same
- configuration.</strong>
-
- <p>
- Before evaluating queries, <code>cquery</code> triggers a build up to just
- before the point where build actions would execute. The targets it
- "builds" are by default selected from all labels that appear in the query
- expression (this can be overridden
- with <a href="#universe_scope-comma-separated-list"><code>--universe_scope</code></a>). These
- must have the same configuration.
- </p>
-
- <p>
- While these generally share the top-level "target" configuration,
- rules can change their own configuration with
-
- <a href="skylark/config.html#incoming-edge-transitions">incoming edge transitions</a>.
- This is where </code>cquery</code> falls short.
- </p>
-
- <p>
- Workaround: If possible, set <code>--universe_scope</code> to a stricter
- scope. For example:
- </p>
-
- <pre>
-# This command attempts to build the transitive closures of both //foo and
-# //bar. //bar uses an incoming edge transition to change its --cpu flag.
-$ bazel cquery 'somepath(//foo, //bar)'
-ERROR: Error doing post analysis query: Top-level targets //foo and //bar
-have different configurations (top-level targets with different
-configurations is not supported)
-
-# This command only builds the transitive closure of //foo, under which
-# //bar should exist in the correct configuration.
-$ bazel cquery 'somepath(//foo, //bar)' --universe_scope=//foo
- </pre>
- </li>
-
- <li>
- <strong>No support
- for <a href="query.html#output-xml"><code>--output=xml</code></a>.</strong>
- </li>
-
- <li>
- <strong>Non-deterministic output.</strong>
-
- <p>
- <code>cquery</code> does not automatically wipe the build graph from
- previous commands and is therefore prone to picking up results from past
- queries. For example, <code>genquery</code> exerts a host transition on
- its <code>tools</code> attribute - that is, it configures its tools in the
- <a href="https://docs.bazel.build/versions/main/skylark/rules.html#configurations">host
- configuration</a>.
- </p>
-
- <p>
- You can see the lingering effects of that transition below.
- </p>
-
-<pre>
-$ cat > foo/BUILD <<<EOF
-genrule(
- name = "my_gen",
- srcs = ["x.in"],
- outs = ["x.cc"],
- cmd = "$(locations :tool) $< >$@",
- tools = [":tool"],
-)
-cc_library(
- name = "tool",
-)
-EOF
-
-$ bazel cquery "//foo:tool"
-tool(target_config)
-
-$ bazel cquery "deps(//foo:my_gen)"
-my_gen (target_config)
-tool (host_config)
-...
-
-$ bazel cquery "//foo:tool"
-tool(host_config)
-</pre>
-
-<p>
- Workaround: change any startup option to force re-analysis of configured targets. For example,
- add <code>--test_arg=<whatever></code> to your build command.
-</p>
-
- </li>
-</ul>
-
-<h2 id='troubleshooting'>Troubleshooting</h2>
-
-<h3>Recursive target patterns (<code>/...</code>)</h3>
-
-<p>
- If you encounter:
-</p>
-
-<pre>
-$ bazel cquery --universe_scope=//foo:app "somepath(//foo:app, //foo/...)"
-ERROR: Error doing post analysis query: Evaluation failed: Unable to load package '[foo]'
-because package is not in scope. Check that all target patterns in query expression are within the
---universe_scope of this query.
-</pre>
-
-<p>
- this incorrectly suggests package <code>//foo</code> isn't in scope even though
- <code>--universe_scope=//foo:app</code> includes it. This is due to design limitations in
- <code>cquery</code>. As a workaround, explicitly include <code>//foo/...</code> in the universe
- scope:
-</p>
-
-<pre>
-$ bazel cquery --universe_scope=//foo:app,//foo/... "somepath(//foo:app, //foo/...)"
-</pre>
-
-<p>
- If that doesn't work (for example, because some target in <code>//foo/...</code> can't build
- with the chosen build flags), manually unwrap the pattern into its constituent packages with a
- pre-processing query:
-</p>
-
-<pre>
-# Replace "//foo/..." with a subshell query call (not cquery!) outputting each package, piped into
-# a sed call converting "<pkg>" to "//<pkg>:*", piped into a "+"-delimited line merge.
-# Output looks like "//foo:*+//foo/bar:*+//foo/baz".
-#
-$ bazel cquery --universe_scope=//foo:app "somepath(//foo:app, $(bazel query //foo/...
---output=package | sed -e 's/^/\/\//' -e 's/$/:*/' | paste -sd "+" -))"
-</pre>
-
diff --git a/site/docs/exec-groups.md b/site/docs/exec-groups.md
deleted file mode 100644
index 4a9d8d4..0000000
--- a/site/docs/exec-groups.md
+++ /dev/null
@@ -1,250 +0,0 @@
----
-layout: documentation
-title: Execution groups
----
-
-<div style="background-color: #EFCBCB; color: #AE2B2B; border: 1px solid #AE2B2B; border-radius: 5px; border-left: 10px solid #AE2B2B; padding: 0.5em;">
-<b>IMPORTANT:</b> The Bazel docs have moved! Please update your bookmark to <a href="https://bazel.build/reference/exec-groups" style="color: #0000EE;">https://bazel.build/reference/exec-groups</a>
-<p/>
-You can <a href="https://blog.bazel.build/2022/02/17/Launching-new-Bazel-site.html" style="color: #0000EE;">read about</a> the migration, and let us <a href="https://forms.gle/onkAkr2ZwBmcbWXj7" style="color: #0000EE;">know what you think</a>.
-</div>
-
-
-# Execution Groups
-
-
-Execution groups allow for multiple execution platforms within a single target.
-Each execution group has its own [toolchain](toolchains.md) dependencies and
-performs its own [toolchain resolution](toolchains.md#toolchain-resolution).
-
-## Current status
-
-## Background
-
-Execution groups allow the rule author to define sets of actions, each with a
-potentially different execution platform. Multiple execution platforms can allow
-actions to execution differently, for example compiling an iOS app on a remote
-(linux) worker and then linking/code signing on a local mac worker.
-
-Being able to define groups of actions also helps alleviate the usage of action
-mnemonics as a proxy for specifying actions. Mnemonics are not guaranteed to be
-unique and can only reference a single action. This is especially helpful in
-allocating extra resources to specific memory and processing intensive actions
-like linking in c++ builds without over-allocating to less demanding tasks.
-
-## Defining execution groups
-
-During rule definition, rule authors can
-[declare](https://docs.bazel.build/versions/main/skylark/lib/globals.html#exec_group)
-a set of execution groups. On each execution group, the rule author can specify
-everything needed to select an execution platform for that execution group,
-namely any constraints via `exec_compatible_with` and toolchain types via
-`toolchain`.
-
-```python
-# foo.bzl
-my_rule = rule(
- _impl,
- exec_groups = {
- "link": exec_group(
- exec_compatible_with = ["@platforms//os:linux"],
- toolchains = ["//foo:toolchain_type"],
- ),
- "test": exec_group(
- toolchains = ["//foo_tools:toolchain_type"],
- ),
- },
- attrs = {
- "_compiler": attr.label(cfg = config.exec("link"))
- },
-)
-```
-
-In the code snippet above, you can see that tool dependencies can also specify
-transition for an exec group using the
-[`cfg`](https://docs.bazel.build/versions/main/skylark/lib/attr.html#label)
-attribute param and the
-[`config`](https://docs.bazel.build/versions/main/skylark/lib/config.html)
-module. The module exposes an `exec` function which takes a single string
-parameter which is the name of the exec group for which the dependency should be
-built.
-
-As on native rules, the `test` execution group is present by default on Stalark
-test rules.
-
-### Execution group inheritance
-
-In addition to defining its own constraints and toolchains, a new execution
-group can declare that it wants to inherit from the rule's default execution
-group, by passing the `copy_from_rule = True` parameter. It is an error to set
-`copy_from_rule` to true and to also pass `exec_compatible_with` or
-`toolchains`.
-
-An execution group that inherits from the default execution group copies
-constraints, toolchains, and execution properties from the default. This
-includes constraints and execution properties set on the target level, not just
-those specified by the rule itself. In other words, given the following:
-
-```python
-# foo.bzl
-my_rule = rule(
- _impl,
- exec_groups = {
- "copied": exec_group(
- copy_from_rule = True,
- # This will inherit exec_compatible_with and toolchains.
- # Setting them here directly would be an error, however.
- ),
- },
- toolchains = ["//foo_tools:toolchain_type"],
- exec_compatible_with = [ "@platforms//os:linux" ]
-)
-
-# BUILD
-
-my_rule(
- name = "demo",
- exec_compatible_with = [":local_constraint"],
-)
-```
-
-The `copied` execution group for the configured target `demo` will include all
-of:
-- `//fool_tools:toolchain_type`
-- `@platforms//os:linux`
-- `:local_constraint`
-
-## Accessing execution groups
-
-In the rule implementation, you can declare that actions should be run on the
-execution platform of an execution group. You can do this by using the `exec_group`
-param of action generating methods, specifically [`ctx.actions.run`]
-(https://docs.bazel.build/versions/main/skylark/lib/actions.html#run) and
-[`ctx.actions.run_shell`](https://docs.bazel.build/versions/main/skylark/lib/actions.html#run_shell).
-
-```python
-# foo.bzl
-def _impl(ctx):
- ctx.actions.run(
- inputs = [ctx.attr._some_tool, ctx.srcs[0]]
- exec_group = "compile",
- # ...
- )
-```
-
-Rule authors will also be able to access the [resolved toolchains]
-(toolchains.md#toolchain-resolution) of execution groups, similarly to how you
-can access the resolved toolchain of a target:
-
-```python
-# foo.bzl
-def _impl(ctx):
- foo_info = ctx.exec_groups["link"].toolchains["//foo:toolchain_type"].fooinfo
- ctx.actions.run(
- inputs = [foo_info, ctx.srcs[0]]
- exec_group = "link",
- # ...
- )
-```
-
-Note: If an action uses a toolchain from an execution group, but doesn't specify
-that execution group in the action declaration, that may potentially cause
-issues. A mismatch like this may not immediately cause failures, but is a latent
-problem.
-
-## Using execution groups to set execution properties
-
-Execution groups are integrated with the
-[`exec_properties`](be/common-definitions.html#common-attributes)
-attribute that exists on every rule and allows the target writer to specify a
-string dict of properties that is then passed to the execution machinery. For
-example, if you wanted to set some property, say memory, for the target and give
-certain actions a higher memory allocation, you would write an `exec_properties`
-entry with an execution-group-augmented key, e.g.:
-
-```python
-# BUILD
-my_rule(
- name = 'my_target',
- exec_properties = {
- 'mem': '12g',
- 'link.mem': '16g'
- }
- …
-)
-```
-
-All actions with `exec_group = "link"` would see the exec properties
-dictionary as `{"mem": "16g"}`. As you see here, execution-group-level
-settings override target-level settings.
-
-### Execution groups for native rules
-
-The following execution groups are available for actions defined by native rules:
-
-* `test`: Test runner actions.
-* `cpp_link`: C++ linking actions.
-
-### Creating exec groups to set exec properties
-
-Sometimes you want to use an exec group to give specific actions different exec
-properties but don't actually want different toolchains or constraints than the
-rule. For these situations, you can create exec groups using the `copy_from_rule`
-parameter:
-
-```python
-# foo.bzl
-
-# Creating an exec group with `copy_from_rule=True` is the same as explicitly
-# setting the exec group's toolchains and constraints to the same values as the
-# rule's respective parameters.
-my_rule = rule(
- _impl,
- exec_compatible_with = [ "@platforms//os:linux" ],
- toolchains = ["//foo:toolchain_type"],
- exec_groups = {
- # The following two groups have the same toolchains and constraints:
- "foo": exec_group(copy_from_rule = True),
- "bar": exec_group(
- exec_compatible_with = [ "@platforms//os:linux" ],
- toolchains = ["//foo:toolchain_type"],
- ),
- },
-)
-
-#
-```
-
-### Execution groups and platform execution properties
-
-It is possible to define `exec_properties` for arbitrary execution groups on
-platform targets (unlike `exec_properties` set directly on a target, where
-properties for unknown execution groups are rejected). Targets then inherit the
-execution platform's `exec_properties` that affect the default execution group
-and any other relevant execution groups.
-
-For example, suppose running a C++ test requires some resource to be available,
-but it isn't required for compiling and linking; this can be modelled as
-follows:
-
-```python
-constraint_setting(name = "resource")
-constraint_value(name = "has_resource", constraint_setting = ":resource")
-
-platform(
- name = "platform_with_resource",
- constraint_values = [":has_resource"],
- exec_properties = {
- "test.resource": "...",
- },
-)
-
-cc_test(
- name = "my_test",
- srcs = ["my_test.cc"],
- exec_compatible_with = [":has_resource"],
-)
-```
-
-`exec_properties` defined directly on targets take precedence over those that
-are inherited from the execution platform.
diff --git a/site/docs/guide.md b/site/docs/guide.md
deleted file mode 100644
index 727f9c5..0000000
--- a/site/docs/guide.md
+++ /dev/null
@@ -1,1112 +0,0 @@
----
-layout: documentation
-title: User's guide
----
-
-<div style="background-color: #EFCBCB; color: #AE2B2B; border: 1px solid #AE2B2B; border-radius: 5px; border-left: 10px solid #AE2B2B; padding: 0.5em;">
-<b>IMPORTANT:</b> The Bazel docs have moved! Please update your bookmark to <a href="https://bazel.build/docs/build" style="color: #0000EE;">https://bazel.build/docs/build</a>
-<p/>
-You can <a href="https://blog.bazel.build/2022/02/17/Launching-new-Bazel-site.html" style="color: #0000EE;">read about</a> the migration, and let us <a href="https://forms.gle/onkAkr2ZwBmcbWXj7" style="color: #0000EE;">know what you think</a>.
-</div>
-
-
-# A User's Guide to Bazel
-
-To run Bazel, go to your base [workspace](build-ref.html#workspace) directory
-or any of its subdirectories and type `bazel`.
-
-<pre>
- % bazel help
- [Bazel release bazel-<<i>version</i>>]
- Usage: bazel <command> <options> ...
-
- Available commands:
- <a href='user-manual.html#analyze-profile'>analyze-profile</a> Analyzes build profile data.
- <a href='user-manual.html#aquery'>aquery</a> Executes a query on the <a href='#analysis-phase'>post-analysis</a> action graph.
- <a href='#build'>build</a> Builds the specified targets.
- <a href='user-manual.html#canonicalize'>canonicalize-flags</a> Canonicalize Bazel flags.
- <a href='user-manual.html#clean'>clean</a> Removes output files and optionally stops the server.
-
- <a href='user-manual.html#query'>cquery</a> Executes a <a href='#analysis-phase'>post-analysis</a> dependency graph query.
-
- <a href='user-manual.html#dump'>dump</a> Dumps the internal state of the Bazel server process.
-
- <a href='user-manual.html#help'>help</a> Prints help for commands, or the index.
- <a href='user-manual.html#info'>info</a> Displays runtime info about the bazel server.
-
- <a href='#fetch'>fetch</a> Fetches all external dependencies of a target.
- <a href='user-manual.html#mobile-install'>mobile-install</a> Installs apps on mobile devices.
-
- <a href='user-manual.html#query'>query</a> Executes a dependency graph query.
-
- <a href='user-manual.html#run'>run</a> Runs the specified target.
- <a href='user-manual.html#shutdown'>shutdown</a> Stops the Bazel server.
- <a href='user-manual.html#test'>test</a> Builds and runs the specified test targets.
- <a href='user-manual.html#version'>version</a> Prints version information for Bazel.
-
- Getting more help:
- bazel help <command>
- Prints help and options for <command>.
- bazel help <a href='user-manual.html#startup_options'>startup_options</a>
- Options for the JVM hosting Bazel.
- bazel help <a href='#target-patterns'>target-syntax</a>
- Explains the syntax for specifying targets.
- bazel help info-keys
- Displays a list of keys used by the info command.
-
-</pre>
-
-The `bazel` tool performs many functions, called commands. The most commonly
-used ones are `bazel build` and `bazel test`. You can browse the online help
-messages using `bazel help`.
-
-<a id="build"></a>
-
-## Building programs with Bazel
-
-### The `build` command
-
-Type `bazel build` followed by the name of the [target](#target-patterns) you
-wish to build. Here's a typical session:
-
-```
-% bazel build //foo
-INFO: Analyzed target //foo:foo (14 packages loaded, 48 targets configured).
-INFO: Found 1 target...
-Target //foo:foo up-to-date:
- bazel-bin/foo/foo
-INFO: Elapsed time: 9.905s, Critical Path: 3.25s
-INFO: Build completed successfully, 6 total actions
-```
-
-Bazel prints the progress messages as it loads all the packages in the
-transitive closure of dependencies of the requested target, then analyzes them
-for correctness and to create the build actions, finally executing the compilers
-and other tools of the build.
-
-Bazel prints progress messages during the [execution phase](#execution-phase) of
-the build, showing the current build step (compiler, linker, etc.) that is being
-started, and the number completed over the total number of build actions. As the
-build starts the number of total actions will often increase as Bazel discovers
-the entire action graph, but the number will usually stabilize within a few
-seconds.
-
-At the end of the build Bazel prints which targets were requested, whether or
-not they were successfully built, and if so, where the output files can be
-found. Scripts that run builds can reliably parse this output; see
-[`--show_result`](user-manual.html#flag--show_result) for more details.
-
-Typing the same command again:
-
-```
-% bazel build //foo
-INFO: Analyzed target //foo:foo (0 packages loaded, 0 targets configured).
-INFO: Found 1 target...
-Target //foo:foo up-to-date:
- bazel-bin/foo/foo
-INFO: Elapsed time: 0.144s, Critical Path: 0.00s
-INFO: Build completed successfully, 1 total action
-```
-
-You see a "null" build: in this case, there are no packages to reload, since
-nothing changed, and no build steps to execute. (If something changed in
-"foo" or some of its dependencies, resulting in the re-execution of some build
-actions, you would call it an "incremental" build, not a "null" build.)
-
-Before you can start a build, you will need a Bazel workspace. This is simply a
-directory tree that contains all the source files needed to build your
-application. Bazel allows you to perform a build from a completely read-only
-volume.
-
-<a id="target-patterns"></a>
-
-### Specifying targets to build
-
-Bazel allows a number of ways to specify the targets to be built. Collectively,
-these are known as _target patterns_. This syntax is used in commands like
-`build`, `test`, or `query`.
-
-Whereas [labels](build-ref.html#labels) are used to specify individual targets,
-e.g. for declaring dependencies in `BUILD` files, Bazel's target patterns are a
-syntax for specifying multiple targets: they are a generalization of the label
-syntax for _sets_ of targets, using wildcards. In the simplest case, any valid
-label is also a valid target pattern, identifying a set of exactly one target.
-
-All target patterns starting with `//` are resolved relative to the current
-workspace.
-
-<table>
-<tr>
- <td><code>//foo/bar:wiz</code></td>
- <td>Just the single target <code>//foo/bar:wiz</code>.</td>
-</tr>
-<tr>
- <td><code>//foo/bar</code></td>
- <td>Equivalent to <code>//foo/bar:bar</code>.</td>
-</tr>
-<tr>
- <td><code>//foo/bar:all</code></td>
- <td>All rule targets in the package <code>foo/bar</code>.</td>
-</tr>
-<tr>
- <td><code>//foo/...</code></td>
- <td>All rule targets in all packages beneath the directory <code>foo</code>.</td>
-</tr>
-<tr>
- <td><code>//foo/...:all</code></td>
- <td>All rule targets in all packages beneath the directory <code>foo</code>.</td>
-</tr>
-<tr>
- <td><code>//foo/...:*</code></td>
- <td>All targets (rules and files) in all packages beneath the directory <code>foo</code>.</td>
-</tr>
-<tr>
- <td><code>//foo/...:all-targets</code></td>
- <td>All targets (rules and files) in all packages beneath the directory <code>foo</code>.</td>
-</tr>
-<tr>
- <td><code>//...</code></td>
- <td>All targets in packages in the workspace. This does not include targets
- from <a href="external.html">external repositories</a>.</td>
-</tr>
-<tr>
- <td><code>//:all</code></td>
- <td>All targets in the top-level package, if there is a `BUILD` file at the
- root of the workspace.</td>
-</tr>
-</table>
-
-Target patterns which do not begin with `//` are resolved relative to the
-current _working directory_. These examples assume a working directory of `foo`:
-
-<table>
-<tr>
- <td><code>:foo</code></td>
- <td>Equivalent to <code>//foo:foo</code>.</td>
-</tr>
-<tr>
- <td><code>bar:wiz</code></td>
- <td>Equivalent to <code>//foo/bar:wiz</code>.</td>
-</tr>
-<tr>
- <td><code>bar/wiz</code></td>
- <td>Equivalent to:
- <code>//foo/bar/wiz:wiz</code> if <code>foo/bar/wiz</code> is a package,
- <code>//foo/bar:wiz</code> if <code>foo/bar</code> is a package,
- <code>//foo:bar/wiz</code> otherwise.
- </td>
-</tr>
-<tr>
- <td><code>bar:all</code></td>
- <td>Equivalent to <code>//foo/bar:all</code>.</td>
-</tr>
-<tr>
- <td><code>:all</code></td>
- <td>Equivalent to <code>//foo:all</code>.</td>
-</tr>
-<tr>
- <td><code>...:all</code></td>
- <td>Equivalent to <code>//foo/...:all</code>.</td>
-</tr>
-<tr>
- <td><code>...</code></td>
- <td>Equivalent to <code>//foo/...:all</code>.</td>
-</tr>
-<tr>
- <td><code>bar/...:all</code></td>
- <td>Equivalent to <code>//foo/bar/...:all</code>.</td>
-</tr>
-</table>
-
-By default, directory symlinks are followed for recursive target patterns,
-except those that point to under the output base, such as the convenience
-symlinks that are created in the root directory of the workspace.
-
-In addition, Bazel does not follow symlinks when evaluating recursive target
-patterns in any directory that contains a file named as follows:
-`DONT_FOLLOW_SYMLINKS_WHEN_TRAVERSING_THIS_DIRECTORY_VIA_A_RECURSIVE_TARGET_PATTERN`
-
-`foo/...` is a wildcard over _packages_, indicating all packages recursively
-beneath directory `foo` (for all roots of the package path). `:all` is a
-wildcard over _targets_, matching all rules within a package. These two may be
-combined, as in `foo/...:all`, and when both wildcards are used, this may be
-abbreviated to `foo/...`.
-
-In addition, `:*` (or `:all-targets`) is a wildcard that matches _every target_
-in the matched packages, including files that aren't normally built by any rule,
-such as `_deploy.jar` files associated with `java_binary` rules.
-
-This implies that `:*` denotes a _superset_ of `:all`; while potentially
-confusing, this syntax does allow the familiar `:all` wildcard to be used for
-typical builds, where building targets like the `_deploy.jar` is not desired.
-
-In addition, Bazel allows a slash to be used instead of the colon required by
-the label syntax; this is often convenient when using Bash filename expansion.
-For example, `foo/bar/wiz` is equivalent to `//foo/bar:wiz` (if there is a
-package `foo/bar`) or to `//foo:bar/wiz` (if there is a package `foo`).
-
-Many Bazel commands accept a list of target patterns as arguments, and they all
-honor the prefix negation operator `-`. This can be used to subtract a set of
-targets from the set specified by the preceding arguments. Note that this means
-order matters. For example,
-
-```
-bazel build foo/... bar/...
-```
-
-means "build all targets beneath `foo` _and_ all targets beneath `bar`", whereas
-
-```
-bazel build -- foo/... -foo/bar/...
-```
-
-means "build all targets beneath `foo` _except_ those beneath `foo/bar`". (The
-`--` argument is required to prevent the subsequent arguments starting with `-`
-from being interpreted as additional options.)
-
-It's important to point out though that subtracting targets this way will not
-guarantee that they are not built, since they may be dependencies of targets
-that weren't subtracted. For example, if there were a target `//foo:all-apis`
-that among others depended on `//foo/bar:api`, then the latter would be built as
-part of building the former.
-
-Targets with `tags = ["manual"]` are not included in wildcard target patterns
-(`...`, `:*`, `:all`, etc.) when specified in commands like
-<code>bazel build</code> and <code>bazel test</code>; you should specify such
-test targets with explicit target patterns on the command line if you want Bazel
-to build/test them. In contrast, <code>bazel query</code> doesn't perform any
-such filtering automatically (that would defeat the purpose of
-<code>bazel query</code>).
-
-<a id="fetch"></a>
-### Fetching external dependencies
-
-By default, Bazel will download and symlink external dependencies during the
-build. However, this can be undesirable, either because you'd like to know
-when new external dependencies are added or because you'd like to
-"prefetch" dependencies (say, before a flight where you'll be offline). If you
-would like to prevent new dependencies from being added during builds, you
-can specify the `--fetch=false` flag. Note that this flag only
-applies to repository rules that do not point to a directory in the local
-file system. Changes, for example, to `local_repository`,
-`new_local_repository` and Android SDK and NDK repository rules
-will always take effect regardless of the value `--fetch` .
-
-If you disallow fetching during builds and Bazel finds new external
-dependencies, your build will fail.
-
-You can manually fetch dependencies by running `bazel fetch`. If
-you disallow during-build fetching, you'll need to run `bazel fetch`:
-
-- Before you build for the first time.
-- After you add a new external dependency.
-
-Once it has been run, you should not need to run it again until the WORKSPACE
-file changes.
-
-`fetch` takes a list of targets to fetch dependencies for. For
-example, this would fetch dependencies needed to build `//foo:bar`
-and `//bar:baz`:
-
-```
-$ bazel fetch //foo:bar //bar:baz
-```
-
-To fetch all external dependencies for a workspace, run:
-
-```
-$ bazel fetch //...
-```
-
-You do not need to run bazel fetch at all if you have all of the tools you are
-using (from library jars to the JDK itself) under your workspace root.
-However, if you're using anything outside of the workspace directory then Bazel
-will automatically run `bazel fetch` before running
-`bazel build`.
-
-<a id="repository-cache"></a>
-#### The repository cache
-
-Bazel tries to avoid fetching the same file several times, even if the same
-file is needed in different workspaces, or if the definition of an external
-repository changed but it still needs the same file to download. To do so,
-bazel caches all files downloaded in the repository cache which, by default,
-is located at `~/.cache/bazel/_bazel_$USER/cache/repos/v1/`. The
-location can be changed by the `--repository_cache` option. The
-cache is shared between all workspaces and installed versions of bazel.
-An entry is taken from the cache if
-Bazel knows for sure that it has a copy of the correct file, that is, if the
-download request has a SHA256 sum of the file specified and a file with that
-hash is in the cache. So specifying a hash for each external file is
-not only a good idea from a security perspective; it also helps avoiding
-unnecessary downloads.
-
-Upon each cache hit, the modification time of the file in the cache is
-updated. In this way, the last use of a file in the cache directory can easily
-be determined, for example to manually clean up the cache. The cache is never
-cleaned up automatically, as it might contain a copy of a file that is no
-longer available upstream.
-
-<a id="distdir"></a>
-#### Distribution files directories
-
-The distribution directory is another Bazel mechanism to avoid unnecessary
-downloads. Bazel searches distribution directories before the repository cache.
-The primary difference is that the distribution directory requires manual
-preparation.
-
-Using the
-[`--distdir=/path/to-directory`](https://docs.bazel.build/versions/main/command-line-reference.html#flag--distdir)
-option, you can specify additional read-only directories to look for files
-instead of fetching them. A file is taken from such a directory if the file name
-is equal to the base name of the URL and additionally the hash of the file is
-equal to the one specified in the download request. This only works if the
-file hash is specified in the WORKSPACE declaration.
-
-While the condition on the file name is not necessary for correctness, it
-reduces the number of candidate files to one per specified directory. In this
-way, specifying distribution files directories remains efficient, even if the
-number of files in such a directory grows large.
-
-#### Running Bazel in an airgapped environment
-
-To keep Bazel's binary size small, Bazel's implicit dependencies are fetched
-over the network while running for the first time. These implicit dependencies
-contain toolchains and rules that may not be necessary for everyone. For
-example, Android tools are unbundled and fetched only when building Android
-projects.
-
-However, these implicit dependencies may cause problems when running
-Bazel in an airgapped environment, even if you have vendored all of your
-WORKSPACE dependencies. To solve that, you can prepare a distribution directory
-containing these dependencies on a machine with network access, and then
-transfer them to the airgapped environment with an offline approach.
-
-To prepare the [distribution directory](distribution-files-directories), use the
-[`--distdir`](https://docs.bazel.build/versions/main/command-line-reference.html#flag--distdir)
-flag. You will need to do this once for every new Bazel binary version, since
-the implicit dependencies can be different for every release.
-
-To build these dependencies outside of your airgapped environment, first
-checkout the Bazel source tree at the right version:
-
-```
-git clone https://github.com/bazelbuild/bazel "$BAZEL_DIR"
-cd "$BAZEL_DIR"
-git checkout "$BAZEL_VERSION"
-```
-
-Then, build the tarball containing the implicit runtime dependencies for that
-specific Bazel version:
-
-```
-bazel build @additional_distfiles//:archives.tar
-```
-
-Export this tarball to a directory that can be copied into your airgapped
-environment. Note the `--strip-components` flag, because `--distdir` can be
-quite finicky with the directory nesting level:
-
-
-```
-tar xvf bazel-bin/external/additional_distfiles/archives.tar \
- -C "$NEW_DIRECTORY" --strip-components=3
-```
-
-Finally, when you use Bazel in your airgapped environment, pass the `--distdir`
-flag pointing to the directory. For convenience, you can add it as an `.bazelrc`
-entry:
-
-```
-build --distdir=path/to/directory
-```
-
-
-<a id="configurations"></a>
-
-### Build configurations and cross-compilation
-
-All the inputs that specify the behavior and result of a given build can be
-divided into two distinct categories. The first kind is the intrinsic
-information stored in the `BUILD` files of your project: the build rule, the
-values of its attributes, and the complete set of its transitive dependencies.
-The second kind is the external or environmental data, supplied by the user or
-by the build tool: the choice of target architecture, compilation and linking
-options, and other toolchain configuration options. We refer to a complete set
-of environmental data as a **configuration**.
-
-In any given build, there may be more than one configuration. Consider a
-cross-compile, in which you build a `//foo:bin` executable for a 64-bit
-architecture, but your workstation is a 32-bit machine. Clearly, the build will
-require building `//foo:bin` using a toolchain capable of creating 64-bit
-executables, but the build system must also build various tools used during the
-build itself—for example tools that are built from source, then subsequently
-used in, say, a genrule—and these must be built to run on your workstation. Thus
-we can identify two configurations: the **host configuration**, which is used
-for building tools that run during the build, and the **target configuration**
-(or _request configuration_, but we say "target configuration" more often even
-though that word already has many meanings), which is used for building the
-binary you ultimately requested.
-
-Typically, there are many libraries that are prerequisites of both the requested
-build target (`//foo:bin`) and one or more of the host tools, for example some
-base libraries. Such libraries must be built twice, once for the host
-configuration, and once for the target configuration. Bazel takes care of
-ensuring that both variants are built, and that the derived files are kept
-separate to avoid interference; usually such targets can be built concurrently,
-since they are independent of each other. If you see progress messages
-indicating that a given target is being built twice, this is most likely the
-explanation.
-
-Bazel uses one of two ways to select the host configuration, based on the
-`--distinct_host_configuration` option. This boolean option is somewhat subtle,
-and the setting may improve (or worsen) the speed of your builds.
-
-#### `--distinct_host_configuration=false`
-
-We do not recommend this option.
-
-
-- If you frequently make changes to your request configuration, such as
- alternating between `-c opt` and `-c dbg` builds, or between simple- and
- cross-compilation, you will typically rebuild the majority of your codebase
- each time you switch.
-
-When this option is false, the host and request configurations are identical:
-all tools required during the build will be built in exactly the same way as
-target programs. This setting means that no libraries need to be built twice
-during a single build.
-
-However, it does mean that any change to your request configuration also affects
-your host configuration, causing all the tools to be rebuilt, and then anything
-that depends on the tool output to be rebuilt too. Thus, for example, simply
-changing a linker option between builds might cause all tools to be re-linked,
-and then all actions using them re-executed, and so on, resulting in a very
-large rebuild. Also, please note: if your host architecture is not capable of
-running your target binaries, your build will not work.
-
-#### `--distinct_host_configuration=true` _(default)_
-
-If this option is true, then instead of using the same configuration for the
-host and request, a completely distinct host configuration is used. The host
-configuration is derived from the target configuration as follows:
-
-- Use the same version of Crosstool (`--crosstool_top`) as specified in the
- request configuration, unless `--host_crosstool_top` is specified.
-- Use the value of `--host_cpu` for `--cpu` (default: `k8`).
-- Use the same values of these options as specified in the request
- configuration: `--compiler`, `--use_ijars`, and if `--host_crosstool_top` is
- used, then the value of `--host_cpu` is used to look up a
- `default_toolchain` in the Crosstool (ignoring `--compiler`) for the host
- configuration.
-- Use the value of `--host_javabase` for `--javabase`
-- Use the value of `--host_java_toolchain` for `--java_toolchain`
-- Use optimized builds for C++ code (`-c opt`).
-- Generate no debugging information (`--copt=-g0`).
-- Strip debug information from executables and shared libraries
- (`--strip=always`).
-- Place all derived files in a special location, distinct from that used by
- any possible request configuration.
-- Suppress stamping of binaries with build data (see `--embed_*` options).
-- All other values remain at their defaults.
-
-There are many reasons why it might be preferable to select a distinct host
-configuration from the request configuration. Some are too esoteric to mention
-here, but two of them are worth pointing out.
-
-Firstly, by using stripped, optimized binaries, you reduce the time spent
-linking and executing the tools, the disk space occupied by the tools, and the
-network I/O time in distributed builds.
-
-Secondly, by decoupling the host and request configurations in all builds, you
-avoid very expensive rebuilds that would result from minor changes to the
-request configuration (such as changing a linker options does), as described
-earlier.
-
-That said, for certain builds, this option may be a hindrance. In particular,
-builds in which changes of configuration are infrequent (especially certain Java
-builds), and builds where the amount of code that must be built in both host and
-target configurations is large, may not benefit.
-
-<a id="correctness"></a>
-
-### Correct incremental rebuilds
-
-One of the primary goals of the Bazel project is to ensure correct incremental
-rebuilds. Previous build tools, especially those based on Make, make several
-unsound assumptions in their implementation of incremental builds.
-
-Firstly, that timestamps of files increase monotonically. While this is the
-typical case, it is very easy to fall afoul of this assumption; syncing to an
-earlier revision of a file causes that file's modification time to decrease;
-Make-based systems will not rebuild.
-
-More generally, while Make detects changes to files, it does not detect changes
-to commands. If you alter the options passed to the compiler in a given build
-step, Make will not re-run the compiler, and it is necessary to manually discard
-the invalid outputs of the previous build using `make clean`.
-
-Also, Make is not robust against the unsuccessful termination of one of its
-subprocesses after that subprocess has started writing to its output file. While
-the current execution of Make will fail, the subsequent invocation of Make will
-blindly assume that the truncated output file is valid (because it is newer than
-its inputs), and it will not be rebuilt. Similarly, if the Make process is
-killed, a similar situation can occur.
-
-Bazel avoids these assumptions, and others. Bazel maintains a database of all
-work previously done, and will only omit a build step if it finds that the set
-of input files (and their timestamps) to that build step, and the compilation
-command for that build step, exactly match one in the database, and, that the
-set of output files (and their timestamps) for the database entry exactly match
-the timestamps of the files on disk. Any change to the input files or output
-files, or to the command itself, will cause re-execution of the build step.
-
-The benefit to users of correct incremental builds is: less time wasted due to
-confusion. (Also, less time spent waiting for rebuilds caused by use of `make
-clean`, whether necessary or pre-emptive.)
-
-#### Build consistency and incremental builds
-
-Formally, we define the state of a build as _consistent_ when all the expected
-output files exist, and their contents are correct, as specified by the steps or
-rules required to create them. When you edit a source file, the state of the
-build is said to be _inconsistent_, and remains inconsistent until you next run
-the build tool to successful completion. We describe this situation as _unstable
-inconsistency_, because it is only temporary, and consistency is restored by
-running the build tool.
-
-There is another kind of inconsistency that is pernicious: _stable
-inconsistency_. If the build reaches a stable inconsistent state, then repeated
-successful invocation of the build tool does not restore consistency: the build
-has gotten "stuck", and the outputs remain incorrect. Stable inconsistent states
-are the main reason why users of Make (and other build tools) type `make clean`.
-Discovering that the build tool has failed in this manner (and then recovering
-from it) can be time consuming and very frustrating.
-
-Conceptually, the simplest way to achieve a consistent build is to throw away
-all the previous build outputs and start again: make every build a clean build.
-This approach is obviously too time-consuming to be practical (except perhaps
-for release engineers), and therefore to be useful, the build tool must be able
-to perform incremental builds without compromising consistency.
-
-Correct incremental dependency analysis is hard, and as described above, many
-other build tools do a poor job of avoiding stable inconsistent states during
-incremental builds. In contrast, Bazel offers the following guarantee: after a
-successful invocation of the build tool during which you made no edits, the
-build will be in a consistent state. (If you edit your source files during a
-build, Bazel makes no guarantee about the consistency of the result of the
-current build. But it does guarantee that the results of the _next_ build will
-restore consistency.)
-
-As with all guarantees, there comes some fine print: there are some known ways
-of getting into a stable inconsistent state with Bazel. We won't guarantee to
-investigate such problems arising from deliberate attempts to find bugs in the
-incremental dependency analysis, but we will investigate and do our best to fix
-all stable inconsistent states arising from normal or "reasonable" use of the
-build tool.
-
-If you ever detect a stable inconsistent state with Bazel, please report a bug.
-
-
-<a id="sandboxing"></a>
-
-#### Sandboxed execution
-
-NOTE: Sandboxing is enabled by default for local execution.
-
-Bazel can use sandboxes to guarantee that actions run hermetically<sup>1</sup>
-and correctly. Bazel runs _spawns_ (loosely speaking: actions) in sandboxes that
-only contain the minimal set of files the tool requires to do its job. Currently
-sandboxing works on Linux 3.12 or newer with the `CONFIG_USER_NS` option
-enabled, and also on macOS 10.11 or newer.
-
-Bazel will print a warning if your system does not support sandboxing to alert
-you to the fact that builds are not guaranteed to be hermetic and might affect
-the host system in unknown ways. To disable this warning you can pass the
-`--ignore_unsupported_sandboxing` flag to Bazel.
-
-<sup>1</sup>: Hermeticity means that the action only uses its declared input
-files and no other files in the filesystem, and it only produces its declared
-output files.
-
-On some platforms such as [Google Kubernetes
-Engine](https://cloud.google.com/kubernetes-engine/) cluster nodes or Debian,
-user namespaces are deactivated by default due to security
-concerns. This can be checked by looking at the file
-`/proc/sys/kernel/unprivileged_userns_clone`: if it exists and contains a 0,
-then user namespaces can be activated with
-`sudo sysctl kernel.unprivileged_userns_clone=1`.
-
-In some cases, the Bazel sandbox fails to execute rules because of the system
-setup. The symptom is generally a failure that output a message similar to
-`namespace-sandbox.c:633: execvp(argv[0], argv): No such file or directory`.
-In that case, try to deactivate the sandbox for genrules with
-`--strategy=Genrule=standalone` and for other rules with
-`--spawn_strategy=standalone`. Also please report a bug on our
-issue tracker and mention which Linux distribution you're using so that we can
-investigate and provide a fix in a subsequent release.
-
-
-<a id="phases"></a>
-
-### Phases of a build
-
-In Bazel, a build occurs in three distinct phases; as a user, understanding the
-difference between them provides insight into the options which control a build
-(see below).
-
-#### Loading phase
-
-The first is **loading** during which all the necessary BUILD files for the
-initial targets, and their transitive closure of dependencies, are loaded,
-parsed, evaluated and cached.
-
-For the first build after a Bazel server is started, the loading phase typically
-takes many seconds as many BUILD files are loaded from the file system. In
-subsequent builds, especially if no BUILD files have changed, loading occurs
-very quickly.
-
-Errors reported during this phase include: package not found, target not found,
-lexical and grammatical errors in a BUILD file, and evaluation errors.
-
-#### Analysis phase
-
-The second phase, **analysis**, involves the semantic analysis and validation of
-each build rule, the construction of a build dependency graph, and the
-determination of exactly what work is to be done in each step of the build.
-
-Like loading, analysis also takes several seconds when computed in its entirety.
-However, Bazel caches the dependency graph from one build to the next and only
-reanalyzes what it has to, which can make incremental builds extremely fast in
-the case where the packages haven't changed since the previous build.
-
-Errors reported at this stage include: inappropriate dependencies, invalid
-inputs to a rule, and all rule-specific error messages.
-
-The loading and analysis phases are fast because Bazel avoids unnecessary file
-I/O at this stage, reading only BUILD files in order to determine the work to be
-done. This is by design, and makes Bazel a good foundation for analysis tools,
-such as Bazel's [query](#query) command, which is implemented atop the loading
-phase.
-
-#### Execution phase
-
-The third and final phase of the build is **execution**. This phase ensures that
-the outputs of each step in the build are consistent with its inputs, re-running
-compilation/linking/etc. tools as necessary. This step is where the build spends
-the majority of its time, ranging from a few seconds to over an hour for a large
-build. Errors reported during this phase include: missing source files, errors
-in a tool executed by some build action, or failure of a tool to produce the
-expected set of outputs.
-
-<a id="client/server"></a>
-
-## Client/server implementation
-
-The Bazel system is implemented as a long-lived server process. This allows it
-to perform many optimizations not possible with a batch-oriented implementation,
-such as caching of BUILD files, dependency graphs, and other metadata from one
-build to the next. This improves the speed of incremental builds, and allows
-different commands, such as `build` and `query` to share the same cache of
-loaded packages, making queries very fast.
-
-When you run `bazel`, you're running the client. The client finds the server
-based on the output base, which by default is determined by the path of the base
-workspace directory and your userid, so if you build in multiple workspaces,
-you'll have multiple output bases and thus multiple Bazel server processes.
-Multiple users on the same workstation can build concurrently in the same
-workspace because their output bases will differ (different userids). If the
-client cannot find a running server instance, it starts a new one. The server
-process will stop after a period of inactivity (3 hours, by default, which can
-be modified using the startup option `--max_idle_secs`).
-
-For the most part, the fact that there is a server running is invisible to the
-user, but sometimes it helps to bear this in mind. For example, if you're
-running scripts that perform a lot of automated builds in different directories,
-it's important to ensure that you don't accumulate a lot of idle servers; you
-can do this by explicitly shutting them down when you're finished with them, or
-by specifying a short timeout period.
-
-The name of a Bazel server process appears in the output of `ps x` or `ps -e f`
-as <code>bazel(<i>dirname</i>)</code>, where _dirname_ is the basename of the
-directory enclosing the root of your workspace directory. For example:
-
-```
-% ps -e f
-16143 ? Sl 3:00 bazel(src-johndoe2) -server -Djava.library.path=...
-```
-
-This makes it easier to find out which server process belongs to a given
-workspace. (Beware that with certain other options to `ps`, Bazel server
-processes may be named just `java`.) Bazel servers can be stopped using the
-[shutdown](user-manual.html#shutdown) command.
-
-When running `bazel`, the client first checks that the server is the appropriate
-version; if not, the server is stopped and a new one started. This ensures that
-the use of a long-running server process doesn't interfere with proper
-versioning.
-
-
-<a id="bazelrc"></a>
-
-## `.bazelrc`, the Bazel configuration file
-
-Bazel accepts many options. Some options are varied frequently (for example,
-`--subcommands`) while others stay the same across several builds (such as
-`--package_path`). To avoid specifying these unchanged options for every build
-(and other commands), you can specify options in a configuration file.
-
-### Where are the `.bazelrc` files?
-Bazel looks for optional configuration files in the following locations,
-in the order shown below. The options are interpreted in this order, so
-options in later files can override a value from an earlier file if a
-conflict arises. All options that control which of these files are loaded are
-startup options, which means they must occur after `bazel` and
-before the command (`build`, `test`, etc).
-
-1. **The system RC file**, unless `--nosystem_rc` is present.
-
- Path:
-
- - On Linux/macOS/Unixes: `/etc/bazel.bazelrc`
- - On Windows: `%ProgramData%\bazel.bazelrc`
-
- It is not an error if this file does not exist.
-
- If another system-specified location is required, you must build a custom
- Bazel binary, overriding the `BAZEL_SYSTEM_BAZELRC_PATH` value in
- [`//src/main/cpp:option_processor`](https://github.com/bazelbuild/bazel/blob/0.28.0/src/main/cpp/BUILD#L141).
- The system-specified location may contain environment variable references,
- such as `${VAR_NAME}` on Unix or `%VAR_NAME%` on Windows.
-
-2. **The workspace RC file**, unless `--noworkspace_rc` is present.
-
- Path: `.bazelrc` in your workspace directory (next to the main
- `WORKSPACE` file).
-
- It is not an error if this file does not exist.
-
-3. **The home RC file**, unless `--nohome_rc` is present.
-
- Path:
-
- - On Linux/macOS/Unixes: `$HOME/.bazelrc`
- - On Windows: `%USERPROFILE%\.bazelrc` if exists, or `%HOME%/.bazelrc`
-
- It is not an error if this file does not exist.
-
-4. **The user-specified RC file**, if specified with
- <code>--bazelrc=<var>file</var></code>
-
- This flag is optional but can also be specified multiple times.
-
- `/dev/null` indicates that all further `--bazelrc`s will be ignored, which
- is useful to disable the search for a user rc file, e.g. in release builds.
-
- For example:
- ```
- --bazelrc=x.rc --bazelrc=y.rc --bazelrc=/dev/null --bazelrc=z.rc
- ```
- 1. `x.rc` and `y.rc` are read.
- 2. `z.rc` is ignored due to the prior `/dev/null`.
-
-In addition to this optional configuration file, Bazel looks for a global rc
-file. For more details, see the [global bazelrc section](#global_bazelrc).
-
-
-### `.bazelrc` syntax and semantics
-
-Like all UNIX "rc" files, the `.bazelrc` file is a text file with a line-based
-grammar. Empty lines and lines starting with `#` (comments) are ignored. Each
-line contains a sequence of words, which are tokenized according to the same
-rules as the Bourne shell.
-
-#### Imports
-
-Lines that start with `import` or `try-import` are special: use these to load
-other "rc" files. To specify a path that is relative to the workspace root,
-write `import %workspace%/path/to/bazelrc`.
-
-The difference between `import` and `try-import` is that Bazel fails if the
-`import`'ed file is missing (or can't be read), but not so for a `try-import`'ed
-file.
-
-Import precedence:
-
-- Options in the imported file take precedence over options specified before
- the import statement.
-- Options specified after the import statement take precedence over the
- options in the imported file.
-- Options in files imported later take precedence over files imported earlier.
-
-#### Option defaults
-
-Most lines of a bazelrc define default option values. The first word on each
-line specifies when these defaults are applied:
-
-- `startup`: startup options, which go before the command, and are described
- in `bazel help startup_options`.
-- `common`: options that apply to all Bazel commands.
-- _`command`_: Bazel command, such as `build` or `query` to which the options
- apply. These options also apply to all commands that inherit from the
- specified command. (For example, `test` inherits from `build`.)
-
-Each of these lines may be used more than once and the arguments that follow the
-first word are combined as if they had appeared on a single line. (Users of CVS,
-another tool with a "Swiss army knife" command-line interface, will find the
-syntax similar to that of `.cvsrc`.) For example, the lines:
-
-```
-build --test_tmpdir=/tmp/foo --verbose_failures
-build --test_tmpdir=/tmp/bar
-```
-
-are combined as:
-
-```
-build --test_tmpdir=/tmp/foo --verbose_failures --test_tmpdir=/tmp/bar
-```
-
-so the effective flags are `--verbose_failures` and `--test_tmpdir=/tmp/bar`.
-
-Option precedence:
-
-- Options on the command line always take precedence over those in rc files.
- For example, if a rc file says `build -c opt` but the command line flag is
- `-c dbg`, the command line flag takes precedence.
-- Within the rc file, precedence is governed by specificity: lines for a more
- specific command take precedence over lines for a less specific command.
-
- Specificity is defined by inheritance. Some commands inherit options from
- other commands, making the inheriting command more specific than the base
- command. For example `test` inherits from the `build` command, so all `bazel
- build` flags are valid for `bazel test`, and all `build` lines apply also to
- `bazel test` unless there's a `test` line for the same option. If the rc
- file says:
-
- ```
- test -c dbg --test_env=PATH
- build -c opt --verbose_failures
- ```
-
- then `bazel build //foo` will use `-c opt --verbose_failures`, and `bazel
- test //foo` will use `--verbose_failures -c dbg --test_env=PATH`.
-
- The inheritance (specificity) graph is:
-
- * Every command inherits from `common`
- * The following commands inherit from (and are more specific than)
- `build`: `test`, `run`, `clean`, `mobile-install`, `info`,
- `print_action`, `config`, `cquery`, and `aquery`
- * `coverage` inherits from `test`
-
-- Two lines specifying options for the same command at equal specificity are
- parsed in the order in which they appear within the file.
-
-- Because this precedence rule does not match the file order, it helps
- readability if you follow the precedence order within rc files: start with
- `common` options at the top, and end with the most-specific commands at the
- bottom of the file. This way, the order in which the options are read is the
- same as the order in which they are applied, which is more intuitive.
-
-The arguments specified on a line of an rc file may include arguments that are
-not options, such as the names of build targets, and so on. These, like the
-options specified in the same files, have lower precedence than their siblings
-on the command line, and are always prepended to the explicit list of non-
-option arguments.
-
-#### `--config`
-
-In addition to setting option defaults, the rc file can be used to group options
-and provide a shorthand for common groupings. This is done by adding a `:name`
-suffix to the command. These options are ignored by default, but will be
-included when the option <code>--config=<var>name</var></code> is present,
-either on the command line or in a `.bazelrc` file, recursively, even inside of
-another config definition. The options specified by `command:name` will only be
-expanded for applicable commands, in the precedence order described above.
-
-Note that configs can be defined in any `.bazelrc` file, and that all lines of
-the form `command:name` (for applicable commands) will be expanded, across the
-different rc files. In order to avoid name conflicts, we suggest that configs
-defined in personal rc files start with an underscore (`_`) to avoid
-unintentional name sharing.
-
-`--config=foo` expands to the options defined in
-[the rc files](#where-are-the-bazelrc-files) "in-place" so that the options
-specified for the config have the same precedence that the `--config=foo` option
-had.
-
-This syntax does not extend to the use of `startup` to set
-[startup options](#option-defaults), e.g. setting
-`startup:config-name --some_startup_option` in the .bazelrc will be ignored.
-
-#### Example
-
-Here's an example `~/.bazelrc` file:
-
-```
-# Bob's Bazel option defaults
-
-startup --host_jvm_args=-XX:-UseParallelGC
-import /home/bobs_project/bazelrc
-build --show_timestamps --keep_going --jobs 600
-build --color=yes
-query --keep_going
-
-# Definition of --config=memcheck
-build:memcheck --strip=never --test_timeout=3600
-```
-
-
-<a id="startup files"></a>
-### Other files governing Bazel's behavior
-
-#### `.bazelignore`
-
-You can specify directories within the workspace
-that you want Bazel to ignore, such as related projects
-that use other build systems. Place a file called
-`.bazelignore` at the root of the workspace
-and add the directories you want Bazel to ignore, one per
-line. Entries are relative to the workspace root.
-
-<a id="global_bazelrc"></a>
-
-### The global bazelrc file
-
-In addition to your personal `.bazelrc` file, Bazel reads global bazelrc
-files in this order: `$workspace/tools/bazel.rc`, `.bazelrc` next to the
-Bazel binary, and `/etc/bazel.bazelrc`. (It's fine if any are missing.)
-
-You can make Bazel ignore the global bazelrcs by passing the
-`--nomaster_bazelrc` startup option.
-
-
-<a id="scripting"></a>
-
-## Calling Bazel from scripts
-
-Bazel can be called from scripts in order to perform a build, run tests or query
-the dependency graph. Bazel has been designed to enable effective scripting, but
-this section lists some details to bear in mind to make your scripts more
-robust.
-
-
-### Choosing the output base
-
-The `--output_base` option controls where the Bazel process should write the
-outputs of a build to, as well as various working files used internally by
-Bazel, one of which is a lock that guards against concurrent mutation of the
-output base by multiple Bazel processes.
-
-Choosing the correct output base directory for your script depends on several
-factors. If you need to put the build outputs in a specific location, this will
-dictate the output base you need to use. If you are making a "read only" call to
-Bazel (e.g. `bazel query`), the locking factors will be more important. In
-particular, if you need to run multiple instances of your script concurrently,
-you will need to give each one a different (or random) output base.
-
-If you use the default output base value, you will be contending for the same
-lock used by the user's interactive Bazel commands. If the user issues
-long-running commands such as builds, your script will have to wait for those
-commands to complete before it can continue.
-
-### Notes about server mode
-
-By default, Bazel uses a long-running [server process](#client/server) as an
-optimization. When running Bazel in a script, don't forget to call `shutdown`
-when you're finished with the server, or, specify `--max_idle_secs=5` so that
-idle servers shut themselves down promptly.
-
-### What exit code will I get?
-
-Bazel attempts to differentiate failures due to the source code under
-consideration from external errors that prevent Bazel from executing properly.
-Bazel execution can result in following exit codes:
-
-**Exit Codes common to all commands:**
-
-- `0` - Success
-- `2` - Command Line Problem, Bad or Illegal flags or command combination, or
- Bad Environment Variables. Your command line must be modified.
-- `8` - Build Interrupted but we terminated with an orderly shutdown.
-- `32` - External Environment Failure not on this machine.
-
-- `33` - Bazel ran out of memory and crashed. You need to modify your command line.
-- `34` - Reserved for Google-internal use.
-- `35` - Reserved for Google-internal use.
-- `36` - Local Environmental Issue, suspected permanent.
-- `37` - Unhandled Exception / Internal Bazel Error.
-- `38` - Reserved for Google-internal use.
-- `41-44` - Reserved for Google-internal use.
-- `45` - Error publishing results to the Build Event Service.
-- `47` - Reserved for Google-internal use.
-
-**Return codes for commands `bazel build`, `bazel test`:**
-
-- `1` - Build failed.
-- `3` - Build OK, but some tests failed or timed out.
-- `4` - Build successful but no tests were found even though testing was
- requested.
-
-
-**For `bazel run`:**
-
-- `1` - Build failed.
-- If the build succeeds but the executed subprocess returns a non-zero exit
- code it will be the exit code of the command as well.
-
-**For `bazel query`:**
-
-- `3` - Partial success, but the query encountered 1 or more errors in the
- input BUILD file set and therefore the results of the operation are not 100%
- reliable. This is likely due to a `--keep_going` option on the command line.
-- `7` - Command failure.
-
-Future Bazel versions may add additional exit codes, replacing generic failure
-exit code `1` with a different non-zero value with a particular meaning.
-However, all non-zero exit values will always constitute an error.
-
-
-### Reading the .bazelrc file
-
-By default, Bazel reads the [`.bazelrc` file](#bazelrc) from the base
-workspace directory or the user's home directory. Whether or not this is
-desirable is a choice for your script; if your script needs to be perfectly
-hermetic (e.g. when doing release builds), you should disable reading the
-.bazelrc file by using the option `--bazelrc=/dev/null`. If you want to perform
-a build using the user's preferred settings, the default behavior is better.
-
-
-### Command log
-
-The Bazel output is also available in a command log file which you can find with
-the following command:
-
-```
-% bazel info command_log
-```
-
-The command log file contains the interleaved stdout and stderr streams of the
-most recent Bazel command. Note that running `bazel info` will overwrite the
-contents of this file, since it then becomes the most recent Bazel command.
-However, the location of the command log file will not change unless you change
-the setting of the `--output_base` or `--output_user_root` options.
-
-### Parsing output
-
-The Bazel output is quite easy to parse for many purposes. Two options that may
-be helpful for your script are `--noshow_progress` which suppresses progress
-messages, and <code>--show_result <var>n</var></code>, which controls whether or
-not "build up-to-date" messages are printed; these messages may be parsed to
-discover which targets were successfully built, and the location of the output
-files they created. Be sure to specify a very large value of _n_ if you rely on
-these messages.
-
-
-<a id="profiling"></a>
-
-## Troubleshooting performance by profiling
-
-See the [Performance Profiling](skylark/performance.md#performance-profiling) section.
-
diff --git a/site/docs/images/a_b_a_c.svg b/site/docs/images/a_b_a_c.svg
deleted file mode 100644
index d38be07..0000000
--- a/site/docs/images/a_b_a_c.svg
+++ /dev/null
@@ -1,42 +0,0 @@
-<?xml version="1.0" encoding="UTF-8" standalone="no"?>
-<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
-<!-- Generated by graphviz version 2.40.1 (20161225.0304)
- -->
-<!-- Title: G Pages: 1 -->
-<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="188pt" height="56pt" viewBox="0.00 0.00 188.00 55.76">
-<g id="graph0" class="graph" transform="scale(1 1) rotate(0) translate(4 51.757)">
-<title>G</title>
-<polygon fill="white" stroke="transparent" points="-4,4 -4,-51.757 184,-51.757 184,4 -4,4"/>
-<!-- a -->
-<g id="node1" class="node">
-<title>a</title>
-<ellipse fill="none" stroke="black" cx="18" cy="-29.757" rx="18" ry="18"/>
-<text text-anchor="middle" x="18" y="-26.057" font-family="Times,serif" font-size="14.00">a</text>
-</g>
-<!-- b -->
-<g id="node2" class="node">
-<title>b</title>
-<ellipse fill="none" stroke="black" cx="90" cy="-29.757" rx="18" ry="18"/>
-<text text-anchor="middle" x="90" y="-26.057" font-family="Times,serif" font-size="14.00">b</text>
-</g>
-<!-- a->b -->
-<g id="edge1" class="edge">
-<title>a->b</title>
-<path fill="none" stroke="black" d="M36.1686,-29.757C43.869,-29.757 53.0257,-29.757 61.5834,-29.757"/>
-<polygon fill="black" stroke="black" points="61.5868,-33.2571 71.5867,-29.757 61.5867,-26.2571 61.5868,-33.2571"/>
-</g>
-<!-- c -->
-<g id="node3" class="node">
-<title>c</title>
-<ellipse fill="none" stroke="black" cx="162" cy="-29.757" rx="18" ry="18"/>
-<text text-anchor="middle" x="162" y="-26.057" font-family="Times,serif" font-size="14.00">c</text>
-</g>
-<!-- a->c -->
-<g id="edge3" class="edge">
-<title>a->c</title>
-<path fill="none" stroke="black" d="M33.3269,-19.6799C43.7533,-13.4476 58.1264,-6.0321 72,-2.757 87.572,.919 92.428,.919 108,-2.757 118.2968,-5.1878 128.8688,-9.8992 137.8982,-14.7149"/>
-<polygon fill="black" stroke="black" points="136.2461,-17.8015 146.6731,-19.6799 139.6933,-11.7091 136.2461,-17.8015"/>
-</g>
-<!-- b->c -->
-</g>
-</svg>
diff --git a/site/docs/images/a_b_c.svg b/site/docs/images/a_b_c.svg
deleted file mode 100644
index acd948a..0000000
--- a/site/docs/images/a_b_c.svg
+++ /dev/null
@@ -1,41 +0,0 @@
-<?xml version="1.0" encoding="UTF-8" standalone="no"?>
-<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
-<!-- Generated by graphviz version 2.40.1 (20161225.0304)
- -->
-<!-- Title: G Pages: 1 -->
-<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="188pt" height="44pt" viewBox="0.00 0.00 188.00 44.00">
-<g id="graph0" class="graph" transform="scale(1 1) rotate(0) translate(4 40)">
-<title>G</title>
-<polygon fill="white" stroke="transparent" points="-4,4 -4,-40 184,-40 184,4 -4,4"/>
-<!-- a -->
-<g id="node1" class="node">
-<title>a</title>
-<ellipse fill="none" stroke="black" cx="18" cy="-18" rx="18" ry="18"/>
-<text text-anchor="middle" x="18" y="-14.3" font-family="Times,serif" font-size="14.00">a</text>
-</g>
-<!-- b -->
-<g id="node2" class="node">
-<title>b</title>
-<ellipse fill="none" stroke="black" cx="90" cy="-18" rx="18" ry="18"/>
-<text text-anchor="middle" x="90" y="-14.3" font-family="Times,serif" font-size="14.00">b</text>
-</g>
-<!-- a->b -->
-<g id="edge1" class="edge">
-<title>a->b</title>
-<path fill="none" stroke="black" d="M36.1686,-18C43.869,-18 53.0257,-18 61.5834,-18"/>
-<polygon fill="black" stroke="black" points="61.5868,-21.5001 71.5867,-18 61.5867,-14.5001 61.5868,-21.5001"/>
-</g>
-<!-- c -->
-<g id="node3" class="node">
-<title>c</title>
-<ellipse fill="none" stroke="black" cx="162" cy="-18" rx="18" ry="18"/>
-<text text-anchor="middle" x="162" y="-14.3" font-family="Times,serif" font-size="14.00">c</text>
-</g>
-<!-- b->c -->
-<g id="edge2" class="edge">
-<title>b->c</title>
-<path fill="none" stroke="black" d="M108.1686,-18C115.869,-18 125.0257,-18 133.5834,-18"/>
-<polygon fill="black" stroke="black" points="133.5868,-21.5001 143.5867,-18 133.5867,-14.5001 133.5868,-21.5001"/>
-</g>
-</g>
-</svg>
diff --git a/site/docs/images/a_b_c_ac.svg b/site/docs/images/a_b_c_ac.svg
deleted file mode 100644
index b099c53..0000000
--- a/site/docs/images/a_b_c_ac.svg
+++ /dev/null
@@ -1,47 +0,0 @@
-<?xml version="1.0" encoding="UTF-8" standalone="no"?>
-<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
-<!-- Generated by graphviz version 2.40.1 (20161225.0304)
- -->
-<!-- Title: G Pages: 1 -->
-<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="188pt" height="56pt" viewBox="0.00 0.00 188.00 55.76">
-<g id="graph0" class="graph" transform="scale(1 1) rotate(0) translate(4 51.757)">
-<title>G</title>
-<polygon fill="white" stroke="transparent" points="-4,4 -4,-51.757 184,-51.757 184,4 -4,4"/>
-<!-- a -->
-<g id="node1" class="node">
-<title>a</title>
-<ellipse fill="none" stroke="black" cx="18" cy="-29.757" rx="18" ry="18"/>
-<text text-anchor="middle" x="18" y="-26.057" font-family="Times,serif" font-size="14.00">a</text>
-</g>
-<!-- b -->
-<g id="node2" class="node">
-<title>b</title>
-<ellipse fill="none" stroke="black" cx="90" cy="-29.757" rx="18" ry="18"/>
-<text text-anchor="middle" x="90" y="-26.057" font-family="Times,serif" font-size="14.00">b</text>
-</g>
-<!-- a->b -->
-<g id="edge1" class="edge">
-<title>a->b</title>
-<path fill="none" stroke="black" d="M36.1686,-29.757C43.869,-29.757 53.0257,-29.757 61.5834,-29.757"/>
-<polygon fill="black" stroke="black" points="61.5868,-33.2571 71.5867,-29.757 61.5867,-26.2571 61.5868,-33.2571"/>
-</g>
-<!-- c -->
-<g id="node3" class="node">
-<title>c</title>
-<ellipse fill="none" stroke="black" cx="162" cy="-29.757" rx="18" ry="18"/>
-<text text-anchor="middle" x="162" y="-26.057" font-family="Times,serif" font-size="14.00">c</text>
-</g>
-<!-- a->c -->
-<g id="edge3" class="edge">
-<title>a->c</title>
-<path fill="none" stroke="black" d="M33.3269,-19.6799C43.7533,-13.4476 58.1264,-6.0321 72,-2.757 87.572,.919 92.428,.919 108,-2.757 118.2968,-5.1878 128.8688,-9.8992 137.8982,-14.7149"/>
-<polygon fill="black" stroke="black" points="136.2461,-17.8015 146.6731,-19.6799 139.6933,-11.7091 136.2461,-17.8015"/>
-</g>
-<!-- b->c -->
-<g id="edge2" class="edge">
-<title>b->c</title>
-<path fill="none" stroke="black" d="M108.1686,-29.757C115.869,-29.757 125.0257,-29.757 133.5834,-29.757"/>
-<polygon fill="black" stroke="black" points="133.5868,-33.2571 143.5867,-29.757 133.5867,-26.2571 133.5868,-33.2571"/>
-</g>
-</g>
-</svg>
diff --git a/site/docs/images/ab_c.svg b/site/docs/images/ab_c.svg
deleted file mode 100644
index bcc4563..0000000
--- a/site/docs/images/ab_c.svg
+++ /dev/null
@@ -1,36 +0,0 @@
-<?xml version="1.0" encoding="UTF-8" standalone="no"?>
-<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
-<!-- Generated by graphviz version 2.40.1 (20161225.0304)
- -->
-<!-- Title: G Pages: 1 -->
-<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="188pt" height="44pt" viewBox="0.00 0.00 188.00 44.00">
-<g id="graph0" class="graph" transform="scale(1 1) rotate(0) translate(4 40)">
-<title>G</title>
-<polygon fill="white" stroke="transparent" points="-4,4 -4,-40 184,-40 184,4 -4,4"/>
-<!-- a -->
-<g id="node1" class="node">
-<title>a</title>
-<ellipse fill="none" stroke="black" cx="18" cy="-18" rx="18" ry="18"/>
-<text text-anchor="middle" x="18" y="-14.3" font-family="Times,serif" font-size="14.00">a</text>
-</g>
-<!-- b -->
-<g id="node2" class="node">
-<title>b</title>
-<ellipse fill="none" stroke="black" cx="90" cy="-18" rx="18" ry="18"/>
-<text text-anchor="middle" x="90" y="-14.3" font-family="Times,serif" font-size="14.00">b</text>
-</g>
-<!-- a->b -->
-<g id="edge1" class="edge">
-<title>a->b</title>
-<path fill="none" stroke="black" d="M36.1686,-18C43.869,-18 53.0257,-18 61.5834,-18"/>
-<polygon fill="black" stroke="black" points="61.5868,-21.5001 71.5867,-18 61.5867,-14.5001 61.5868,-21.5001"/>
-</g>
-<!-- c -->
-<g id="node3" class="node">
-<title>c</title>
-<ellipse fill="none" stroke="black" cx="162" cy="-18" rx="18" ry="18"/>
-<text text-anchor="middle" x="162" y="-14.3" font-family="Times,serif" font-size="14.00">c</text>
-</g>
-<!-- b->c -->
-</g>
-</svg>
diff --git a/site/docs/images/allpaths.svg b/site/docs/images/allpaths.svg
deleted file mode 100644
index 47d0ee3..0000000
--- a/site/docs/images/allpaths.svg
+++ /dev/null
@@ -1,141 +0,0 @@
-<?xml version="1.0" encoding="UTF-8" standalone="no"?>
-<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
-<!-- Generated by graphviz version 2.40.1 (20161225.0304)
- -->
-<!-- Title: allpaths Pages: 1 -->
-<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="152pt" height="288pt" viewBox="0.00 0.00 152.33 288.00">
-<g id="graph0" class="graph" transform="scale(.8456 .8456) rotate(0) translate(4 336.5928)">
-<title>allpaths</title>
-<polygon fill="white" stroke="transparent" points="-4,4 -4,-336.5928 176.1482,-336.5928 176.1482,4 -4,4"/>
-<!-- n1 -->
-<g id="node1" class="node">
-<title>n1</title>
-<ellipse fill="none" stroke="black" cx="40" cy="-312.4446" rx="18" ry="18"/>
-</g>
-<!-- n2 -->
-<g id="node2" class="node">
-<title>n2</title>
-<ellipse fill="pink" stroke="black" cx="41" cy="-236.1482" rx="18" ry="18"/>
-</g>
-<!-- n1->n2 -->
-<g id="edge1" class="edge">
-<title>n1->n2</title>
-<path fill="none" stroke="black" d="M40.237,-294.3634C40.3532,-285.4965 40.4959,-274.6075 40.6264,-264.6554"/>
-<polygon fill="black" stroke="black" points="44.1298,-264.4091 40.7612,-254.364 37.1304,-264.3173 44.1298,-264.4091"/>
-</g>
-<!-- n3 -->
-<g id="node3" class="node">
-<title>n3</title>
-<ellipse fill="pink" stroke="black" cx="18" cy="-162" rx="18" ry="18"/>
-</g>
-<!-- n2->n3 -->
-<g id="edge2" class="edge">
-<title>n2->n3</title>
-<path fill="none" stroke="black" d="M35.6655,-218.9508C32.9275,-210.1237 29.5274,-199.1624 26.4435,-189.2204"/>
-<polygon fill="black" stroke="black" points="29.6908,-187.8752 23.3852,-179.3611 23.0051,-189.9491 29.6908,-187.8752"/>
-</g>
-<!-- n10 -->
-<g id="node10" class="node">
-<title>n10</title>
-<ellipse fill="pink" stroke="black" cx="23" cy="-90" rx="18" ry="18"/>
-</g>
-<!-- n2->n10 -->
-<g id="edge9" class="edge">
-<title>n2->n10</title>
-<path fill="none" stroke="black" d="M44.2389,-218.297C47.0603,-199.5961 49.9868,-169.4573 45,-144 43.1054,-134.328 39.4698,-124.2023 35.6916,-115.3671"/>
-<polygon fill="black" stroke="black" points="38.7737,-113.6893 31.4504,-106.033 32.4008,-116.5851 38.7737,-113.6893"/>
-</g>
-<!-- n3->n10 -->
-<g id="edge10" class="edge">
-<title>n3->n10</title>
-<path fill="none" stroke="black" d="M19.2617,-143.8314C19.7965,-136.131 20.4323,-126.9743 21.0266,-118.4166"/>
-<polygon fill="black" stroke="black" points="24.52,-118.6317 21.7213,-108.4133 17.5368,-118.1467 24.52,-118.6317"/>
-</g>
-<!-- n4 -->
-<g id="node4" class="node">
-<title>n4</title>
-<ellipse fill="pink" stroke="black" cx="74" cy="-18" rx="18" ry="18"/>
-<text text-anchor="middle" x="74" y="-14.3" font-family="Times,serif" font-size="14.00">E</text>
-</g>
-<!-- n5 -->
-<g id="node5" class="node">
-<title>n5</title>
-<ellipse fill="pink" stroke="black" cx="96" cy="-236.1482" rx="18" ry="18"/>
-</g>
-<!-- n6 -->
-<g id="node6" class="node">
-<title>n6</title>
-<ellipse fill="pink" stroke="black" cx="114" cy="-162" rx="18" ry="18"/>
-</g>
-<!-- n5->n6 -->
-<g id="edge5" class="edge">
-<title>n5->n6</title>
-<path fill="none" stroke="black" d="M100.2657,-218.5761C102.3577,-209.9588 104.9266,-199.3765 107.2745,-189.7046"/>
-<polygon fill="black" stroke="black" points="110.7446,-190.2464 109.7025,-179.7029 103.9421,-188.595 110.7446,-190.2464"/>
-</g>
-<!-- n6->n4 -->
-<g id="edge6" class="edge">
-<title>n6->n4</title>
-<path fill="none" stroke="black" d="M106.6597,-145.2221C102.2549,-134.6847 96.7901,-120.7254 93,-108 86.8937,-87.4979 81.9754,-63.8091 78.6739,-45.8822"/>
-<polygon fill="black" stroke="black" points="82.0777,-45.033 76.8756,-35.8032 75.1866,-46.2626 82.0777,-45.033"/>
-</g>
-<!-- n9 -->
-<g id="node9" class="node">
-<title>n9</title>
-<ellipse fill="none" stroke="black" cx="120" cy="-90" rx="18" ry="18"/>
-</g>
-<!-- n6->n9 -->
-<g id="edge8" class="edge">
-<title>n6->n9</title>
-<path fill="none" stroke="black" d="M115.5141,-143.8314C116.1558,-136.131 116.9188,-126.9743 117.6319,-118.4166"/>
-<polygon fill="black" stroke="black" points="121.1229,-118.6694 118.4656,-108.4133 114.1471,-118.088 121.1229,-118.6694"/>
-</g>
-<!-- n7 -->
-<g id="node7" class="node">
-<title>n7</title>
-<ellipse fill="pink" stroke="black" cx="96" cy="-312.4446" rx="20.2975" ry="20.2975"/>
-<text text-anchor="middle" x="96" y="-308.7446" font-family="Times,serif" font-size="14.00">S1</text>
-</g>
-<!-- n7->n2 -->
-<g id="edge4" class="edge">
-<title>n7->n2</title>
-<path fill="none" stroke="black" d="M84.0658,-295.8894C76.3372,-285.1683 66.1629,-271.0544 57.6441,-259.2371"/>
-<polygon fill="black" stroke="black" points="60.4794,-257.1848 51.7924,-251.1195 54.801,-261.2782 60.4794,-257.1848"/>
-</g>
-<!-- n7->n5 -->
-<g id="edge3" class="edge">
-<title>n7->n5</title>
-<path fill="none" stroke="black" d="M96,-291.9986C96,-283.5595 96,-273.6353 96,-264.5119"/>
-<polygon fill="black" stroke="black" points="99.5001,-264.3065 96,-254.3065 92.5001,-264.3065 99.5001,-264.3065"/>
-</g>
-<!-- n8 -->
-<g id="node8" class="node">
-<title>n8</title>
-<ellipse fill="pink" stroke="black" cx="152" cy="-236.1482" rx="20.2975" ry="20.2975"/>
-<text text-anchor="middle" x="152" y="-232.4482" font-family="Times,serif" font-size="14.00">S2</text>
-</g>
-<!-- n8->n6 -->
-<g id="edge7" class="edge">
-<title>n8->n6</title>
-<path fill="none" stroke="black" d="M142.8013,-218.199C138.0739,-208.9747 132.2319,-197.5753 127.0475,-187.4592"/>
-<polygon fill="black" stroke="black" points="130.012,-185.5695 122.3363,-178.2664 123.7824,-188.7621 130.012,-185.5695"/>
-</g>
-<!-- n10->n4 -->
-<g id="edge11" class="edge">
-<title>n10->n4</title>
-<path fill="none" stroke="black" d="M33.5672,-75.0816C40.4738,-65.3311 49.6369,-52.395 57.4935,-41.3032"/>
-<polygon fill="black" stroke="black" points="60.5222,-43.0827 63.4463,-32.8993 54.81,-39.0365 60.5222,-43.0827"/>
-</g>
-<!-- n11 -->
-<g id="node11" class="node">
-<title>n11</title>
-<ellipse fill="none" stroke="black" cx="20" cy="-18" rx="18" ry="18"/>
-</g>
-<!-- n10->n11 -->
-<g id="edge12" class="edge">
-<title>n10->n11</title>
-<path fill="none" stroke="black" d="M22.243,-71.8314C21.9221,-64.131 21.5406,-54.9743 21.184,-46.4166"/>
-<polygon fill="black" stroke="black" points="24.6806,-46.2589 20.7672,-36.4133 17.6867,-46.5503 24.6806,-46.2589"/>
-</g>
-</g>
-</svg>
diff --git a/site/docs/images/deps.svg b/site/docs/images/deps.svg
deleted file mode 100644
index 4354222..0000000
--- a/site/docs/images/deps.svg
+++ /dev/null
@@ -1,101 +0,0 @@
-<?xml version="1.0" encoding="UTF-8" standalone="no"?>
-<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
-<!-- Generated by graphviz version 2.40.1 (20161225.0304)
- -->
-<!-- Title: G1 Pages: 1 -->
-<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="157pt" height="246pt" viewBox="0.00 0.00 156.50 246.00">
-<g id="graph0" class="graph" transform="scale(1 1) rotate(0) translate(4 242)">
-<title>G1</title>
-<polygon fill="white" stroke="transparent" points="-4,4 -4,-242 152.5,-242 152.5,4 -4,4"/>
-<!-- r1 -->
-<g id="node1" class="node">
-<title>r1</title>
-<polygon fill="none" stroke="black" points="88.5,-173 34.5,-173 34.5,-137 88.5,-137 88.5,-173"/>
-<text text-anchor="middle" x="61.5" y="-152.5" font-family="Courier,monospace" font-weight="bold" font-size="10.00" fill="#006000">rule</text>
-</g>
-<!-- s1 -->
-<g id="node3" class="node">
-<title>s1</title>
-<ellipse fill="none" stroke="black" cx="14.5" cy="-223.5" rx="14.5" ry="14.5"/>
-<text text-anchor="middle" x="14.5" y="-221" font-family="Courier,monospace" font-weight="bold" font-size="10.00" fill="#006000">in</text>
-</g>
-<!-- r1->s1 -->
-<g id="edge1" class="edge">
-<title>r1->s1</title>
-<path fill="none" stroke="black" d="M48.9049,-173.3567C42.6407,-182.4865 35.0482,-193.5522 28.5909,-202.9632"/>
-<polygon fill="black" stroke="black" points="25.5999,-201.1362 22.8282,-211.3621 31.3719,-205.0965 25.5999,-201.1362"/>
-</g>
-<!-- s2 -->
-<g id="node4" class="node">
-<title>s2</title>
-<ellipse fill="none" stroke="black" cx="61.5" cy="-223.5" rx="14.5" ry="14.5"/>
-<text text-anchor="middle" x="61.5" y="-221" font-family="Courier,monospace" font-weight="bold" font-size="10.00" fill="#006000">in</text>
-</g>
-<!-- r1->s2 -->
-<g id="edge2" class="edge">
-<title>r1->s2</title>
-<path fill="none" stroke="black" d="M61.5,-173.3567C61.5,-181.1589 61.5,-190.3749 61.5,-198.7638"/>
-<polygon fill="black" stroke="black" points="58.0001,-198.7787 61.5,-208.7787 65.0001,-198.7788 58.0001,-198.7787"/>
-</g>
-<!-- s3 -->
-<g id="node5" class="node">
-<title>s3</title>
-<ellipse fill="none" stroke="black" cx="108.5" cy="-223.5" rx="14.5" ry="14.5"/>
-<text text-anchor="middle" x="108.5" y="-221" font-family="Courier,monospace" font-weight="bold" font-size="10.00" fill="#006000">in</text>
-</g>
-<!-- r1->s3 -->
-<g id="edge3" class="edge">
-<title>r1->s3</title>
-<path fill="none" stroke="black" d="M74.0951,-173.3567C80.3593,-182.4865 87.9518,-193.5522 94.4091,-202.9632"/>
-<polygon fill="black" stroke="black" points="91.6281,-205.0965 100.1718,-211.3621 97.4001,-201.1362 91.6281,-205.0965"/>
-</g>
-<!-- r2 -->
-<g id="node2" class="node">
-<title>r2</title>
-<polygon fill="none" stroke="black" points="148.5,-101 94.5,-101 94.5,-65 148.5,-65 148.5,-101"/>
-<text text-anchor="middle" x="121.5" y="-80.5" font-family="Courier,monospace" font-weight="bold" font-size="10.00" fill="#006000">rule</text>
-</g>
-<!-- r2->r1 -->
-<g id="edge5" class="edge">
-<title>r2->r1</title>
-<path fill="none" stroke="black" d="M106.3595,-101.1686C99.3783,-109.546 90.9609,-119.6469 83.3124,-128.8251"/>
-<polygon fill="black" stroke="black" points="80.5575,-126.6638 76.8444,-136.5867 85.9351,-131.1452 80.5575,-126.6638"/>
-</g>
-<!-- s4 -->
-<g id="node6" class="node">
-<title>s4</title>
-<ellipse fill="none" stroke="black" cx="121.5" cy="-155" rx="14.5" ry="14.5"/>
-<text text-anchor="middle" x="121.5" y="-152.5" font-family="Courier,monospace" font-weight="bold" font-size="10.00" fill="#006000">in</text>
-</g>
-<!-- r2->s4 -->
-<g id="edge4" class="edge">
-<title>r2->s4</title>
-<path fill="none" stroke="black" d="M121.5,-101.1686C121.5,-110.0069 121.5,-120.7634 121.5,-130.331"/>
-<polygon fill="black" stroke="black" points="118.0001,-130.4622 121.5,-140.4622 125.0001,-130.4623 118.0001,-130.4622"/>
-</g>
-<!-- o1 -->
-<g id="node7" class="node">
-<title>o1</title>
-<ellipse fill="none" stroke="black" cx="61.5" cy="-83" rx="14.5" ry="14.5"/>
-<text text-anchor="middle" x="61.5" y="-80.5" font-family="Courier,monospace" font-weight="bold" font-size="10.00" fill="#006000">out</text>
-</g>
-<!-- o1->r1 -->
-<g id="edge6" class="edge">
-<title>o1->r1</title>
-<path fill="none" stroke="black" d="M61.5,-97.5703C61.5,-105.8989 61.5,-116.6335 61.5,-126.564"/>
-<polygon fill="black" stroke="black" points="58.0001,-126.872 61.5,-136.872 65.0001,-126.8721 58.0001,-126.872"/>
-</g>
-<!-- o2 -->
-<g id="node8" class="node">
-<title>o2</title>
-<ellipse fill="none" stroke="black" cx="121.5" cy="-14.5" rx="14.5" ry="14.5"/>
-<text text-anchor="middle" x="121.5" y="-12" font-family="Courier,monospace" font-weight="bold" font-size="10.00" fill="#006000">out</text>
-</g>
-<!-- o2->r2 -->
-<g id="edge7" class="edge">
-<title>o2->r2</title>
-<path fill="none" stroke="black" d="M121.5,-29.0271C121.5,-36.5355 121.5,-45.9623 121.5,-54.8278"/>
-<polygon fill="black" stroke="black" points="118.0001,-54.8287 121.5,-64.8287 125.0001,-54.8287 118.0001,-54.8287"/>
-</g>
-</g>
-</svg>
diff --git a/site/docs/images/graph_ex_1.svg b/site/docs/images/graph_ex_1.svg
deleted file mode 100644
index dd7427f..0000000
--- a/site/docs/images/graph_ex_1.svg
+++ /dev/null
@@ -1,131 +0,0 @@
-<?xml version="1.0" encoding="UTF-8" standalone="no"?>
-<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
-<!-- Generated by graphviz version 2.40.1 (20161225.0304)
- -->
-<!-- Title: mygraph Pages: 1 -->
-<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="710pt" height="332pt" viewBox="0.00 0.00 709.50 332.00">
-<g id="graph0" class="graph" transform="scale(1 1) rotate(0) translate(4 328)">
-<title>mygraph</title>
-<polygon fill="white" stroke="transparent" points="-4,4 -4,-328 705.5,-328 705.5,4 -4,4"/>
-<!-- //net/proto_compiler:protocol-compiler -->
-<g id="node1" class="node">
-<title>//net/proto_compiler:protocol-compiler</title>
-<polygon fill="none" stroke="black" points="418,-324 188,-324 188,-288 418,-288 418,-324"/>
-<text text-anchor="middle" x="303" y="-302.3" font-family="Times,serif" font-size="14.00">//net/proto_compiler:protocol-compiler</text>
-</g>
-<!-- //net/proto_compiler:util -->
-<g id="node2" class="node">
-<title>//net/proto_compiler:util</title>
-<polygon fill="none" stroke="black" points="150,-180 0,-180 0,-144 150,-144 150,-180"/>
-<text text-anchor="middle" x="75" y="-158.3" font-family="Times,serif" font-size="14.00">//net/proto_compiler:util</text>
-</g>
-<!-- //net/proto_compiler:protocol-compiler->//net/proto_compiler:util -->
-<g id="edge1" class="edge">
-<title>//net/proto_compiler:protocol-compiler->//net/proto_compiler:util</title>
-<path fill="none" stroke="black" d="M239.5865,-287.9961C214.5565,-279.2804 186.2795,-267.3314 163,-252 136.491,-234.5418 111.7343,-207.9214 95.2752,-188.1561"/>
-<polygon fill="black" stroke="black" points="97.7805,-185.69 88.7485,-180.1516 92.3553,-190.1136 97.7805,-185.69"/>
-</g>
-<!-- //net/proto_compiler:protocol-compiler-lib -->
-<g id="node3" class="node">
-<title>//net/proto_compiler:protocol-compiler-lib</title>
-<polygon fill="none" stroke="black" points="701.5,-252 452.5,-252 452.5,-216 701.5,-216 701.5,-252"/>
-<text text-anchor="middle" x="577" y="-230.3" font-family="Times,serif" font-size="14.00">//net/proto_compiler:protocol-compiler-lib</text>
-</g>
-<!-- //net/proto_compiler:protocol-compiler->//net/proto_compiler:protocol-compiler-lib -->
-<g id="edge2" class="edge">
-<title>//net/proto_compiler:protocol-compiler->//net/proto_compiler:protocol-compiler-lib</title>
-<path fill="none" stroke="black" d="M371.7881,-287.9243C410.3041,-277.8033 458.4771,-265.1447 498.4684,-254.6361"/>
-<polygon fill="black" stroke="black" points="499.4015,-258.0098 508.1836,-252.0831 497.6224,-251.2396 499.4015,-258.0098"/>
-</g>
-<!-- //net/proto2/bridge/public:compiler_upgrader -->
-<g id="node4" class="node">
-<title>//net/proto2/bridge/public:compiler_upgrader</title>
-<polygon fill="none" stroke="black" points="434.5,-252 171.5,-252 171.5,-216 434.5,-216 434.5,-252"/>
-<text text-anchor="middle" x="303" y="-230.3" font-family="Times,serif" font-size="14.00">//net/proto2/bridge/public:compiler_upgrader</text>
-</g>
-<!-- //net/proto_compiler:protocol-compiler->//net/proto2/bridge/public:compiler_upgrader -->
-<g id="edge3" class="edge">
-<title>//net/proto_compiler:protocol-compiler->//net/proto2/bridge/public:compiler_upgrader</title>
-<path fill="none" stroke="black" d="M303,-287.8314C303,-280.131 303,-270.9743 303,-262.4166"/>
-<polygon fill="black" stroke="black" points="306.5001,-262.4132 303,-252.4133 299.5001,-262.4133 306.5001,-262.4132"/>
-</g>
-<!-- //net/proto_compiler:parser -->
-<g id="node6" class="node">
-<title>//net/proto_compiler:parser</title>
-<polygon fill="none" stroke="black" points="548.5,-108 383.5,-108 383.5,-72 548.5,-72 548.5,-108"/>
-<text text-anchor="middle" x="466" y="-86.3" font-family="Times,serif" font-size="14.00">//net/proto_compiler:parser</text>
-</g>
-<!-- //net/proto_compiler:util->//net/proto_compiler:parser -->
-<g id="edge9" class="edge">
-<title>//net/proto_compiler:util->//net/proto_compiler:parser</title>
-<path fill="none" stroke="black" d="M150.0776,-145.7681C153.0893,-145.1626 156.0723,-144.571 159,-144 230.8248,-129.9926 312.4276,-115.7165 373.4389,-105.3638"/>
-<polygon fill="black" stroke="black" points="374.1563,-108.7922 383.4317,-103.672 372.9878,-101.8905 374.1563,-108.7922"/>
-</g>
-<!-- //net/proto_compiler:proto-min-lib -->
-<g id="node5" class="node">
-<title>//net/proto_compiler:proto-min-lib</title>
-<polygon fill="none" stroke="black" points="700,-180 494,-180 494,-144 700,-144 700,-180"/>
-<text text-anchor="middle" x="597" y="-158.3" font-family="Times,serif" font-size="14.00">//net/proto_compiler:proto-min-lib</text>
-</g>
-<!-- //net/proto_compiler:protocol-compiler-lib->//net/proto_compiler:proto-min-lib -->
-<g id="edge11" class="edge">
-<title>//net/proto_compiler:protocol-compiler-lib->//net/proto_compiler:proto-min-lib</title>
-<path fill="none" stroke="black" d="M582.0468,-215.8314C584.2094,-208.0463 586.7853,-198.7729 589.1848,-190.1347"/>
-<polygon fill="black" stroke="black" points="592.581,-190.9852 591.8852,-180.4133 585.8364,-189.1117 592.581,-190.9852"/>
-</g>
-<!-- //net/proto_compiler:protocol-compiler-lib->//net/proto_compiler:parser -->
-<g id="edge10" class="edge">
-<title>//net/proto_compiler:protocol-compiler-lib->//net/proto_compiler:parser</title>
-<path fill="none" stroke="black" d="M529.6391,-215.7791C513.2165,-207.2457 496.1464,-195.4806 485,-180 472.1477,-162.1502 467.6252,-137.4553 466.1895,-118.448"/>
-<polygon fill="black" stroke="black" points="469.6758,-118.0892 465.6686,-108.2814 462.685,-118.4475 469.6758,-118.0892"/>
-</g>
-<!-- //net/proto2/bridge/internal:compiler_upgrader -->
-<g id="node8" class="node">
-<title>//net/proto2/bridge/internal:compiler_upgrader</title>
-<polygon fill="none" stroke="black" points="438,-180 168,-180 168,-144 438,-144 438,-180"/>
-<text text-anchor="middle" x="303" y="-158.3" font-family="Times,serif" font-size="14.00">//net/proto2/bridge/internal:compiler_upgrader</text>
-</g>
-<!-- //net/proto2/bridge/public:compiler_upgrader->//net/proto2/bridge/internal:compiler_upgrader -->
-<g id="edge12" class="edge">
-<title>//net/proto2/bridge/public:compiler_upgrader->//net/proto2/bridge/internal:compiler_upgrader</title>
-<path fill="none" stroke="black" d="M297.0476,-215.8314C296.2972,-208.131 296.0763,-198.9743 296.3849,-190.4166"/>
-<polygon fill="black" stroke="black" points="299.8792,-190.6161 297.024,-180.4133 292.8935,-190.1697 299.8792,-190.6161"/>
-</g>
-<!-- //net/proto_compiler:proto-min-lib->//net/proto_compiler:parser -->
-<g id="edge4" class="edge">
-<title>//net/proto_compiler:proto-min-lib->//net/proto_compiler:parser</title>
-<path fill="none" stroke="black" d="M563.9432,-143.8314C547.0323,-134.5368 526.2615,-123.1208 508.2059,-113.1971"/>
-<polygon fill="black" stroke="black" points="509.4957,-109.9122 499.0463,-108.1628 506.124,-116.0468 509.4957,-109.9122"/>
-</g>
-<!-- //util/regexp:regexp -->
-<g id="node7" class="node">
-<title>//util/regexp:regexp</title>
-<polygon fill="none" stroke="black" points="582.5,-36 459.5,-36 459.5,0 582.5,0 582.5,-36"/>
-<text text-anchor="middle" x="521" y="-14.3" font-family="Times,serif" font-size="14.00">//util/regexp:regexp</text>
-</g>
-<!-- //net/proto_compiler:proto-min-lib->//util/regexp:regexp -->
-<g id="edge5" class="edge">
-<title>//net/proto_compiler:proto-min-lib->//util/regexp:regexp</title>
-<path fill="none" stroke="black" d="M590.352,-143.9306C583.2667,-125.4072 571.2598,-95.9968 558,-72 552.9416,-62.8456 546.7384,-53.2943 540.8671,-44.8146"/>
-<polygon fill="black" stroke="black" points="543.5648,-42.5677 534.9308,-36.4273 537.8511,-46.6117 543.5648,-42.5677"/>
-</g>
-<!-- //net/proto_compiler:parser->//util/regexp:regexp -->
-<g id="edge8" class="edge">
-<title>//net/proto_compiler:parser->//util/regexp:regexp</title>
-<path fill="none" stroke="black" d="M479.8788,-71.8314C486.2136,-63.5386 493.8384,-53.557 500.7926,-44.4533"/>
-<polygon fill="black" stroke="black" points="503.6452,-46.4847 506.9343,-36.4133 498.0825,-42.2353 503.6452,-46.4847"/>
-</g>
-<!-- //net/proto2/bridge/internal:compiler_upgrader->//net/proto2/bridge/public:compiler_upgrader -->
-<g id="edge7" class="edge">
-<title>//net/proto2/bridge/internal:compiler_upgrader->//net/proto2/bridge/public:compiler_upgrader</title>
-<path fill="none" stroke="black" d="M308.976,-180.4133C309.7071,-188.0593 309.9203,-197.1084 309.6155,-205.5726"/>
-<polygon fill="black" stroke="black" points="306.1048,-205.6264 308.9524,-215.8314 313.0902,-206.078 306.1048,-205.6264"/>
-</g>
-<!-- //net/proto2/bridge/internal:compiler_upgrader->//net/proto_compiler:parser -->
-<g id="edge6" class="edge">
-<title>//net/proto2/bridge/internal:compiler_upgrader->//net/proto_compiler:parser</title>
-<path fill="none" stroke="black" d="M344.1318,-143.8314C365.9321,-134.2018 392.8878,-122.295 415.9004,-112.1299"/>
-<polygon fill="black" stroke="black" points="417.4308,-115.2802 425.164,-108.038 414.6024,-108.877 417.4308,-115.2802"/>
-</g>
-</g>
-</svg>
diff --git a/site/docs/images/out-ranked.svg b/site/docs/images/out-ranked.svg
deleted file mode 100644
index 07e9680..0000000
--- a/site/docs/images/out-ranked.svg
+++ /dev/null
@@ -1,71 +0,0 @@
-<?xml version="1.0" encoding="UTF-8" standalone="no"?>
-<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
-<!-- Generated by graphviz version 2.40.1 (20161225.0304)
- -->
-<!-- Title: mygraph Pages: 1 -->
-<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="139pt" height="260pt" viewBox="0.00 0.00 138.50 260.00">
-<g id="graph0" class="graph" transform="scale(1 1) rotate(0) translate(4 256)">
-<title>mygraph</title>
-<polygon fill="white" stroke="transparent" points="-4,4 -4,-256 134.5,-256 134.5,4 -4,4"/>
-<!-- //a:a -->
-<g id="node1" class="node">
-<title>//a:a</title>
-<polygon fill="none" stroke="black" points="55,-108 1,-108 1,-72 55,-72 55,-108"/>
-<text text-anchor="middle" x="28" y="-86.3" font-family="Times,serif" font-size="14.00">//a:a</text>
-</g>
-<!-- //a:a.cc -->
-<g id="node2" class="node">
-<title>//a:a.cc</title>
-<polygon fill="none" stroke="black" points="56,-36 0,-36 0,0 56,0 56,-36"/>
-<text text-anchor="middle" x="28" y="-14.3" font-family="Times,serif" font-size="14.00">//a:a.cc</text>
-</g>
-<!-- //a:a->//a:a.cc -->
-<g id="edge1" class="edge">
-<title>//a:a->//a:a.cc</title>
-<path fill="none" stroke="black" d="M28,-71.8314C28,-64.131 28,-54.9743 28,-46.4166"/>
-<polygon fill="black" stroke="black" points="31.5001,-46.4132 28,-36.4133 24.5001,-46.4133 31.5001,-46.4132"/>
-</g>
-<!-- //b:b -->
-<g id="node3" class="node">
-<title>//b:b</title>
-<polygon fill="none" stroke="black" points="110,-180 56,-180 56,-144 110,-144 110,-180"/>
-<text text-anchor="middle" x="83" y="-158.3" font-family="Times,serif" font-size="14.00">//b:b</text>
-</g>
-<!-- //b:b->//a:a -->
-<g id="edge2" class="edge">
-<title>//b:b->//a:a</title>
-<path fill="none" stroke="black" d="M69.1212,-143.8314C62.7864,-135.5386 55.1616,-125.557 48.2074,-116.4533"/>
-<polygon fill="black" stroke="black" points="50.9175,-114.2353 42.0657,-108.4133 45.3548,-118.4847 50.9175,-114.2353"/>
-</g>
-<!-- //b:b.cc -->
-<g id="node4" class="node">
-<title>//b:b.cc</title>
-<polygon fill="none" stroke="black" points="130.5,-108 73.5,-108 73.5,-72 130.5,-72 130.5,-108"/>
-<text text-anchor="middle" x="102" y="-86.3" font-family="Times,serif" font-size="14.00">//b:b.cc</text>
-</g>
-<!-- //b:b->//b:b.cc -->
-<g id="edge3" class="edge">
-<title>//b:b->//b:b.cc</title>
-<path fill="none" stroke="black" d="M87.7945,-143.8314C89.8489,-136.0463 92.296,-126.7729 94.5756,-118.1347"/>
-<polygon fill="black" stroke="black" points="97.9735,-118.9753 97.1409,-108.4133 91.2052,-117.1892 97.9735,-118.9753"/>
-</g>
-<!-- //c:c -->
-<g id="node5" class="node">
-<title>//c:c</title>
-<polygon fill="none" stroke="black" points="82,-252 28,-252 28,-216 82,-216 82,-252"/>
-<text text-anchor="middle" x="55" y="-230.3" font-family="Times,serif" font-size="14.00">//c:c</text>
-</g>
-<!-- //c:c->//a:a -->
-<g id="edge5" class="edge">
-<title>//c:c->//a:a</title>
-<path fill="none" stroke="black" d="M51.5804,-215.7623C46.9549,-191.0928 38.6612,-146.8598 33.245,-117.9731"/>
-<polygon fill="black" stroke="black" points="36.6748,-117.2733 31.3918,-108.0896 29.7947,-118.5634 36.6748,-117.2733"/>
-</g>
-<!-- //c:c->//b:b -->
-<g id="edge4" class="edge">
-<title>//c:c->//b:b</title>
-<path fill="none" stroke="black" d="M62.0656,-215.8314C65.126,-207.9617 68.7779,-198.5712 72.1682,-189.8533"/>
-<polygon fill="black" stroke="black" points="75.4768,-191.0019 75.8393,-180.4133 68.9527,-188.4647 75.4768,-191.0019"/>
-</g>
-</g>
-</svg>
diff --git a/site/docs/images/somepath1.svg b/site/docs/images/somepath1.svg
deleted file mode 100644
index 5e5f881..0000000
--- a/site/docs/images/somepath1.svg
+++ /dev/null
@@ -1,141 +0,0 @@
-<?xml version="1.0" encoding="UTF-8" standalone="no"?>
-<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
-<!-- Generated by graphviz version 2.40.1 (20161225.0304)
- -->
-<!-- Title: somepath1 Pages: 1 -->
-<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="152pt" height="288pt" viewBox="0.00 0.00 152.33 288.00">
-<g id="graph0" class="graph" transform="scale(.8456 .8456) rotate(0) translate(4 336.5928)">
-<title>somepath1</title>
-<polygon fill="white" stroke="transparent" points="-4,4 -4,-336.5928 176.1482,-336.5928 176.1482,4 -4,4"/>
-<!-- n1 -->
-<g id="node1" class="node">
-<title>n1</title>
-<ellipse fill="none" stroke="black" cx="40" cy="-312.4446" rx="18" ry="18"/>
-</g>
-<!-- n2 -->
-<g id="node2" class="node">
-<title>n2</title>
-<ellipse fill="pink" stroke="black" cx="41" cy="-236.1482" rx="18" ry="18"/>
-</g>
-<!-- n1->n2 -->
-<g id="edge1" class="edge">
-<title>n1->n2</title>
-<path fill="none" stroke="black" d="M40.237,-294.3634C40.3532,-285.4965 40.4959,-274.6075 40.6264,-264.6554"/>
-<polygon fill="black" stroke="black" points="44.1298,-264.4091 40.7612,-254.364 37.1304,-264.3173 44.1298,-264.4091"/>
-</g>
-<!-- n3 -->
-<g id="node3" class="node">
-<title>n3</title>
-<ellipse fill="pink" stroke="black" cx="18" cy="-162" rx="18" ry="18"/>
-</g>
-<!-- n2->n3 -->
-<g id="edge2" class="edge">
-<title>n2->n3</title>
-<path fill="none" stroke="black" d="M35.6655,-218.9508C32.9275,-210.1237 29.5274,-199.1624 26.4435,-189.2204"/>
-<polygon fill="black" stroke="black" points="29.6908,-187.8752 23.3852,-179.3611 23.0051,-189.9491 29.6908,-187.8752"/>
-</g>
-<!-- n10 -->
-<g id="node10" class="node">
-<title>n10</title>
-<ellipse fill="pink" stroke="black" cx="23" cy="-90" rx="18" ry="18"/>
-</g>
-<!-- n2->n10 -->
-<g id="edge9" class="edge">
-<title>n2->n10</title>
-<path fill="none" stroke="black" d="M44.2389,-218.297C47.0603,-199.5961 49.9868,-169.4573 45,-144 43.1054,-134.328 39.4698,-124.2023 35.6916,-115.3671"/>
-<polygon fill="black" stroke="black" points="38.7737,-113.6893 31.4504,-106.033 32.4008,-116.5851 38.7737,-113.6893"/>
-</g>
-<!-- n3->n10 -->
-<g id="edge10" class="edge">
-<title>n3->n10</title>
-<path fill="none" stroke="black" d="M19.2617,-143.8314C19.7965,-136.131 20.4323,-126.9743 21.0266,-118.4166"/>
-<polygon fill="black" stroke="black" points="24.52,-118.6317 21.7213,-108.4133 17.5368,-118.1467 24.52,-118.6317"/>
-</g>
-<!-- n4 -->
-<g id="node4" class="node">
-<title>n4</title>
-<ellipse fill="pink" stroke="black" cx="74" cy="-18" rx="18" ry="18"/>
-<text text-anchor="middle" x="74" y="-14.3" font-family="Times,serif" font-size="14.00">E</text>
-</g>
-<!-- n5 -->
-<g id="node5" class="node">
-<title>n5</title>
-<ellipse fill="none" stroke="black" cx="96" cy="-236.1482" rx="18" ry="18"/>
-</g>
-<!-- n6 -->
-<g id="node6" class="node">
-<title>n6</title>
-<ellipse fill="none" stroke="black" cx="114" cy="-162" rx="18" ry="18"/>
-</g>
-<!-- n5->n6 -->
-<g id="edge5" class="edge">
-<title>n5->n6</title>
-<path fill="none" stroke="black" d="M100.2657,-218.5761C102.3577,-209.9588 104.9266,-199.3765 107.2745,-189.7046"/>
-<polygon fill="black" stroke="black" points="110.7446,-190.2464 109.7025,-179.7029 103.9421,-188.595 110.7446,-190.2464"/>
-</g>
-<!-- n6->n4 -->
-<g id="edge6" class="edge">
-<title>n6->n4</title>
-<path fill="none" stroke="black" d="M106.6597,-145.2221C102.2549,-134.6847 96.7901,-120.7254 93,-108 86.8937,-87.4979 81.9754,-63.8091 78.6739,-45.8822"/>
-<polygon fill="black" stroke="black" points="82.0777,-45.033 76.8756,-35.8032 75.1866,-46.2626 82.0777,-45.033"/>
-</g>
-<!-- n9 -->
-<g id="node9" class="node">
-<title>n9</title>
-<ellipse fill="none" stroke="black" cx="120" cy="-90" rx="18" ry="18"/>
-</g>
-<!-- n6->n9 -->
-<g id="edge8" class="edge">
-<title>n6->n9</title>
-<path fill="none" stroke="black" d="M115.5141,-143.8314C116.1558,-136.131 116.9188,-126.9743 117.6319,-118.4166"/>
-<polygon fill="black" stroke="black" points="121.1229,-118.6694 118.4656,-108.4133 114.1471,-118.088 121.1229,-118.6694"/>
-</g>
-<!-- n7 -->
-<g id="node7" class="node">
-<title>n7</title>
-<ellipse fill="pink" stroke="black" cx="96" cy="-312.4446" rx="20.2975" ry="20.2975"/>
-<text text-anchor="middle" x="96" y="-308.7446" font-family="Times,serif" font-size="14.00">S1</text>
-</g>
-<!-- n7->n2 -->
-<g id="edge4" class="edge">
-<title>n7->n2</title>
-<path fill="none" stroke="black" d="M84.0658,-295.8894C76.3372,-285.1683 66.1629,-271.0544 57.6441,-259.2371"/>
-<polygon fill="black" stroke="black" points="60.4794,-257.1848 51.7924,-251.1195 54.801,-261.2782 60.4794,-257.1848"/>
-</g>
-<!-- n7->n5 -->
-<g id="edge3" class="edge">
-<title>n7->n5</title>
-<path fill="none" stroke="black" d="M96,-291.9986C96,-283.5595 96,-273.6353 96,-264.5119"/>
-<polygon fill="black" stroke="black" points="99.5001,-264.3065 96,-254.3065 92.5001,-264.3065 99.5001,-264.3065"/>
-</g>
-<!-- n8 -->
-<g id="node8" class="node">
-<title>n8</title>
-<ellipse fill="none" stroke="black" cx="152" cy="-236.1482" rx="20.2975" ry="20.2975"/>
-<text text-anchor="middle" x="152" y="-232.4482" font-family="Times,serif" font-size="14.00">S2</text>
-</g>
-<!-- n8->n6 -->
-<g id="edge7" class="edge">
-<title>n8->n6</title>
-<path fill="none" stroke="black" d="M142.8013,-218.199C138.0739,-208.9747 132.2319,-197.5753 127.0475,-187.4592"/>
-<polygon fill="black" stroke="black" points="130.012,-185.5695 122.3363,-178.2664 123.7824,-188.7621 130.012,-185.5695"/>
-</g>
-<!-- n10->n4 -->
-<g id="edge11" class="edge">
-<title>n10->n4</title>
-<path fill="none" stroke="black" d="M33.5672,-75.0816C40.4738,-65.3311 49.6369,-52.395 57.4935,-41.3032"/>
-<polygon fill="black" stroke="black" points="60.5222,-43.0827 63.4463,-32.8993 54.81,-39.0365 60.5222,-43.0827"/>
-</g>
-<!-- n11 -->
-<g id="node11" class="node">
-<title>n11</title>
-<ellipse fill="none" stroke="black" cx="20" cy="-18" rx="18" ry="18"/>
-</g>
-<!-- n10->n11 -->
-<g id="edge12" class="edge">
-<title>n10->n11</title>
-<path fill="none" stroke="black" d="M22.243,-71.8314C21.9221,-64.131 21.5406,-54.9743 21.184,-46.4166"/>
-<polygon fill="black" stroke="black" points="24.6806,-46.2589 20.7672,-36.4133 17.6867,-46.5503 24.6806,-46.2589"/>
-</g>
-</g>
-</svg>
diff --git a/site/docs/images/somepath2.svg b/site/docs/images/somepath2.svg
deleted file mode 100644
index 911f2c9..0000000
--- a/site/docs/images/somepath2.svg
+++ /dev/null
@@ -1,141 +0,0 @@
-<?xml version="1.0" encoding="UTF-8" standalone="no"?>
-<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
-<!-- Generated by graphviz version 2.40.1 (20161225.0304)
- -->
-<!-- Title: somepath2 Pages: 1 -->
-<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="152pt" height="288pt" viewBox="0.00 0.00 152.33 288.00">
-<g id="graph0" class="graph" transform="scale(.8456 .8456) rotate(0) translate(4 336.5928)">
-<title>somepath2</title>
-<polygon fill="white" stroke="transparent" points="-4,4 -4,-336.5928 176.1482,-336.5928 176.1482,4 -4,4"/>
-<!-- n1 -->
-<g id="node1" class="node">
-<title>n1</title>
-<ellipse fill="none" stroke="black" cx="40" cy="-312.4446" rx="18" ry="18"/>
-</g>
-<!-- n2 -->
-<g id="node2" class="node">
-<title>n2</title>
-<ellipse fill="none" stroke="black" cx="41" cy="-236.1482" rx="18" ry="18"/>
-</g>
-<!-- n1->n2 -->
-<g id="edge1" class="edge">
-<title>n1->n2</title>
-<path fill="none" stroke="black" d="M40.237,-294.3634C40.3532,-285.4965 40.4959,-274.6075 40.6264,-264.6554"/>
-<polygon fill="black" stroke="black" points="44.1298,-264.4091 40.7612,-254.364 37.1304,-264.3173 44.1298,-264.4091"/>
-</g>
-<!-- n3 -->
-<g id="node3" class="node">
-<title>n3</title>
-<ellipse fill="none" stroke="black" cx="18" cy="-162" rx="18" ry="18"/>
-</g>
-<!-- n2->n3 -->
-<g id="edge2" class="edge">
-<title>n2->n3</title>
-<path fill="none" stroke="black" d="M35.6655,-218.9508C32.9275,-210.1237 29.5274,-199.1624 26.4435,-189.2204"/>
-<polygon fill="black" stroke="black" points="29.6908,-187.8752 23.3852,-179.3611 23.0051,-189.9491 29.6908,-187.8752"/>
-</g>
-<!-- n10 -->
-<g id="node10" class="node">
-<title>n10</title>
-<ellipse fill="none" stroke="black" cx="23" cy="-90" rx="18" ry="18"/>
-</g>
-<!-- n2->n10 -->
-<g id="edge9" class="edge">
-<title>n2->n10</title>
-<path fill="none" stroke="black" d="M44.2389,-218.297C47.0603,-199.5961 49.9868,-169.4573 45,-144 43.1054,-134.328 39.4698,-124.2023 35.6916,-115.3671"/>
-<polygon fill="black" stroke="black" points="38.7737,-113.6893 31.4504,-106.033 32.4008,-116.5851 38.7737,-113.6893"/>
-</g>
-<!-- n3->n10 -->
-<g id="edge10" class="edge">
-<title>n3->n10</title>
-<path fill="none" stroke="black" d="M19.2617,-143.8314C19.7965,-136.131 20.4323,-126.9743 21.0266,-118.4166"/>
-<polygon fill="black" stroke="black" points="24.52,-118.6317 21.7213,-108.4133 17.5368,-118.1467 24.52,-118.6317"/>
-</g>
-<!-- n4 -->
-<g id="node4" class="node">
-<title>n4</title>
-<ellipse fill="pink" stroke="black" cx="74" cy="-18" rx="18" ry="18"/>
-<text text-anchor="middle" x="74" y="-14.3" font-family="Times,serif" font-size="14.00">E</text>
-</g>
-<!-- n5 -->
-<g id="node5" class="node">
-<title>n5</title>
-<ellipse fill="none" stroke="black" cx="96" cy="-236.1482" rx="18" ry="18"/>
-</g>
-<!-- n6 -->
-<g id="node6" class="node">
-<title>n6</title>
-<ellipse fill="pink" stroke="black" cx="114" cy="-162" rx="18" ry="18"/>
-</g>
-<!-- n5->n6 -->
-<g id="edge5" class="edge">
-<title>n5->n6</title>
-<path fill="none" stroke="black" d="M100.2657,-218.5761C102.3577,-209.9588 104.9266,-199.3765 107.2745,-189.7046"/>
-<polygon fill="black" stroke="black" points="110.7446,-190.2464 109.7025,-179.7029 103.9421,-188.595 110.7446,-190.2464"/>
-</g>
-<!-- n6->n4 -->
-<g id="edge6" class="edge">
-<title>n6->n4</title>
-<path fill="none" stroke="black" d="M106.6597,-145.2221C102.2549,-134.6847 96.7901,-120.7254 93,-108 86.8937,-87.4979 81.9754,-63.8091 78.6739,-45.8822"/>
-<polygon fill="black" stroke="black" points="82.0777,-45.033 76.8756,-35.8032 75.1866,-46.2626 82.0777,-45.033"/>
-</g>
-<!-- n9 -->
-<g id="node9" class="node">
-<title>n9</title>
-<ellipse fill="none" stroke="black" cx="120" cy="-90" rx="18" ry="18"/>
-</g>
-<!-- n6->n9 -->
-<g id="edge8" class="edge">
-<title>n6->n9</title>
-<path fill="none" stroke="black" d="M115.5141,-143.8314C116.1558,-136.131 116.9188,-126.9743 117.6319,-118.4166"/>
-<polygon fill="black" stroke="black" points="121.1229,-118.6694 118.4656,-108.4133 114.1471,-118.088 121.1229,-118.6694"/>
-</g>
-<!-- n7 -->
-<g id="node7" class="node">
-<title>n7</title>
-<ellipse fill="none" stroke="black" cx="96" cy="-312.4446" rx="20.2975" ry="20.2975"/>
-<text text-anchor="middle" x="96" y="-308.7446" font-family="Times,serif" font-size="14.00">S1</text>
-</g>
-<!-- n7->n2 -->
-<g id="edge4" class="edge">
-<title>n7->n2</title>
-<path fill="none" stroke="black" d="M84.0658,-295.8894C76.3372,-285.1683 66.1629,-271.0544 57.6441,-259.2371"/>
-<polygon fill="black" stroke="black" points="60.4794,-257.1848 51.7924,-251.1195 54.801,-261.2782 60.4794,-257.1848"/>
-</g>
-<!-- n7->n5 -->
-<g id="edge3" class="edge">
-<title>n7->n5</title>
-<path fill="none" stroke="black" d="M96,-291.9986C96,-283.5595 96,-273.6353 96,-264.5119"/>
-<polygon fill="black" stroke="black" points="99.5001,-264.3065 96,-254.3065 92.5001,-264.3065 99.5001,-264.3065"/>
-</g>
-<!-- n8 -->
-<g id="node8" class="node">
-<title>n8</title>
-<ellipse fill="pink" stroke="black" cx="152" cy="-236.1482" rx="20.2975" ry="20.2975"/>
-<text text-anchor="middle" x="152" y="-232.4482" font-family="Times,serif" font-size="14.00">S2</text>
-</g>
-<!-- n8->n6 -->
-<g id="edge7" class="edge">
-<title>n8->n6</title>
-<path fill="none" stroke="black" d="M142.8013,-218.199C138.0739,-208.9747 132.2319,-197.5753 127.0475,-187.4592"/>
-<polygon fill="black" stroke="black" points="130.012,-185.5695 122.3363,-178.2664 123.7824,-188.7621 130.012,-185.5695"/>
-</g>
-<!-- n10->n4 -->
-<g id="edge11" class="edge">
-<title>n10->n4</title>
-<path fill="none" stroke="black" d="M33.5672,-75.0816C40.4738,-65.3311 49.6369,-52.395 57.4935,-41.3032"/>
-<polygon fill="black" stroke="black" points="60.5222,-43.0827 63.4463,-32.8993 54.81,-39.0365 60.5222,-43.0827"/>
-</g>
-<!-- n11 -->
-<g id="node11" class="node">
-<title>n11</title>
-<ellipse fill="none" stroke="black" cx="20" cy="-18" rx="18" ry="18"/>
-</g>
-<!-- n10->n11 -->
-<g id="edge12" class="edge">
-<title>n10->n11</title>
-<path fill="none" stroke="black" d="M22.243,-71.8314C21.9221,-64.131 21.5406,-54.9743 21.184,-46.4166"/>
-<polygon fill="black" stroke="black" points="24.6806,-46.2589 20.7672,-36.4133 17.6867,-46.5503 24.6806,-46.2589"/>
-</g>
-</g>
-</svg>
diff --git a/site/docs/images/targets.svg b/site/docs/images/targets.svg
deleted file mode 100644
index 82f47e7..0000000
--- a/site/docs/images/targets.svg
+++ /dev/null
@@ -1,113 +0,0 @@
-<?xml version="1.0" encoding="UTF-8" standalone="no"?>
-<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
-<!-- Generated by graphviz version 2.40.1 (20161225.0304)
- -->
-<!-- Title: G1 Pages: 1 -->
-<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="498pt" height="188pt" viewBox="0.00 0.00 498.19 188.00">
-<g id="graph0" class="graph" transform="scale(1 1) rotate(0) translate(4 184)">
-<title>G1</title>
-<polygon fill="white" stroke="transparent" points="-4,4 -4,-184 494.1903,-184 494.1903,4 -4,4"/>
-<!-- Target -->
-<g id="node1" class="node">
-<title>Target</title>
-<ellipse fill="none" stroke="black" cx="319.1459" cy="-162" rx="33.5952" ry="18"/>
-<text text-anchor="middle" x="319.1459" y="-158.3" font-family="Times,serif" font-size="14.00">Target</text>
-</g>
-<!-- Rule -->
-<g id="node2" class="node">
-<title>Rule</title>
-<ellipse fill="none" stroke="black" cx="196.1459" cy="-90" rx="27.0966" ry="18"/>
-<text text-anchor="middle" x="196.1459" y="-86.3" font-family="Times,serif" font-size="14.00">Rule</text>
-</g>
-<!-- Target->Rule -->
-<g id="edge1" class="edge">
-<title>Target->Rule</title>
-<path fill="none" stroke="black" d="M296.2988,-148.6261C276.3598,-136.9545 247.3049,-119.9468 225.6191,-107.2526"/>
-<polygon fill="black" stroke="black" points="227.2227,-104.1357 216.8244,-102.1045 223.6864,-110.1769 227.2227,-104.1357"/>
-</g>
-<!-- File -->
-<g id="node6" class="node">
-<title>File</title>
-<ellipse fill="none" stroke="black" cx="319.1459" cy="-90" rx="27" ry="18"/>
-<text text-anchor="middle" x="319.1459" y="-86.3" font-family="Times,serif" font-size="14.00">File</text>
-</g>
-<!-- Target->File -->
-<g id="edge5" class="edge">
-<title>Target->File</title>
-<path fill="none" stroke="black" d="M319.1459,-143.8314C319.1459,-136.131 319.1459,-126.9743 319.1459,-118.4166"/>
-<polygon fill="black" stroke="black" points="322.646,-118.4132 319.1459,-108.4133 315.646,-118.4133 322.646,-118.4132"/>
-</g>
-<!-- Package group -->
-<g id="node9" class="node">
-<title>Package group</title>
-<ellipse fill="none" stroke="black" cx="427.1459" cy="-90" rx="63.0888" ry="18"/>
-<text text-anchor="middle" x="427.1459" y="-86.3" font-family="Times,serif" font-size="14.00">Package group</text>
-</g>
-<!-- Target->Package group -->
-<g id="edge8" class="edge">
-<title>Target->Package group</title>
-<path fill="none" stroke="black" d="M340.4832,-147.7751C355.5596,-137.7242 376.077,-124.0459 393.3637,-112.5215"/>
-<polygon fill="black" stroke="black" points="395.684,-115.1811 402.0631,-106.7219 391.8011,-109.3567 395.684,-115.1811"/>
-</g>
-<!-- cc_library -->
-<g id="node3" class="node">
-<title>cc_library</title>
-<ellipse fill="none" stroke="black" cx="46.1459" cy="-18" rx="46.2923" ry="18"/>
-<text text-anchor="middle" x="46.1459" y="-14.3" font-family="Times,serif" font-size="14.00">cc_library</text>
-</g>
-<!-- Rule->cc_library -->
-<g id="edge2" class="edge">
-<title>Rule->cc_library</title>
-<path fill="none" stroke="black" d="M174.0129,-79.3762C150.5101,-68.0948 112.9146,-50.049 84.5596,-36.4386"/>
-<polygon fill="black" stroke="black" points="85.8614,-33.1811 75.3316,-32.0091 82.8322,-39.4918 85.8614,-33.1811"/>
-</g>
-<!-- java_test -->
-<g id="node4" class="node">
-<title>java_test</title>
-<ellipse fill="none" stroke="black" cx="152.1459" cy="-18" rx="42.4939" ry="18"/>
-<text text-anchor="middle" x="152.1459" y="-14.3" font-family="Times,serif" font-size="14.00">java_test</text>
-</g>
-<!-- Rule->java_test -->
-<g id="edge3" class="edge">
-<title>Rule->java_test</title>
-<path fill="none" stroke="black" d="M185.9408,-73.3008C180.654,-64.6496 174.077,-53.8873 168.134,-44.1623"/>
-<polygon fill="black" stroke="black" points="171.1106,-42.3209 162.9095,-35.6132 165.1376,-45.9711 171.1106,-42.3209"/>
-</g>
-<!-- ... -->
-<g id="node5" class="node">
-<title>...</title>
-<ellipse fill="none" stroke="black" cx="239.1459" cy="-18" rx="27" ry="18"/>
-<text text-anchor="middle" x="239.1459" y="-14.3" font-family="Times,serif" font-size="14.00">...</text>
-</g>
-<!-- Rule->... -->
-<g id="edge4" class="edge">
-<title>Rule->...</title>
-<path fill="none" stroke="black" d="M206.3363,-72.937C211.5308,-64.2393 217.9565,-53.4799 223.7407,-43.7948"/>
-<polygon fill="black" stroke="black" points="226.9061,-45.3206 229.0287,-34.9405 220.8963,-41.7314 226.9061,-45.3206"/>
-</g>
-<!-- Source -->
-<g id="node7" class="node">
-<title>Source</title>
-<ellipse fill="none" stroke="black" cx="319.1459" cy="-18" rx="35.194" ry="18"/>
-<text text-anchor="middle" x="319.1459" y="-14.3" font-family="Times,serif" font-size="14.00">Source</text>
-</g>
-<!-- File->Source -->
-<g id="edge6" class="edge">
-<title>File->Source</title>
-<path fill="none" stroke="black" d="M319.1459,-71.8314C319.1459,-64.131 319.1459,-54.9743 319.1459,-46.4166"/>
-<polygon fill="black" stroke="black" points="322.646,-46.4132 319.1459,-36.4133 315.646,-46.4133 322.646,-46.4132"/>
-</g>
-<!-- Generated -->
-<g id="node8" class="node">
-<title>Generated</title>
-<ellipse fill="none" stroke="black" cx="419.1459" cy="-18" rx="46.5926" ry="18"/>
-<text text-anchor="middle" x="419.1459" y="-14.3" font-family="Times,serif" font-size="14.00">Generated</text>
-</g>
-<!-- File->Generated -->
-<g id="edge7" class="edge">
-<title>File->Generated</title>
-<path fill="none" stroke="black" d="M337.9551,-76.4574C352.2161,-66.1894 372.1136,-51.8633 388.6413,-39.9633"/>
-<polygon fill="black" stroke="black" points="390.8591,-42.6794 396.9294,-33.9959 386.7689,-36.9986 390.8591,-42.6794"/>
-</g>
-</g>
-</svg>
diff --git a/site/docs/platforms-intro.md b/site/docs/platforms-intro.md
deleted file mode 100644
index eddeee9..0000000
--- a/site/docs/platforms-intro.md
+++ /dev/null
@@ -1,468 +0,0 @@
----
-layout: documentation
-title: Building with platforms
-category: getting-started
----
-
-<div style="background-color: #EFCBCB; color: #AE2B2B; border: 1px solid #AE2B2B; border-radius: 5px; border-left: 10px solid #AE2B2B; padding: 0.5em;">
-<b>IMPORTANT:</b> The Bazel docs have moved! Please update your bookmark to <a href="https://bazel.build/concepts/platform-intro" style="color: #0000EE;">https://bazel.build/concepts/platform-intro</a>
-<p/>
-You can <a href="https://blog.bazel.build/2022/02/17/Launching-new-Bazel-site.html" style="color: #0000EE;">read about</a> the migration, and let us <a href="https://forms.gle/onkAkr2ZwBmcbWXj7" style="color: #0000EE;">know what you think</a>.
-</div>
-
-
-# Building with Platforms
-
-
-Bazel has sophisticated support for modeling [platforms][Platforms] and
-[toolchains][Toolchains]. Integrating this into real projects requires
-coherent cooperation between project and library owners, rule maintainers,
-and core Bazel devs.
-
-This page summarizes the arguments for using platforms and shows how to
-navigate these relationships for maximum value with minimum cognitive
-overhead.
-
-**In short:** the core APIs are available but the rule and depot migrations required
-to make them work universally are ongoing. This means you *may* be able to use
-platforms and toolchains with your project, with some work. But you have to
-explicitly opt your project in.
-
-For more formal documentation, see:
-
-* [Platforms][Platforms]
-* [Toolchains][Toolchains]
-
-## Background
-*Platforms* and *toolchains* were introduced to *standardize* the need for
- software projects to target different kinds of computers with different
- language-appropriate tools.
-
-This is a relatively recent addition to Bazel. It was
-[inspired][Inspiration]
-by the observation that language maintainers were *already* doing this in ad hoc
-and incompatible ways. For example, C++ rules use `--cpu` and `--crosstool_top`
-to set a build's target CPU and C++ toolchain. Neither of these correctly models a
-"platform". Historic attempts to use them for that inevitably led to awkward and
-inaccurate build APIs. They also don't say anything about Java toolchains,
-which evolved their own independent interface with `--java_toolchain`.
-
-Bazel aims to excel at large, mixed-language, multi-platform projects. This
-demands more principled support for these concepts, including clear APIs that
-bind rather than diverge languages and projects. This is what the new platform
-and toolchain APIs achieve.
-
-### Migration
-These APIs aren't enough for all projects to use platforms, and the old APIs
-have to be retired. This isn't trivial because all of a project's languages,
-toolchains, dependencies, and `select()`s have to support the new APIs. This
-requires an *ordered migration sequence* to keep projects working correctly.
-
-For example, Bazel's
-[C++ Rules] aleady support platforms while the
-[Android Rules] don't. *Your* C++ project may not care about Android. But others may. So
-it's not yet safe to globally enable platforms for all C++ builds.
-
-The remainder of this page describes this migration sequence and how and when
-your projects can fit in.
-
-## Goal
-Bazel's platform migration is complete when all projects build with the form:
-
-```sh
-$ bazel build //:myproject --platforms=//:myplatform
-```
-
-This implies:
-
-1. The rules your project uses can infer correct toolchains from
-`//:myplatform`.
-1. The rules your project's dependencies use can infer correct toolchains
-from `//:myplatform`.
-1. *Either* the projects depending on yours support `//:myplatform` *or* your
-project supports the legacy APIs (like `--crosstool_top`).
-1. `//:myplatform` references
-[common declarations][Common Platform Declaration]
-of `CPU`, `OS`, and other generic concepts that support automatic cross-project
-compatibility.
-1. All relevant projects'
-[`select()`s][select()]
-understand the machine properties implied by `//:myplatform`.
-1. `//:myplatform` is defined in a clear, reusable place: in your project's
-repo if the platform is unique to your project, otherwise somewhere all projects
-that may use this platform can find.
-
-The old APIs will be removed as soon as this goal is achieved and this will
-become the standard way projects select platforms and toolchains.
-
-## Should I use platforms?
-If you just want to build or cross-compile a project, you should follow the
-project’s official documentation.
-
-If you’re a project, language, or toolchain maintainer, you'll eventually want
-to support the new APIs. Whether you wait until the global migration is complete
-or opt in early depends on your specific value / cost needs:
-
-### Value
-* You can `select()` or choose toolchains on the exact properties you care
- about instead of hard-coded flags like `--cpu`. For example, multiple CPUs
- can support the [same instruction set](https://en.wikipedia.org/wiki/SSE4).
-* More correct builds. If you `select()` with `--cpu` in the above example, then
- add a new CPU that supports the same instruction set, the `select()`
- fails to recognize the new CPU. But a `select()` on platforms remains accurate.
-* Simpler user experience. All projects understand:
- `--platforms=//:myplatform`. No need for multiple language-specific
- flags on the command line.
-* Simpler language design. All languages share a common API for defining
- toolchains, using toolchains, and selecting the right toolchain for a platform.
-* Targets can be [skipped](platforms.html#skipping-incompatible-targets) in the
- build and test phase if they are incompatible with the target platform.
-
-### Costs
-* Dependent projects that don't yet support platforms might not automatically work
- with yours.
-* Making them work may require [additional temporary maintenance](#platform-mappings).
-* Co-existence of new and legacy APIs requires more careful user guidance to
- avoid confusion.
-* Canonical definitions for [common properties](#common-platorm-properties) like
- `OS` and `CPU` are still evolving and may require extra initial contributions.
-* Canonical definitions for language-specific toolchains are still evolving and
- may require extra initial contributions.
-
-
-## API review
-A [`platform`][platform Rule] is a collection of
-[`constraint_value` targets][constraint_value Rule]:
-
-```python
-platform(
- name = "myplatform",
- constraint_values = [
- "@platforms//os:linux",
- "@platforms//cpu:arm",
- ],
-)
-```
-
-A [`constraint_value`][constraint_value Rule] is a machine
-property. Values of the same "kind" are grouped under a common
-[`constraint_setting`][constraint_setting Rule]:
-
-```python
-constraint_setting(name = "os")
-constraint_value(
- name = "linux",
- constraint_setting = ":os",
-)
-constraint_value(
- name = "mac",
- constraint_setting = ":os",
-)
-```
-
-A [`toolchain`][Toolchains] is a [Starlark rule]. Its
-attributes declare a language's tools (like `compiler =
-"//mytoolchain:custom_gcc"`). Its [providers][Starlark Provider] pass
-this information to rules that need to build with these tools.
-
-Toolchains declare the `constraint_value`s of machines they can
-[target][target_compatible_with Attribute]
-(`target_compatible_with = ["@platforms//os:linux"]`) and machines their tools can
-[run on][exec_compatible_with Attribute]
-(`exec_compatible_with = ["@platforms//os:mac"]`).
-
-When building `$ bazel build //:myproject --platforms=//:myplatform`, Bazel
-automatically selects a toolchain that can run on the build machine and
-build binaries for `//:myplatform`. This is known as *toolchain resolution*.
-
-The set of available toolchains can be registered in the `WORKSPACE` with
-[`register_toolchains`][register_toolchains Function] or at the
-command line with [`--extra_toolchains`][extra_toolchains Flag].
-
-See [here][Toolchains] for a deeper dive.
-
-## Status
-Current platform support varies among languages. All of Bazel's major rules are
-moving to platforms. But this process will take time. This is for three main reasons:
-
-1. Rule logic must be updated to get tool info from the new [toolchain
-API][Toolchains] (`ctx.toolchains`) and stop reading legacy settings like
-`--cpu` and `--crosstool_top`. This is relatively straightforward.
-
-1. Toolchain maintainers must define toolchains and make them accessible to
- users (in GitHub repositories and `WORKSPACE` entries).
- This is technically straightforward but must be intelligently organized to
- maintain an easy user experience.
-
- Platform definitions are also necessary (unless you build for the same machine
- Bazel runs on). Generally, projects should define their own platforms.
-
-1. Existing projects must be migrated. `select()`s and
-[transitions][Starlark transitions] also have to be
-migrated. This is the biggest challenge. It's particularly challenging for
-multi-language projects (which may fail if *all* languages can't read
-`--platforms`).
-
-If you're designing a new rule set, you must support platforms from the
-beginning. This automatically makes your rules compatible with other
-rules and projects, with increasing value as the platform API becomes
-more ubiquitious.
-
-Details:
-
-### Common platform properties
-Platform properties like `OS` and `CPU` that are common across projects should
-be declared in a standard, centralized place. This encourages cross-project
-and cross-language compatibility.
-
-For example, if *MyApp* has a `select()` on `constraint_value`
-`@myapp//cpus:arm` and *SomeCommonLib* has a `select()` on
-`@commonlib//constraints:arm`, these trigger their "arm" modes with incompatible
-criteria.
-
-Globally common properties are declared in the
-[`@platforms`](https://github.com/bazelbuild/platforms) repo
-(so the canonical label for the above example is `@platforms//cpu:arm`).
-Language-common properties should be declared in the repos of their respective
-languages.
-
-### Default platforms
-Generally, project owners should define explicit
-[platforms][Defining Constraints and Platforms] to describe the
-kinds of machines they want to build for. These are then triggered with
-`--platforms`.
-
-When `--platforms` isn't set, Bazel defaults to a `platform` representing the
-local build machine. This is auto-generated at `@local_config_platform//:host`
-so there's no need to explicitly define it. It maps the local machine's `OS`
-and `CPU` with `constraint_value`s declared in
-[`@platforms`](https://github.com/bazelbuild/platforms).
-
-### C++
-Bazel's C++ rules use platforms to select toolchains when you set
-`--incompatible_enable_cc_toolchain_resolution`
-([#7260](https://github.com/bazelbuild/bazel/issues/7260)).
-
-This means you can configure a C++ project with
-
-```sh
-$ bazel build //:my_cpp_project --platforms=//:myplatform
-```
-
-instead of the legacy
-
-```sh
-$ bazel build //:my_cpp_project` --cpu=... --crosstool_top=... --compiler=...
-```
-
-If your project is pure C++ and not depended on by non-C++ projects, you can use
-this mode safely as long as your [`select`](#select)s and
-[transitions](#transitions) also work with platforms. See
-[#7260](https://github.com/bazelbuild/bazel/issues/7260) and [Configuring C++
-toolchains] for further migration guidance.
-
-This mode is not enabled by default. This is because Android and iOS projects
-still configure C++ dependencies with `--cpu` and `--crosstool_top`
-([example](https://github.com/bazelbuild/bazel/issues/8716#issuecomment-507230303)). Enabling
-it requires adding platform support for Android and iOS.
-
-### Java
-
-Bazel's Java rules use platforms and configuration flags to select toolchains.
-
-This replaces legacy flags `--java_toolchain`, `--host_java_toolchain`,
-`--javabase`, and `--host_javabase`.
-
-To learn how to use the configuration flags, see the [Bazel and Java](bazel-and-java.md) manual.
-For additional information, see the [Design document](https://docs.google.com/document/d/1MVbBxbKVKRJJY7DnkptHpvz7ROhyAYy4a-TZ-n7Q0r4).
-
-If you are still using legacy flags, follow the migration process in [Issue #7849](https://github.com/bazelbuild/bazel/issues/7849).
--->
-
-### Android
-Bazel's Android rules do not yet support platforms to select Android toolchains.
-
-They do support setting `--platforms` to select NDK toolchains: see
-[here][Android Rules Platforms].
-
-Most importantly,
-[`--fat_apk_cpu`][Android Rules Platforms],
-which builds multi-architecture fat APKs, does not work with platform-enabled
-C++. This is because it sets legacy flags like `--cpu` and `--crosstool_top`,
-which platform-enabled C++ rules don't read. Until this is migrated, using
-`--fat_apk_cpu` with `--platforms` requires [platform
-mappings](#platform-mappings).
-
-### Apple
-Bazel's Apple rules do not yet support platforms to select Apple toolchains.
-
-They also don't support platform-enabled C++ dependencies because they use the
-legacy `--crosstool_top` to set the C++ toolchain. Until this is migrated, you
-can mix Apple projects with platorm-enabled C++ with [platform
-mappings](#platform-mappings)
-([example](https://github.com/bazelbuild/bazel/issues/8716#issuecomment-516572378)).
-
-### Other languages
-* Bazel's [Rust rules](https://github.com/bazelbuild/rules_rust) fully support
-platforms.
-* Bazel's [Go rules](https://github.com/bazelbuild/rules_go) fully support
-platforms
-([details](https://github.com/bazelbuild/rules_go#how-do-i-cross-compile)).
-
-If you're designing rules for a new language, use platforms
-to select your language's toolchains. See the
-[toolchains documentation](toolchains.md) for a good walkthrough.
-
-### `select()`
-Projects can [`select()`][select()] on
-[`constraint_value` targets][constraint_value Rule] but not complete
-platforms. This is intentional so that `select()`s supports as wide a variety
-of machines as possible. A library with `ARM`-specific sources should support
-*all* `ARM`-powered machines unless there's reason to be more specific.
-
-To select on one or more `constraint_value`s, use
-
-```python
-config_setting(
- name = "is_arm",
- constraint_values = [
- "@platforms//cpu:arm",
- ],
-)
-```
-
-This is equivalent to traditionally selecting on `--cpu`:
-
-```python
-config_setting(
- name = "is_arm",
- values = {
- "cpu": "arm",
- },
-)
-```
-
-More details [here][select() Platforms].
-
-`select`s on `--cpu`, `--crosstool_top`, etc. don't understand `--platforms`. When
-migrating your project to platforms, you must either convert them to
-`constraint_values` or use [platform mappings](#platform-mappings) to support
-both styles through the migration window.
-
-### Transitions
-[Starlark transitions][Starlark transitions] change
-flags down parts of your build graph. If your project uses a transition that
-sets `--cpu`, `--crossstool_top`, or other legacy flags, rules that read
-`--platforms` won't see these changes.
-
-When migrating your project to platforms, you must either convert changes like
-`return { "//command_line_option:cpu": "arm" }` to `return {
-"//command_line_options:platforms": "//:my_arm_platform" }` or use [platform
-mappings](#platform-mappings) to support both styles through the migration
-window.
-
-## How to use platforms today
-If you just want to build or cross-compile a project, you should follow the
-project's official documentation. It's up to language and project maintainers to
-determine how and when to integrate with platforms, and what value that offers.
-
-If you're a project, language, or toolchain maintainer and your build doesn't
-use platforms by default, you have three options (besides waiting for the global
-migration):
-
-1. Flip on the "use platforms" flag for your project's languages ([if they have
- one](#status)) and do whatever testing you need to see if the projects you care
- about work.
-
-1. If the projects you care about still depend on legacy flags like `--cpu` and
- `--crosstool_top`, use these together with `--platforms`:
-
-
- `$ bazel build //:my_mixed_project --platforms==//:myplatform
- --cpu=... --crosstool_top=...`
-
- This has some maintenance cost (you have to manually make sure the settings
- match). But this should work in the absence of renegade
- [transitions](#transitions).
-
-1. Write [platform mappings](#platform-mappings) to support both styles by
- mapping `--cpu`-style settings to corresponding platforms and vice versa.
-
-### Platform mappings
-*Platform mappings* is a temporary API that lets platform-powered and
-legacy-powered logic co-exist in the same build through the latter's deprecation
-window.
-
-A platform mapping is a map of either a `platform()` to a
-corresponding set of legacy flags or the reverse. For example:
-
-```python
-platforms:
- # Maps "--platforms=//platforms:ios" to "--cpu=ios_x86_64 --apple_platform_type=ios".
- //platforms:ios
- --cpu=ios_x86_64
- --apple_platform_type=ios
-
-flags:
- # Maps "--cpu=ios_x86_64 --apple_platform_type=ios" to "--platforms=//platforms:ios".
- --cpu=ios_x86_64
- --apple_platform_type=ios
- //platforms:ios
-
- # Maps "--cpu=darwin --apple_platform_type=macos" to "//platform:macos".
- --cpu=darwin
- --apple_platform_type=macos
- //platforms:macos
-```
-
-Bazel uses this to guarantee all settings, both platform-based and
-legacy, are consistently applied throughout the build, including through
-[transitions](#transitions).
-
-By default Bazel reads mappings from the `platform_mappings` file in your
-workspace root. You can also set
-`--platform_mappings=//:my_custom_mapping`.
-
-See
-[here](https://docs.google.com/document/d/1Vg_tPgiZbSrvXcJ403vZVAGlsWhH9BUDrAxMOYnO0Ls/edit)
-for complete details.
-
-## Questions
-For general support and questions about the migration timeline, contact
-[bazel-discuss@googlegroups.com](https://groups.google.com/forum/#!forum/bazel-discuss)
-or the owners of the appropriate rules.
-
-For discussions on the design and evolution of the platform/toolchain APIs,
-contact
-[bazel-dev@googlegroups.com](https://groups.google.com/forum/#!forum/bazel-dev).
-
-## See also
-
-* [Configurable Builds - Part 1](https://blog.bazel.build/2019/02/11/configurable-builds-part-1.html)
-* [Platforms]
-* [Toolchains]
-* [Bazel Platforms Cookbook](https://docs.google.com/document/d/1UZaVcL08wePB41ATZHcxQV4Pu1YfA1RvvWm8FbZHuW8/)
-* [`hlopko/bazel_platforms_examples`](https://github.com/hlopko/bazel_platforms_examples)
-* [Example C++ custom toolchain](https://github.com/gregestren/snippets/tree/master/custom_cc_toolchain_with_platforms)
-
-[Platforms]: platforms.md
-[Toolchains]: toolchains.md
-[Inspiration]: https://blog.bazel.build/2019/02/11/configurable-builds-part-1.html
-[C++ Rules]: /versions/main/bazel-and-cpp.html
-[Android Rules]: /versions/main/bazel-and-android.html
-[Common Platform Declarations]: https://github.com/bazelbuild/platforms#motivation
-[select()]: https://docs.bazel.build/versions/main/configurable-attributes.html
-[select() Platforms]: configurable-attributes.md#platforms
-[platform Rule]: be/platform.html#platform
-[constraint_value Rule]: be/platform.html#constraint_value
-[constraint_setting Rule]: be/platform.html#constraint_setting
-[Starlark rule]: skylark/rules.html
-[Starlark provider]: skylark/rules.html#providers
-[target_compatible_with Attribute]: be/platform.html#toolchain.target_compatible_with
-[exec_compatible_with Attribute]: be/platform.html#toolchain.exec_compatible_with
-[register_toolchains Function]: skylark/lib/globals.html#register_toolchains
-[extra_toolchains Flag]: command-line-reference.html#flag--extra_toolchains
-[Starlark transitions]: skylark/config.html#user-defined-transitions
-[Defining Constraints and Platforms]: platforms.md#defining-constraints-and-platforms
-[Configuring C++ toolchains]: tutorial/cc-toolchain-config.html
-[Android Rules Platforms]: android-ndk.html#integration-with-platforms-and-toolchains
diff --git a/site/docs/platforms.md b/site/docs/platforms.md
deleted file mode 100644
index b120212..0000000
--- a/site/docs/platforms.md
+++ /dev/null
@@ -1,258 +0,0 @@
----
-layout: documentation
-title: Platforms
----
-
-<div style="background-color: #EFCBCB; color: #AE2B2B; border: 1px solid #AE2B2B; border-radius: 5px; border-left: 10px solid #AE2B2B; padding: 0.5em;">
-<b>IMPORTANT:</b> The Bazel docs have moved! Please update your bookmark to <a href="https://bazel.build/docs/platforms" style="color: #0000EE;">https://bazel.build/docs/platforms</a>
-<p/>
-You can <a href="https://blog.bazel.build/2022/02/17/Launching-new-Bazel-site.html" style="color: #0000EE;">read about</a> the migration, and let us <a href="https://forms.gle/onkAkr2ZwBmcbWXj7" style="color: #0000EE;">know what you think</a>.
-</div>
-
-
-# Platforms
-
-
-Bazel can build and test code on a variety of hardware, operating systems, and
-system configurations, using many different versions of build tools such as
-linkers and compilers. To help manage this complexity, Bazel has a concept of
-*constraints* and *platforms*. A constraint is a dimension in which build or
-production environments may differ, such as CPU architecture, the presence or
-absence of a GPU, or the version of a system-installed compiler. A platform is a
-named collection of choices for these constraints, representing the particular
-resources that are available in some environment.
-
-Modeling the environment as a platform helps Bazel to automatically select the
-appropriate
-[toolchains](toolchains.html)
-for build actions. Platforms can also be used in combination with the
-[config_setting](be/general.html#config_setting)
-rule to write
-<a href="configurable-attributes.html"> configurable attributes</a>.
-
-Bazel recognizes three roles that a platform may serve:
-
-* **Host** - the platform on which Bazel itself runs.
-* **Execution** - a platform on which build tools execute build actions to
- produce intermediate and final outputs.
-* **Target** - a platform on which a final output resides and executes.
-
-Bazel supports the following build scenarios regarding platforms:
-
-* **Single-platform builds** (default) - host, execution, and target platforms
- are the same. For example, building a Linux executable on Ubuntu running on
- an Intel x64 CPU.
-
-* **Cross-compilation builds** - host and execution platforms are the same, but
- the target platform is different. For example, building an iOS app on macOS
- running on a MacBook Pro.
-
-* **Multi-platform builds** - host, execution, and target platforms are all
- different.
-
-## Defining constraints and platforms
-
-The space of possible choices for platforms is defined by using the
- [`constraint_setting`](be/platform.html#constraint_setting) and
- [`constraint_value`](be/platform.html#constraint_value) rules within `BUILD` files. `constraint_setting` creates a new dimension, while
-`constraint_value` creates a new value for a given dimension; together they
-effectively define an enum and its possible values. For example, the following
-snippet of a `BUILD` file introduces a constraint for the system's glibc version
-with two possible values.
-
-```python
-constraint_setting(name = "glibc_version")
-
-constraint_value(
- name = "glibc_2_25",
- constraint_setting = ":glibc_version",
-)
-
-constraint_value(
- name = "glibc_2_26",
- constraint_setting = ":glibc_version",
-)
-```
-
-Constraints and their values may be defined across different packages in the
-workspace. They are referenced by label and subject to the usual visibility
-controls. If visibility allows, you can extend an existing constraint setting by
-defining your own value for it.
-
-The
- [`platform`](be/platform.html#platform) rule introduces a new platform with certain choices of constraint values. The
-following creates a platform named `linux_x86`, and says that it describes any
-environment that runs a Linux operating system on an x86_64 architecture with a
-glibc version of 2.25. (See below for more on Bazel's built-in constraints.)
-
-```python
-platform(
- name = "linux_x86",
- constraint_values = [
- "@platforms//os:linux",
- "@platforms//cpu:x86_64",
- ":glibc_2_25",
- ],
-)
-```
-
-Note that it is an error for a platform to specify more than one value of the
-same constraint setting, such as `@platforms//cpu:x86_64` and
-`@platforms//cpu:arm` for `@platforms//cpu:cpu`.
-
-
-## Generally useful constraints and platforms
-
-To keep the ecosystem consistent, Bazel team maintains a repository with
-constraint definitions for the most popular CPU architectures and operating
-systems. These are all located in
-[https://github.com/bazelbuild/platforms](https://github.com/bazelbuild/platforms).
-
-Bazel ships with the following special platform definition:
-`@local_config_platform//:host`. This is the autodetected host platform value -
-represents autodetected platform for the system Bazel is running on.
-
-## Specifying a platform for a build
-
-You can specify the host and target platforms for a build using the following
-command-line flags:
-
-* `--host_platform` - defaults to `@bazel_tools//platforms:host_platform`
-* `--platforms` - defaults to `@bazel_tools//platforms:target_platform`
-
-## Skipping incompatible targets
-
-When building for a specific target platform it is often desirable to skip
-targets that will never work on that platform. For example, your Windows device
-driver is likely going to generate lots of compiler errors when building on a
-Linux machine with `//...`. Use the
-[`target_compatible_with`](be/common-definitions.html#common.target_compatible_with)
-attribute to tell Bazel what target platform constraints your code has.
-
-The simplest use of this attribute restricts a target to a single platform.
-The target will not be built for any platform that doesn't satisfy all of the
-constraints. The following example restricts `win_driver_lib.cc` to 64-bit
-Windows.
-
-```python
-cc_library(
- name = "win_driver_lib",
- srcs = ["win_driver_lib.cc"],
- target_compatible_with = [
- "@platforms//cpu:x86_64",
- "@platforms//os:windows",
- ],
-)
-```
-
-`:win_driver_lib` is *only* compatible for building with 64-bit Windows and
-incompatible with all else. Incompatibility is transitive. Any targets
-that transitively depend on an incompatible target are themselves considered
-incompatible.
-
-### When are targets skipped?
-
-Targets are skipped when they are considered incompatible and included in the
-build as part of a target pattern expansion. For example, the following two
-invocations skip any incompatible targets found in a target pattern expansion.
-
-```console
-$ bazel build --platforms=//:myplatform //...
-```
-
-```console
-$ bazel build --platforms=//:myplatform //:all
-```
-
-Incompatible tests in a [`test_suite`](be/general.html#test_suite) are
-similarly skipped if the `test_suite` is specified on the command line with
-[`--expand_test_suites`](command-line-reference.html#flag--expand_test_suites).
-In other words, `test_suite` targets on the command line behave like `:all` and
-`...`. Using `--noexpand_test_suites` prevents expansion and causes
-`test_suite` targets with incompatible tests to also be incompatible.
-
-Explicitly specifying an incompatible target on the command line results in an
-error message and a failed build.
-
-```console
-$ bazel build --platforms=//:myplatform //:target_incompatible_with_myplatform
-...
-ERROR: Target //:target_incompatible_with_myplatform is incompatible and cannot be built, but was explicitly requested.
-...
-FAILED: Build did NOT complete successfully
-```
-
-### More expressive constraints
-
-For more flexibility in expressing constraints, use the
-`@platforms//:incompatible`
-[`constraint_value`](be/platform.html#constraint_value) that no platform
-satisfies.
-
-Use [`select()`](functions.html#select) in combination with
-`@platforms//:incompatible` to express more complicated restrictions. For
-example, use it to implement basic OR logic. The following marks a library
-compatible with macOS and Linux, but no other platforms. Note that an empty
-constraints list is equivalent to "compatible with everything".
-
-```python
-cc_library(
- name = "unixish_lib",
- srcs = ["unixish_lib.cc"],
- target_compatible_with = select({
- "@platforms//os:osx": [],
- "@platforms//os:linux": [],
- "//conditions:default": ["@platforms//:incompatible"],
- }),
-)
-```
-
-The above can be interpreted as follows:
-
-1. When targeting macOS, the target has no constraints.
-2. When targeting Linux, the target has no constraints.
-3. Otherwise, the target has the `@platforms//:incompatible` constraint. Because
- `@platforms//:incompatible` is not part of any platform, the target is
- deemed incompatible.
-
-To make your constraints more readable, use
-[skylib](https://github.com/bazelbuild/bazel-skylib)'s
-[`selects.with_or()`](https://github.com/bazelbuild/bazel-skylib/blob/main/docs/selects_doc.md#selectswith_or).
-
-You can express inverse compatibility in a similar way. The following example
-describes a library that is compatible with everything _except_ for ARM.
-
-```python
-cc_library(
- name = "non_arm_lib",
- srcs = ["non_arm_lib.cc"],
- target_compatible_with = select({
- "@platforms//cpu:arm": ["@platforms//:incompatible"],
- "//conditions:default": [],
- ],
-)
-```
-
-### Detecting incompatible targets using `bazel cquery`
-
-You can use the
-[`IncompatiblePlatformProvider`](skylark/lib/IncompatiblePlatformProvider.html)
-in `bazel cquery`'s [Starlark output
-format](cquery.html#defining-the-output-format-using-starlark) to distinguish
-incompatible targets from compatible ones.
-
-This can be used to filter out incompatible targets. The example below will
-only print the labels for targets that are compatible. Incompatible targets are
-not printed.
-
-```console
-$ cat example.cquery
-
-def format(target):
- if "IncompatiblePlatformProvider" not in providers(target):
- return target.label
- return ""
-
-
-$ bazel cquery //... --output=starlark --starlark:file=example.cquery
-```
diff --git a/site/docs/query-how-to.html b/site/docs/query-how-to.html
deleted file mode 100644
index e0dbc3c..0000000
--- a/site/docs/query-how-to.html
+++ /dev/null
@@ -1,329 +0,0 @@
----
-layout: documentation
-title: Bazel query how-to
----
-
-<div style="background-color: #EFCBCB; color: #AE2B2B; border: 1px solid #AE2B2B; border-radius: 5px; border-left: 10px solid #AE2B2B; padding: 0.5em;">
-<b>IMPORTANT:</b> The Bazel docs have moved! Please update your bookmark to <a href="https://bazel.build/docs/query-how-to" style="color: #0000EE;">https://bazel.build/docs/query-how-to</a>
-<p/>
-You can <a href="https://blog.bazel.build/2022/02/17/Launching-new-Bazel-site.html" style="color: #0000EE;">read about</a> the migration, and let us <a href="https://forms.gle/onkAkr2ZwBmcbWXj7" style="color: #0000EE;">know what you think</a>.
-</div>
-
-<h1>Bazel Query How-To</h1>
-
-<p>
- This page covers how to get started using Bazel's query language to trace
- dependencies in your code.
-</p>
-
-<p>
- For a language details and <code>--output</code> flag details, please see the
- reference manuals, <a href="query.html">Bazel query reference</a>
- and <a href="cquery.html">Bazel cquery reference</a>. You can get help by
- typing <code>bazel help query</code> or <code>bazel help cquery</code> on the
- command line.
-</p>
-
-<p>
- To execute a query while ignoring errors such as missing targets, use the
- <code>--keep_going</code> flag.
-</p>
-
-
-<h2 id="Finding_the_Dependencies_of_a_Ru">Finding the dependencies of a rule</h2>
-
-<p>To see the dependencies of <code>//foo</code>, use the
-<code>deps</code> function in bazel query:</p>
-
-<pre>
-$ bazel query "deps(//foo)"
-//foo:foo
-//foo:foo-dep
-...
-</pre>
-
-<p>This is the set of all targets required to build <code>//foo</code>.</p>
-
-<h2 id="Tracing_the_Dependency_Chain_bet">Tracing the dependency chain between two packages</h2>
-
-<p>The library <code>//third_party/zlib:zlibonly</code> isn't in the BUILD file for
-<code>//foo</code>, but it is an indirect dependency. How can
-we trace this dependency path? There are two useful functions here:
-<code>allpaths</code> and <code>somepath</code>. You may also want to exclude
-tooling dependencies with <code>--notool_deps</code> if you care only about
-what is included in the artifact you built, and not every possible job.
-
-<p>To visualize the graph of all dependencies, pipe the bazel query output through
- the <code>dot</code> command-line tool:</p>
-<pre>
-$ bazel query "allpaths(//foo, third_party/...)" --notool_deps --output graph | dot -Tsvg > /tmp/deps.svg
-</pre>
-
-<p>
- Note that <code>dot</code> supports other image formats, just replace <code>svg</code> with the
- format identifier, for example, <code>png</code>.
-</p>
-
-<p>When a dependency graph is big and complicated, it can be helpful start with a single path:</p>
-
-<pre>
-$ bazel query "somepath(//foo:foo, third_party/zlib:zlibonly)"
-//foo:foo
-//translations/tools:translator
-//translations/base:base
-//third_party/py/MySQL:MySQL
-//third_party/py/MySQL:_MySQL.so
-//third_party/mysql:mysql
-//third_party/zlib:zlibonly
-</pre>
-
-<p>If you do not specify <code>--output graph</code> with <code>allpaths</code>,
-you will get a flattened list of the dependency graph.</p>
-<pre>
-$ bazel query "allpaths(//foo, third_party/...)"
- ...many errors detected in BUILD files...
-//foo:foo
-//translations/tools:translator
-//translations/tools:aggregator
-//translations/base:base
-//tools/pkg:pex
-//tools/pkg:pex_phase_one
-//tools/pkg:pex_lib
-//third_party/python:python_lib
-//translations/tools:messages
-//third_party/py/xml:xml
-//third_party/py/xml:utils/boolean.so
-//third_party/py/xml:parsers/sgmlop.so
-//third_party/py/xml:parsers/pyexpat.so
-//third_party/py/MySQL:MySQL
-//third_party/py/MySQL:_MySQL.so
-//third_party/mysql:mysql
-//third_party/openssl:openssl
-//third_party/zlib:zlibonly
-//third_party/zlib:zlibonly_v1_2_3
-//third_party/python:headers
-//third_party/openssl:crypto
-</pre>
-
-<h3 id="Aside_implicit_dependencies">Aside: implicit dependencies</h3>
-
-<p>The BUILD file for <code>//foo</code> never references
-<code>//translations/tools:aggregator</code>. So, where's the direct dependency?</p>
-
-<p>Certain rules include implicit dependencies on additional libraries or tools.
-For example, to build a <code>genproto</code> rule, you need first to build the Protocol
-Compiler, so every <code>genproto</code> rule carries an implicit dependency on the
-protocol compiler. These dependencies are not mentioned in the build file,
-but added in by the build tool. The full set of implicit dependencies is
- currently undocumented. Using <code>--noimplicit_deps</code> allows you to filter out
- these deps from your query results. For cquery, this will include resolved toolchains.
-
-<h2 id="Reverse_Dependencies">Reverse dependencies</h2>
-
-<p>You might want to know the set of targets that depends on some target. e.g.,
-if you're going to change some code, you might want to know what other code
-you're about to break. You can use <code>rdeps(u, x)</code> to find the reverse
-dependencies of the targets in <code>x</code> within the transitive closure of <code>u</code>.</p>
-
-Bazel's <a href="query.html#sky-query">Sky Query</a> supports the <code>allrdeps</code>
-function, which allows you to query <code>rdeps</code> in a universe you specify.
-<h2 id="Miscellaneous_Uses">Miscellaneous uses</h2>
-
-<p>You can use <code>bazel query</code> to analyze many dependency relationships.</p>
-
-<h3 id="What_exists_">What exists ...</h3>
-
-<h4 id="What_packages_exist_beneath_foo_">What packages exist beneath <code>foo</code>?</h4>
-
-<pre>bazel query 'foo/...' --output package</pre>
-
-<h4 id="What_rules_are_defined_in_the_foo">What rules are defined in the <code>foo</code> package?</h4>
-
-<pre>bazel query 'kind(rule, foo:*)' --output label_kind</pre>
-
-<h4 id="What_files_are_generated_by_rule">What files are generated by rules in the <code>foo</code> package?</h4>
-
-<pre>bazel query 'kind("generated file", //foo:*)'</pre>
-
-<h4 id="What_targets_are_generated_by_macro">What targets are generated by starlark macro <code>foo</code>?</h4>
-
-<pre>bazel query 'attr(generator_function, foo, //path/to/search/...)'</pre>
-
-<h4 id="What_s_the_set_of_BUILD_files_ne">What's the set of BUILD files needed to build <code>//foo</code>?</h4>
-
-<pre>bazel query 'buildfiles(deps(//foo))' | cut -f1 -d:</pre>
-
-<h4 id="What_are_the_individual_tests_th">What are the individual tests that a <code>test_suite</code> expands to?</h4>
-
-<pre>bazel query 'tests(//foo:smoke_tests)'</pre>
-
-<h4 id="Which_of_those_are_C_tests_">Which of those are C++ tests?</h4>
-
-<pre>bazel query 'kind(cc_.*, tests(//foo:smoke_tests))'</pre>
-
-<h4 id="Which_of_those_are_small_Medium_">Which of those are small? Medium? Large?</h4>
-
-<pre>
-bazel query 'attr(size, small, tests(//foo:smoke_tests))'
-
-bazel query 'attr(size, medium, tests(//foo:smoke_tests))'
-
-bazel query 'attr(size, large, tests(//foo:smoke_tests))'
-</pre>
-
-<h4 id="What_are_the_tests_beneath_foo_t">What are the tests beneath <code>foo</code> that match a pattern?</h4>
-
-<pre>bazel query 'filter("pa?t", kind(".*_test rule", //foo/...))'</pre>
-
-<p>The pattern is a regex and is applied to the full name of the rule. It's similar to doing</p>
-
-<pre>bazel query 'kind(".*_test rule", //foo/...)' | grep -E 'pa?t'</pre>
-
-<h4 id="What_package_contains_file_java_">What package contains file <code>path/to/file/bar.java</code>?</h4>
-
-<pre> bazel query path/to/file/bar.java --output=package</pre>
-
-<h4 id="What_is_the_build_label_for_java">What is the build label for <code>path/to/file/bar.java?</code></h4>
-
-<pre>bazel query path/to/file/bar.java</pre>
-
-<h4 id="What_build_rule_contains_file_ja">What rule target(s) contain file <code>path/to/file/bar.java</code> as a source?</h4>
-
-<pre>
-fullname=$(bazel query path/to/file/bar.java)
-bazel query "attr('srcs', $fullname, ${fullname//:*/}:*)"
-</pre>
-
-<h3 id="What_package_dependencies_exist_">What package dependencies exist ...</h3>
-
-<h4 id="What_packages_does_foo_depend_on">What packages does <code>foo</code> depend on? (What do I need to check out to build <code>foo</code>)</h4>
-
-<pre>bazel query 'buildfiles(deps(//foo:foo))' --output package</pre>
-
-<p>Note, <code>buildfiles</code> is required in order to correctly obtain all files
-referenced by <code>subinclude</code>; see the reference manual for details.</p>
-
-<h4 id="What_packages_does_the_foo_">What packages does the <code>foo</code> tree depend on, excluding <code>foo/contrib</code>?</h4>
-
-<pre>bazel query 'deps(foo/... except foo/contrib/...)' --output package</pre>
-
-<h3 id="What_rule_dependencies_exist_">What rule dependencies exist ...</h3>
-
-<h4 id="What_genproto_rules_does_bar_">What genproto rules does bar depend upon?</h4>
-
-<pre>bazel query 'kind(genproto, deps(bar/...))'</pre>
-
-<h4 id="Find_the_definition_of_some_JNI_">Find the definition of some JNI (C++) library that is transitively depended upon by a Java binary rule in the servlet tree.</h4>
-
-<pre>bazel query 'some(kind(cc_.*library, deps(kind(java_binary, //java/com/example/frontend/...))))' --output location</pre>
-
-<h5 id="_Now_find_the_definitions_of_all">...Now find the definitions of all the Java binaries that depend on them</h5>
-
-<pre>bazel query 'let jbs = kind(java_binary, //java/com/example/frontend/...) in
- let cls = kind(cc_.*library, deps($jbs)) in
- $jbs intersect allpaths($jbs, $cls)'
-</pre>
-
-<h3 id="What_file_dependencies_exist_">What file dependencies exist ...</h3>
-
-<h4 id="What_s_the_complete_set_of_Java_">What's the complete set of Java source files required to build foo?</h4>
-
-<p>Source files:</p>
-
-<pre>bazel query 'kind("source file", deps(//path/to/target/foo/...))' | grep java$</pre>
-
-<p>Generated files:</p>
-
-<pre>bazel query 'kind("generated file", deps(//path/to/target/foo/...))' | grep java$</pre>
-
-<h4 id="What_is_the_complete_set_of_Java">What is the complete set of Java source files required to build QUX's tests?</h4>
-
-<p>Source files:</p>
-
-<pre>bazel query 'kind("source file", deps(kind(".*_test rule", javatests/com/example/qux/...)))' | grep java$</pre>
-
-<p>Generated files:</p>
-
-<pre>bazel query 'kind("generated file", deps(kind(".*_test rule", javatests/com/example/qux/...)))' | grep java$</pre>
-
-<h3 id="What_differences_in_dependencies">What differences in dependencies between X and Y exist ...</h3>
-
-<h4 id="What_targets_does_foo_depend_on_">What targets does <code>//foo</code> depend on that <code>//foo:foolib</code> does not?</h4>
-
-<pre>bazel query 'deps(//foo) except deps(//foo:foolib)'</pre>
-
-<h4 id="What_C_libraries_do_the_foo_test">What C++ libraries do the <code>foo</code> tests depend on that the <code>//foo</code> production binary does <em>not</em> depend on?</h4>
-
-<pre>bazel query 'kind("cc_library", deps(kind(".*test rule", foo/...)) except deps(//foo))'</pre>
-
-<h3 id="Why_does_this_dependency_exist_">Why does this dependency exist ...</h3>
-
-<h4 id="Why_does_bar_depend_on_groups">Why does <code>bar</code> depend on <code>groups2</code>?</h4>
-
-<pre>bazel query 'somepath(bar/...,groups2/...:*)'</pre>
-
-<p>Once you have the results of this query, you will often find that a single
-target stands out as being an unexpected or egregious and undesirable
-dependency of <code>bar</code>. The query can then be further refined to:</p>
-
-<h4 id="Show_me_a_path_from_docker_updater">Show me a path from <code>docker/updater:updater_systest</code> (a <code>py_test</code>) to some <code>cc_library</code> that it depends upon:</h4>
-
-<pre>bazel query 'let cc = kind(cc_library, deps(docker/updater:updater_systest)) in
- somepath(docker/updater:updater_systest, $cc)'</pre>
-
-<h4 id="Why_does_library_photos_frontend">Why does library <code>//photos/frontend:lib</code> depend on two variants of the same library <code>//third_party/jpeglib</code> and <code>//third_party/jpeg</code>?</h4>
-
-<p>This query boils down to: "show me the subgraph of <code>//photos/frontend:lib</code> that
-depends on both libraries". When shown in topological order, the last element
-of the result is the most likely culprit.</p>
-
-<pre>bazel query 'allpaths(//photos/frontend:lib, //third_party/jpeglib)
- intersect
- allpaths(//photos/frontend:lib, //third_party/jpeg)'
-//photos/frontend:lib
-//photos/frontend:lib_impl
-//photos/frontend:lib_dispatcher
-//photos/frontend:icons
-//photos/frontend/modules/gadgets:gadget_icon
-//photos/thumbnailer:thumbnail_lib
-//third_party/jpeg/img:renderer
-</pre>
-
-<h3 id="What_depends_on_">What depends on ...</h3>
-
-<h4 id="What_rules_under_bar_depend_o">What rules under bar depend on Y?</h4>
-
-<pre>bazel query 'bar/... intersect allpaths(bar/..., Y)'</pre>
-
-<p>Note: <code>X intersect allpaths(X, Y)</code> is the general idiom for the query "which X
-depend on Y?" If expression X is non-trivial, it may be convenient to bind a
-name to it using <code>let</code> to avoid duplication.</p>
-
-<h4 id="What_are_the_intra_package_direct_rdeps">What targets directly depend on T, in T's package?</h4>
-
-<pre>bazel query 'same_pkg_direct_rdeps(T)'</pre>
-
-<h3 id="How_do_I_break_a_dependency_">How do I break a dependency ...</h3>
-
-<p><!-- TODO find a convincing value of X to plug in here -->
-
-<h4 id="What_dependency_paths_do_I_have_">What dependency paths do I have to break to make <code>bar</code> no longer depend on X?</h4>
-
-<p>To output the graph to a <code>svg</code> file:</p>
-
-<pre>bazel query 'allpaths(bar/...,X)' --output graph | dot -Tsvg > /tmp/dep.svg</pre>
-
-<h3 id="Misc_">Misc ...</h3>
-
-<h4 id="How_many_sequential_steps_are_th">How many sequential steps are there in the <code>//foo-tests</code> build?</h4>
-
-<p>Unfortunately, the query language can't currently give you the longest path
-from x to y, but it can find the (or rather <em>a</em>) most distant node from the
-starting point, or show you the <em>lengths</em> of the longest path from x to every
-y that it depends on. Use <code>maxrank</code>:</p>
-
-<pre>bazel query 'deps(//foo-tests)' --output maxrank | tail -1
-85 //third_party/zlib:zutil.c</pre>
-
-<p>The result indicates that there exist paths of length 85 that must occur in
-order in this build.</p>
diff --git a/site/docs/query.html b/site/docs/query.html
deleted file mode 100644
index 9eefd05..0000000
--- a/site/docs/query.html
+++ /dev/null
@@ -1,1619 +0,0 @@
----
-layout: documentation
-title: Query language
----
-
-<div style="background-color: #EFCBCB; color: #AE2B2B; border: 1px solid #AE2B2B; border-radius: 5px; border-left: 10px solid #AE2B2B; padding: 0.5em;">
-<b>IMPORTANT:</b> The Bazel docs have moved! Please update your bookmark to <a href="https://bazel.build/reference/query" style="color: #0000EE;">https://bazel.build/reference/query</a>
-<p/>
-You can <a href="https://blog.bazel.build/2022/02/17/Launching-new-Bazel-site.html" style="color: #0000EE;">read about</a> the migration, and let us <a href="https://forms.gle/onkAkr2ZwBmcbWXj7" style="color: #0000EE;">know what you think</a>.
-</div>
-
-<h1>The Bazel Query Reference</h1>
-
-
-This page is the reference manual for the <em>Bazel Query Language</em> used
-when you use <code>bazel query</code> to analyze build dependencies. It also
-describes the output formats <code>bazel query</code> supports.
-
-<p>
- If you were looking for a how-to, please see the <a href='query-how-to.md'>Bazel Query How-To</a>.
-</p>
-<h3> bazel cquery </h3>
-<p>Traditional Bazel query runs on the post-loading phase target graph and therefore
- has no concept of configurations and their related concepts. Notably, this means it does not
- correctly resolve <a href = "be/functions.html#select">select statements</a>
- and rather returns all possible resolutions of selects. A newer query environment, cquery,
- properly handles configurations but doesn't provide all of the functionality of this original
- query. For more information, see the <a href="cquery.html">Bazel cquery reference</a>.
-</p>
-<h2 id='examples'>Examples</h2>
-
-<p>
- How do people use <code>bazel query</code>? Here are typical examples:
-</p>
-
-<p>
- Why does the <code>//foo</code> tree depend on <code>//bar/baz</code>?
- Show a path:</p>
- <pre>somepath(foo/..., //bar/baz:all)</pre>
-
-
-<p>
- What C++ libraries do all the <code>foo</code> tests depend on that
- the <code>foo_bin</code> target does not?</p>
- <pre>kind("cc_library", deps(kind(".*test rule", foo/...)) except deps(//foo:foo_bin))</pre>
-
-
-<h2 id='tokens'>Tokens: The lexical syntax</h2>
-
-<p>
- Expressions in the query language are composed of the following
- tokens:</p>
- <ul>
- <li>
- <p>
- <b>Keywords</b>, such as <code>let</code>. Keywords are the reserved words of the
- language, and each of them is described below. The complete set
- of keywords is:
- </p>
-
-<code><!-- keep this alphabetically sorted -->
-<a href="#set-operations">except</a><br/>
-<a href="#variables">in</a><br/>
-<a href="#set-operations">intersect</a><br/>
-<a href="#variables">let</a><br/>
-<a href="#set">set</a><br/>
-<a href="#set-operations">union</a><br/>
-</code>
- </li>
-
- <li>
- <p>
- <b>Words</b>, such as <code>foo/...</code> or
- <code>".*test rule"</code> or <code>//bar/baz:all</code>. If a
- character sequence is "quoted" (begins and ends with a single-quote
- <code>'</code> or begins and ends with a double-quote
- <code>"</code>), it is a word. If a character sequence is not
- quoted, it may still be parsed as a word. Unquoted words are sequences
- of characters drawn from the alphabet characters <code>A-Za-z</code>,
- the numerals <code>0-9</code>, and the special characters <code>*/@.-_:$~</code>
- (asterisk, forward slash, at, period, hyphen, underscore, colon, dollar sign, tilde).
- </p>
- <p>
- Exceptions:
-
- <ul>
- <li>An unquoted word may not start with a hyphen <code>-</code>.</li>
- <li>
- An unquoted word may not include the characters plus sign <code>+</code> or equals sign
- <code>=</code> at all.
- </li>
- </ul>
- <p>
- These three characters are permitted in <a href="build-ref.html#name">target names</a> but
- they are also used for operators in the query language. For example,
- </p>
- <pre>
- //foo:bar+wiz # WRONG: scanned as //foo:bar + wiz.
- //foo:bar=wiz # WRONG: scanned as //foo:bar = wiz.
- "//foo:bar+wiz" # OK.
- "//foo:bar=wiz" # OK.
- </pre>
-
- Concrete examples, for the first argument to the <a href='#kind'>kind</a> function:
-
- <pre>
- kind("blah rule", //a:b) # The first argument contains a space character, so it needs to be quoted.
- kind(.blah, //a:b) # It's fine for the first argument to be unquoted and start with a period.
- kind(".+blah", //a:b) # The first argument contains a plus character, so it needs to be quoted.
- kind(*blah, //a:b) # It's fine for the first argument to be unquoted and start with an asterisk. (But this is a silly example, because the first argument is an invalid regex).
- </pre>
-
- <p>
- Therefore, it is recommended to quote strings when producing query expressions programmatically from arbitrary user-supplied values.
- <p>
- <p>
- Additionally, your shell may have its own quoting requirements, e.g.
- </p>
- <pre>
- bazel query ' "//foo:bar=wiz" ' # single-quotes for shell, double-quotes for Bazel.
- </pre>
-
- <p>
- Keywords, when quoted, are treated as ordinary words. For example,
- <code>set</code> is a keyword and <code>"set"</code> in quotes is treated as a word.
- Both <code>foo</code> and <code>"foo"</code> are words.
- </p>
-
- <p>
- However, be careful when using single or double quotes in target names. When quoting one or
- more target names, use only one type of quotes (either all single or all double quotes).
-
- </p>
- <pre>
- The following are examples of what the Java query string will be:
-
- 'a"'a' # WRONG: Error message: unclosed quotation.
- "a'"a" # WRONG: Error message: unclosed quotation.
- '"a" + 'a'' # WRONG: Error message: unexpected token 'a' after query expression '"a" + '
- "'a' + "a"" # WRONG: Error message: unexpected token 'a' after query expression ''a' + '
- "a'a" # OK.
- 'a"a' # OK.
- '"a" + "a"' # OK
- "'a' + 'a'" # OK
- </pre>
-
- <li><b>Punctuation</b>, such as parens <code>()</code>, period
- <code>.</code> and comma <code>,</code>, etc. Words containing
- punctuation (other than the exceptions listed above in <b>Words</b>) must be quoted.
- </ul>
-
-<p>
- Whitespace characters outside of a quoted word are ignored.
-</p>
-
-<h2 id='concepts'>Bazel query language concepts</h2>
-<p>
- The Bazel query language is a language of expressions. Every
- expression evaluates to a <b>partially-ordered set</b> of targets,
- or equivalently, a <b>graph</b> (DAG) of targets. This is the only
- datatype.
-</p>
-<p>
- Set and graph refer to the same datatype, but emphasize different
- aspects of it, for example:
-</p>
-<ul>
- <li><b>Set:</b> The partial order of the targets is not interesting.</li>
- <li><b>Graph:</b> The partial order of targets is significant.</li>
-</ul>
-
-<h3>Cycles in the dependency graph</h3>
-<p>
- Build dependency graphs should be acyclic.
-
- The algorithms used by the query language are intended for use in
- acyclic graphs, but are robust against cycles. The details of how
- cycles are treated are not specified and should not be relied upon.
-</p>
-
-<h3 id='implicit_deps'>Implicit dependencies</h3>
-
-<p>
- In addition to build dependencies that are defined explicitly in <code>BUILD</code> files,
- Bazel adds additional <em>implicit</em> dependencies to rules. For example
- every Java rule implicitly depends on the JavaBuilder. Implicit dependencies
- are established using attributes that start with <code>$</code> and they
- cannot be overridden in <code>BUILD</code> files.
-
-</p>
-
-<p>
- Per default <code>bazel query</code> takes implicit dependencies into account
- when computing the query result. This behavior can be changed with
- the <code>--[no]implicit_deps</code> option. Note that, as query does not consider
- configurations, potential toolchains are never considered.
-</p>
-
-<h3 id='soundness'>Soundness</h3>
-
-<p>
- Bazel query language expressions operate over the build
- dependency graph, which is the graph implicitly defined by all
- rule declarations in all <code>BUILD</code> files. It is important to understand
- that this graph is somewhat abstract, and does not constitute a
- complete description of how to perform all the steps of a build. In
- order to perform a build, a <em>configuration</em> is required too;
- see the <a href='user-manual.html#configurations'>configurations</a>
- section of the User's Guide for more detail.
-</p>
-
-<p>
- The result of evaluating an expression in the Bazel query language
- is true <em>for all configurations</em>, which means that it may be
- a conservative over-approximation, and not exactly precise. If you
- use the query tool to compute the set of all source files needed
- during a build, it may report more than are actually necessary
- because, for example, the query tool will include all the files
- needed to support message translation, even though you don't intend
- to use that feature in your build.
-</p>
-
-<h3 id='graph-order'>On the preservation of graph order</h3>
-
-<p>
- Operations preserve any ordering
- constraints inherited from their subexpressions. You can think of
- this as "the law of conservation of partial order". Consider an
- example: if you issue a query to determine the transitive closure of
- dependencies of a particular target, the resulting set is ordered
- according to the dependency graph. If you filter that set to
- include only the targets of <code>file</code> kind, the same
- <em>transitive</em> partial ordering relation holds between every
- pair of targets in the resulting subset—even though none of
- these pairs is actually directly connected in the original graph.
- (There are no file–file edges in the build dependency graph).
-</p>
-
-<p>
- However, while all operators <em>preserve</em> order, some
- operations, such as the <a href='#set-operations'>set operations</a>
- don't <em>introduce</em> any ordering constraints of their own.
- Consider this expression:
-</p>
-
-<pre>deps(x) union y</pre>
-
-<p>
- The order of the final result set is guaranteed to preserve all the
- ordering constraints of its subexpressions, namely, that all the
- transitive dependencies of <code>x</code> are correctly ordered with
- respect to each other. However, the query guarantees nothing about
- the ordering of the targets in <code>y</code>, nor about the
- ordering of the targets in <code>deps(x)</code> relative to those in
- <code>y</code> (except for those targets in
- <code>y</code> that also happen to be in <code>deps(x)</code>).
-</p>
-
-<p>
- Operators that introduce ordering constraints include:
- <code>allpaths</code>,
- <code>deps</code>,
- <code>rdeps</code>,
- <code>somepath</code>,
- and the target pattern wildcards
- <code>package:*</code>,
- <code>dir/...</code>, etc.
-</p>
-
-<h3 id='sky-query'>Sky Query</h3>
-
-<i>Sky Query</i> is a mode of query that operates over a specified <i>universe scope</i>.
-
-<h4 id='sky-query-special-functions'>Special functions available only in SkyQuery</h4>
-
-Sky Query mode has the additional query functions <a href='#allrdeps'><code>allrdeps</code></a> and
-<a href='#rbuildfiles'><code>rbuildfiles</code></a>. These functions operate over the entire
-universe scope (which is why they don't make sense for normal Query).
-
-
-<p>
- Sky Query mode is activated by passing the following two flags:
- (<code>--universe_scope</code> or <code>--infer_universe_scope</code>) and
- <code>--order_output=no</code>.
- <code>--universe_scope=<target_pattern1>,...,<target_patternN></code> tells query to
- preload the transitive closure of the target pattern specified by the target patterns, which can
- be both additive and subtractive. All queries are then evaluated in this "scope". In particular,
- the <a href='#allrdeps'><code>allrdeps</code></a> and
- <a href='#rbuildfiles'><code>rbuildfiles</code></a> operators only return results from this scope.
- <code>--infer_universe_scope</code> tells Bazel to infer a value for <code>--universe_scope</code>
- from the query expression. This inferred value is the list of unique target patterns in the
- query expression, but this might not be what you want. For example:
-</p>
-<pre>
- bazel query --infer_universe_scope --order_output=no "allrdeps(//my:target)"
-</pre>
-<p>
- The list of unique target patterns in this query expression is <code>["//my:target"]</code>, so
- Bazel treats this the same as the invocation:
-</p>
-<pre>
- bazel query --universe_scope=//my:target --order_output=no "allrdeps(//my:target)"
-</pre>
-<p>
- But the result of that query with <code>--universe_scope</code> is only <code>//my:target</code>;
- none of the reverse dependencies of <code>//my:target</code> will be in the universe, by
- construction! On the other hand, consider:
-<pre>
- bazel query --infer_universe_scope --order_output=no "tests(//a/... + b/...) intersect allrdeps(siblings(rbuildfiles(my/starlark/file.bzl)))"
-</pre>
-<p>
- This is a meaningful query invocation that is trying to compute the test targets in the
- <a href='#tests'><code>tests</code></a> expansion of the targets under some directories that
- transitively depend on targets whose definition uses a certain <code>.bzl</code> file. Here,
- <code>--infer_universe_scope</code> is a convenience, especially in the case where the choice of
- <code>--universe_scope</code> would otherwise require you to parse the query expression yourself.
-</p>
-<p>
- So, for query expressions that use universe-scoped operators like
- <a href='#allrdeps'><code>allrdeps</code></a> and
- <a href='#rbuildfiles'><code>rbuildfiles</code></a> be sure to use
- <code>--infer_universe_scope</code> only if its behavior is what you want.
-</p>
-
-<p>
- Sky Query has some advantages and disadvantages compared to the default query. The main
- disadvantage is that it cannot order its output according to graph order, and thus certain
- <a href='#output-formats'>output formats</a> are forbidden. Its advantages are that it provides
- two operators (<a href='#allrdeps'><code>allrdeps</code></a> and
- <a href='#rbuildfiles'><code>rbuildfiles</code></a>) that are not available in the default query.
- As well, Sky Query does its work by introspecting the
- <a href='https://bazel.build/designs/skyframe.html'>Skyframe</a> graph, rather than creating a new
- graph, which is what the default implementation does. Thus, there are some circumstances in which
- it is faster and uses less memory.
-</p>
-
-<h2 id='expressions'>Expressions: Syntax and semantics of the grammar</h2>
-
-<p>
- This is the grammar of the Bazel query language, expressed in EBNF
- notation:
-</p>
-
-
-<pre>expr ::= <var>word</var>
- | let <var>name</var> = <var>expr</var> in <var>expr</var>
- | (<var>expr</var>)
- | <var>expr</var> intersect <var>expr</var>
- | <var>expr</var> ^ <var>expr</var>
- | <var>expr</var> union <var>expr</var>
- | <var>expr</var> + <var>expr</var>
- | <var>expr</var> except <var>expr</var>
- | <var>expr</var> - <var>expr</var>
- | set(<var>word</var> *)
- | <var>word</var> '(' <var>int</var> | <var>word</var> | <var>expr</var> ... ')'
-</pre>
-
-<p>
- The following sections describe each of the productions of this grammar in order.
-</p>
-
-<h3 id="target-patterns">Target patterns</h3>
-<pre>expr ::= <var>word</var></pre>
-<p>
- Syntactically, a <em>target pattern</em> is just a word. It
- is interpreted as an (unordered) set of targets. The simplest
- target pattern is a label,
- which identifies a single target (file or rule). For example, the
- target pattern <code>//foo:bar</code> evaluates to a set
- containing one element, the target, the <code>bar</code>
- rule.
-</p>
-
-<p>
- Target patterns generalize labels to include wildcards over packages
- and targets. For example, <code>foo/...:all</code> (or
- just <code>foo/...</code>) is a target pattern that evaluates to a
- set containing all <em>rules</em> in every package recursively
- beneath the <code>foo</code> directory;
- <code>bar/baz:all</code> is a target pattern that
- evaluates to a set containing all the rules in the
- <code>bar/baz</code> package, but not its subpackages.
-</p>
-
-<p>
- Similarly, <code>foo/...:*</code> is a target pattern that evaluates
- to a set containing all <em>targets</em> (rules <em>and</em> files) in
- every package recursively beneath the <code>foo</code> directory;
- <code>bar/baz:*</code> evaluates to a set containing
- all the targets in the
- <code>bar/baz</code> package, but not its subpackages.
-</p>
-
-<p>
- Because the <code>:*</code> wildcard matches files as well as rules,
- it is often more useful than <code>:all</code> for queries.
- Conversely, the <code>:all</code> wildcard (implicit in target
- patterns like <code>foo/...</code>) is typically more useful for
- builds.
-</p>
-
-<p>
- <code>bazel query</code> target patterns work the same as
- <code>bazel build</code> build targets do;
- refer to <a href='user-manual.html#target-patterns'>Target Patterns</a>
- in the Bazel User Manual for further details, or type <code>bazel
- help target-syntax</code>.
-
-</p>
-
-<p>
- Target patterns may evaluate to a singleton set (in the case of a
- label), to a set containing many elements (as in the case of
- <code>foo/...</code>, which has thousands of elements) or to the
- empty set, if the target pattern matches no targets.
-</p>
-
-<p>
- All nodes in the result of a target pattern expression are correctly
- ordered relative to each other according to the dependency relation.
- So, the result of <code>foo:*</code> is not just the set of targets
- in package <code>foo</code>, it is also the <em>graph</em> over
- those targets. (No guarantees are made about the relative ordering
- of the result nodes against other nodes.) See the section
- on <a href='#graph-order'>graph order</a> for more details.
-</p>
-
-<h3 id="variables">Variables</h3>
-<pre>expr ::= let <var>name</var> = <var>expr</var><sub>1</sub> in <var>expr</var><sub>2</sub>
- | <var>$name</var></pre>
-<p>
- The Bazel query language allows definitions of and references to
- variables. The
- result of evaluation of a <code>let</code> expression is the same as
- that of <var>expr</var><sub>2</sub>, with all free occurrences of
- variable <var>name</var> replaced by the value of
- <var>expr</var><sub>1</sub>.
-</p>
-
-<p>
- For example, <code>let v = foo/... in allpaths($v, //common)
- intersect $v</code> is equivalent to the <code>allpaths(foo/...,
- //common) intersect foo/...</code>.
-</p>
-
-<p>
- An occurrence of a variable reference <code>name</code> other than in
- an enclosing <code>let <var>name</var> = ...</code> expression is an
- error. In other words, toplevel query expressions cannot have free
- variables.
-</p>
-
-<p>
- In the above grammar productions, <code>name</code> is like
- <em>word</em>, but with the additional constraint that it be a legal
- identifier in the C programming language. References to the variable
- must be prepended with the "$" character.
-</p>
-
-<p>
- Each <code>let</code> expression defines only a single variable,
- but you can nest them.
-</p>
-
-<p>
- (Both <a
- href='#target-patterns'>target patterns</a> and variable references
- consist of just a single token, a word, creating a syntactic
- ambiguity. However, there is no semantic ambiguity, because the
- subset of words that are legal variable names is disjoint from the
- subset of words that are legal target patterns.)
-</p>
-
-<p>
- (Technically speaking, <code>let</code> expressions do not increase
- the expressiveness of the query language: any query expressible in
- the language can also be expressed without them. However, they
- improve the conciseness of many queries, and may also lead to more
- efficient query evaluation.)
-</p>
-
-<h3 id="parentheses">Parenthesized expressions</h3>
-<pre>expr ::= (<var>expr</var>)</pre>
-
-<p>
- Parentheses associate subexpressions to force an
- order of evaluation.
- A parenthesized expression evaluates
- to the value of its argument.
-</p>
-
-<h3 id="set-operations">Algebraic set operations:
- intersection, union, set difference</h3>
-
-<pre>expr ::= <var>expr</var> intersect <var>expr</var>
- | <var>expr</var> ^ <var>expr</var>
- | <var>expr</var> union <var>expr</var>
- | <var>expr</var> + <var>expr</var>
- | <var>expr</var> except <var>expr</var>
- | <var>expr</var> - <var>expr</var>
-</pre>
-
-<p>
- These three operators compute the usual set operations over their
- arguments. Each operator has two forms, a nominal form such
- as <code>intersect</code> and a symbolic form such
- as <code>^</code>. Both forms are equivalent;
- the symbolic forms are quicker to type. (For clarity, the rest of
- this manual uses the nominal forms.) For example,
-</p>
-
-<pre>foo/... except foo/bar/...</pre>
-
- evaluates to the set of targets that match
- <code>foo/...</code> but not
- <code>foo/bar/...</code> . Equivalently:
-
-<pre>foo/... - foo/bar/...</pre>
-
- The <code>intersect</code> (<code>^</code>)
- and <code>union</code> (<code>+</code>) operations are commutative
- (symmetric); <code>except</code> (<code>-</code>) is
- asymmetric. The parser treats all three operators as
- left-associative and of equal precedence, so you might want parentheses.
- For example, the first two of these expressions are
- equivalent, but the third is not:
-
-<pre>x intersect y union z
-(x intersect y) union z
-x intersect (y union z)</pre>
-
-<p>
- <b>Recommendation:</b> Use parentheses where there is
- any danger of ambiguity in reading a query expression.
-</p>
-
-<h3 id="set">Read targets from an external source: set</h3>
-<pre>expr ::= set(<var>word</var> *) </pre>
-<p>
- The <code>set(<var>a</var> <var>b</var> <var>c</var> ...)</code>
- operator computes the union of a set of zero or
- more <a href='#target-patterns'>target patterns</a>, separated by
- whitespace (no commas).
-</p>
-
-<p>
- In conjunction with the Bourne shell's <code>$(...)</code>
- feature, <code>set()</code> provides a means of saving the results
- of one query in a regular text file, manipulating that text file
- using other programs (e.g. standard UNIX shell tools), and then
- introducing the result back into the query tool as a value for
- further processing. For example:
-</p>
-<pre>
- bazel query deps(//my:target) --output=label | grep ... | sed ... | awk ... > foo
- bazel query "kind(cc_binary, set($(<foo)))"
-</pre>
-<p>
- In the next example, <code>kind(cc_library,
- deps(//some_dir/foo:main, 5))</code> is effectively computed
- by filtering on the <code>maxrank</code> values using
- an <code>awk</code> program.
-</p>
-<pre>
- bazel query 'deps(//some_dir/foo:main)' --output maxrank |
- awk '($1 < 5) { print $2;} ' > foo
- bazel query "kind(cc_library, set($(<foo)))"
-</pre>
-<p>
- In these examples, <code>$(<foo)</code> is a shorthand
- for <code>$(cat foo)</code>, but shell commands other
- than <code>cat</code> may be used too—such as
- the previous <code>awk</code> command.
-</p>
-
-<p>
- Note, <code>set()</code> introduces no graph ordering constraints,
- so path information may be lost when saving and reloading sets of
- nodes using it. See the <a href='#graph-order'>graph order</a>
- section below for more detail.
-</p>
-
-<h2 id="functions">Functions</h2>
-<pre>expr ::= <var>word</var> '(' <var>int</var> | <var>word</var> | <var>expr</var> ... ')'</pre>
-<p>
- The query language defines several functions. The name of the function
- determines the number and type of arguments it requires. The following
- functions are available:
-</p>
-
-<code><!-- keep this alphabetically sorted -->
-<a href="#path-operators">allpaths</a><br/>
-<a href="#attr">attr</a><br/>
-
-<a href="#buildfiles">buildfiles</a><br/>
-<a href="#rbuildfiles">rbuildfiles</a><br/>
-
-<a href="#deps">deps</a><br/>
-<a href="#filter">filter</a><br/>
-<a href="#kind">kind</a><br/>
-<a href="#labels">labels</a><br/>
-<a href="#loadfiles">loadfiles</a><br/>
-<a href="#rdeps">rdeps</a><br/>
-<a href="#allrdeps">allrdeps</a><br/>
-<a href="#same_pkg_direct_rdeps">same_pkg_direct_rdeps</a><br/>
-<a href="#siblings">siblings</a><br/>
-<a href="#some">some</a><br/>
-<a href="#path-operators">somepath</a><br/>
-<a href="#tests">tests</a><br/>
-<a href="#visible">visible</a><br/>
-</code>
-
-<h3 id="deps">Transitive closure of dependencies: deps</h3>
-<pre>expr ::= deps(<var>expr</var>)
- | deps(<var>expr</var>, <var>depth</var>)</pre>
-<p>
- The <code>deps(<var>x</var>)</code> operator evaluates to the graph
- formed by the transitive closure of dependencies of its argument set
- <var>x</var>. For example, the value of <code>deps(//foo)</code> is
- the dependency graph rooted at the single node <code>foo</code>,
- including all its dependencies. The value of
- <code>deps(foo/...)</code> is the dependency graphs whose roots are
- all rules in every package beneath the <code>foo</code> directory.
- Please note that 'dependencies' means only rule and file targets
- in this context, therefore the <code>BUILD</code> and Starlark files needed to
- create these targets are not included here. For that you should use the
- <a href="#buildfiles"><code>buildfiles</code></a> operator.
-</p>
-
-<p>
- The resulting graph is ordered according to the dependency relation.
- See the section on <a href='#graph-order'>graph order</a> for more
- details.
-</p>
-
-<p>
- The <code>deps</code> operator accepts an optional second argument,
- which is an integer literal specifying an upper bound on the depth
- of the search. So <code>deps(foo:*, 0)</code> returns all targets
- in the <code>foo</code> package, while <code>deps(foo:*, 1)</code>
- further includes the direct prerequisites of any target in the
- <code>foo</code> package, and <code>deps(foo:*, 2)</code> further
- includes the nodes directly reachable from the nodes in
- <code>deps(foo:*, 1)</code>, and so on.
- (These numbers correspond to the ranks shown in
- the <a href='#output-ranked'><code>minrank</code></a> output
- format.) If the <var>depth</var> parameter is omitted, the search
- is unbounded, i.e. it computes the reflexive transitive closure of
- prerequsites.
-</p>
-
-<h3 id="rdeps">Transitive closure of reverse dependencies: rdeps</h3>
-<pre>expr ::= rdeps(<var>expr</var>, <var>expr</var>)
- | rdeps(<var>expr</var>, <var>expr</var>, <var>depth</var>)</pre>
-<p>
- The <code>rdeps(<var>u</var>, <var>x</var>)</code> operator evaluates
- to the reverse dependencies of the argument set <var>x</var> within the
- transitive closure of the universe set <var>u</var>.
-</p>
-
-<p>
- The resulting graph is ordered according to the dependency relation. See the
- section on <a href='#graph-order'>graph order</a> for more details.
-</p>
-
-<p>
- The <code>rdeps</code> operator accepts an optional third argument,
- which is an integer literal specifying an upper bound on the depth of the
- search. The resulting graph will only include nodes within a distance of the
- specified depth from any node in the argument set. So
- <code>rdeps(//foo, //common, 1)</code> evaluates to all nodes in the
- transitive closure of <code>//foo</code> that directly depend on
- <code>//common</code>. (These numbers correspond to the ranks shown in the
- <a href='#output-ranked'><code>minrank</code></a> output format.) If the
- <var>depth</var> parameter is omitted, the search is unbounded.
-</p>
-
-<h3 id="allrdeps">Transitive closure of all reverse dependencies: allrdeps</h3>
-<pre>expr ::= allrdeps(<var>expr</var>)
- | allrdeps(<var>expr</var>, <var>depth</var>)</pre>
-<b>Only available with <a href='#sky-query'>Sky Query</a></b><br/>
-<p>
- The <code>allrdeps</code> operator behaves just like the <a href='#rdeps'><code>rdeps</code></a>
- operator, except that the "universe set" is whatever the <code>--universe_scope</code> flag
- evaluated to, instead of being separately specified. Thus, if
- <code>--universe_scope=//foo/...</code> was passed, then <code>allrdeps(//bar)</code> is
- equivalent to <code>rdeps(//foo/..., //bar)</code>.
-</p>
-
-<h3 id="same_pkg_direct_rdeps">Direct reverse dependencies in the same package: same_pkg_direct_rdeps</h3>
-<pre>expr ::= same_pkg_direct_rdeps(<var>expr</var>)</pre>
-<p>
- The <code>same_pkg_direct_rdeps(<var>x</var>)</code> operator evalutes to the full set of targets
- that are in the same package as a target in the argument set, and which directly depend on it.
-</p>
-
-<h3 id="siblings">Dealing with a target's package: siblings</h3>
-<pre>expr ::= siblings(<var>expr</var>)</pre>
-<p>
- The <code>siblings(<var>x</var>)</code> operator evalutes to the full set of targets that are in
- the same package as a target in the argument set.
-</p>
-
-<h3 id="some">Arbitrary choice: some</h3>
-<pre>expr ::= some(<var>expr</var>)</pre>
-<p>
- The <code>some(<var>x</var>)</code> operator selects one target
- arbitrarily from its argument set <var>x</var>, and evaluates to a
- singleton set containing only that target. For example, the
- expression <code>some(//foo:main union //bar:baz)</code>
- evaluates to a set containing either <code>//foo:main</code> or
- <code>//bar:baz</code>—though which one is not defined.
-</p>
-
-<p>
- If the argument is a singleton, then <code>some</code>
- computes the identity function: <code>some(//foo:main)</code> is
- equivalent to <code>//foo:main</code>.
-
- It is an error if the specified argument set is empty, as in the
- expression <code>some(//foo:main intersect //bar:baz)</code>.
-</p>
-
-<h3 id="path-operators">Path operators: somepath, allpaths</h3>
-<pre>expr ::= somepath(<var>expr</var>, <var>expr</var>)
- | allpaths(<var>expr</var>, <var>expr</var>)</pre>
-<p>
- The <code>somepath(<var>S</var>, <var>E</var>)</code> and
- <code>allpaths(<var>S</var>, <var>E</var>)</code> operators compute
- paths between two sets of targets. Both queries accept two
- arguments, a set <var>S</var> of starting points and a set
- <var>E</var> of ending points. <code>somepath</code> returns the
- graph of nodes on <em>some</em> arbitrary path from a target in
- <var>S</var> to a target in <var>E</var>; <code>allpaths</code>
- returns the graph of nodes on <em>all</em> paths from any target in
- <var>S</var> to any target in <var>E</var>.
-</p>
-
-<p>
- The resulting graphs are ordered according to the dependency relation.
- See the section on <a href='#graph-order'>graph order</a> for more
- details.
-</p>
-
-<table style='margin: auto'><tr>
-<td style='text-align: center'>
-<!-- digraph somepath1 {
- graph [size="4,4"]
- node [label="",shape=circle];
- n1;
- n2 [fillcolor="pink",style=filled];
- n3 [fillcolor="pink",style=filled];
- n4 [fillcolor="pink",style=filled,label="E"];
- n5; n6;
- n7 [fillcolor="pink",style=filled,label="S1"];
- n8 [label="S2"];
- n9;
- n10 [fillcolor="pink",style=filled];
-
- n1 -> n2;
- n2 -> n3;
- n7 -> n5;
- n7 -> n2;
- n5 -> n6;
- n6 -> n4;
- n8 -> n6;
- n6 -> n9;
- n2 -> n10;
- n3 -> n10;
- n10 -> n4;
- n10 -> n11;
-} -->
-<img src="images/somepath1.svg" alt="somepath1.svg" style="margin-left=10;" />
-<p><code>somepath(S1 + S2, E)</code>,<br/>one possible result.</p>
-</td>
-<td style='padding: 40px; text-align: center'>
-<!-- digraph somepath2 {
- graph [size="4,4"]
- node [label="",shape=circle];
-
- n1; n2; n3;
- n4 [fillcolor="pink",style=filled,label="E"];
- n5;
- n6 [fillcolor="pink",style=filled];
- n7 [label="S1"];
- n8 [fillcolor="pink",style=filled,label="S2"];
- n9; n10;
-
- n1 -> n2;
- n2 -> n3;
- n7 -> n5;
- n7 -> n2;
- n5 -> n6;
- n6 -> n4;
- n8 -> n6;
- n6 -> n9;
- n2 -> n10;
- n3 -> n10;
- n10 -> n4;
- n10 -> n11;
-} -->
-<img src="images/somepath2.svg" alt="somepath2.svg" style="margin-left=10;" />
-<p><code>somepath(S1 + S2, E)</code>,<br/>another possible result.</p>
-</td>
-<td style='text-align: center'>
-<!-- digraph allpaths {
- graph [size="4,4"]
- node [label="",shape=circle];
- n1;
- n2 [fillcolor="pink",style=filled];
- n3 [fillcolor="pink",style=filled];
- n4 [fillcolor="pink",style=filled,label="E"];
- n5 [fillcolor="pink",style=filled];
- n6 [fillcolor="pink",style=filled];
- n7 [fillcolor="pink",style=filled, label="S1"];
- n8 [fillcolor="pink",style=filled, label="S2"];
- n9;
- n10 [fillcolor="pink",style=filled];
-
- n1 -> n2;
- n2 -> n3;
- n7 -> n5;
- n7 -> n2;
- n5 -> n6;
- n6 -> n4;
- n8 -> n6;
- n6 -> n9;
- n2 -> n10;
- n3 -> n10;
- n10 -> n4;
- n10 -> n11;
-} -->
-<img src="images/allpaths.svg" alt="allpaths.svg" style="margin-left=10;" />
-<p><code>allpaths(S1 + S2, E)</code>.</p>
-</td>
-</tr></table>
-
-<h3 id="kind">Target kind filtering: kind</h3>
-<pre>expr ::= kind(<var>word</var>, <var>expr</var>) </pre>
-<p>
- The <code>kind(<var>pattern</var>, <var>input</var>)</code> operator
- applies a filter to a set of targets, and discards those targets
- that are not of the expected kind. The <var>pattern</var> parameter specifies
- what kind of target to match.
-</p>
-<ul>
-<li><b>file</b> patterns can be one of:
- <ul>
- <li><code>source file</code>
- <li><code>generated file</code>
- </ul>
-<li><b>rule</b> patterns can be one of:
- <ul>
- <li><code><var>ruletype</var> rule</code>
- <li><code><var>ruletype</var></code><br>
- Where <var>ruletype</var> is a build rule. The difference between these
- forms is that including "rule" causes the <a href="#regex">regular expression</a> match for
- <var>ruletype</var> to be anchored.
- </ul>
-<li><b>package group</b> patterns should simply be:
- <ul>
- <li><code>package group</code>
- </ul>
-</ul>
-<p>
- For example, the kinds for the four targets defined by the <code>BUILD</code> file
- (for package <code>p</code>) shown below are illustrated in the
- table:
-</p>
-
-<table style='margin: auto'><tr><td style='padding-right:10px'>
-<pre style='margin-left: 0em;'>
-genrule(
- name = "a",
- srcs = ["a.in"],
- outs = ["a.out"],
- cmd = "...",
-)
-</pre>
-</td><td>
- <table class="grid">
- <tr><th>Target</th><th>Kind</th></tr>
- <tr class='tt'><td>//p:a</td><td>genrule rule</td></tr>
- <tr class='tt'><td>//p:a.in</td><td>source file</td></tr>
- <tr class='tt'><td>//p:a.out</td><td>generated file</td></tr>
- <tr class='tt'><td>//p:BUILD</td><td>source file</td></tr>
- </table>
-</td></tr></table>
-
-<p>
- Thus, <code>kind("cc_.* rule", foo/...)</code> evaluates to the set
- of all <code>cc_library</code>, <code>cc_binary</code>, etc,
- rule targets beneath
- <code>foo</code>, and <code>kind("source file", deps(//foo))</code>
- evaluates to the set of all source files in the transitive closure
- of dependencies of the <code>//foo</code> target.
-</p>
-
-<p>
- Quotation of the <var>pattern</var> argument is often required
- because without it, many <a href="#regex">regular expressions</a>, such as <code>source
- file</code> and <code>.*_test</code>, are not considered words by
- the parser.
-</p>
-
-<p>
- When matching for <code>package group</code>, targets ending in
- <code>:all</code> may not yield any results.
- Use <code>:all-targets</code> instead.
-</p>
-
-<h3 id="filter">Target name filtering: filter</h3>
-<pre>expr ::= filter(<var>word</var>, <var>expr</var>) </pre>
-<p>
- The <code>filter(<var>pattern</var>, <var>input</var>)</code> operator
- applies a filter to a set of targets, and discards targets whose
- labels (in absolute form) do not match the pattern; it
- evaluates to a subset of its input.
-</p>
-
-<p>
- The first argument, <var>pattern</var> is a word containing a
- <a href="#regex">regular expression</a> over target names. A <code>filter</code> expression
- evaluates to the set containing all targets <var>x</var> such that
- <var>x</var> is a member of the set <var>input</var> and the
- label (in absolute form, e.g. <code>//foo:bar</code>)
- of <var>x</var> contains an (unanchored) match
- for the regular expression <var>pattern</var>. Since all
- target names start with <code>//</code>, it may be used as an alternative
- to the <code>^</code> regular expression anchor.
-</p>
-
-<p>
- This operator often provides a much faster and more robust alternative to the
- <code>intersect</code> operator. For example, in order to see all
- <code>bar</code> dependencies of the <code>//foo:foo</code> target, one could
- evaluate
-</p>
-<pre>deps(//foo) intersect //bar/...</pre>
-<p>
- This statement, however, will require parsing of all <code>BUILD</code> files in the
- <code>bar</code> tree, which will be slow and prone to errors in
- irrelevant <code>BUILD</code> files. An alternative would be:
-</p>
-<pre>filter(//bar, deps(//foo))</pre>
-<p>
- which would first calculate the set of <code>//foo</code> dependencies and
- then would filter only targets matching the provided pattern—in other
- words, targets with names containing <code>//bar</code> as a
- substring.
-</p>
-
-<p>
- Another common use of the <code>filter(<var>pattern</var>,
- <var>expr</var>)</code> operator is to filter specific files by their
- name or extension. For example,
-</p>
-<pre>filter("\.cc$", deps(//foo))</pre>
-<p>
- will provide a list of all <code>.cc</code> files used to build
- <code>//foo</code>.
-</p>
-
-<h3 id="attr">Rule attribute filtering: attr</h3>
-<pre>expr ::= attr(<var>word</var>, <var>word</var>, <var>expr</var>) </pre>
-<p>
- The <code>attr(<var>name</var>, <var>pattern</var>, <var>input</var>)</code>
- operator applies a filter to a set of targets, and discards targets that
- are not rules, rule targets that do not have attribute <var>name</var>
- defined or rule targets where the attribute value does not match the provided
- <a href="#regex">regular expression</a> <var>pattern</var>; it evaluates to a subset of its input.
-</p>
-
-<p>
- The first argument, <var>name</var> is the name of the rule attribute that
- should be matched against the provided <a href="#regex">regular expression</a> pattern. The second
- argument, <var>pattern</var> is a regular expression over the attribute
- values. An <code>attr</code> expression evaluates to the set containing all
- targets <var>x</var> such that <var>x</var> is a member of the set
- <var>input</var>, is a rule with the defined attribute <var>name</var> and
- the attribute value contains an (unanchored) match for the regular expression
- <var>pattern</var>. Please note, that if <var>name</var> is an optional
- attribute and rule does not specify it explicitly then default attribute
- value will be used for comparison. For example,
-</p>
-<pre>attr(linkshared, 0, deps(//foo))</pre>
-<p>
- will select all <code>//foo</code> dependencies that are allowed to have a
- linkshared attribute (e.g., <code>cc_binary</code> rule) and have it either
- explicitly set to 0 or do not set it at all but default value is 0 (e.g. for
- <code>cc_binary</code> rules).
-</p>
-
-<p>
- List-type attributes (such as <code>srcs</code>, <code>data</code>, etc) are
- converted to strings of the form <code>[value<sub>1</sub>, ..., value<sub>n</sub>]</code>,
- starting with a <code>[</code> bracket, ending with a <code>]</code> bracket
- and using "<code>, </code>" (comma, space) to delimit multiple values.
- Labels are converted to strings by using the absolute form of the
- label. For example, an attribute <code>deps=[":foo",
- "//otherpkg:bar", "wiz"]</code> would be converted to the
- string <code>[//thispkg:foo, //otherpkg:bar, //thispkg:wiz]</code>.
- Brackets
- are always present, so the empty list would use string value <code>[]</code>
- for matching purposes. For example,
-</p>
-<pre>attr("srcs", "\[\]", deps(//foo))</pre>
-<p>
- will select all rules among <code>//foo</code> dependencies that have an
- empty <code>srcs</code> attribute, while
-</p>
-<pre>attr("data", ".{3,}", deps(//foo))</pre>
-<p>
- will select all rules among <code>//foo</code> dependencies that specify at
- least one value in the <code>data</code> attribute (every label is at least
- 3 characters long due to the <code>//</code> and <code>:</code>).
-</p>
-
-<h3 id="visible">Rule visibility filtering: visible</h3>
-<pre>expr ::= visible(<var>expr</var>, <var>expr</var>) </pre>
-<p>
- The <code>visible(<var>predicate</var>, <var>input</var>)</code> operator
- applies a filter to a set of targets, and discards targets without the
- required visibility.
-</p>
-
-<p>
- The first argument, <var>predicate</var>, is a set of targets that all targets
- in the output must be visible to. A <var>visible</var> expression
- evaluates to the set containing all targets <var>x</var> such that <var>x</var>
- is a member of the set <var>input</var>, and for all targets <var>y</var> in
- <var>predicate</var> <var>x</var> is visible to <var>y</var>. For example:
-</p>
-<pre>visible(//foo, //bar:*)</pre>
-<p>
- will select all targets in the package <code>//bar</code> that <code>//foo</code>
- can depend on without violating visibility restrictions.
-</p>
-
-<h3 id="labels">Evaluation of rule attributes of type label: labels</h3>
-<pre>expr ::= labels(<var>word</var>, <var>expr</var>) </pre>
-<p>
- The <code>labels(<var>attr_name</var>, <var>inputs</var>)</code>
- operator returns the set of targets specified in the
- attribute <var>attr_name</var> of type "label" or "list of label" in
- some rule in set <var>inputs</var>.
-</p>
-
-<p>
- For example, <code>labels(srcs, //foo)</code> returns the set of
- targets appearing in the <code>srcs</code> attribute of
- the <code>//foo</code> rule. If there are multiple rules
- with <code>srcs</code> attributes in the <var>inputs</var> set, the
- union of their <code>srcs</code> is returned.
-</p>
-
-<h3 id="tests">Expand and filter test_suites: tests</h3>
-<pre>expr ::= tests(<var>expr</var>)</pre>
-<p>
- The <code>tests(<var>x</var>)</code> operator returns the set of all test
- rules in set <var>x</var>, expanding any <code>test_suite</code> rules into
- the set of individual tests that they refer to, and applying filtering by
- <code>tag</code> and <code>size</code>.
-
- By default, query evaluation
- ignores any non-test targets in all <code>test_suite</code> rules. This can be
- changed to errors with the <code>--strict_test_suite</code> option.
-</p>
-
-<p>
- For example, the query <code>kind(test, foo:*)</code> lists all
- the <code>*_test</code> and <code>test_suite</code> rules
- in the <code>foo</code> package. All the results are (by
- definition) members of the <code>foo</code> package. In contrast,
- the query <code>tests(foo:*)</code> will return all of the
- individual tests that would be executed by <code>bazel test
- foo:*</code>: this may include tests belonging to other packages,
- that are referenced directly or indirectly
- via <code>test_suite</code> rules.
-</p>
-
-
-<h3 id="buildfiles">Package definition files: buildfiles</h3>
-<pre>expr ::= buildfiles(<var>expr</var>)</pre>
-<p>
- The <code>buildfiles(<var>x</var>)</code> operator returns the set
- of files that define the packages of each target in
- set <var>x</var>; in other words, for each package, its <code>BUILD</code> file,
- plus any .bzl files it references via <code>load</code>. Note that this
- also returns the <code>BUILD</code> files of the packages containing these
- <code>load</code>ed files.
-</p>
-
-<p>
- This operator is typically used when determining what files or
- packages are required to build a specified target, often in conjunction with
- the <a href='#output-package'><code>--output package</code></a>
- option, below). For example,
-</p>
-<pre>bazel query 'buildfiles(deps(//foo))' --output package</pre>
-<p>
- returns the set of all packages on which <code>//foo</code> transitively
- depends.
-</p>
-
-<p>
- (Note: a naive attempt at the above query would omit
- the <code>buildfiles</code> operator and use only <code>deps</code>,
- but this yields an incorrect result: while the result contains the
- majority of needed packages, those packages that contain only files
- that are <code>load()</code>'ed will be missing.
-</p>
-
-<p style="background-color:#cc6666;">
- <strong>WARNING:</strong> Bazel pretends each <code>.bzl</code> file produced by
- <code>buildfiles</code> has a corresponding target (for example, file <code>a/b.bzl</code> =>
- target <code>//a:b.bzl</code>), but this isn't necessarily the case. Therefore,
- <code>buildfiles</code> doesn't compose well with other query operators and its results can be
- misleading when formatted in a structured way, such as
- <code><a href='#output-xml'>--output=xml</a></code>.
-</p>
-
-<h3 id="rbuildfiles">Package definition files: rbuildfiles</h3>
-<pre>expr ::= rbuildfiles(<var>word</var>, ...)</pre>
-<b>Only available with <a href='#sky-query'>Sky Query</a></b><br/>
-<p>
- The <code>rbuildfiles</code> operator takes a comma-separated list of path fragments and returns
- the set of <code>BUILD</code> files that transitively depend on these path fragments. For instance, if
- <code>//foo</code> is a package, then <code>rbuildfiles(foo/BUILD)</code> will return the
- <code>//foo:BUILD</code> target. If the <code>foo/BUILD</code> file has
- <code>load('//bar:file.bzl'...</code> in it, then <code>rbuildfiles(bar/file.bzl)</code> will
- return the <code>//foo:BUILD</code> target, as well as the targets for any other <code>BUILD</code> files that
- load <code>//bar:file.bzl</code>
-</p>
-
-<p>
- The scope of the <scope>rbuildfiles</scope> operator is the universe specified by the
- <code>--universe_scope</code> flag. Files that do not correspond directly to <code>BUILD</code> files and <code>.bzl</code>
- files do not affect the results. For instance, source files (like <code>foo.cc</code>) are ignored,
- even if they are explicitly mentioned in the <code>BUILD</code> file. Symlinks, however, are respected, so that
- if <code>foo/BUILD</code> is a symlink to <code>bar/BUILD</code>, then
- <code>rbuildfiles(bar/BUILD)</code> will include <code>//foo:BUILD</code> in its results.
-</p>
-
-<p>
- The <code>rbuildfiles</code> operator is almost morally the inverse of the
- <a href='#buildfiles'><code>buildfiles</code></a> operator. However, this moral inversion
- holds more strongly in one direction: the outputs of <code>rbuildfiles</code> are just like the
- inputs of <code>buildfiles</code>; the former will only contain <code>BUILD</code> file targets in packages,
- and the latter may contain such targets. In the other direction, the correspondence is weaker. The
- outputs of the <code>buildfiles</code> operator are targets corresponding to all packages and <code>.bzl</code>
- files needed by a given input. However, the inputs of the <code>rbuildfiles</code> operator are
- not those targets, but rather the path fragments that correspond to those targets.
-</p>
-
-<h3 id="loadfiles">Package definition files: loadfiles</h3>
-<pre>expr ::= loadfiles(<var>expr</var>)</pre>
-<p>
- The <code>loadfiles(<var>x</var>)</code> operator returns the set of
- Starlark files that are needed to load the packages of each target in
- set <var>x</var>. In other words, for each package, it returns the
- .bzl files that are referenced from its <code>BUILD</code> files.
-</p>
-
-<p style="background-color:#cc6666;">
- <strong>WARNING:</strong> Bazel pretends each of these .bzl files has a corresponding target
- (for example, file <code>a/b.bzl</code> => target <code>//a:b.bzl</code>), but this isn't
- necessarily the case. Therefore, <code>loadfiles</code> doesn't compose well with other query
- operators and its results can be misleading when formatted in a structured way, such as
- <code><a href='#output-xml'>--output=xml</a></code>.
-</p>
-
-<h2 id='output-formats'>Output formats</h2>
-
-<p>
- <code>bazel query</code> generates a graph.
- You specify the content, format, and ordering by which
- <code>bazel query</code> presents this graph
- by means of the <code>--output</code>
- command-line option.
- </p>
-
-<p>
- When running with <a href='#sky-query'>Sky Query</a>, only output formats that are compatible with
- unordered output are allowed. Specifically, <code>graph</code>, <code>minrank</code>, and
- <code>maxrank</code> output formats are forbidden.
-</p>
-
-<p>
- Some of the output formats accept additional options. The name of
- each output option is prefixed with the output format to which it
- applies, so <code>--graph:factored</code> applies only
- when <code>--output=graph</code> is being used; it has no effect if
- an output format other than <code>graph</code> is used. Similarly,
- <code>--xml:line_numbers</code> applies only when <code>--output=xml</code>
- is being used.
-</p>
-
-<h3 id='result-order'>On the ordering of results</h3>
-
-<p>
- Although query expressions always follow the "<a href='#graph-order'>law of
- conservation of graph order</a>", <i>presenting</i> the results may be done
- in either a dependency-ordered or unordered manner. This does <b>not</b>
- influence the targets in the result set or how the query is computed. It only
- affects how the results are printed to stdout. Moreover, nodes that are
- equivalent in the dependency order may or may not be ordered alphabetically.
- The <code>--order_output</code> flag can be used to control this behavior.
- (The <code>--[no]order_results</code> flag has a subset of the functionality
- of the <code>--order_output</code> flag and is deprecated.)
-</p>
-<p>
- The default value of this flag is <code>auto</code>, which prints results in <b>lexicographical
- order</b>. However, when <code>somepath(a,b)</code> is used, the results will be printed in
- <code>deps</code> order instead.
-</p>
-<p>
- When this flag is <code>no</code> and <code>--output</code> is one of
- <code>build</code>, <code>label</code>, <code>label_kind</code>,
- <code>location</code>, <code>package</code>, <code>proto</code>, or
- <code>xml</code>, the outputs will be printed in arbitrary order. <b>This is
- generally the fastest option</b>. It is not supported though when
- <code>--output</code> is one of <code>graph</code>, <code>minrank</code> or
- <code>maxrank</code>: with these formats, bazel will always print results
- ordered by the dependency order or rank.
-</p>
-<p>
- When this flag is <code>deps</code>, bazel prints results in some topological order—that is,
- dependencies first. However, nodes that are unordered by the dependency order
- (because there is no path from either one to the other) may be printed in any order.
-</p>
-<p>
- When this flag is <code>full</code>, bazel prints nodes in a fully deterministic (total) order.
- First, all nodes are sorted alphabetically. Then, each node in the list is used as the start of a
- post-order depth-first search in which outgoing edges to unvisited nodes are traversed in
- alphabetical order of the successor nodes. Finally, nodes are printed in the reverse of the order
- in which they were visited.
-</p>
-<p>
- Printing nodes in this order may be slower, so it should be used only when determinism is
- important.
-</p>
-
-<h3 id="output-build">Print the source form of targets as they would appear in BUILD</h3>
-<pre>--output build</pre>
-<p>
- With this option, the representation of each target is as if it were
- hand-written in the BUILD language. All variables and function calls
- (e.g. glob, macros) are expanded, which is useful for seeing the effect
- of Starlark macros. Additionally, each effective rule reports a
- <code>generator_name</code> and/or <code>generator_function</code>) value,
- giving the name of the macro that was evaluated to produce the effective
- rule.
-</p>
-<p>
- Although the output uses the same syntax as <code>BUILD</code> files, it is not
- guaranteed to produce a valid <code>BUILD</code> file.
-</p>
-
-<h3 id="output-label">Print the label of each target</h3>
-<pre>--output label</pre>
-<p>
- With this option, the set of names (or <em>labels</em>) of each target
- in the resulting graph is printed, one label per line, in
- topological order (unless <code>--noorder_results</code> is specified, see
- <a href='#result-order'>notes on the ordering of results</a>).
- (A topological ordering is one in which a graph
- node appears earlier than all of its successors.) Of course there
- are many possible topological orderings of a graph (<em>reverse
- postorder</em> is just one); which one is chosen is not specified.
-
- When printing the output of a <code>somepath</code> query, the order
- in which the nodes are printed is the order of the path.
-</p>
-
-<p>
- Caveat: in some corner cases, there may be two distinct targets with
- the same label; for example, a <code>sh_binary</code> rule and its
- sole (implicit) <code>srcs</code> file may both be called
- <code>foo.sh</code>. If the result of a query contains both of
- these targets, the output (in <code>label</code> format) will appear
- to contain a duplicate. When using the <code>label_kind</code> (see
- below) format, the distinction becomes clear: the two targets have
- the same name, but one has kind <code>sh_binary rule</code> and the
- other kind <code>source file</code>.
-</p>
-
-<h3 id="output-label_kind">Print the label and kind of each target</h3>
-<pre>--output label_kind</pre>
-<p>
- Like <code>label</code>, this output format prints the labels of
- each target in the resulting graph, in topological order, but it
- additionally precedes the label by
- the <a href='#kind'><em>kind</em></a> of the target.
-</p>
-
-<h3 id="output-ranked">Print the label of each target, in rank order</h3>
-<pre>--output minrank
---output maxrank</pre>
-<p>
- Like <code>label</code>, the <code>minrank</code>
- and <code>maxrank</code> output formats print the labels of each
- target in the resulting graph, but instead of appearing in
- topological order, they appear in rank order, preceded by their
- rank number. These are unaffected by the result ordering
- <code>--[no]order_results</code> flag (see <a href='#result-order'>notes on
- the ordering of results</a>).
-</p>
-
-<p>
- There are two variants of this format: <code>minrank</code> ranks
- each node by the length of the shortest path from a root node to it.
- "Root" nodes (those which have no incoming edges) are of rank 0,
- their successors are of rank 1, etc. (As always, edges point from a
- target to its prerequisites: the targets it depends upon.)
-</p>
-
-<p>
- <code>maxrank</code> ranks each node by the length of the longest
- path from a root node to it. Again, "roots" have rank 0, all other
- nodes have a rank which is one greater than the maximum rank of all
- their predecessors.
-</p>
-
-<p>
- All nodes in a cycle are considered of equal rank. (Most graphs are
- acyclic, but cycles do occur
- simply because <code>BUILD</code> files contain erroneous cycles.)
-</p>
-
-<p>
- These output formats are useful for discovering how deep a graph is.
- If used for the result of a <code>deps(x)</code>, <code>rdeps(x)</code>,
- or <code>allpaths</code> query, then the rank number is equal to the
- length of the shortest (with <code>minrank</code>) or longest
- (with <code>maxrank</code>) path from <code>x</code> to a node in
- that rank. <code>maxrank</code> can be used to determine the
- longest sequence of build steps required to build a target.
-</p>
-
-<p>
- Please note, the ranked output of a <code>somepath</code> query is
- basically meaningless because <code>somepath</code> doesn't
- guarantee to return either a shortest or a longest path, and it may
- include "transitive" edges from one path node to another that are
- not direct edges in original graph.
-</p>
-
-<p>
- For example, the graph on the left yields the outputs on the right
- when <code>--output minrank</code> and <code>--output maxrank</code>
- are specified, respectively.
-</p>
-
-<table style='margin: auto'><tr><td>
-<!-- digraph mygraph {
- node [shape=box];
-"//a:a" -> "//a:a.cc"
-"//b:b" -> "//a:a"
-"//b:b" -> "//b:b.cc"
-"//c:c" -> "//b:b"
-"//c:c" -> "//a:a"
-} -->
-<img src="images/out-ranked.svg" alt="out-ranked.svg" style="margin-left=10;" />
-</td><td>
-<pre>
-minrank
-
-0 //c:c
-1 //b:b
-1 //a:a
-2 //b:b.cc
-2 //a:a.cc
-</pre>
-</td><td>
-<pre>
-maxrank
-
-0 //c:c
-1 //b:b
-2 //a:a
-2 //b:b.cc
-3 //a:a.cc
-</pre>
-</td></tr></table>
-
-<h3 id="output-location">Print the location of each target</h3>
-<pre>--output location</pre>
-<p>
- Like <code>label_kind</code>, this option prints out, for each
- target in the result, the target's kind and label, but it is
- prefixed by a string describing the location of that target, as a
- filename and line number. The format resembles the output of
- <code>grep</code>. Thus, tools that can parse the latter (such as Emacs
- or vi) can also use the query output to step through a series of
- matches, allowing the Bazel query tool to be used as a
- dependency-graph-aware "grep for BUILD files".
-</p>
-
-<p>
- The location information varies by target kind (see the <a
- href='#kind'>kind</a> operator). For rules, the
- location of the rule's declaration within the <code>BUILD</code> file is printed.
- For source files, the location of line 1 of the actual file is
- printed. For a generated file, the location of the rule that
- generates it is printed. (The query tool does not have sufficient
- information to find the actual location of the generated file, and
- in any case, it might not exist if a build has not yet been
- performed.)
-</p>
-
-<h3 id="output-package">Print the set of packages</h3>
-<pre>--output package</pre>
-<p>
- This option prints the name of all packages to which
- some target in the result set belongs. The names are printed in
- lexicographical order; duplicates are excluded. Formally, this
- is a <em>projection</em> from the set of labels (package, target) onto
- packages.
-</p>
-
-<p>
- Packages in external repositories are formatted as
- <code>@repo//foo/bar</code> while packages in the main repository are
- formatted as <code>foo/bar</code>.
-</p>
-<p>
- In conjunction with the <code>deps(...)</code> query, this output
- option can be used to find the set of packages that must be checked
- out in order to build a given set of targets.
-</p>
-
-<h3 id="output-graph">Display a graph of the result</h3>
-<pre>--output graph</pre>
-<p>
- This option causes the query result to be printed as a directed
- graph in the popular AT&T GraphViz format. Typically the
- result is saved to a file, such as <code>.png</code> or <code>.svg</code>.
- (If the <code>dot</code> program is not installed on your workstation, you
- can install it using the command <code>sudo apt-get install graphviz</code>.)
- See the example section below for a sample invocation.
-</p>
-
-<p>
- This output format is particularly useful for <code>allpaths</code>,
- <code>deps</code>, or <code>rdeps</code> queries, where the result
- includes a <em>set of paths</em> that cannot be easily visualized when
- rendered in a linear form, such as with <code>--output label</code>.
-</p>
-
-<p>
- By default, the graph is rendered in a <em>factored</em> form. That is,
- topologically-equivalent nodes are merged together into a single
- node with multiple labels. This makes the graph more compact
- and readable, because typical result graphs contain highly
- repetitive patterns. For example, a <code>java_library</code> rule
- may depend on hundreds of Java source files all generated by the
- same <code>genrule</code>; in the factored graph, all these files
- are represented by a single node. This behavior may be disabled
- with the <code>--nograph:factored</code> option.
-</p>
-
-<h4><code>--graph:node_limit <var>n</var></code></h4>
-<p>
- The option specifies the maximum length of the label string for a
- graph node in the output. Longer labels will be truncated; -1
- disables truncation. Due to the factored form in which graphs are
- usually printed, the node labels may be very long. GraphViz cannot
- handle labels exceeding 1024 characters, which is the default value
- of this option. This option has no effect unless
- <code>--output=graph</code> is being used.
-</p>
-
-<h4><code>--[no]graph:factored</code></h4>
-<p>
- By default, graphs are displayed in factored form, as explained
- <a href='#output-graph'>above</a>.
- When <code>--nograph:factored</code> is specified, graphs are
- printed without factoring. This makes visualization using GraphViz
- impractical, but the simpler format may ease processing by other
- tools (e.g. grep). This option has no effect
- unless <code>--output=graph</code> is being used.
-</p>
-
-<h3 id="output-xml">XML</h3>
-<pre>--output xml</pre>
-<p>
- This option causes the resulting targets to be printed in an XML
- form. The output starts with an XML header such as this
-</p>
-<pre>
- <?xml version="1.0" encoding="UTF-8"?>
- <query version="2">
-</pre>
-<!-- The docs should continue to document version 2 into perpetuity,
- even if we add new formats, to handle clients synced to old CLs. -->
-<p>
- and then continues with an XML element for each target
- in the result graph, in topological order (unless
- <a href='#result-order'>unordered results</a> are requested),
- and then finishes with a terminating
-</p>
-<pre>
-</query>
-</pre>
-<p>
- Simple entries are emitted for targets of <code>file</code>
- kind:
-</p>
-<pre>
- <source-file name='//foo:foo_main.cc' .../>
- <generated-file name='//foo:libfoo.so' .../>
-</pre>
-<p>
- But for rules, the XML is structured and contains definitions of all
- the attributes of the rule, including those whose value was not
- explicitly specified in the rule's <code>BUILD</code> file.
-</p>
-<p>
- Additionally, the result includes <code>rule-input</code> and
- <code>rule-output</code> elements so that the topology of the
- dependency graph can be reconstructed without having to know that,
- for example, the elements of the <code>srcs</code> attribute are
- forward dependencies (prerequisites) and the contents of the
- <code>outs</code> attribute are backward dependencies (consumers).
-
- <code>rule-input</code> elements for <a
- href='#implicit_deps'>implicit dependencies</a> are suppressed if
- <code>--noimplicit_deps</code> is specified.
-</p>
-<pre>
- <rule class='cc_binary rule' name='//foo:foo' ...>
- <list name='srcs'>
- <label value='//foo:foo_main.cc'/>
- <label value='//foo:bar.cc'/>
- ...
- </list>
- <list name='deps'>
- <label value='//common:common'/>
- <label value='//collections:collections'/>
- ...
- </list>
- <list name='data'>
- ...
- </list>
- <int name='linkstatic' value='0'/>
- <int name='linkshared' value='0'/>
- <list name='licenses'/>
- <list name='distribs'>
- <distribution value="INTERNAL" />
- </list>
- <rule-input name="//common:common" />
- <rule-input name="//collections:collections" />
- <rule-input name="//foo:foo_main.cc" />
- <rule-input name="//foo:bar.cc" />
- ...
- </rule>
-</pre>
-
-<p>
- Every XML element for a target contains a <code>name</code>
- attribute, whose value is the target's label, and
- a <code>location</code> attribute, whose value is the target's
- location as printed by the <a href='output-location'><code>--output
- location</code></a>.
-</p>
-
-<h4><code>--[no]xml:line_numbers</code></h4>
-<p>
- By default, the locations displayed in the XML output contain line numbers.
- When <code>--noxml:line_numbers</code> is specified, line numbers are not
- printed.
-</p>
-
-<h4><code>--[no]xml:default_values</code></h4>
-<p>
- By default, XML output does not include rule attribute whose value
- is the default value for that kind of attribute (e.g. because it
- were not specified in the <code>BUILD</code> file, or the default value was
- provided explicitly). This option causes such attribute values to
- be included in the XML output.
-</p>
-
-
-<h3 id="regex">Regular expressions</h3>
-
-Regular expressions in the query language use the Java regex library, so you can use the
-full syntax for <a href="https://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html"><code>java.util.regex.Pattern</code></a>.
-
-
-<h3 id="external-repos">Querying with external repositories</h3>
-
-<p>
- If the build depends on rules from external repositories (defined in the
- WORKSPACE file) then query results will include these dependencies. For
- example, if <code>//foo:bar</code> depends on <code>//external:some-lib</code>
- and <code>//external:some-lib</code> is bound to
- <code>@other-repo//baz:lib</code>, then
- <code>bazel query 'deps(//foo:bar)'</code>
- will list both <code>@other-repo//baz:lib</code> and
- <code>//external:some-lib</code> as dependencies.
-</p>
-
-<p>
- External repositories themselves are not dependencies of a build. That is, in
- the example above, <code>//external:other-repo</code> is not a dependency. It
- can be queried for as a member of the <code>//external</code> package, though,
- for example:
-<p>
-
-<pre>
- # Querying over all members of //external returns the repository.
- bazel query 'kind(http_archive, //external:*)'
- //external:other-repo
-
- # ...but the repository is not a dependency.
- bazel query 'kind(http_archive, deps(//foo:bar))'
- INFO: Empty results
-</pre>
diff --git a/site/docs/skylark/build-style.md b/site/docs/skylark/build-style.md
deleted file mode 100644
index 1423152..0000000
--- a/site/docs/skylark/build-style.md
+++ /dev/null
@@ -1,244 +0,0 @@
----
-layout: documentation
-title: BUILD style guide
----
-
-<div style="background-color: #EFCBCB; color: #AE2B2B; border: 1px solid #AE2B2B; border-radius: 5px; border-left: 10px solid #AE2B2B; padding: 0.5em;">
-<b>IMPORTANT:</b> The Bazel docs have moved! Please update your bookmark to <a href="https://bazel.build/rules/build-style" style="color: #0000EE;">https://bazel.build/rules/build-style</a>
-<p/>
-You can <a href="https://blog.bazel.build/2022/02/17/Launching-new-Bazel-site.html" style="color: #0000EE;">read about</a> the migration, and let us <a href="https://forms.gle/onkAkr2ZwBmcbWXj7" style="color: #0000EE;">know what you think</a>.
-</div>
-
-
-# BUILD Style Guide
-
-
-`BUILD` file formatting follows the same approach as Go, where a standardized
-tool takes care of most formatting issues.
-[Buildifier](https://github.com/bazelbuild/buildifier) is a tool that parses and
-emits the source code in a standard style. Every `BUILD` file is therefore
-formatted in the same automated way, which makes formatting a non-issue during
-code reviews. It also makes it easier for tools to understand, edit, and
-generate `BUILD` files.
-
-`BUILD` file formatting must match the output of `buildifier`.
-
-
-## Formatting example
-
-```python
-# Test code implementing the Foo controller.
-package(default_testonly = True)
-
-py_test(
- name = "foo_test",
- srcs = glob(["*.py"]),
- data = [
- "//data/production/foo:startfoo",
- "//foo",
- "//third_party/java/jdk:jdk-k8",
- ],
- flaky = True,
- deps = [
- ":check_bar_lib",
- ":foo_data_check",
- ":pick_foo_port",
- "//pyglib",
- "//testing/pybase",
- ],
-)
-```
-
-## File structure
-
-**Recommendation**: Use the following order (every element is optional):
-
-* Package description (a comment)
-
-* All `load()` statements
-
-* The `package()` function.
-
-* Calls to rules and macros
-
-Buildifier makes a distinction between a standalone comment and a comment
-attached to an element. If a comment is not attached to a specific element, use
-an empty line after it. The distinction is important when doing automated
-changes (for example, to keep or remove a comment when deleting a rule).
-
-```python
-# Standalone comment (e.g. to make a section in a file)
-
-# Comment for the cc_library below
-cc_library(name = "cc")
-```
-
-## References to targets in the current package
-
-Files should be referred to by their paths relative to the package directory
-(without ever using up-references, such as `..`). Generated files should be
-prefixed with "`:`" to indicate that they are not sources. Source files
-should not be prefixed with `:`. Rules should be prefixed with `:`. For
-example, assuming `x.cc` is a source file:
-
-```python
-cc_library(
- name = "lib",
- srcs = ["x.cc"],
- hdrs = [":gen_header"],
-)
-
-genrule(
- name = "gen_header",
- srcs = [],
- outs = ["x.h"],
- cmd = "echo 'int x();' > $@",
-)
-```
-
-## Target naming
-
-Target names should be descriptive. If a target contains one source file,
-the target should generally have a name derived from that source (e.g., a
-`cc_library` for `chat.cc` could be named "`chat`", or a `java_library` for
-`DirectMessage.java` could be named "`direct_message`").
-
-The eponymous target for a package (the target with the same name as the
-containing directory) should provide the functionality described by the
-directory name. If there is no such target, do not create an eponymous
-target.
-
-Prefer using the short name when referring to an eponymous target (`//x`
-instead of `//x:x`). If you are in the same package, prefer the local
-reference (`:x` instead of `//x`).
-
-Avoid using "reserved" target names which have special meaning. This includes
-"`all`", "`__pkg__`", and "`__subpackages__`", these names have special
-semantics and can cause confusion and unexpected behaviors when they are used.
-
-In the absence of a prevailing team convention these are some non-binding
-recommendations that are broadly used at Google:
-
-* In general, use ["snake_case"](https://en.wikipedia.org/wiki/Snake_case)
- * For a java_library with one src this would mean using a name that is not
- the same as the filename without the extension
- * For Java \*\_binary and \*\_test rules use
- ["Upper CamelCase"](https://en.wikipedia.org/wiki/Camel_case). This
- allows for the target name to match one of the srcs. For
- java\_test, this makes it possible for the test\_class attribute to be
- inferred from the name of the target.
-* If there are multiple variants of a particular target then add a suffix to
- disambiguate (i.e. :foo_dev, :foo_prod or :bar_x86, :bar_x64)
-* \_test targets should be suffixed with "\_test", "\_unittest", "Test", or
- "Tests"
-* Avoid meaningless suffixes like "\_lib" or "\_library" (unless necessary to
- avoid conflicts between a \_library target and its corresponding \_binary)
-* For proto related targets:
- * proto_library targets should have names ending in "\_proto"
- * Languages specific \*\_proto_library rules should match the underlying
- proto but replace "\_proto" with a language specific suffix such as:
- * cc_proto_library: "\_cc\_proto"
- * java_proto_library: "\_java\_proto"
- * java_lite_proto_library: "\_java_proto_lite"
-
-## Visibility
-
-Visibility should be scoped as tightly as possible, while still allowing access
-by tests and reverse dependencies. Use `__pkg__` and `__subpackages__` as
-appropriate.
-
-Avoid setting package `default_visibility` to `//visibility:public`.
-`//visibility:public` should be individually set only for targets in the
-project's public API. These could be libraries that are designed to be depended
-on by external projects or binaries that could be used by an external project's
-build process.
-
-## Dependencies
-
-Dependencies should be restricted to direct dependencies (dependencies
-needed by the sources listed in the rule). Do not list transitive
-dependencies.
-
-Package-local dependencies should be listed first and referred to in a way
-compatible with the
-[References to targets in the current package](#references-to-targets-in-the-current-package)
-section above (not by their absolute package name).
-
-Prefer to list dependencies directly, as a single list. Putting the "common"
-dependencies of several targets into a variable reduces maintainability, makes
-it impossible for tools to change the dependencies of a target and can lead to
-unused dependencies.
-
-## Globs
-
-Indicate "no targets" with `[]`. Do not use a glob that matches nothing: it
-is more error-prone and less obvious than an empty list.
-
-### Recursive
-
-Do not use recursive globs to match source files (for example,
-`glob(["**/*.java"])`).
-
-Recursive globs make `BUILD` files difficult to reason about because they skip
-subdirectories containing `BUILD` files.
-
-Recursive globs are generally less efficient than having a `BUILD` file per
-directory with a dependency graph defined between them as this enables better
-remote caching and parallelism.
-
-It is good practice to author a `BUILD` file in each directory and define a
-dependency graph between them.
-
-### Non-recursive
-
-Non-recursive globs are generally acceptable.
-
-## Other conventions
-
- * Use uppercase and underscores to declare constants (e.g. `GLOBAL_CONSTANT`),
- use lowercase and underscores to declare variables (e.g. `my_variable`).
-
- * Labels should never be split, even if they are longer than 79 characters.
- Labels should be string literals whenever possible. Rationale: It makes
- find and replace easy. It also improves readability.
-
- * The value of the name attribute should be a literal constant string (except
- in macros). *Rationale*: External tools use the name attribute to refer a
- rule. They need to find rules without having to interpret code.
-
- * When setting boolean-type attributes, use boolean values, not integer values.
- For legacy reasons, rules will still convert integers to booleans as needed,
- but this is discouraged. *Rationale*: `flaky = 1` could be misread as saying
- "deflake this target by rerunning it once". `flaky = True` unambiguously says
- "this test is flaky".
-
-## Differences with Python style guide
-
-Although compatibility with
-[Python style guide](https://www.python.org/dev/peps/pep-0008/) is a goal, there
-are a few differences:
-
- * No strict line length limit. Long comments and long strings are often split
- to 79 columns, but it is not required. It should not be enforced in code
- reviews or presubmit scripts. *Rationale*: Labels can be long and exceed this
- limit. It is common for `BUILD` files to be generated or edited by tools,
- which does not go well with a line length limit.
-
- * Implicit string concatenation is not supported. Use the `+` operator.
- *Rationale*: `BUILD` files contain many string lists. It is easy to forget a
- comma, which leads to a complete different result. This has created many bugs
- in the past. [See also this discussion.](https://lwn.net/Articles/551438/)
-
- * Use spaces around the `=` sign for keywords arguments in rules. *Rationale*:
- Named arguments are much more frequent than in Python and are always on a
- separate line. Spaces improve readability. This convention has been around
- for a long time, and it is not worth modifying all existing `BUILD` files.
-
- * By default, use double quotation marks for strings. *Rationale*: This is not
- specified in the Python style guide, but it recommends consistency. So we
- decided to use only double-quoted strings. Many languages use double-quotes
- for string literals.
-
- * Use a single blank line between two top-level definitions. *Rationale*: The
- structure of a `BUILD` file is not like a typical Python file. It has only
- top-level statements. Using a single-blank line makes `BUILD` files shorter.
diff --git a/site/docs/skylark/bzl-style.md b/site/docs/skylark/bzl-style.md
deleted file mode 100644
index 8057e8d..0000000
--- a/site/docs/skylark/bzl-style.md
+++ /dev/null
@@ -1,220 +0,0 @@
----
-layout: documentation
-title: .bzl style guide
-category: extending
----
-
-<div style="background-color: #EFCBCB; color: #AE2B2B; border: 1px solid #AE2B2B; border-radius: 5px; border-left: 10px solid #AE2B2B; padding: 0.5em;">
-<b>IMPORTANT:</b> The Bazel docs have moved! Please update your bookmark to <a href="https://bazel.build/rules/bzl-style" style="color: #0000EE;">https://bazel.build/rules/bzl-style</a>
-<p/>
-You can <a href="https://blog.bazel.build/2022/02/17/Launching-new-Bazel-site.html" style="color: #0000EE;">read about</a> the migration, and let us <a href="https://forms.gle/onkAkr2ZwBmcbWXj7" style="color: #0000EE;">know what you think</a>.
-</div>
-
-
-# .bzl style guide
-
-
-This page covers basic style guidelines for Starlark and also includes
-information on macros and rules.
-
-[Starlark](https://docs.bazel.build/versions/main/skylark/language.html) is a
-language that defines how software is built, and as such it is both a
-programming and a configuration language.
-
-You will use Starlark to write `BUILD` files, macros, and build rules. Macros
-and rules are essentially meta-languages - they define how `BUILD` files are
-written. `BUILD` files are intended to be simple and repetitive.
-
-All software is read more often than it is written. This is especially true for
-Starlark, as engineers read `BUILD` files to understand dependencies of their
-targets and details of their builds. This reading will often happen in passing,
-in a hurry, or in parallel to accomplishing some other task. Consequently,
-simplicity and readability are very important so that users can parse and
-comprehend `BUILD` files quickly.
-
-When a user opens a `BUILD` file, they quickly want to know the list of targets
-in the file; or review the list of sources of that C++ library; or remove a
-dependency from that Java binary. Each time you add a layer of abstraction, you
-make it harder for a user to do these tasks.
-
-`BUILD` files are also analyzed and updated by many different tools. Tools may
-not be able to edit your `BUILD` file if it uses abstractions. Keeping your
-`BUILD` files simple will allow you to get better tooling. As a code base grows,
-it becomes more and more frequent to do changes across many `BUILD` files in
-order to update a library or do a cleanup.
-
-**IMPORTANT:** Do not create a variable or macro just to avoid some amount of
-repetition in `BUILD` files. Your `BUILD` file should be easily readable both by
-developers and tools. The
-[DRY](https://en.wikipedia.org/wiki/Don%27t_repeat_yourself) principle doesn't
-really apply here.
-
-## General advice
-
-* Use [Buildifier](https://github.com/bazelbuild/buildtools/tree/master/buildifier#linter)
- as a formatter and linter.
-* Follow [testing guidelines](testing.md).
-
-## Style
-
-
-### Python style
-
-When in doubt, follow the
-[PEP 8 style guide](https://www.python.org/dev/peps/pep-0008/) where possible.
-In particular, use four rather than two spaces for indentation to follow the
-Python convention.
-
-Since
-[Starlark is not Python](https://docs.bazel.build/versions/main/skylark/language.md#differences-with-python),
-some aspects of Python style do not apply. For example, PEP 8 advises that
-comparisons to singletons be done with `is`, which is not an operator in
-Starlark.
-
-### Docstring
-
-Document files and functions using
-[docstrings](https://github.com/bazelbuild/buildtools/blob/master/WARNINGS.md#function-docstring).
-Use a docstring at the top of each `.bzl` file, and a docstring for each public
-function.
-
-### Document rules and aspects
-
-Rules and aspects, along with their attributes, as well as providers and their
-fields, should be documented using the `doc` argument.
-
-### Naming convention
-
-* Variables and function names use lowercase with words separated by
- underscores (`[a-z][a-z0-9_]*`), e.g. `cc_library`.
-* Top-level private values start with one underscore. Bazel enforces that
- private values cannot be used from other files. Local variables should not
- use the underscore prefix.
-
-### Line length
-
-As in `BUILD` files, there is no strict line length limit as labels can be long.
-When possible, try to use at most 79 characters per line (following Python's
-style guide, [PEP 8](https://www.python.org/dev/peps/pep-0008/)).
-
-### Keyword arguments
-
-In keyword arguments, spaces around the equal sign are preferred:
-
-```python
-def fct(name, srcs):
- filtered_srcs = my_filter(source = srcs)
- native.cc_library(
- name = name,
- srcs = filtered_srcs,
- testonly = True,
- )
-```
-
-### Boolean values
-
-Prefer values `True` and `False` (rather than of `1` and `0`) for boolean values
-(e.g. when using a boolean attribute in a rule).
-
-### Use print only for debugging
-
-Do not use the `print()` function in production code; it is only intended for
-debugging, and will spam all direct and indirect users of your `.bzl` file. The
-only exception is that you may submit code that uses `print()` if it is disabled
-by default and can only be enabled by editing the source -- for example, if all
-uses of `print()` are guarded by `if DEBUG:` where `DEBUG` is hardcoded to
-`False`. Be mindful of whether these statements are useful enough to justify
-their impact on readability.
-
-
-## Macros
-
-A macro is a function which instantiates one or more rules during the loading
-phase. In general, use rules whenever possible instead of macros. The build
-graph seen by the user is not the same as the one used by Bazel during the
-build - macros are expanded *before Bazel does any build graph analysis.*
-
-Because of this, when something goes wrong, the user will need to understand
-your macro's implementation to troubleshoot build problems. Additionally, `bazel
-query` results can be hard to interpret because targets shown in the results
-come from macro expansion. Finally, aspects are not aware of macros, so tooling
-depending on aspects (IDEs and others) might fail.
-
-A safe use for macros is for defining additional targets intended to be
-referenced directly at the Bazel CLI or in BUILD files: In that case, only the
-*end users* of those targets need to know about them, and any build problems
-introduced by macros are never far from their usage.
-
-For macros that define internal targets (implementation details of the macro
-which are not supposed to be referred to at the CLI or depended on by targets
-not instantiated by that macro), follow these best practices:
-
-* A macro should take a `name` argument and define a target with that name.
- That target becomes that macro's *main target*.
-* All other targets defined by a macro should have their names preceded with
- an underscore (`_`), followed by the name attribute. For instance, if the
- macro is supplied with the name *resources*, internal targets should have
- names beginning with *_resources*. They should also have restricted
- visibility.
-* The `name` should only be used to derive names of targets defined by the
- macro, and not for anything else. For example, don't use the name to derive
- a dependency or input file that is not generated by the macro itself.
-* All the targets created in the macro should be coupled in some way to the
- main target.
-* Keep the parameter names in the macro consistent. If a parameter is passed
- as an attribute value to the main target, keep its name the same. If a macro
- parameter serves the same purpose as a common rule attribute, such as
- `deps`, name as you would the attribute (see below).
-* When calling a macro, use only keyword arguments. This is consistent with
- rules, and greatly improves readability.
-
-Engineers often write macros when the Starlark API of relevant rules is
-insufficient for their specific use case, regardless of whether the rule is
-defined within Bazel in native code, or in Starlark. If you're facing this
-problem, ask the rule author if they can extend the API to accomplish your
-goals.
-
-As a rule of thumb, the more macros resemble the rules, the better.
-
-## Rules
-
-* Rules, aspects, and their attributes should use lower_case names ("snake
- case").
-* Rule names are nouns that describe the main kind of artifact produced by the
- rule, from the point of view of its dependencies (or for leaf rules, the
- user). This is not necessarily a file suffix. For instance, a rule that
- produces C++ artifacts meant to be used as Python extensions might be called
- `py_extension`. For most languages, typical rules include:
- * `*_library` - a compilation unit or "module".
- * `*_binary` - a target producing an executable or a deployment unit.
- * `*_test` - a test target. This can include multiple tests. Expect all
- tests in a `*_test` target to be variations on the same theme, for
- example, testing a single library.
- * `*_import`: a target encapsulating a pre-compiled artifact, such as a
- `.jar`, or a `.dll` that is used during compilation.
-* Use consistent names and types for attributes. Some generally applicable
- attributes include:
- * `srcs`: `label_list`, allowing files: source files, typically
- human-authored.
- * `deps`: `label_list`, typically *not* allowing files: compilation
- dependencies.
- * `data`: `label_list`, allowing files: data files, such as test data etc.
- * `runtime_deps`: `label_list`: runtime dependencies that are not needed
- for compilation.
-* For any attributes with non-obvious behavior (for example, string templates
- with special substitutions, or tools that are invoked with specific
- requirements), provide documentation using the `doc` keyword argument to the
- attribute's declaration (`attr.label_list()` or similar).
-* Rule implementation functions should almost always be private functions
- (named with a leading underscore). A common style is to give the
- implementation function for `myrule` the name `_myrule_impl`.
-* Pass information between your rules using a well-defined
- [provider](https://docs.bazel.build/versions/main/skylark/rules.html#providers)
- interface. Declare and document provider fields.
-* Design your rule with extensibility in mind. Consider that other rules might
- want to interact with your rule, access your providers, and reuse the
- actions you create.
-* Follow
- [performance guidelines](https://docs.bazel.build/versions/main/skylark/performance.html)
- in your rules.
-
diff --git a/site/docs/skylark/config.md b/site/docs/skylark/config.md
deleted file mode 100644
index ab930e2..0000000
--- a/site/docs/skylark/config.md
+++ /dev/null
@@ -1,816 +0,0 @@
----
-layout: documentation
-title: Configurations
-category: extending
----
-
-<div style="background-color: #EFCBCB; color: #AE2B2B; border: 1px solid #AE2B2B; border-radius: 5px; border-left: 10px solid #AE2B2B; padding: 0.5em;">
-<b>IMPORTANT:</b> The Bazel docs have moved! Please update your bookmark to <a href="https://bazel.build/rules/config" style="color: #0000EE;">https://bazel.build/rules/config</a>
-<p/>
-You can <a href="https://blog.bazel.build/2022/02/17/Launching-new-Bazel-site.html" style="color: #0000EE;">read about</a> the migration, and let us <a href="https://forms.gle/onkAkr2ZwBmcbWXj7" style="color: #0000EE;">know what you think</a>.
-</div>
-
-
-# Configurations
-
-
-This page covers the benefits and basic usage of Starlark configurations,
-Bazel's API for customizing how your project builds. It includes how to define
-build settings and provides examples.
-
-This makes it possible to:
-
-* define custom flags for your project, obsoleting the need for
- [`--define`](../configurable-attributes.html#custom-keys)
-* write
- [transitions](lib/transition.html#transition) to configure deps in different configurations
- than their parents (e.g. `--compilation_mode=opt` or `--cpu=arm`)
-
-* bake better defaults into rules (e.g. automatically build `//my:android_app`
- with a specified SDK)
-
-and more, all completely from .bzl files (no Bazel release required). See the
-`bazelbuild/examples` repo for
-[examples](https://github.com/bazelbuild/examples/tree/HEAD/rules/starlark_configurations).
-
-<!-- [TOC] -->
-
-## User-defined build settings
-A build setting is a single piece of
-[configuration](rules.html#configurations)
-information. Think of a configuration as a key/value map. Setting `--cpu=ppc`
-and `--copt="-DFoo"` produces a configuration that looks like
-`{cpu: ppc, copt: "-DFoo"}`. Each entry is a build setting.
-
-Traditional flags like `cpu` and `copt` are native settings i.e.
-their keys are defined and their values are set inside native bazel java code.
-Bazel users can only read and write them via the command line
-and other APIs maintained natively. Changing native flags, and the APIs
-that expose them, requires a bazel release. User-defined build
-settings are defined in `.bzl` files (and thus, don't need a bazel release to
-register changes). They also can be set via the command line
-(if they're designated as `flags`, see more below), but can also be
-set via [user-defined transitions](#user-defined-transitions).
-
-### Defining build settings
-
-[End to end example](https://github.com/bazelbuild/examples/tree/HEAD/rules/starlark_configurations/basic_build_setting)
-
-#### The `build_setting` `rule()` parameter
-
-Build settings are rules like any other rule and are differentiated using the
-Starlark `rule()` function's `build_setting`
-[attribute](lib/globals.html#rule.build_setting).
-
-```python
-# example/buildsettings/build_settings.bzl
-string_flag = rule(
- implementation = _impl,
- build_setting = config.string(flag = True)
-)
-```
-
-The `build_setting` attribute takes a function that designates the type of the
-build setting. The type is limited to a set of basic Starlark types like
-`bool` and `string`. See the `config` module
- [documentation](lib/config.html) for details. More complicated typing can be done in the rule's
-implementation function. More on this below.
-
-The `config` module's functions takes an optional boolean parameter, `flag`, which is
-set to false by default. if `flag` is set to true, the build setting can be set
-on the command line by users as well as internally by rule writers via default
-values and
-[transitions](lib/transition.html#transition).
-Not all settings should be settable by users. For example if you as a rule
-writer have some debug mode that you'd like to turn on inside test rules,
-you don't want to give users the ability to indiscriminately turn on that
-feature inside other non-test rules.
-
-#### Using ctx.build_setting_value
-
-Like all rules, build setting rules have [implementation functions](rules.html#implementation-function).
-The basic Starlark-type value of the build settings can be accessed via the
-`ctx.build_setting_value` method. This method is only available to
- [`ctx`](lib/ctx.html) objects of build setting rules. These implementation methods can directly
-forward the build settings value or do additional work on it, like type checking
-or more complex struct creation. Here's how you would implement an `enum`-typed
-build setting:
-
-```python
-# example/buildsettings/build_settings.bzl
-TemperatureProvider = provider(fields = ['type'])
-
-temperatures = ["HOT", "LUKEWARM", "ICED"]
-
-def _impl(ctx):
- raw_temperature = ctx.build_setting_value
- if raw_temperature not in temperatures:
- fail(str(ctx.label) + " build setting allowed to take values {"
- + ", ".join(temperatures) + "} but was set to unallowed value "
- + raw_temperature)
- return TemperatureProvider(type = raw_temperature)
-
-temperature = rule(
- implementation = _impl,
- build_setting = config.string(flag = True)
-)
-```
-
-Note: if a rule depends on a build setting, it will receive whatever providers
-the build setting implementation function returns, like any other dependency.
-But all other references to the value of the build setting (e.g. in transitions)
-will see its basic Starlark-typed value, not this post implementation function
-value.
-
-#### Defining multi-set string flags
-String settings have an additional `allow_multiple` parameter which allows the
-flag to be set multiple times on the command line or in bazelrcs. Their default
-value is still set with a string-typed attribute:
-
-```python
-# example/buildsettings/build_settings.bzl
-allow_multiple_flag = rule(
- implementation = _impl,
- build_setting = config.string(flag = True, allow_multiple = True)
-)
-```
-
-```python
-# example/buildsettings/BUILD
-load("//example/buildsettings:build_settings.bzl", "allow_multiple_flag")
-allow_multiple_flag(
- name = "roasts",
- build_setting_default = "medium"
-)
-```
-
-Each setting of the flag is treated as a single value:
-
-```shell
-$ bazel build //my/target --//example:roasts=blonde \
- --//example:roasts=medium,dark
-```
-
-The above is parsed to `{"//example:roasts": ["blonde", "medium,dark"]}` and
-`ctx.build_setting_value` returns the list `["blonde", "medium,dark"]`.
-
-#### Instantiating build settings
-
-Rules defined with the `build_setting` parameter have an implicit mandatory
-`build_setting_default` attribute. This attribute takes on the same type as
-declared by the `build_setting` param.
-
-```python
-# example/buildsettings/build_settings.bzl
-FlavorProvider = provider(fields = ['type'])
-
-def _impl(ctx):
- return FlavorProvider(type = ctx.build_setting_value)
-
-flavor = rule(
- implementation = _impl,
- build_setting = config.string(flag = True)
-)
-```
-
-```python
-# example/buildsettings/BUILD
-load("//example/buildsettings:build_settings.bzl", "flavor")
-flavor(
- name = "favorite_flavor",
- build_setting_default = "APPLE"
-)
-```
-
-### Predefined settings
-
-[End to end example](https://github.com/bazelbuild/examples/tree/HEAD/rules/starlark_configurations/use_skylib_build_setting)
-
-The
-[Skylib](https://github.com/bazelbuild/bazel-skylib)
-library includes a set of predefined settings you can instantiate without having
-to write custom Starlark.
-
-For example, to define a setting that accepts a limited set of string values:
-
-```python
-# example/BUILD
-load("@bazel_skylib//rules:common_settings.bzl", "string_flag")
-string_flag(
- name = "myflag",
- values = ["a", "b", "c"],
- build_setting_default = "a",
-)
-```
-
-For a complete list, see
-[Common build setting rules](https://github.com/bazelbuild/bazel-skylib/blob/main/rules/common_settings.bzl).
-
-### Using build settings
-
-#### Depending on build settings
-If a target would like to read a piece of configuration information, it can
-directly depend on the build setting via a regular attribute dependency.
-
-```python
-# example/rules.bzl
-load("//example/buildsettings:build_settings.bzl", "FlavorProvider")
-def _rule_impl(ctx):
- if ctx.attr.flavor[FlavorProvider].type == "ORANGE":
- ...
-
-drink_rule = rule(
- implementation = _rule_impl,
- attrs = {
- "flavor": attr.label()
- }
-)
-```
-
-```python
-# example/BUILD
-load("//example:rules.bzl", "drink_rule")
-load("//example/buildsettings:build_settings.bzl", "flavor")
-flavor(
- name = "favorite_flavor",
- build_setting_default = "APPLE"
-)
-drink_rule(
- name = "my_drink",
- flavor = ":favorite_flavor",
-)
-```
-
-Languages may wish to create a canonical set of build settings which all rules
-for that language depend on. Though the native concept of `fragments` no longer
-exists as a hardcoded object in Starlark configuration world, one way to
-translate this concept would be to use sets of common implicit attributes. For
-example:
-
-```python
-# kotlin/rules.bzl
-_KOTLIN_CONFIG = {
- "_compiler": attr.label(default = "//kotlin/config:compiler-flag"),
- "_mode": attr.label(default = "//kotlin/config:mode-flag"),
- ...
-}
-
-...
-
-kotlin_library = rule(
- implementation = _rule_impl,
- attrs = dicts.add({
- "library-attr": attr.string()
- }, _KOTLIN_CONFIG)
-)
-
-kotlin_binary = rule(
- implementation = _binary_impl,
- attrs = dicts.add({
- "binary-attr": attr.label()
- }, _KOTLIN_CONFIG)
-
-```
-
-#### Using build settings on the command line
-
-Similar to most native flags, you can use the command line to set build settings
-[that are marked as flags](#the-build-setting-rule-parameter). The build
-setting's name is its full target path using `name=value` syntax:
-
-```shell
-$ bazel build //my/target --//example:string_flag=some-value # allowed
-$ bazel build //my/target --//example:string_flag some-value # not allowed
-```
-
-Special boolean syntax is supported:
-
-```shell
-$ bazel build //my/target --//example:boolean_flag
-$ bazel build //my/target --no//example:boolean_flag
-```
-
-#### Using build setting aliases
-
-You can set an alias for your build setting target path to make it easier to read
-on the command line. Aliases function similarly to native flags and also make use
-of the double-dash option syntax.
-
-Set an alias by adding `--flag_alias=ALIAS_NAME=TARGET_PATH`
-to your `.bazelrc` . For example, to set an alias to `coffee`:
-
-```shell
-# .bazelrc
-build --flag_alias=coffee=//experimental/user/starlark_configurations/basic_build_setting:coffee-temp
-```
-
-Best Practice: Setting an alias multiple times results in the most recent
-one taking precedence. Use unique alias names to avoid unintended parsing results.
-
-To make use of the alias, type it in place of the build setting target path.
-With the above example of `coffee` set in the user's `.bazelrc`:
-
-```shell
-$ bazel build //my/target --coffee=ICED
-```
-
-instead of
-
-```shell
-$ bazel build //my/target --//experimental/user/starlark_configurations/basic_build_setting:coffee-temp=ICED
-```
-Best Practice: While it possible to set aliases on the command line, leaving them
-in a `.bazelrc` reduces command line clutter.
-
-### Label-typed build settings
-
-[End to end example](https://github.com/bazelbuild/examples/tree/HEAD/rules/starlark_configurations/label_typed_build_setting)
-
-Unlike other build settings, label-typed settings cannot be defined using the
-`build_setting` rule parameter. Instead, bazel has two built-in rules:
-`label_flag` and `label_setting`. These rules forward the providers of the
-actual target to which the build setting is set. `label_flag` and
-`label_setting` can be read/written by transitions and `label_flag` can be set
-by the user like other `build_setting` rules can. Their only difference is they
-can't customely defined.
-
-Label-typed settings will eventually replace the functionality of late-bound
-defaults. Late-bound default attributes are Label-typed attributes whose
-final values can be affected by configuration. In Starlark, this will replace
-the [`configuration_field`](lib/globals.html#configuration_field)
- API.
-
-```python
-# example/rules.bzl
-MyProvider = provider(fields = ["my_field"])
-
-def _dep_impl(ctx):
- return MyProvider(my_field = "yeehaw")
-
-dep_rule = rule(
- implementation = _dep_impl
-)
-
-def _parent_impl(ctx):
- if ctx.attr.my_field_provider[MyProvider].my_field == "cowabunga":
- ...
-
-parent_rule = rule(
- implementation = _parent_impl,
- attrs = { "my_field_provider": attr.label() }
-)
-
-```
-
-```python
-# example/BUILD
-load("//example:rules.bzl", "dep_rule", "parent_rule")
-
-dep_rule(name = "dep")
-
-parent_rule(name = "parent", my_field_provider = ":my_field_provider")
-
-label_flag(
- name = "my_field_provider",
- build_setting_default = ":dep"
-)
-```
-
-TODO(bazel-team): Expand supported build setting types.
-
-### Build settings and select()
-
-[End to end example](https://github.com/bazelbuild/examples/tree/HEAD/rules/starlark_configurations/select_on_build_setting)
-
-Users can configure attributes on build settings by using
- [`select()`](../be/functions.html#select). Build setting targets can be passed to the `flag_values` attribute of
-`config_setting`. The value to match to the configuration is passed as a
-`String` then parsed to the type of the build setting for matching.
-
-```python
-config_setting(
- name = "my_config",
- flag_values = {
- "//example:favorite_flavor": "MANGO"
- }
-)
-```
-
-
-## User-defined transitions
-
-A configuration
-[transition](lib/transition.html#transition)
-maps the transformation from one configured target to another within the
-build graph.
-
-> IMPORTANT: Transitions have [memory and performance impact](#memory-and-performance-considerations).
-> Rules that set them must include a special attribute:
->
-> ```python
-> "_allowlist_function_transition": attr.label(
-> default = "@bazel_tools//tools/allowlists/function_transition_allowlist"
-> )
-> ```
->
-> By adding transitions you can pretty easily explode the size of
-> your build graph. This sets an allowlist on the packages in which you can
-> create targets of this rule. The default value in the codeblock above
-> allowlists everything. But if you'd like to restrict who is using your rule,
-> you can set that attribute to point to your own custom allowlist.
-> Contact bazel-discuss@googlegroups.com if you'd like advice or assistance
-> understanding how transitions can affect on your build performance.
-
-### Defining
-
-Transitions define configuration changes between rules. For example, a request
-like "compile my dependency for a different CPU than its parent" is handled by a
-transition.
-
-Formally, a transition is a function from an input configuration to one or more
-output configurations. Most transitions are 1:1 e.g. "override the input
-configuration with `--cpu=ppc`". 1:2+ transitions can also exist but come
-with special restrictions.
-
-In Starlark, transitions are defined much like rules, with a defining
-`transition()`
-[function](lib/transition.html#transition)
-and an implementation function.
-
-```python
-# example/transitions/transitions.bzl
-def _impl(settings, attr):
- _ignore = (settings, attr)
- return {"//example:favorite_flavor" : "MINT"}
-
-hot_chocolate_transition = transition(
- implementation = _impl,
- inputs = [],
- outputs = ["//example:favorite_flavor"]
-)
-```
-The `transition()` function takes in an implementation function, a set of
-build settings to read(`inputs`), and a set of build settings to write
-(`outputs`). The implementation function has two parameters, `settings` and
-`attr`. `settings` is a dictionary {`String`:`Object`} of all settings declared
-in the `inputs` parameter to `transition()`.
-
-`attr` is a dictionary of attributes and values of the rule to which the
-transition is attached. When attached as an
-[outgoing edge transition](#outgoing-edge-transitions), the values of these
-attributes are all configured i.e. post-select() resolution. When attached as
-an [incoming edge transition](#incoming-edge-transitions), `attr` does not
-include any attributes that use a selector to resolve their value. If an
-incoming edge transition on `--foo` reads attribute `bar` and then also
-selects on `--foo` to set attribute `bar`, then there's a chance for the
-incoming edge transition to read the wrong value of `bar` in the transition.
-
-Note: since transitions are attached to rule definitions and `select()`s are
-attached to rule instantiations (i.e. targets), errors related to `select()`s on
-read attributes will pop up when users create targets rather than when rules are
-written. It may be worth taking extra care to communicate to rule users which
-attributes they should be wary of selecting on or taking other precautions.
-
-The implementation function must return a dictionary (or list of
-dictionaries, in the case of
-transitions with multiple output configurations)
-of new build settings values to apply. The returned dictionary keyset(s) must
-contain exactly the set of build settings passed to the `outputs`
-parameter of the transition function. This is true even if a build setting is
-not actually changed over the course of the transition - its original value must
-be explicitly passed through in the returned dictionary.
-
-### Defining 1:2+ transitions
-
-[End to end example](https://github.com/bazelbuild/examples/tree/HEAD/rules/starlark_configurations/multi_arch_binary)
-
-[Outgoing edge transitions](#outgoing-edge-transitions) can map a single input
-configuration to two or more output configurations. This is useful for defining
-rules that bundle multi-architecture code.
-
-1:2+ transitions are defined by returning a list of dictionaries in the
-transition implementation function.
-
-```python
-# example/transitions/transitions.bzl
-def _impl(settings, attr):
- _ignore = (settings, attr)
- return [
- {"//example:favorite_flavor" : "LATTE"},
- {"//example:favorite_flavor" : "MOCHA"},
- ]
-
-coffee_transition = transition(
- implementation = _impl,
- inputs = [],
- outputs = ["//example:favorite_flavor"]
-)
-```
-
-They can also set custom keys that the rule implementation function can use to
-read individual dependencies:
-
-```python
-# example/transitions/transitions.bzl
-def _impl(settings, attr):
- _ignore = (settings, attr)
- return {
- "Apple deps": {"//command_line_option:cpu": "ppc"},
- "Linux deps": {"//command_line_option:cpu": "x86"},
- }
-
-multi_arch_transition = transition(
- implementation = _impl,
- inputs = [],
- outputs = ["//command_line_option:cpu"]
-)
-```
-
-See [Accessing attributes with transitions](#accessing-attributes-with-transitions)
-for how to read these keys.
-
-### Attaching transitions
-
-[End to end example](https://github.com/bazelbuild/examples/tree/HEAD/rules/starlark_configurations/attaching_transitions_to_rules)
-
-Transitions can be attached in two places: incoming edges and outgoing edges.
-Effectively this means rules can transition their own configuration (incoming
-edge transition) and transition their dependencies' configurations (outgoing
-edge transition).
-
-NOTE: There is currently no way to attach Starlark transitions to native rules.
-If you need to do this, contact
-bazel-discuss@googlegroups.com
-for help with figuring out workarounds.
-
-### Incoming edge transitions
-Incoming edge transitions are activated by attaching a `transition` object
-(created by `transition()`) to `rule()`'s `cfg` parameter:
-
-```python
-# example/rules.bzl
-load("example/transitions:transitions.bzl", "hot_chocolate_transition")
-drink_rule = rule(
- implementation = _impl,
- cfg = hot_chocolate_transition,
- ...
-```
-
-Incoming edge transitions must be 1:1 transitions.
-
-### Outgoing edge transitions
-Outgoing edge transitions are activated by attaching a `transition` object
-(created by `transition()`) to an attribute's `cfg` parameter:
-
-```python
-# example/rules.bzl
-load("example/transitions:transitions.bzl", "coffee_transition")
-drink_rule = rule(
- implementation = _impl,
- attrs = { "dep": attr.label(cfg = coffee_transition)}
- ...
-```
-Outgoing edge transitions can be 1:1 or 1:2+.
-
-### Transitions on native options
-
-[End to end example](https://github.com/bazelbuild/examples/tree/HEAD/rules/starlark_configurations/transition_on_native_flag)
-
-WARNING: Long term, the plan is to reimplement all native options as build
-settings. When that happens, this syntax will be deprecated. Currently other
-issues are blocking that migration but be aware you may have to migrate your
-transitions at some point in the future.
-
-Starlark transitions can also declare reads and writes on native build
-configuration options via a special prefix to the option name.
-
-```python
-# example/transitions/transitions.bzl
-def _impl(settings, attr):
- _ignore = (settings, attr)
- return {"//command_line_option:cpu": "k8"}
-
-cpu_transition = transition(
- implementation = _impl,
- inputs = [],
- outputs = ["//command_line_option:cpu"]
-```
-
-#### Unsupported native options
-
-Bazel doesn't support transitioning on `--define` with
-`"//command_line_option:define"`. Instead, use a custom
-[build setting](#user-defined-build-settings). In general, new usages of
-`--define` are discouraged in favor of build settings.
-
-Bazel doesn't support transitioning on `--config`. This is because `--config` is
-an "expansion" flag that expands to other flags.
-
-Crucially, `--config` may include flags that don't affect build configuration,
-such as
-[`--spawn_strategy`](https://docs.bazel.build/versions/main/user-manual.html#flag--spawn_strategy)
-. Bazel, by design, can't bind such flags to individual targets. This means
-there's no coherent way to apply them in transitions.
-
-As a workaround, you can explicitly itemize the flags that *are* part of
-the configuration in your transition. This requires maintaining the `--config`'s
-expansion in two places, which is a known UI blemish.
-
-### Transitions on allow multiple build settings
-
-When setting build settings that
-[allow multiple values](#defining-multi-set-string-flags), the value of the
-setting must be set with a list.
-
-```python
-# example/buildsettings/build_settings.bzl
-string_flag = rule(
- implementation = _impl,
- build_setting = config.string(flag = True, allow_multiple = True)
-)
-```
-
-```python
-# example/BUILD
-load("//example/buildsettings:build_settings.bzl", "string_flag")
-string_flag(name = "roasts", build_setting_default = "medium")
-```
-
-```python
-# example/transitions/rules.bzl
-def _transition_impl(settings, attr):
- # Using a value of just "dark" here will throw an error
- return {"//example:roasts" : ["dark"]},
-
-coffee_transition = transition(
- implementation = _transition_impl,
- inputs = [],
- outputs = ["//example:roasts"]
-)
-```
-
-### No-op transitions
-
-If a transition returns `{}`, `[]`, or `None`, this is shorthand for keeping all
-settings at their original values. This can be more convenient than explicitly
-setting each output to itself.
-
-```python
-# example/transitions/transitions.bzl
-def _impl(settings, attr):
- _ignore = (attr)
- if settings["//example:already_chosen"] is True:
- return {}
- return {
- "//example:favorite_flavor": "dark chocolate",
- "//example:include_marshmallows": "yes",
- "//example:desired_temperature": "38C",
- }
-
-hot_chocolate_transition = transition(
- implementation = _impl,
- inputs = ["//example:already_chosen"],
- outputs = [
- "//example:favorite_flavor",
- "//example:include_marshmallows",
- "//example:desired_temperature",
- ]
-)
-```
-
-### Accessing attributes with transitions
-
-[End to end example](https://github.com/bazelbuild/examples/tree/HEAD/rules/starlark_configurations/read_attr_in_transition)
-
-When [attaching a transition to an outgoing edge](#outgoing-edge-transitions)
-(regardless of whether the transition is a [1:1](#defining) or
-[1:2+](#defining-12-transitions) transition) `ctx.attr` is forced to be a list
-if it isn't already. The order of elements in this list is unspecified.
-
-```python
-# example/transitions/rules.bzl
-def _transition_impl(settings, attr):
- return {"//example:favorite_flavor" : "LATTE"},
-
-coffee_transition = transition(
- implementation = _transition_impl,
- inputs = [],
- outputs = ["//example:favorite_flavor"]
-)
-
-def _rule_impl(ctx):
- # Note: List access even though "dep" is not declared as list
- transitioned_dep = ctx.attr.dep[0]
-
- # Note: Access doesn't change, other_deps was already a list
- for other dep in ctx.attr.other_deps:
- # ...
-
-
-coffee_rule = rule(
- implementation = _rule_impl,
- attrs = {
- "dep": attr.label(cfg = coffee_transition)
- "other_deps": attr.label_list(cfg = coffee_transition)
- })
-```
-
-If the transition is `1:2+` and sets custom keys, `ctx.split_attr` can be used
-to read individual deps for each key:
-
-```python
-# example/transitions/rules.bzl
-def _impl(settings, attr):
- _ignore = (settings, attr)
- return {
- "Apple deps": {"//command_line_option:cpu": "ppc"},
- "Linux deps": {"//command_line_option:cpu": "x86"},
- }
-
-multi_arch_transition = transition(
- implementation = _impl,
- inputs = [],
- outputs = ["//command_line_option:cpu"]
-)
-
-def _rule_impl(ctx):
- apple_dep = ctx.split_attr.dep["Apple deps"]
- linux_dep = ctx.split_attr.dep["Linux deps"]
- # ctx.attr has a list of all deps for all keys. Order is not guaranteed.
- all_deps = ctx.attr.dep
-
-multi_arch_rule = rule(
- implementation = _rule_impl,
- attrs = {
- "dep": attr.label(cfg = multi_arch_transition)
- })
-```
-
-See [here](https://github.com/bazelbuild/examples/tree/main/rules/starlark_configurations/multi_arch_binary)
-for a complete example.
-
-## Integration with platforms and toolchains
-Many native flags today, like `--cpu` and `--crosstool_top` are related to
-toolchain resolution. In the future, explicit transitions on these types of
-flags will likely be replaced by transitioning on the
-[target platform](../platforms.html).
-
-## Memory and performance considerations
-
-Adding transitions, and therefore new configurations, to your build comes at a
-cost: larger build graphs, less comprehensible build graphs, and slower
-builds. It's worth considering these costs when considering
-using transitions in your build rules. Below is an example of how a transition
-might create exponential growth of your build graph.
-
-### Badly behaved builds: a case study
-Say you have the following target structure:
-
-<img src="scalability-graph.png" width="600px" alt="a graph showing a top level target, //pkg:app, which depends on two targets, //pkg:1_0 and //pkg:1_1. Both these targets depend on two targets, //pkg:2_0 and //pkg:2_1. Both these targets depend on two targets, //pkg:3_0 and //pkg:3_1. This continues on until //pkg:n_0 and //pkg:n_1, which both depend on a single target, //pkg:dep." />
-
-Building `//pkg:app` requires \\(2n+2\\) targets:
-
-* `//pkg:app`
-* `//pkg:dep`
-* `//pkg:i_0` and `//pkg:i_1` for \\(i\\) in \\([1..n]\\)
-
-Imagine you [implement](#user-defined-build-settings)) a flag
-`--//foo:owner=<STRING>` and `//pkg:i_b` applies
-
- depConfig = myConfig + depConfig.owner="$(myConfig.owner)$(b)"
-
-In other words, `//pkg:i_b` appends `b` to the old value of `--owner` for all
-its deps.
-
-This produces the following [configured targets](glossary.md#configured-target):
-
-```
-//pkg:app //foo:owner=""
-//pkg:1_0 //foo:owner=""
-//pkg:1_1 //foo:owner=""
-//pkg:2_0 (via //pkg:1_0) //foo:owner="0"
-//pkg:2_0 (via //pkg:1_1) //foo:owner="1"
-//pkg:2_1 (via //pkg:1_0) //foo:owner="0"
-//pkg:2_1 (via //pkg:1_1) //foo:owner="1"
-//pkg:3_0 (via //pkg:1_0 → //pkg:2_0) //foo:owner="00"
-//pkg:3_0 (via //pkg:1_0 → //pkg:2_1) //foo:owner="01"
-//pkg:3_0 (via //pkg:1_1 → //pkg:2_0) //foo:owner="10"
-//pkg:3_0 (via //pkg:1_1 → //pkg:2_1) //foo:owner="11"
-...
-```
-
-`//pkg:dep` produces \\(2^n\\) configured targets: `config.owner=`
-"\\(b_0b_1...b_n\\)" for all \\(b_i\\) in \\(\{0,1\}\\).
-
-This makes the build graph exponentially larger than the target graph, with
-corresponding memory and performance consequences.
-
-TODO: Add strategies for measurement and mitigation of these issues.
-
-## Further reading
-
-For more details on modifying build configurations, see:
-
- * [Starlark Build Configuration](https://docs.google.com/document/d/1vc8v-kXjvgZOdQdnxPTaV0rrLxtP2XwnD2tAZlYJOqw/edit?usp=sharing)
- * [Bazel Configurability Roadmap](https://bazel.build/roadmaps/configuration.html)
- * Full [set](https://github.com/bazelbuild/examples/tree/HEAD/rules/starlark_configurations) of end to end examples
diff --git a/site/docs/skylark/macros.md b/site/docs/skylark/macros.md
deleted file mode 100644
index 50aca34..0000000
--- a/site/docs/skylark/macros.md
+++ /dev/null
@@ -1,249 +0,0 @@
----
-layout: documentation
-title: Macros
-category: extending
----
-
-<div style="background-color: #EFCBCB; color: #AE2B2B; border: 1px solid #AE2B2B; border-radius: 5px; border-left: 10px solid #AE2B2B; padding: 0.5em;">
-<b>IMPORTANT:</b> The Bazel docs have moved! Please update your bookmark to <a href="https://bazel.build/rules/macros" style="color: #0000EE;">https://bazel.build/rules/macros</a>
-<p/>
-You can <a href="https://blog.bazel.build/2022/02/17/Launching-new-Bazel-site.html" style="color: #0000EE;">read about</a> the migration, and let us <a href="https://forms.gle/onkAkr2ZwBmcbWXj7" style="color: #0000EE;">know what you think</a>.
-</div>
-
-
-# Macros
-
-
-This page covers the basics of using macros and includes typical use cases,
-debugging, and conventions.
-
-A macro is a function called from the `BUILD` file that can instantiate rules.
-Macros are mainly used for encapsulation and code reuse of existing rules
-and other macros. By the end of the
-[loading phase](concepts.md#evaluation-model), macros don't exist anymore,
-and Bazel sees only the concrete set of instantiated rules.
-
-## Usage
-
-The typical use case for a macro is when you want to reuse a rule.
-
-For example, genrule in a `BUILD` file generates a file using
-`//:generator` with a `some_arg` argument hardcoded in the command:
-
-```python
-genrule(
- name = "file",
- outs = ["file.txt"],
- cmd = "$(location //:generator) some_arg > $@",
- tools = ["//:generator"],
-)
-```
-
-> Tip: `$@` is a [Make variable](../be/make-variables.html#predefined_genrule_variables)
-> that refers to the execution-time locations of the files in the `outs` attribute list.
-> It is equivalent to `$(locations :file.txt)`.
-
-If you want to generate more files with different arguments, you may want to
-extract this code to a macro function. Let's call the macro `file_generator`, which
-has `name` and `arg` parameters. Replace the genrule with the following:
-
-```python
-load("//path:generator.bzl", "file_generator")
-
-file_generator(
- name = "file",
- arg = "some_arg",
-)
-
-file_generator(
- name = "file-two",
- arg = "some_arg_two",
-)
-
-file_generator(
- name = "file-three",
- arg = "some_arg_three",
-)
-```
-
-Here, you load the `file_generator` symbol from a `.bzl` file located
-in the `//path` package. By putting macro function definitions in a separate
-`.bzl` file, you keep your `BUILD` files clean and declarative, The `.bzl`
-file can be loaded from any package in the workspace.
-
-Finally, in `path/generator.bzl`, write the definition of the macro to
-encapsulate and parameterize the original genrule definition:
-
-```python
-def file_generator(name, arg, visibility=None):
- native.genrule(
- name = name,
- outs = [name + ".txt"],
- cmd = "$(location //:generator) %s > $@" % arg,
- tools = ["//:generator"],
- visibility = visibility,
- )
-```
-
-You can also use macros to chain rules together. This example shows chained
-genrules, where a genrule uses the outputs of a previous genrule as inputs:
-
-```python
-def chained_genrules(name, visibility=None):
- native.genrule(
- name = name + "-one",
- outs = [name + ".one"],
- cmd = "$(location :tool-one) $@",
- tools = [":tool-one"],
- visibility = ["//visibility:private"],
- )
-
- native.genrule(
- name = name + "-two",
- srcs = [name + ".one"],
- outs = [name + ".two"],
- cmd = "$(location :tool-two) $< $@",
- tools = [":tool-two"],
- visibility = visibility,
- )
-```
-
-The example only assigns a visibility value to the second genrule. This allows
-macro authors to hide the outputs of intermediate rules from being depended upon
-by other targets in the workspace.
-
-> Tip: Similar to `$@` for outputs, `$<` expands to the locations of files in
-the `srcs` attribute list.
-
-## Expanding macros
-
-When you want to investigate what a macro does, use the `query` command with
-`--output=build` to see the expanded form:
-
-```
-$ bazel query --output=build :file
-# /absolute/path/test/ext.bzl:42:3
-genrule(
- name = "file",
- tools = ["//:generator"],
- outs = ["//test:file.txt"],
- cmd = "$(location //:generator) some_arg > $@",
-)
-```
-
-## Instantiating native rules
-
-Native rules (i.e. rules that don't need a `load()` statement) can be
-instantiated from the [native](lib/native.html) module, e.g.
-
-```python
-def my_macro(name, visibility=None):
- native.cc_library(
- name = name,
- srcs = ["main.cc"],
- visibility = visibility,
- )
-```
-
-If you need to know the package name (i.e. which `BUILD` file is calling the
-macro), use the function [native.package_name()](lib/native.html#package_name).
-Note that `native` can only be used in `.bzl` files, and not in `WORKSPACE` or
-`BUILD` files.
-
-## Label resolution in macros
-
-Since macros are evaluated in the [loading phase](concepts.md#evaluation-model),
-label strings such as `"//foo:bar"` that occur in a macro are interpreted
-relative to the `BUILD` file in which the macro is used rather than relative to
-the `.bzl` file in which it is defined. This behavior is generally undesirable
-for macros that are meant to be used in other repositories, e.g. because they
-are part of a published Starlark ruleset.
-
-To get the same behavior as for Starlark rules, wrap the label strings with the
-[`Label`](lib/Label.html#Label) constructor:
-
-```python
-# @my_ruleset//rules:defs.bzl
-def my_cc_wrapper(name, deps = [], **kwargs):
- native.cc_library(
- name = name,
- deps = deps + select({
- # Due to the use of Label, this label is resolved within @my_ruleset,
- # regardless of its site of use.
- Label("//config:needs_foo"): [
- # Due to the use of Label, this label will resolve to the correct target
- # even if the canonical name of @dep_of_my_ruleset should be different
- # in the main workspace, e.g. due to repo mappings.
- Label("@dep_of_my_ruleset//tools:foo"),
- ],
- "//conditions:default": [],
- }),
- **kwargs,
- )
-```
-
-## Debugging
-
-* `bazel query --output=build //my/path:all` will show you how the `BUILD` file
- looks after evaluation. All macros, globs, loops are expanded. Known
- limitation: `select` expressions are currently not shown in the output.
-
-* You may filter the output based on `generator_function` (which function
- generated the rules) or `generator_name` (the name attribute of the macro),
- e.g.
- ```bash
- $ bazel query --output=build 'attr(generator_function, my_macro, //my/path:all)'
- ```
-
-* To find out where exactly the rule `foo` is generated in a `BUILD` file, you
- can try the following trick. Insert this line near the top of the `BUILD`
- file: `cc_library(name = "foo")`. Run Bazel. You will get an exception when
- the rule `foo` is created (due to a name conflict), which will show you the
- full stack trace.
-
-* You can also use [print](lib/globals.html#print) for debugging. It displays
- the message as a `DEBUG` log line during the loading phase. Except in rare
- cases, either remove `print` calls, or make them conditional under a
- `debugging` parameter that defaults to `False` before submitting the code to
- the depot.
-
-## Errors
-
-If you want to throw an error, use the [fail](lib/globals.html#fail) function.
-Explain clearly to the user what went wrong and how to fix their `BUILD` file.
-It is not possible to catch an error.
-
-```python
-def my_macro(name, deps, visibility=None):
- if len(deps) < 2:
- fail("Expected at least two values in deps")
- # ...
-```
-
-## Conventions
-
-* All public functions (functions that don't start with underscore) that
- instantiate rules must have a `name` argument. This argument should not be
- optional (don't give a default value).
-
-* Public functions should use a docstring following [Python
- conventions](https://www.python.org/dev/peps/pep-0257/#one-line-docstrings).
-
-* In `BUILD` files, the `name` argument of the macros must be a keyword
- argument (not a positional argument).
-
-* The `name` attribute of rules generated by a macro should include the name
- argument as a prefix. For example, `macro(name = "foo")` can generate a
- `cc_library` `foo` and a genrule `foo_gen`.
-
-* In most cases, optional parameters should have a default value of `None`.
- `None` can be passed directly to native rules, which treat it the same as if
- you had not passed in any argument. Thus, there is no need to replace it
- with `0`, `False`, or `[]` for this purpose. Instead, the macro should defer
- to the rules it creates, as their defaults may be complex or may change over
- time. Additionally, a parameter that is explicitly set to its default value
- looks different than one that is never set (or set to `None`) when accessed
- through the query language or build-system internals.
-
-* Macros should have an optional `visibility` argument.
-
diff --git a/site/docs/skylark/performance.md b/site/docs/skylark/performance.md
deleted file mode 100644
index 0399291..0000000
--- a/site/docs/skylark/performance.md
+++ /dev/null
@@ -1,451 +0,0 @@
----
-layout: documentation
-title: Optimizing performance
-category: extending
----
-
-<div style="background-color: #EFCBCB; color: #AE2B2B; border: 1px solid #AE2B2B; border-radius: 5px; border-left: 10px solid #AE2B2B; padding: 0.5em;">
-<b>IMPORTANT:</b> The Bazel docs have moved! Please update your bookmark to <a href="https://bazel.build/rules/performance" style="color: #0000EE;">https://bazel.build/rules/performance</a>
-<p/>
-You can <a href="https://blog.bazel.build/2022/02/17/Launching-new-Bazel-site.html" style="color: #0000EE;">read about</a> the migration, and let us <a href="https://forms.gle/onkAkr2ZwBmcbWXj7" style="color: #0000EE;">know what you think</a>.
-</div>
-
-
-# Optimizing Performance
-
-
-When writing rules, the most common performance pitfall is to traverse or copy
-data that is accumulated from dependencies. When aggregated over the whole
-build, these operations can easily take O(N^2) time or space. To avoid this, it
-is crucial to understand how to use depsets effectively.
-
-This can be hard to get right, so Bazel also provides a memory profiler that
-assists you in finding spots where you might have made a mistake. Be warned:
-The cost of writing an inefficient rule may not be evident until it is in
-widespread use.
-
-
-## Use depsets
-
-Whenever you are rolling up information from rule dependencies you should use
-[depsets](lib/depset.html). Only use plain lists or dicts to publish information
-local to the current rule.
-
-A depset represents information as a nested graph which enables sharing.
-
-Consider the following graph:
-
-```
-C -> B -> A
-D ---^
-```
-
-Each node publishes a single string. With depsets the data looks like this:
-
-```
-a = depset(direct=['a'])
-b = depset(direct=['b'], transitive=[a])
-c = depset(direct=['c'], transitive=[b])
-d = depset(direct=['d'], transitive=[b])
-```
-
-Note that each item is only mentioned once. With lists you would get this:
-
-```
-a = ['a']
-b = ['b', 'a']
-c = ['c', 'b', 'a']
-d = ['d', 'b', 'a']
-```
-
-Note that in this case `'a'` is mentioned four times! With larger graphs this
-problem will only get worse.
-
-Here is an example of a rule implementation that uses depsets correctly to
-publish transitive information. Note that it is OK to publish rule-local
-information using lists if you want since this is not O(N^2).
-
-```
-MyProvider = provider()
-
-def _impl(ctx):
- my_things = ctx.attr.things
- all_things = depset(
- direct=my_things,
- transitive=[dep[MyProvider].all_things for dep in ctx.attr.deps]
- )
- ...
- return [MyProvider(
- my_things=my_things, # OK, a flat list of rule-local things only
- all_things=all_things, # OK, a depset containing dependencies
- )]
-```
-
-See the [depset overview](depsets.md) page for more information.
-
-### Avoid calling `depset.to_list()`
-
-You can coerce a depset to a flat list using
-[`to_list()`](lib/depset.html#to_list), but doing so usually results in O(N^2)
-cost. If at all possible, avoid any flattening of depsets except for debugging
-purposes.
-
-A common misconception is that you can freely flatten depsets if you only do it
-at top-level targets, such as an `<xx>_binary` rule, since then the cost is not
-accumulated over each level of the build graph. But this is *still* O(N^2) when
-you build a set of targets with overlapping dependencies. This happens when
-building your tests `//foo/tests/...`, or when importing an IDE project.
-
-### Reduce the number of calls to `depset`
-
-Calling `depset` inside a loop is often a mistake. It can lead to depsets with
-very deep nesting, which perform poorly. For example:
-
-```python
-x = depset()
-for i in inputs:
- # Do not do that.
- x = depset(transitive = [x, i.deps])
-```
-
-This code can be replaced easily. First, collect the transitive depsets and
-merge them all at once:
-
-```python
-transitive = []
-
-for i in inputs:
- transitive.append(i.deps)
-
-x = depset(transitive = transitive)
-```
-
-This can sometimes be reduced using a list comprehension:
-
-```python
-x = depset(transitive = [i.deps for i in inputs])
-```
-
-## Use ctx.actions.args() for command lines
-
-When building command lines you should use [ctx.actions.args()](lib/Args.html).
-This defers expansion of any depsets to the execution phase.
-
-Apart from being strictly faster, this will reduce the memory consumption of
-your rules -- sometimes by 90% or more.
-
-Here are some tricks:
-
-* Pass depsets and lists directly as arguments, instead of flattening them
-yourself. They will get expanded by `ctx.actions.args()` for you.
-If you need any transformations on the depset contents, look at
-[ctx.actions.args#add](lib/Args.html#add) to see if anything fits the bill.
-
-* Are you passing `File#path` as arguments? No need. Any
-[File](lib/File.html) is automatically turned into its
-[path](lib/File.html#path), deferred to expansion time.
-
-* Avoid constructing strings by concatenating them together.
-The best string argument is a constant as its memory will be shared between
-all instances of your rule.
-
-* If the args are too long for the command line an `ctx.actions.args()` object
-can be conditionally or unconditionally written to a param file using
-[`ctx.actions.args#use_param_file`](lib/Args.html#use_param_file). This is
-done behind the scenes when the action is executed. If you need to explicitly
-control the params file you can write it manually using
-[`ctx.actions.write`](lib/actions.html#write).
-
-Example:
-
-```
-def _impl(ctx):
- ...
- args = ctx.actions.args()
- file = ctx.declare_file(...)
- files = depset(...)
-
- # Bad, constructs a full string "--foo=<file path>" for each rule instance
- args.add("--foo=" + file.path)
-
- # Good, shares "--foo" among all rule instances, and defers file.path to later
- # It will however pass ["--foo", <file path>] to the action command line,
- # instead of ["--foo=<file_path>"]
- args.add("--foo", file)
-
- # Use format if you prefer ["--foo=<file path>"] to ["--foo", <file path>]
- args.add(format="--foo=%s", value=file)
-
- # Bad, makes a giant string of a whole depset
- args.add(" ".join(["-I%s" % file.short_path for file in files])
-
- # Good, only stores a reference to the depset
- args.add_all(files, format_each="-I%s", map_each=_to_short_path)
-
-# Function passed to map_each above
-def _to_short_path(f):
- return f.short_path
-```
-
-## Transitive action inputs should be depsets
-
-When building an action using [ctx.actions.run](lib/actions.html?#run), do not
-forget that the `inputs` field accepts a depset. Use this whenever inputs are
-collected from dependencies transitively.
-
-```
-inputs = depset(...)
-ctx.actions.run(
- inputs = inputs, # Do *not* turn inputs into a list
- ...
-)
-```
-
-## Hanging
-
-If Bazel appears to be hung, you can hit <kbd>Ctrl-\</kbd> or send
-Bazel a `SIGQUIT` signal (`kill -3 $(bazel info server_pid)`) to get a thread
-dump in the file `$(bazel info output_base)/server/jvm.out`.
-
-Since you may not be able to run `bazel info` if bazel is hung, the
-`output_base` directory is usually the parent of the `bazel-<workspace>`
-symlink in your workspace directory.
-
-## Performance profiling
-
-Bazel writes a JSON profile to `command.profile.gz` in the output base by
-default. You can configure the location with the
-[`--profile`](user-manual.html#flag--profile) flag, for example
-`--profile=/tmp/profile.gz`. Location ending with `.gz` are compressed with
-GZIP.
-
-To see the results, open `chrome://tracing` in a Chrome browser tab, click
-"Load" and pick the (potentially compressed) profile file. For more detailed
-results, click the boxes in the lower left corner.
-
-You can use these keyboard controls to navigate:
-
-* Press `1` for "select" mode. In this mode, you can select
- particular boxes to inspect the event details (see lower left corner).
- Select multiple events to get a summary and aggregated statistics.
-* Press `2` for "pan" mode. Then drag the mouse to move the view. You
- can also use `a`/`d` to move left/right.
-* Press `3` for "zoom" mode. Then drag the mouse to zoom. You can
- also use `w`/`s` to zoom in/out.
-* Press `4` for "timing" mode where you can measure the distance
- between two events.
-* Press `?` to learn about all controls.
-
-### Profile information
-
-Example profile:
-<img src="profile.png" alt="Example Profile" />
-
-There are some special rows:
-
-* `action counters`: Displays how many concurrent actions are in flight. Click
- on it to see the actual value. Should go up to the value of `--jobs` in
- clean builds.
-* `cpu counters`: For each second of the build, displays the amount of CPU
- that is used by Bazel (a value of 1 equals one core being 100% busy).
-* `Critical Path`: Displays one block for each action on the critical path.
-* `grpc-command-1`: Bazel's main thread. Useful to get a high-level picture of
- what Bazel is doing, for example "Launch Bazel", "evaluateTargetPatterns",
- and "runAnalysisPhase".
-* `Service Thread`: Displays minor and major Garbage Collection (GC) pauses.
-
-Other rows represent Bazel threads and show all events on that thread.
-
-### Common performance issues
-
-When analyzing performance profiles, look for:
-
-* Slower than expected analysis phase (`runAnalysisPhase`), especially on
- incremental builds. This can be a sign of a poor rule implementation, for
- example one that flattens depsets. Package loading can be slow by an
- excessive amount of targets, complex macros or recursive globs.
-* Individual slow actions, especially those on the critical path. It might be
- possible to split large actions into multiple smaller actions or reduce the
- set of (transitive) dependencies to speed them up. Also check for an unusual
- high non-`PROCESS_TIME` (e.g. `REMOTE_SETUP` or `FETCH`).
-* Bottlenecks, that is a small number of threads is busy while all others are
- idling / waiting for the result (see around 15s-30s in above screenshot).
- Optimizing this will most likely require touching the rule implementations
- or Bazel itself to introduce more parallelism. This can also happen when
- there is an unusual amount of GC.
-
-### Profile file format
-
-The top-level object contains metadata (`otherData`) and the actual tracing data
-(`traceEvents`). The metadata contains extra info, for example the invocation ID
-and date of the Bazel invocation.
-
-Example:
-
-```json
-{
- "otherData": {
- "build_id": "101bff9a-7243-4c1a-8503-9dc6ae4c3b05",
- "date": "Tue Jun 16 08:30:21 CEST 2020",
- "output_base": "/usr/local/google/_bazel_johndoe/573d4be77eaa72b91a3dfaa497bf8cd0"
- },
- "traceEvents": [
- {"name":"thread_name","ph":"M","pid":1,"tid":0,"args":{"name":"Critical Path"}},
- {"cat":"build phase marker","name":"Launch Bazel","ph":"X","ts":-1824000,"dur":1824000,"pid":1,"tid":60},
- ...
- {"cat":"general information","name":"NoSpawnCacheModule.beforeCommand","ph":"X","ts":116461,"dur":419,"pid":1,"tid":60},
- ...
- {"cat":"package creation","name":"src","ph":"X","ts":279844,"dur":15479,"pid":1,"tid":838},
- ...
- {"name":"thread_name","ph":"M","pid":1,"tid":11,"args":{"name":"Service Thread"}},
- {"cat":"gc notification","name":"minor GC","ph":"X","ts":334626,"dur":13000,"pid":1,"tid":11},
-
- ...
- {"cat":"action processing","name":"Compiling third_party/grpc/src/core/lib/transport/status_conversion.cc","ph":"X","ts":12630845,"dur":136644,"pid":1,"tid":1546}
- ]
-}
-```
-
-Timestamps (`ts`) and durations (`dur`) in the trace events are given in
-microseconds. The category (`cat`) is one of enum values of `ProfilerTask`.
-Note that some events are merged together if they are very short and close to
-each other; pass `--noslim_json_profile` if you would like to
-prevent event merging.
-
-See also the
-[Chrome Trace Event Format Specification](https://docs.google.com/document/d/1CvAClvFfyA5R-PhYUmn5OOQtYMH4h6I0nSsKchNAySU/preview).
-
-### analyze-profile
-
-This profiling method consists of two steps, first you have to execute your
-build/test with the `--profile` flag, for example
-
-```
-$ bazel build --profile=/tmp/prof //path/to:target
-```
-
-The file generated (in this case `/tmp/prof`) is a binary file, which can be
-postprocessed and analyzed by the `analyze-profile` command:
-
-```
-$ bazel analyze-profile /tmp/prof
-```
-
-By default, it prints summary analysis information for the specified profile
-datafile. This includes cumulative statistics for different task types for each
-build phase and an analysis of the critical path.
-
-The first section of the default output is an overview of the time spent
-on the different build phases:
-
-```
-INFO: Profile created on Tue Jun 16 08:59:40 CEST 2020, build ID: 0589419c-738b-4676-a374-18f7bbc7ac23, output base: /home/johndoe/.cache/bazel/_bazel_johndoe/d8eb7a85967b22409442664d380222c0
-
-=== PHASE SUMMARY INFORMATION ===
-
-Total launch phase time 1.070 s 12.95%
-Total init phase time 0.299 s 3.62%
-Total loading phase time 0.878 s 10.64%
-Total analysis phase time 1.319 s 15.98%
-Total preparation phase time 0.047 s 0.57%
-Total execution phase time 4.629 s 56.05%
-Total finish phase time 0.014 s 0.18%
-------------------------------------------------
-Total run time 8.260 s 100.00%
-
-Critical path (4.245 s):
- Time Percentage Description
- 8.85 ms 0.21% _Ccompiler_Udeps for @local_config_cc// compiler_deps
- 3.839 s 90.44% action 'Compiling external/com_google_protobuf/src/google/protobuf/compiler/php/php_generator.cc [for host]'
- 270 ms 6.36% action 'Linking external/com_google_protobuf/protoc [for host]'
- 0.25 ms 0.01% runfiles for @com_google_protobuf// protoc
- 126 ms 2.97% action 'ProtoCompile external/com_google_protobuf/python/google/protobuf/compiler/plugin_pb2.py'
- 0.96 ms 0.02% runfiles for //tools/aquery_differ aquery_differ
-```
-
-## Memory profiling
-
-Bazel comes with a built-in memory profiler that can help you check your rule's
-memory use. If there is a problem you can dump the heap to find the
-exact line of code that is causing the problem.
-
-### Enabling memory tracking
-
-You must pass these two startup flags to *every* Bazel invocation:
-
- ```
- STARTUP_FLAGS=\
- --host_jvm_args=-javaagent:$(BAZEL)/third_party/allocation_instrumenter/java-allocation-instrumenter-3.3.0.jar \
- --host_jvm_args=-DRULE_MEMORY_TRACKER=1
- ```
- **NOTE**: The bazel repository comes with an allocation instrumenter.
- Make sure to adjust `$(BAZEL)` for your repository location.
-
-These start the server in memory tracking mode. If you forget these for even
-one Bazel invocation the server will restart and you will have to start over.
-
-### Using the Memory Tracker
-
-As an example, look at the target `foo` and see what it does. To only
-run the analysis and not run the build execution phase, add the
-`--nobuild` flag.
-
-```
-$ bazel $(STARTUP_FLAGS) build --nobuild //foo:foo
-```
-
-Next, see how much memory the whole Bazel instance consumes:
-
-```
-$ bazel $(STARTUP_FLAGS) info used-heap-size-after-gc
-> 2594MB
-```
-
-Break it down by rule class by using `bazel dump --rules`:
-
-```
-$ bazel $(STARTUP_FLAGS) dump --rules
->
-
-RULE COUNT ACTIONS BYTES EACH
-genrule 33,762 33,801 291,538,824 8,635
-config_setting 25,374 0 24,897,336 981
-filegroup 25,369 25,369 97,496,272 3,843
-cc_library 5,372 73,235 182,214,456 33,919
-proto_library 4,140 110,409 186,776,864 45,115
-android_library 2,621 36,921 218,504,848 83,366
-java_library 2,371 12,459 38,841,000 16,381
-_gen_source 719 2,157 9,195,312 12,789
-_check_proto_library_deps 719 668 1,835,288 2,552
-... (more output)
-```
-
-Look at where the memory is going by producing a `pprof` file
-using `bazel dump --skylark_memory`:
-
-```
-$ bazel $(STARTUP_FLAGS) dump --skylark_memory=$HOME/prof.gz
-> Dumping Starlark heap to: /usr/local/google/home/$USER/prof.gz
-```
-
-Use the `pprof` tool to investigate the heap. A good starting point is
-getting a flame graph by using `pprof -flame $HOME/prof.gz`.
-
-Get `pprof` from [https://github.com/google/pprof](https://github.com/google/pprof).
-
-Get a text dump of the hottest call sites annotated with lines:
-
-```
-$ pprof -text -lines $HOME/prof.gz
->
- flat flat% sum% cum cum%
- 146.11MB 19.64% 19.64% 146.11MB 19.64% android_library <native>:-1
- 113.02MB 15.19% 34.83% 113.02MB 15.19% genrule <native>:-1
- 74.11MB 9.96% 44.80% 74.11MB 9.96% glob <native>:-1
- 55.98MB 7.53% 52.32% 55.98MB 7.53% filegroup <native>:-1
- 53.44MB 7.18% 59.51% 53.44MB 7.18% sh_test <native>:-1
- 26.55MB 3.57% 63.07% 26.55MB 3.57% _generate_foo_files /foo/tc/tc.bzl:491
- 26.01MB 3.50% 66.57% 26.01MB 3.50% _build_foo_impl /foo/build_test.bzl:78
- 22.01MB 2.96% 69.53% 22.01MB 2.96% _build_foo_impl /foo/build_test.bzl:73
- ... (more output)
-```
diff --git a/site/docs/skylark/testing.md b/site/docs/skylark/testing.md
deleted file mode 100644
index 412ec18..0000000
--- a/site/docs/skylark/testing.md
+++ /dev/null
@@ -1,487 +0,0 @@
----
-layout: documentation
-title: Testing
-category: extending
----
-
-<div style="background-color: #EFCBCB; color: #AE2B2B; border: 1px solid #AE2B2B; border-radius: 5px; border-left: 10px solid #AE2B2B; padding: 0.5em;">
-<b>IMPORTANT:</b> The Bazel docs have moved! Please update your bookmark to <a href="https://bazel.build/rules/testing" style="color: #0000EE;">https://bazel.build/rules/testing</a>
-<p/>
-You can <a href="https://blog.bazel.build/2022/02/17/Launching-new-Bazel-site.html" style="color: #0000EE;">read about</a> the migration, and let us <a href="https://forms.gle/onkAkr2ZwBmcbWXj7" style="color: #0000EE;">know what you think</a>.
-</div>
-
-
-# Testing
-
-
-There are several different approaches to testing Starlark code in Bazel. This
-page gathers the current best practices and frameworks by use case.
-
-
-## For testing rules
-
-[Skylib](https://github.com/bazelbuild/bazel-skylib) has a test framework called
-[`unittest.bzl`](https://github.com/bazelbuild/bazel-skylib/blob/main/lib/unittest.bzl)
-for checking the analysis-time behavior of rules, such as their actions and
-providers. Such tests are called "analysis tests" and are currently the best
-option for testing the inner workings of rules.
-
-
-Some caveats:
-
-* Test assertions occur within the build, not a separate test runner process.
- Targets that are created by the test must be named such that they do not
- collide with targets from other tests or from the build. An error that
- occurs during the test is seen by Bazel as a build breakage rather than a
- test failure.
-
-* It requires a fair amount of boilerplate to set up the rules under test and
- the rules containing test assertions. This boilerplate may seem daunting at
- first. It helps to [keep in mind](concepts.md#evaluation-model) that macros
- are evaluated and targets generated during the loading phase, while rule
- implementation functions don't run until later, during the analysis phase.
-
-* Analysis tests are intended to be fairly small and lightweight. Certain
- features of the analysis testing framework are restricted to verifying
- targets with a maximum number of transitive dependencies (currently 500).
- This is due to performance implications of using these features with larger
- tests.
-
-The basic principle is to define a testing rule that depends on the
-rule-under-test. This gives the testing rule access to the rule-under-test's
-providers.
-
-The testing rule's implementation function carries out assertions. If there are
-any failures, these are not raised immediately by calling `fail()` (which would
-trigger an analysis-time build error), but rather by storing the errors in a
-generated script that fails at test execution time.
-
-See below for a minimal toy example, followed by an example that checks actions.
-
-### Minimal example
-
-`//mypkg/myrules.bzl`:
-
-```python
-MyInfo = provider(fields = {
- "val": "string value",
- "out": "output File",
-})
-
-def _myrule_impl(ctx):
- """Rule that just generates a file and returns a provider."""
- out = ctx.actions.declare_file(ctx.label.name + ".out")
- ctx.actions.write(out, "abc")
- return [MyInfo(val="some value", out=out)]
-
-myrule = rule(
- implementation = _myrule_impl,
-)
-```
-
-`//mypkg/myrules_test.bzl`:
-
-
-```python
-load("@bazel_skylib//lib:unittest.bzl", "asserts", "analysistest")
-load(":myrules.bzl", "myrule", "MyInfo")
-
-# ==== Check the provider contents ====
-
-def _provider_contents_test_impl(ctx):
- env = analysistest.begin(ctx)
-
- target_under_test = analysistest.target_under_test(env)
- # If preferred, could pass these values as "expected" and "actual" keyword
- # arguments.
- asserts.equals(env, "some value", target_under_test[MyInfo].val)
-
- # If you forget to return end(), you will get an error about an analysis
- # test needing to return an instance of AnalysisTestResultInfo.
- return analysistest.end(env)
-
-# Create the testing rule to wrap the test logic. This must be bound to a global
-# variable, not called in a macro's body, since macros get evaluated at loading
-# time but the rule gets evaluated later, at analysis time. Since this is a test
-# rule, its name must end with "_test".
-provider_contents_test = analysistest.make(_provider_contents_test_impl)
-
-# Macro to setup the test.
-def _test_provider_contents():
- # Rule under test. Be sure to tag 'manual', as this target should not be
- # built using `:all` except as a dependency of the test.
- myrule(name = "provider_contents_subject", tags = ["manual"])
- # Testing rule.
- provider_contents_test(name = "provider_contents_test",
- target_under_test = ":provider_contents_subject")
- # Note the target_under_test attribute is how the test rule depends on
- # the real rule target.
-
-# Entry point from the BUILD file; macro for running each test case's macro and
-# declaring a test suite that wraps them together.
-def myrules_test_suite(name):
- # Call all test functions and wrap their targets in a suite.
- _test_provider_contents()
- # ...
-
- native.test_suite(
- name = name,
- tests = [
- ":provider_contents_test",
- # ...
- ],
- )
-```
-
-`//mypkg/BUILD`:
-
-```python
-load(":myrules.bzl", "myrule")
-load(":myrules_test.bzl", "myrules_test_suite")
-
-# Production use of the rule.
-myrule(
- name = "mytarget",
-)
-
-# Call a macro that defines targets that perform the tests at analysis time,
-# and that can be executed with "bazel test" to return the result.
-myrules_test_suite(name = "myrules_test")
-```
-
-The test can be run with `bazel test //mypkg:myrules_test`.
-
-Aside from the initial `load()` statements, there are two main parts to the
-file:
-
-* The tests themselves, each of which consists of 1) an analysis-time
- implementation function for the testing rule, 2) a declaration of the
- testing rule via `analysistest.make()`, and 3) a loading-time function
- (macro) for declaring the rule-under-test (and its dependencies) and testing
- rule. If the assertions do not change between test cases, 1) and 2) may be
- shared by multiple test cases.
-
-* The test suite function, which calls the loading-time functions for each
- test, and declares a `test_suite` target bundling all tests together.
-
-For consistency, follow the recommended naming convention: Let `foo` stand for
-the part of the test name that describes what the test is checking
-(`provider_contents` in the above example). For example, a JUnit test method
-would be named `testFoo`.
-
-Then:
-
-* the macro which generates the test and target under test should should be
- named `_test_foo` (`_test_provider_contents`)
-
-* its test rule type should be named `foo_test` (`provider_contents_test`)
-
-* the label of the target of this rule type should be `foo_test`
- (`provider_contents_test`)
-
-* the implementation function for the testing rule should be named
- `_foo_test_impl` (`_provider_contents_test_impl`)
-
-* the labels of the targets of the rules under test and their dependencies
- should be prefixed with `foo_` (`provider_contents_`)
-
-Note that the labels of all targets can conflict with other labels in the same
-BUILD package, so it's helpful to use a unique name for the test.
-
-### Failure testing
-
-It may be useful to verify that a rule fails given certain inputs or in certain
-state. This can be done using the analysis test framework:
-
-The test rule created with `analysistest.make` should specify `expect_failure`:
-
-```python
-failure_testing_test = analysistest.make(
- _failure_testing_test_impl,
- expect_failure = True,
-)
-```
-
-The test rule implementation should make assertions on the nature of the failure
-that took place (specifically, the failure message):
-
-```python
-def _failure_testing_test_impl(ctx):
- env = analysistest.begin(ctx)
- asserts.expect_failure(env, "This rule should never work")
- return analysistest.end(env)
-```
-
-Also make sure that your target under test is specifically tagged 'manual'.
-Without this, building all targets in your package using `:all` will result in a
-build of the intentionally-failing target and will exhibit a build failure. With
-'manual', your target under test will build only if explicitly specified, or as
-a dependency of a non-manual target (such as your test rule):
-
-```python
-def _test_failure():
- myrule(name = "this_should_fail", tags = ["manual"])
-
- failure_testing_test(name = "failure_testing_test",
- target_under_test = ":this_should_fail")
-
-# Then call _test_failure() in the macro which generates the test suite and add
-# ":failure_testing_test" to the suite's test targets.
-```
-
-### Verifying registered actions
-
-You may want to write tests which make assertions about the actions that your
-rule registers, for example, using `ctx.actions.run()`. This can be done in your
-analysis test rule implementation function. An example:
-
-```python
-def _inspect_actions_test_impl(ctx):
- env = analysistest.begin(ctx)
-
- target_under_test = analysistest.target_under_test(env)
- actions = analysistest.target_actions(env)
- asserts.equals(env, 1, len(actions))
- action_output = actions[0].outputs.to_list()[0]
- asserts.equals(
- env, target_under_test.label.name + ".out", action_output.basename)
- return analysistest.end(env)
-```
-
-Note that `analysistest.target_actions(env)` returns a list of
-[`Action`](lib/Action.html) objects which represent actions registered by the
-target under test.
-
-### Verifying rule behavior under different flags
-
-You may want to verify your real rule behaves a certain way given certain build
-flags. For example, your rule may behave differently if a user specifies:
-
-```shell
-bazel build //mypkg:real_target -c opt
-```
-
-versus
-
-```shell
-bazel build //mypkg:real_target -c dbg
-```
-
-At first glance, this could be done by testing the target under test using the
-desired build flags:
-
-```shell
-bazel test //mypkg:myrules_test -c opt
-```
-
-But then it becomes impossible for your test suite to simultaneously contain a
-test which verifies the rule behavior under `-c opt` and another test which
-verifies the rule behavior under `-c dbg`. Both tests would not be able to run
-in the same build!
-
-This can be solved by specifying the desired build flags when defining the test
-rule:
-
-```python
-myrule_c_opt_test = analysistest.make(
- _myrule_c_opt_test_impl,
- config_settings = {
- "//command_line_option:compilation_mode": "opt",
- },
-)
-```
-
-Normally, a target under test is analyzed given the current build flags.
-Specifying `config_settings` overrides the values of the specified command line
-options. (Any unspecified options will retain their values from the actual
-command line).
-
-In the specified `config_settings` dictionary, command line flags must be
-prefixed with a special placeholder value `//command_line_option:`, as is shown
-above.
-
-
-## For validating artifacts
-
-The main ways to check that your generated files are correct are:
-
-* You can write a test script in shell, Python, or another language, and
- create a target of the appropriate `*_test` rule type.
-
-* You can use a specialized rule for the kind of test you want to perform.
-
-### Using a test target
-
-The most straightforward way to validate an artifact is to write a script and
-add a `*_test` target to your BUILD file. The specific artifacts you want to
-check should be data dependencies of this target. If your validation logic is
-reusable for multiple tests, it should be a script that takes command line
-arguments that are controlled by the test target's `args` attribute. Here's an
-example that validates that the output of `myrule` from above is `"abc"`.
-
-`//mypkg/myrule_validator.sh`:
-
-```shell
-if [ "$(cat $1)" = "abc" ]; then
- echo "Passed"
- exit 0
-else
- echo "Failed"
- exit 1
-fi
-```
-
-`//mypkg/BUILD`:
-
-```python
-...
-
-myrule(
- name = "mytarget",
-)
-
-...
-
-# Needed for each target whose artifacts are to be checked.
-sh_test(
- name = "validate_mytarget",
- srcs = [":myrule_validator.sh"],
- args = ["$(location :mytarget.out)"],
- data = [":mytarget.out"],
-)
-```
-
-### Using a custom rule
-
-A more complicated alternative is to write the shell script as a template that
-gets instantiated by a new rule. This involves more indirection and Starlark
-logic, but leads to cleaner BUILD files. As a side-benefit, any argument
-preprocessing can be done in Starlark instead of the script, and the script is
-slightly more self-documenting since it uses symbolic placeholders (for
-substitutions) instead of numeric ones (for arguments).
-
-`//mypkg/myrule_validator.sh.template`:
-
-```shell
-if [ "$(cat %TARGET%)" = "abc" ]; then
- echo "Passed"
- exit 0
-else
- echo "Failed"
- exit 1
-fi
-```
-
-`//mypkg/myrule_validation.bzl`:
-
-```python
-def _myrule_validation_test_impl(ctx):
- """Rule for instantiating myrule_validator.sh.template for a given target."""
- exe = ctx.outputs.executable
- target = ctx.file.target
- ctx.actions.expand_template(output = exe,
- template = ctx.file._script,
- is_executable = True,
- substitutions = {
- "%TARGET%": target.short_path,
- })
- # This is needed to make sure the output file of myrule is visible to the
- # resulting instantiated script.
- return [DefaultInfo(runfiles=ctx.runfiles(files=[target]))]
-
-myrule_validation_test = rule(
- implementation = _myrule_validation_test_impl,
- attrs = {"target": attr.label(allow_single_file=True),
- # You need an implicit dependency in order to access the template.
- # A target could potentially override this attribute to modify
- # the test logic.
- "_script": attr.label(allow_single_file=True,
- default=Label("//mypkg:myrule_validator"))},
- test = True,
-)
-```
-
-`//mypkg/BUILD`:
-
-```python
-...
-
-myrule(
- name = "mytarget",
-)
-
-...
-
-# Needed just once, to expose the template. Could have also used export_files(),
-# and made the _script attribute set allow_files=True.
-filegroup(
- name = "myrule_validator",
- srcs = [":myrule_validator.sh.template"],
-)
-
-# Needed for each target whose artifacts are to be checked. Notice that you no
-# longer have to specify the output file name in a data attribute, or its
-# $(location) expansion in an args attribute, or the label for the script
-# (unless you want to override it).
-myrule_validation_test(
- name = "validate_mytarget",
- target = ":mytarget",
-)
-```
-
-Alternatively, instead of using a template expansion action, you could have
-inlined the template into the .bzl file as a string and expanded it during the
-analysis phase using the `str.format` method or `%`-formatting.
-
-
-## For testing Starlark utilities
-
-[Skylib](https://github.com/bazelbuild/bazel-skylib)'s
-[`unittest.bzl`](https://github.com/bazelbuild/bazel-skylib/blob/main/lib/unittest.bzl)
-framework can be used to test utility functions (that is, functions that are
-neither macros nor rule implementations). Instead of using `unittest.bzl`'s
-`analysistest` library, `unittest` may be used. For such test suites, the
-convenience function `unittest.suite()` can be used to reduce boilerplate.
-
-`//mypkg/myhelpers.bzl`:
-
-```python
-def myhelper():
- return "abc"
-```
-
-`//mypkg/myhelpers_test.bzl`:
-
-
-```python
-load("@bazel_skylib//lib:unittest.bzl", "asserts", "unittest")
-load(":myhelpers.bzl", "myhelper")
-
-def _myhelper_test_impl(ctx):
- env = unittest.begin(ctx)
- asserts.equals(env, "abc", myhelper())
- return unittest.end(env)
-
-myhelper_test = unittest.make(_myhelper_test_impl)
-
-# No need for a test_myhelper() setup function.
-
-def myhelpers_test_suite(name):
- # unittest.suite() takes care of instantiating the testing rules and creating
- # a test_suite.
- unittest.suite(
- name,
- myhelper_test,
- # ...
- )
-```
-
-`//mypkg/BUILD`:
-
-```python
-load(":myhelpers_test.bzl", "myhelpers_test_suite")
-
-myhelpers_test_suite(name = "myhelpers_tests")
-```
-
-For more examples, see Skylib's own [tests](https://github.com/bazelbuild/bazel-skylib/blob/main/tests/BUILD).
diff --git a/site/docs/test-encyclopedia.html b/site/docs/test-encyclopedia.html
deleted file mode 100644
index 1be5d9d..0000000
--- a/site/docs/test-encyclopedia.html
+++ /dev/null
@@ -1,576 +0,0 @@
----
-layout: documentation
-title: Test Encyclopedia
----
-
-<div style="background-color: #EFCBCB; color: #AE2B2B; border: 1px solid #AE2B2B; border-radius: 5px; border-left: 10px solid #AE2B2B; padding: 0.5em;">
-<b>IMPORTANT:</b> The Bazel docs have moved! Please update your bookmark to <a href="https://bazel.build/reference/test-encyclopedia" style="color: #0000EE;">https://bazel.build/reference/test-encyclopedia</a>
-<p/>
-You can <a href="https://blog.bazel.build/2022/02/17/Launching-new-Bazel-site.html" style="color: #0000EE;">read about</a> the migration, and let us <a href="https://forms.gle/onkAkr2ZwBmcbWXj7" style="color: #0000EE;">know what you think</a>.
-</div>
-
-<h1>Test encyclopedia</h1>
-
-<p class="lead">An Exhaustive Specification of the Test Execution Environment</p>
-
-<h2>Background</h2>
-
-<p>The Bazel BUILD language includes rules which can be used to define
-automated test programs in many languages.</p>
-
-<p>Tests are run using <code><a href="user-manual.html#test">bazel test</a></code>.
-
-Users may also execute test binaries directly. This is allowed but not endorsed, as such
-an invocation will not adhere to the mandates described below.</p>
-
-<p>Tests should be <i>hermetic</i>: that is, they ought to access only those
-resources on which they have a declared dependency. If tests are not properly
-hermetic then they do not give historically reproducible results. This could be a
-significant problem for culprit finding (determining which change broke a test),
-release engineering auditability, and resource isolation of tests (automated
-testing frameworks ought not DDOS a server because some tests happen to
-talk to it).<p>
-
-<h2>Objective</h2>
-
-<p>The goal of this page is to formally establish the runtime environment
-for and expected behavior of Bazel tests. It will also impose requirements on
-the test runner and the build system.
-
-The test environment specification helps test authors avoid relying on
-unspecified behavior, and thus gives the testing infrastructure more freedom
-to make implementation changes. The specification tightens up some
-holes that currently allow many tests to pass despite not being
-properly hermetic, deterministic, and reentrant.</p>
-
-<p>This page is intended to be both normative and authoritative. If
-this specification and the implemented behavior of test runner disagree, the
-specification takes precedence.</p>
-
-<h2>Proposed Specification</h2>
-
-<p>The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD",
-"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" are to be
-interpreted as described in IETF RFC 2119.</p>
-
-<h2>Purpose of tests</h2>
-
-<p>The purpose of Bazel tests is to confirm some property of the source files
-checked into the repository. (On this page, "source files" includes test data,
-golden outputs, and anything else kept under version control.) One
-user writes a test to assert an invariant which they expect to be maintained.
-Other users execute the test later to check whether the invariant has been
-broken. If the test depends on any variables other than source files
-(non-hermetic), its value is diminished, because the later users cannot be sure
-their changes are at fault when the test stops passing.</p>
-
-<p>Therefore the outcome of a test must depend only on:</p>
-<ul>
- <li>source files on which the test has a declared dependency</li>
- <li>products of the build system on which the test has a declared dependency</li>
- <li>resources whose behavior is guaranteed by the test runner to remain constant</li>
-</ul>
-
-<p>Currently, such behavior is not enforced. However, test runners reserve the
-right to add such enforcement in the future.</p>
-
-<h2>Role of the build system</h2>
-
-<p>Test rules are analogous to binary rules in that each must yield an
-executable program. For some languages, this is a stub program which combines
-a language-specific harness with the test code. Test rules must produce other
-outputs as well. In addition to the primary test executable, the test runner
-will need a manifest of <b>runfiles</b>, input files which should be made
-available to the test at runtime, and it may need information about the type,
-size, and tags of a test.</p>
-
-<p>The build system may use the runfiles to deliver code as well as data. (This
-might be used as an optimization to make each test binary smaller by sharing
-files across tests, e.g. through the use of dynamic linking.) The build system
-should ensure that the generated executable loads these files via the runfiles
-image provided by the test runner, rather than hardcoded references to absolute
-locations in the source or output tree.</p>
-
-<h2>Role of the test runner</h2>
-
-<p>From the point of view of the test runner, each test is a program which can
-be invoked with <code>execve()</code>. There may be other ways to execute
-tests; for example, an IDE might allow the execution of Java tests in-process.
-However, the result of running the test as a standalone process must be
-considered authoritative. If a test process runs to completion and terminates
-normally with an exit code of zero, the test has passed. Any other result is
-considered a test failure. In particular, writing any of the strings
-<code>PASS</code> or <code>FAIL</code> to stdout has no significance to the test
-runner.</p>
-
-<p>If a test takes too long to execute, exceeds some resource limit, or the test
-runner otherwise detects prohibited behavior, it may choose to kill the test
-and treat the run as a failure. The runner must not report the test as passing
-after sending a signal to the test process or any children thereof.</p>
-
-<p id="timeout">The whole test target (not individual methods or tests) is given a
-limited amount of time to run to completion. The time limit for a test is based
-on its <a href="be/common-definitions.html#test.timeout"><code>timeout</code></a>
-attribute according to the following table:</p>
-
-<table class="table table-bordered table-striped table-condensed">
- <thead>
- <tr>
- <th><a href="be/common-definitions.html#test.timeout"><code>timeout</code></a></th>
- <th>Time Limit (sec.)</th>
- </tr>
- </thead>
- <tbody>
- <tr><td><code>short</code></td><td>60</td></tr>
- <tr><td><code>moderate</code></td><td>300</td></tr>
- <tr><td><code>long</code></td><td>900</td></tr>
- <tr><td><code>eternal</code></td><td>3600</td></tr>
- </tbody>
-</table>
-
-<p id="size">Tests which do not explicitly specify a timeout have one implied based on the
-test's <a href="be/common-definitions.html#test.size"><code>size</code></a> as follows:</p>
-
-<table class="table table-bordered table-striped table-condensed">
- <thead>
- <tr>
- <th><a href="be/common-definitions.html#test.size"><code>size</code></a></th>
- <th>Implied timeout label</th>
- </tr>
- </thead>
- <tbody>
- <tr><td><code>small</code></td><td>short</td></tr>
- <tr><td><code>medium</code></td><td>moderate</td></tr>
- <tr><td><code>large</code></td><td>long</td></tr>
- <tr><td><code>enormous</code></td><td>eternal</td></tr>
- </tbody>
-</table>
-<p>For example a "large" test with no explicit timeout setting will be allotted
-900 seconds to run. A "medium" test with a timeout of "short" will be allotted
-60 seconds.</p>
-
-<p>Unlike <code>timeout</code>, the <code>size</code> additionally determines the
-the assumed peak usage of other resources (like RAM) when running the test locally,
-as described in <a href="be/common-definitions.html#common-attributes-tests">Common
-definitions</a>.</p>
-
-<p>All combinations of <code>size</code> and <code>timeout</code> labels are
-legal, so an "enormous" test may be declared to have a timeout of "short".
-Presumably it would do some really horrible things very quickly.</p>
-<p>Tests may return arbitrarily fast regardless of timeout. A test is not
-penalized for an overgenerous timeout, although a warning may be issued: you
-should generally set your timeout as tight as you can without incurring any
-flakiness.</p>
-
-<p>The test timeout can be overridden with the <code>--test_timeout</code>
-bazel flag, e.g. for manually running under conditions which are known to be
-slow. The <code>--test_timeout</code> values are in seconds. For example,
-<code>--test_timeout=120</code> will set the test timeout to two minutes.</p>
-
-<p>There is also a recommended lower bound for test timeouts as follows: </p>
-
-<table class="table table-bordered table-striped table-condensed">
- <thead>
- <tr><th>timeout</th><th>Time minimum (sec.)</th></tr>
- </thead>
- <tbody>
- <tr><td><code>short</code></td><td>0</td></tr>
- <tr><td><code>moderate</code></td><td>30</td></tr>
- <tr><td><code>long</code></td><td>300</td></tr>
- <tr><td><code>eternal</code></td><td>900</td></tr>
- </tbody>
-</table>
-
-<p>For example, if a "moderate" test completes in 5.5s, consider setting
-<code>timeout = "short"</code> or <code>size = "small"</code>. Using the bazel
-<code>--test_verbose_timeout_warnings</code> command line option will show the
-tests whose specified size is too big.</p>
-
-<p>Test sizes and timeouts are specified in the BUILD file according to the specification
-<a href="be/common-definitions.html#common-attributes-tests">here</a>.
-If unspecified, a test's size will default to "medium".</p>
-
-<p>If the main process of a test exits, but some of its children are still
-running, the test runner should consider the run complete and count it as a
-success or failure based on the exit code observed from the main process. The
-test runner may kill any stray processes. Tests should not leak processes in
-this fashion.</p>
-
-<h2 id="test-sharding">Test sharding</h2>
-
-<p>Tests can be parallelized via test sharding. See
-<a href="user-manual.html#sharding-strategy"><code>--test_sharding_strategy</code></a>
-and
-<a href="be/common-definitions.html#common-attributes-tests"><code>shard_count</code></a>
-to enable test sharding. When sharding is enabled, the test runner is launched
-once per shard. The environment variable
-<a href="#initial-conditions"><code>TEST_TOTAL_SHARDS</code></a> is the number
-of shards, and
-<a href="#initial-conditions"><code>TEST_SHARD_INDEX</code></a> is the shard
-index, beginning at 0. Runners use this information to select which tests to
-run - for example, using a round-robin strategy. Not all test runners support sharding.
-If a runner supports sharding, it must create or update the last modified date
-of the file specified by
-<a href="#initial-conditions"><code>TEST_SHARD_STATUS_FILE</code></a>.
-Otherwise, Bazel assumes it does not support sharding and will not launch
-additional runners.</p>
-
-<h2 id="initial-conditions">Initial conditions</h2>
-
-<p>When executing a test, the test runner must establish certain initial
-conditions.</p>
-
-<p>The test runner must invoke each test with the path to the test
-executable in <code>argv[0]</code>. This path must be relative and
-beneath the test's current directory (which is in the runfiles tree,
-see below).
-The test runner should not pass any other arguments to a
-test unless the user explicitly requests it.</p>
-
-<p>The initial environment block shall be composed as follows:</p>
-
-<table class="table table-bordered table-striped table-condensed">
- <thead>
- <tr><th>Variable</th><th>Value</th><th>Status</th></tr>
- </thead>
- <tbody>
-
- <tr><td><code>HOME</code></td><td>value of <code>$TEST_TMPDIR</code></td><td>recommended</td></tr>
- <tr><td><code>LANG</code></td><td><i>unset</i></td><td>required</td></tr>
- <tr><td><code>LANGUAGE</code></td><td><i>unset</i></td><td>required</td></tr>
- <tr><td><code>LC_ALL</code></td><td><i>unset</i></td><td>required</td></tr>
- <tr><td><code>LC_COLLATE</code></td><td><i>unset</i></td><td>required</td></tr>
- <tr><td><code>LC_CTYPE</code></td><td><i>unset</i></td><td>required</td></tr>
- <tr><td><code>LC_MESSAGES</code></td><td><i>unset</i></td><td>required</td></tr>
- <tr><td><code>LC_MONETARY</code></td><td><i>unset</i></td><td>required</td></tr>
- <tr><td><code>LC_NUMERIC</code></td><td><i>unset</i></td><td>required</td></tr>
- <tr><td><code>LC_TIME</code></td><td><i>unset</i></td><td>required</td></tr>
- <tr><td><code>LD_LIBRARY_PATH</code></td><td>colon-separated list of directories containing shared libraries</td><td>optional</td></tr>
- <tr><td><code>JAVA_RUNFILES</code></td><td>value of <code>$TEST_SRCDIR</code></td><td>deprecated</td></tr>
-
- <tr><td><code>LOGNAME</code></td><td>value of <code>$USER</code></td><td>required</td></tr>
-
- <tr><td><code>PATH</code></td><td><code>/usr/local/bin:/usr/local/sbin:/usr/bin:/usr/sbin:/bin:/sbin:.</code></td><td>recommended</td></tr>
- <tr><td><code>PWD</code></td><td><code>$TEST_SRCDIR/<i>workspace-name</i></code></td><td>recommended</td></tr>
- <tr><td><code>SHLVL</code></td><td><code>2</code></td><td>recommended</td></tr>
- <tr><td><code>TEST_INFRASTRUCTURE_FAILURE_FILE</code></td><td>absolute path to a private file in a writable directory (This file should only be used to report failures originating from the testing infrastructure, not as a general mechanism for reporting flaky failures of tests. In this context, testing infrastructure is defined as systems or libraries that are not test-specific, but can cause test failures by malfunctioning. The first line is the name of the testing infrastructure component that caused the failure, the second one a human-readable description of the failure. Additional lines are ignored.)</td><td>optional</td></tr>
- <tr><td><code>TEST_LOGSPLITTER_OUTPUT_FILE</code></td><td>absolute path to a private file in a writable directory (used to write Logsplitter protobuffer log)</td><td>optional</td></tr>
- <tr><td><code>TEST_PREMATURE_EXIT_FILE</code></td><td>absolute path to a private file in a writable directory (used for catching calls to exit())</td><td>optional</td></tr>
- <tr>
- <td><code>TEST_RANDOM_SEED</code></td>
- <td>If the <code class='flag'>--runs_per_test</code> option is used, TEST_RANDOM_SEED
- is set to the <var>run number</var> (starting with 1) for each individual test run.</td>
- <td>optional</td>
- </tr>
- <tr>
- <td><code>TEST_RUN_NUMBER</code></td>
- <td>If the <code class='flag'>--runs_per_test</code> option is used, TEST_RUN_NUMBER
- is set to the <var>run number</var> (starting with 1) for each individual test run.</td>
- <td>optional</td>
- </tr>
- <tr><td><code>TEST_TARGET</code></td><td>The name of the target being tested</td><td>optional</td></tr>
- <tr><td><code>TEST_SIZE</code></td><td>The test <a href="#size"><code>size</code></a></td><td>optional</td></tr>
- <tr><td><code>TEST_TIMEOUT</code></td><td>The test <a href="#timeout"><code>timeout</code></a> in seconds</td><td>optional</td></tr>
- <tr><td><code>TEST_SHARD_INDEX</code></td><td>shard index, if <a href="#test-sharding">sharding</a> is used</td><td>optional</td></tr>
- <tr><td><code>TEST_SHARD_STATUS_FILE</code></td><td>path to file to touch to indicate support for <a href="#test-sharding">sharding</a></td><td>optional</td></tr>
- <tr><td><code>TEST_SRCDIR</code></td><td>absolute path to the base of the runfiles tree</td><td>required</td></tr>
- <tr><td><code>TEST_TOTAL_SHARDS</code></td><td>total <a href="be/common-definitions.html#test.shard_count">shard count</a>, if <a href="#test-sharding">sharding</a> is used</td><td>optional</td></tr>
- <tr><td><code>TEST_TMPDIR</code></td><td>absolute path to a private writable directory</td><td>required</td></tr>
-
- <tr><td><code>TEST_WORKSPACE</code></td><td>the local repository's workspace name</td><td>optional</td></tr>
- <tr><td><code>TEST_UNDECLARED_OUTPUTS_DIR</code></td><td>absolute path to a private writable directory (used to write undeclared test outputs)</td><td>optional</td></tr>
-
- <tr><td><code>TEST_UNDECLARED_OUTPUTS_ANNOTATIONS_DIR</code></td><td>absolute path to a private writable directory (used to write undeclared test output annotation .part and .pb files).
- </td><td>optional</td></tr>
-
- <tr><td><code>TEST_WARNINGS_OUTPUT_FILE</code></td><td>absolute path to a private file in a writable directory (used to write test target warnings)</td><td>optional</td></tr>
- <tr><td><code>TESTBRIDGE_TEST_ONLY</code></td><td>value of <a href="user-manual.html#flag--test_filter"><code>--test_filter</code></a>, if specified</td><td>optional</td></tr>
-
- <tr><td><code>TZ</code></td><td><code>UTC</code></td><td>required</td></tr>
- <tr><td><code>USER</code></td><td>value of <code>getpwuid(getuid())->pw_name</code></td><td>required</td></tr>
-
- <tr>
- <td><code>XML_OUTPUT_FILE</code></td>
- <td>Location of the test result XML output file.
- The XML schema is based on the
- <a href="https://windyroad.com.au/dl/Open%20Source/JUnit.xsd">JUnit test result
- schema</a>.
- </td>
- <td>optional</td>
- </tr>
- </tbody>
-</table>
-<br>
-<p>The environment may contain additional entries. Tests should not depend on the
-presence, absence, or value of any environment variable not listed above.</p>
-
-<p>The initial working directory shall be <code>$TEST_SRCDIR/$TEST_WORKSPACE</code>.</p>
-<p> The current process id, process group id, session id, and parent process
-id are unspecified. The process may or may not be a process group leader or a
-session leader. The process may or may not have a controlling terminal. The
-process may have zero or more running or unreaped child processes. The process
-should not have multiple threads when the test code gains control.</p>
-
-<p>File descriptor 0 (stdin) shall be open for reading, but what it is attached
-to is unspecified. Tests must not read from it. File descriptors 1 (stdout)
-and 2 (stderr) shall be open for writing, but what they are attached to is
-unspecified. It could be a terminal, a pipe, a regular file, or anything else
-to which characters can be written. They may share an entry in the open file
-table (meaning that they cannot seek independently). Tests should not inherit
-any other open file descriptors.</p>
-
-<p>The initial umask shall be 022 or 027.</p>
-
-<p>No alarm or interval timer shall be pending.</p>
-
-<p>The initial mask of blocked signals shall be empty. All signals shall be set
-to their default action.</p>
-
-<p>The initial resource limits, both soft and hard, should be set as follows:</p>
-
-<table class="table table-bordered table-striped table-condensed">
- <thead>
- <tr><th>Resource</th><th>Limit</th></tr>
- </thead>
- <tbody>
- <tr><td>RLIMIT_AS</td><td>unlimited</td></tr>
- <tr><td>RLIMIT_CORE</td><td>unspecified</td></tr>
- <tr><td>RLIMIT_CPU</td><td>unlimited</td></tr>
- <tr><td>RLIMIT_DATA</td><td>unlimited</td></tr>
- <tr><td>RLIMIT_FSIZE</td><td>unlimited</td></tr>
- <tr><td>RLIMIT_LOCKS</td><td>unlimited</td></tr>
- <tr><td>RLIMIT_MEMLOCK</td><td>unlimited</td></tr>
- <tr><td>RLIMIT_MSGQUEUE</td><td>unspecified</td></tr>
- <tr><td>RLIMIT_NICE</td><td>unspecified</td></tr>
- <tr><td>RLIMIT_NOFILE</td><td>at least 1024</td></tr>
- <tr><td>RLIMIT_NPROC</td><td>unspecified</td></tr>
- <tr><td>RLIMIT_RSS</td><td>unlimited</td></tr>
- <tr><td>RLIMIT_RTPRIO</td><td>unspecified</td></tr>
- <tr><td>RLIMIT_SIGPENDING</td><td>unspecified</td></tr>
- <tr><td>RLIMIT_STACK</td><td>unlimited, or 2044KB <= rlim <= 8192KB</td></tr>
- </tbody>
-</table>
-
-<p>The initial process times (as returned by <code>times()</code>) and resource
-utilization (as returned by <code>getrusage()</code>) are unspecified.</p>
-
-<p>The initial scheduling policy and priority are unspecified.</p>
-
-<h2>Role of the host system</h2>
-
-<p>In addition to the aspects of user context under direct control of the
-test runner, the operating system on which tests execute must satisfy certain
-properties for a test run to be valid.</p>
-
-<h4>Filesystem</h4>
-
-<p>
-The root directory observed by a test may or may not be the real root directory.<br>
-<code>/proc</code> shall be mounted.<br>
-All build tools shall be present at the absolute paths under <code>/usr</code> used by a local installation.<br>
-Paths starting with <code>/home</code> may not be available. Tests should not access any such paths.<br>
-<code>/tmp</code>
-shall be writable, but tests should avoid using these paths.<br>
-
-Tests must not assume that any constant path is available for their exclusive use.<br>
-Tests must not assume that atimes are enabled for any mounted filesystem.<br>
-</p>
-
-<h4>Users and groups</h4>
-
-<p>The users root, nobody, and unittest must exist. The groups root, nobody,
-and eng must exist.</p>
-
-<p>Tests must be executed as a non-root user. The real and effective user ids
-must be equal; likewise for group ids. Beyond this, the current user id, group
-id, user name, and group name are unspecified. The set of supplementary group
-ids is unspecified.</p>
-
-<p>The current user id and group id must have corresponding names which can be
-retrieved with <code>getpwuid()</code> and <code>getgrgid()</code>. The same
-may not be true for supplementary group ids.</p>
-
-<p>The current user must have a home directory. It may not be writable. Tests
-must not attempt to write to it.</p>
-
-<h4>Networking</h4>
-
-<p>The hostname is unspecified. It may or may not contain a dot. Resolving
-the hostname must give an IP address of the current host. Resolving the
-hostname cut after the first dot must also work. The hostname localhost must
-resolve.</p>
-
-<h4>Other resources</h4>
-
-<p>Tests are granted at least one CPU core. Others may be available but this
-is not guaranteed. Other performance aspects of this core are not specified.
-You can increase the reservation to a higher number of CPU cores by adding the
-tag "cpu:n" (where n is a positive number) to a test rule. If a machine has
-less total CPU cores than requested, Bazel will still run the test. If a test
-uses <a href="#test-sharding">sharding</a>, each individual shard will reserve
-the number of CPU cores specified here.</p>
-
-<p>Tests may create subprocesses, but not process groups or sessions.</p>
-
-<p>There is a limit on the number of input files a test may consume. This limit
-is subject to change, but is currently in the range of tens of thousands of inputs.
-
-</p>
-
-<h4>Time and date</h4>
-
-<p>The current time and date are unspecified. The system timezone is unspecified.
-
-</p>
-
-<p>X Windows may or may not be available. Tests that need an X server should
-start Xvfb.</p>
-
-<h2>Test interaction with the filesystem</h2>
-<p>All file paths specified in test environment variables point to
-somewhere on the local filesystem, unless otherwise specified.</p>
-
-<p>
-Tests should create files only within the directories specified by
-<code>$TEST_TMPDIR</code> and <code>$TEST_UNDECLARED_OUTPUTS_DIR</code>
-(if set).<br>
-These directories will be initially empty.<br>
-Tests must not attempt to remove, chmod, or otherwise alter these directories.<br>
-These directories may be a symbolic links.<br>
-The filesystem type of <code>$TEST_TMPDIR/.</code> remains unspecified.<br>
-Tests may also write .part files to the <code>$TEST_UNDECLARED_OUTPUTS_ANNOTATIONS_DIR</code>
-to annotate undeclared output files.</p>
-
-<p>In rare cases, a test may be forced to create files in <code>/tmp</code>. For
-example, <a href="https://serverfault.com/questions/641347">path length limits
-for Unix domain sockets</a> typically require creating the socket under
-<code>/tmp</code>. Bazel will be unable to track such files; the test itself must
-take care to be hermetic, to use unique paths to avoid colliding with other,
-simultaneously running tests and non-test processes, and to clean up the files it
-creates in <code>/tmp</code>.</p>
-
-<p>Some popular testing frameworks, such as
-<a href="https://junit.org/junit4/javadoc/latest/org/junit/rules/TemporaryFolder.html">
-JUnit4 <code>TemporaryFolder</code></a> or
-<a href="https://golang.org/pkg/testing/#T.TempDir">Go <code>TempDir</code></a>,
-have their own ways to create a temporary directory under <code>/tmp</code>.
-These testing frameworks include functionality that cleans up files in <code>/tmp</code>,
-so you may use them even though they create files outside of <code>TEST_TMPDIR</code>.</p>
-
-<p>Tests must access inputs through the <b>runfiles</b> mechanism, or other
-parts of the execution environment which are specifically intended to make
-input files available.
-
-Tests must not access other outputs of the
-build system at paths inferred from the location of their own executable.</p>
-
-<p>It is unspecified whether the runfiles tree contains regular files, symbolic
-links, or a mixture. The runfiles tree may contain symlinks to directories.
-Tests should avoid using paths containing <code>..</code> components within the
-runfiles tree.</p>
-
-<p>No directory, file, or symlink within the runfiles tree (including paths
-which traverse symlinks) should be writable. (It follows that the initial
-working directory should not be writable.) Tests must not assume that any part
-of the runfiles is writable, or owned by the current user (i.e. chmod and chgrp
-may fail).</p>
-
-<p>The runfiles tree (including paths which traverse symlinks) must not change
-during test execution. Parent directories and filesystem mounts must not change
-in any way which affects the result of resolving a path within the runfiles
-tree.</p>
-
-<p>In order to catch early exit, a test may create a file at the path specified by
-<code>TEST_PREMATURE_EXIT_FILE</code> upon start and remove it upon exit. If
-Bazel sees the file when the test finishes, it will assume that the test exited
-prematurely and mark it as having failed.</p>
-
-<h2 id="tag-conventions">Tag conventions</h2>
-
-<p>
- Some tags in the test rules have a special
- meaning. See also the <a href="be/common-definitions.html#common.tags">Bazel
- Build Encyclopedia on the <code>tags</code> attribute</a>.
-</p>
-
-<table class="table table-bordered table-striped table-condensed">
- <thead>
- <tr><th>Tag</th><th>Meaning</th></tr>
- </thead>
- <tbody>
- <tr>
- <th><code>exclusive</code></th>
-
- <td>run no other test at the same time</td>
- </tr>
- <tr>
- <th><code>external</code></th>
- <td>test has an external dependency; disable test caching</td>
- </tr>
- <tr>
- <th><code>large</code></th>
- <td><code>test_suite</code> convention; suite of large tests</td>
- </tr>
-
- <tr>
- <th><code>manual</code> *</th>
-
- <td>don't include test target in wildcard target patterns like <code>:...</code>, <code>:*</code>, or <code>:all</code>)</td>
- </tr>
- <tr>
- <th><code>medium</code></th>
-
- <td><code>test_suite</code> convention; suite of medium tests</td>
- </tr>
-
- <tr>
- <th><code>small</code></th>
- <td><code>test_suite</code> convention; suite of small tests</td>
- </tr>
-
- <tr>
- <th><code>smoke</code></th>
- <td>
- <code>test_suite</code> convention; means it should be run before committing code changes
- into the version control system
- </td>
- </tr>
-
- </tbody>
-</table>
-
-* Note: bazel <code>query</code> does not respect the manual tag.
-<h2>Runfiles</h2>
-
-<p>In the following, assume there is a *_binary() rule labeled <code>//foo/bar:unittest</code>,
-with a run-time dependency on the rule labeled <code>//deps/server:server</code>.</p>
-
-<h4>Location</h4>
-<p>The runfiles directory for a target <code>//foo/bar:unittest</code> is the directory
-<code>$(WORKSPACE)/$(BINDIR)/foo/bar/unittest.runfiles</code>. This path is referred to as the
-<code>runfiles_dir</code>.</p>
-
-<h4>Dependencies</h4>
-<p>The runfiles directory is declared as a compile-time dependency of the *_binary() rule.
-The runfiles directory itself depends on the set of BUILD files that affect the *_binary() rule
-or any of its compile-time or run-time dependencies. Modifying source files does not affect the
-structure of the runfiles directory, and thus does not trigger any rebuilding.</p>
-
-<h4>Contents</h4>
-<p>The runfiles directory contains the following:</p>
-<ul>
- <li><b>Symlinks to run-time dependencies</b>: each OutputFile and CommandRule that is a run-time
-dependency of the *_binary() rule is represented by one symlink in the runfiles directory.
-The name of the symlink is <code>$(WORKSPACE)/package_name/rule_name</code>. For example, the
-symlink for server would be named <code>$(WORKSPACE)/deps/server/server</code>, and the full path
-would be <code>$(WORKSPACE)/foo/bar/unittest.runfiles/$(WORKSPACE)/deps/server/server</code>.
-The destination of the symlink is the OutputFileName() of the OutputFile or CommandRule,
-expressed as an absolute path. Thus, the destination of the symlink might be
-<code>$(WORKSPACE)/linux-dbg/deps/server/42/server</code>.</li>
- <li><b>Symlinks to sub-runfiles</b>: for every *_binary() Z that is a run-time dependency of
-*_binary() C, there is a second link in the runfiles directory of C to the runfiles of Z.
-The name of the symlink is <code>$(WORKSPACE)/package_name/rule_name.runfiles</code>.
-The target of the symlink is the runfiles directory. I.e. all subprograms share a common
-runfiles directory.</li>
-</ul>
-
diff --git a/site/docs/toolchain_resolution_implementation.md b/site/docs/toolchain_resolution_implementation.md
deleted file mode 100644
index 5d9fa79..0000000
--- a/site/docs/toolchain_resolution_implementation.md
+++ /dev/null
@@ -1,73 +0,0 @@
----
-layout: documentation
-title: Toolchain Resolution Implementation Details
----
-
-<div style="background-color: #EFCBCB; color: #AE2B2B; border: 1px solid #AE2B2B; border-radius: 5px; border-left: 10px solid #AE2B2B; padding: 0.5em;">
-<b>IMPORTANT:</b> The Bazel docs have moved! Please update your bookmark to <a href="https://bazel.build/docs/toolchain_resolution_implementation" style="color: #0000EE;">https://bazel.build/docs/toolchain_resolution_implementation</a>
-<p/>
-You can <a href="https://blog.bazel.build/2022/02/17/Launching-new-Bazel-site.html" style="color: #0000EE;">read about</a> the migration, and let us <a href="https://forms.gle/onkAkr2ZwBmcbWXj7" style="color: #0000EE;">know what you think</a>.
-</div>
-
-
-# Toolchain Resolution Implementation Details
-
-
-**Note:** This section is intended for Bazel developers, and is not needed by
-rule authors.
-
-Several SkyFunction classes implement the [toolchain resolution][Toolchains] process:
-
-1. [`RegisteredToolchainsFunction`][RegisteredToolchainsFunction] and
- [`RegisteredExecutionPlatformsFunction`][RegisteredExecutionPlatformsFunction]
- find available toolchains and execution platforms, based on the current
- configuration and WORKSPACE file.
-
-1. [`SingleToolchainResolutionFunction`][SingleToolchainResolutionFunction]
- resolves a single toolchain type for every execution platform. That is, for
- every execution platform it finds the best registered toolchain to use based
- on the following criteria:
-
- 1. Make sure the toolchain and target platform are compatible, by checking
- the `target_compatible_with` attribute.
- 1. Make sure the toolchain and execution platform are compatible, by
- checking the `exec_compatible_with` attribute.
- 1. If multiple toolchains are left, choose the highest-priority one (the
- one that was registered first).
-
-1. [`ToolchainResolutionFunction`][ToolchainResolutionFunction] calls
- `SingleToolchainResolutionFunction` for each requested toolchain type, and
- then determines the best execution platform to use.
-
- 1. First, remove any execution platform that does not have a valid
- toolchain for each requested toolchain type.
- 2. If multiple execution platforms are left, choose the highest-priority
- one (the one that was registered first).
- 1. If the execution platform is already set by the toolchain
- transition, it will be selected first as described below.
-
-As discussed in [Toolchains and Configurations][Toolchains and Configurations],
-the dependency from a target to a toolchain uses a special configuration that
-forces the execution platform to be the same for both. Despite the name
-"toolchain transition", this is not implemented as a configuration
-transition, but instead as a special subclass of
-[`ConfiguredTargetKey`][ConfiguredTargetKey], called
-[`ToolchainDependencyConfiguredTargetKey`][ToolchainDependencyConfiguredTargetKey].
-In addition to the other data in `ConfiguredTargetKey`, this subclass also holds
-the label of the execution platform. When `ToolchainResolutionFunction` is
-considering which execution platform to use, if the forced execution platform
-from the `ToolchainDependencyConfiguredTargetKey` is valid, it will be used even
-if it is not the highest-priority.
-
-**Note:** If the forced execution platform is not valid (because there are no
-valid toolchains, or because of execution constraints from the rule or target),
-then the highest-priority valid execution platform will be used instead.
-
-[ConfiguredTargetKey]: https://cs.opensource.google/bazel/bazel/+/master:src/main/java/com/google/devtools/build/lib/skyframe/ConfiguredTargetKey.java
-[RegisteredExecutionPlatformsFunction]: https://cs.opensource.google/bazel/bazel/+/master:src/main/java/com/google/devtools/build/lib/skyframe/RegisteredExecutionPlatformsFunction.java
-[RegisteredToolchainsFunction]: https://cs.opensource.google/bazel/bazel/+/master:src/main/java/com/google/devtools/build/lib/skyframe/RegisteredToolchainsFunction.java
-[SingleToolchainResolutionFunction]: https://cs.opensource.google/bazel/bazel/+/master:src/main/java/com/google/devtools/build/lib/skyframe/SingleToolchainResolutionFunction.java
-[ToolchainDependencyConfiguredTargetKey]: https://cs.opensource.google/bazel/bazel/+/master:src/main/java/com/google/devtools/build/lib/skyframe/ConfiguredTargetKey.java;bpv=1;bpt=1;l=164?ss=bazel&q=ConfiguredTargetKey&gsn=ToolchainDependencyConfiguredTargetKey&gs=kythe%3A%2F%2Fgithub.com%2Fbazelbuild%2Fbazel%3Flang%3Djava%3Fpath%3Dcom.google.devtools.build.lib.skyframe.ConfiguredTargetKey.ToolchainDependencyConfiguredTargetKey%2336c7e68f8cd5ea0b5a21b3769e63e6b2d489b9ca8c6f79798839e7f40cf2a19e
-[ToolchainResolutionFunction]: https://cs.opensource.google/bazel/bazel/+/master:src/main/java/com/google/devtools/build/lib/skyframe/ToolchainResolutionFunction.java
-[Toolchains]: toolchains.html
-[Toolchains and Configurations]: toolchains.html#toolchains-and-configurations
diff --git a/site/docs/toolchains.md b/site/docs/toolchains.md
deleted file mode 100644
index 3ddc497..0000000
--- a/site/docs/toolchains.md
+++ /dev/null
@@ -1,534 +0,0 @@
----
-layout: documentation
-title: Toolchains
----
-
-<div style="background-color: #EFCBCB; color: #AE2B2B; border: 1px solid #AE2B2B; border-radius: 5px; border-left: 10px solid #AE2B2B; padding: 0.5em;">
-<b>IMPORTANT:</b> The Bazel docs have moved! Please update your bookmark to <a href="https://bazel.build/docs/toolchains" style="color: #0000EE;">https://bazel.build/docs/toolchains</a>
-<p/>
-You can <a href="https://blog.bazel.build/2022/02/17/Launching-new-Bazel-site.html" style="color: #0000EE;">read about</a> the migration, and let us <a href="https://forms.gle/onkAkr2ZwBmcbWXj7" style="color: #0000EE;">know what you think</a>.
-</div>
-
-
-# Toolchains
-
-
-This page describes the toolchain framework, which is a way for rule authors to
-decouple their rule logic from platform-based selection of tools. It is
-recommended to read the [rules][Rules] and [platforms][Platforms] pages before
-continuing. This page covers why toolchains are needed, how to define and use
-them, and how Bazel selects an appropriate toolchain based on platform
-constraints.
-
-## Motivation
-
-Let's first look at the problem toolchains are designed to solve. Suppose you
-are writing rules to support the "bar" programming language. Your `bar_binary`
-rule would compile `*.bar` files using the `barc` compiler, a tool that itself
-is built as another target in your workspace. Since users who write `bar_binary`
-targets shouldn't have to specify a dependency on the compiler, you make it an
-implicit dependency by adding it to the rule definition as a private attribute.
-
-```python
-bar_binary = rule(
- implementation = _bar_binary_impl,
- attrs = {
- "srcs": attr.label_list(allow_files = True),
- ...
- "_compiler": attr.label(
- default = "//bar_tools:barc_linux", # the compiler running on linux
- providers = [BarcInfo],
- ),
- },
-)
-```
-
-`//bar_tools:barc_linux` is now a dependency of every `bar_binary` target, so
-it'll be built before any `bar_binary` target. It can be accessed by the rule's
-implementation function just like any other attribute:
-
-```python
-BarcInfo = provider(
- doc = "Information about how to invoke the barc compiler.",
- # In the real world, compiler_path and system_lib might hold File objects,
- # but for simplicity they are strings for this example. arch_flags is a list
- # of strings.
- fields = ["compiler_path", "system_lib", "arch_flags"],
-)
-
-def _bar_binary_impl(ctx):
- ...
- info = ctx.attr._compiler[BarcInfo]
- command = "%s -l %s %s" % (
- info.compiler_path,
- info.system_lib,
- " ".join(info.arch_flags),
- )
- ...
-```
-
-The issue here is that the compiler's label is hardcoded into `bar_binary`, yet
-different targets may need different compilers depending on what platform they
-are being built for and what platform they are being built on -- called the
-*target platform* and *execution platform*, respectively. Furthermore, the rule
-author does not necessarily even know all the available tools and platforms, so
-it is not feasible to hardcode them in the rule's definition.
-
-A less-than-ideal solution would be to shift the burden onto users, by making
-the `_compiler` attribute non-private. Then individual targets could be
-hardcoded to build for one platform or another.
-
-```python
-bar_binary(
- name = "myprog_on_linux",
- srcs = ["mysrc.bar"],
- compiler = "//bar_tools:barc_linux",
-)
-
-bar_binary(
- name = "myprog_on_windows",
- srcs = ["mysrc.bar"],
- compiler = "//bar_tools:barc_windows",
-)
-```
-
-You can improve on this solution by using `select` to choose the `compiler`
-[based on the platform][Configurable attributes]:
-
-```python
-config_setting(
- name = "on_linux",
- constraint_values = [
- "@platforms//os:linux",
- ],
-)
-
-config_setting(
- name = "on_windows",
- constraint_values = [
- "@platforms//os:windows",
- ],
-)
-
-bar_binary(
- name = "myprog",
- srcs = ["mysrc.bar"],
- compiler = select({
- ":on_linux": "//bar_tools:barc_linux",
- ":on_windows": "//bar_tools:barc_windows",
- }),
-)
-```
-
-But this is tedious and a bit much to ask of every single `bar_binary` user. If
-this style is not used consistently throughout the workspace, it leads to builds
-that work fine on a single platform but fail when extended to multi-platform
-scenarios. It also does not address the problem of adding support for new
-platforms and compilers without modifying existing rules or targets.
-
-The toolchain framework solves this problem by adding an extra level of
-indirection. Essentially, you declare that your rule has an abstract dependency
-on *some* member of a family of targets (a toolchain type), and Bazel
-automatically resolves this to a particular target (a toolchain) based on the
-applicable platform constraints. Neither the rule author nor the target author
-need know the complete set of available platforms and toolchains.
-
-## Writing rules that use toolchains
-
-Under the toolchain framework, instead of having rules depend directly on tools,
-they instead depend on *toolchain types*. A toolchain type is a simple target
-that represents a class of tools that serve the same role for different
-platforms. For instance, you can declare a type that represents the bar
-compiler:
-
-```python
-# By convention, toolchain_type targets are named "toolchain_type" and
-# distinguished by their package path. So the full path for this would be
-# //bar_tools:toolchain_type.
-toolchain_type(name = "toolchain_type")
-```
-
-The rule definition in the previous section is modified so that instead of
-taking in the compiler as an attribute, it declares that it consumes a
-`//bar_tools:toolchain_type` toolchain.
-
-```python
-bar_binary = rule(
- implementation = _bar_binary_impl,
- attrs = {
- "srcs": attr.label_list(allow_files = True),
- ...
- # No `_compiler` attribute anymore.
- },
- toolchains = ["//bar_tools:toolchain_type"]
-)
-```
-
-The implementation function now accesses this dependency under `ctx.toolchains`
-instead of `ctx.attr`, using the toolchain type as the key.
-
-```python
-def _bar_binary_impl(ctx):
- ...
- info = ctx.toolchains["//bar_tools:toolchain_type"].barcinfo
- # The rest is unchanged.
- command = "%s -l %s %s" % (
- info.compiler_path,
- info.system_lib,
- " ".join(info.arch_flags),
- )
- ...
-```
-
-`ctx.toolchains["//bar_tools:toolchain_type"]` returns the
-[`ToolchainInfo` provider][ToolchainInfo] of whatever target Bazel resolved the
-toolchain dependency to. The fields of the `ToolchainInfo` object are set by the
-underlying tool's rule; in the next section, this rule is defined such that
-there is a `barcinfo` field that wraps a `BarcInfo` object.
-
-Bazel's procedure for resolving toolchains to targets is described
-[below](#toolchain-resolution). Only the resolved toolchain target is actually
-made a dependency of the `bar_binary` target, not the whole space of candidate
-toolchains.
-
-### Writing aspects that use toolchains
-
-Aspects have access to the same toolchain API as rules: you can define required
-toolchain types, access toolchains via the context, and use them to generate new
-actions using the toolchain.
-
-```py
-bar_aspect = aspect(
- implementation = _bar_aspect_impl,
- attrs = {},
- toolchains = ['//bar_tools:toolchain_type'],
-)
-
-def _bar_aspect_impl(target, ctx):
- toolchain = ctx.toolchains['//bar_tools:toolchain_type']
- # Use the toolchain provider like in a rule.
- return []
-```
-
-## Defining toolchains
-
-To define some toolchains for a given toolchain type, you need three things:
-
-1. A language-specific rule representing the kind of tool or tool suite. By
- convention this rule's name is suffixed with "\_toolchain".
-
- 1. **Note:** The `\_toolchain` rule cannot create any build actions.
- Rather, it collects artifacts from other rules and forwards them to the
- rule that uses the toolchain. That rule is responsible for creating all
- build actions.
-
-2. Several targets of this rule type, representing versions of the tool or tool
- suite for different platforms.
-
-3. For each such target, an associated target of the generic
- [`toolchain`][Toolchain rule] rule, to provide metadata used by the
- toolchain framework. This `toolchain` target also refers to the
- `toolchain_type` associated with this toolchain. This means that a given
- `_toolchain` rule could be associated with any `toolchain_type`, and that
- only in a `toolchain` instance that uses this `_toolchain` rule that the
- rule is associated with a `toolchain_type`.
-
-For our running example, here's a definition for a `bar_toolchain` rule. Our
-example has only a compiler, but other tools such as a linker could also be
-grouped underneath it.
-
-```python
-def _bar_toolchain_impl(ctx):
- toolchain_info = platform_common.ToolchainInfo(
- barcinfo = BarcInfo(
- compiler_path = ctx.attr.compiler_path,
- system_lib = ctx.attr.system_lib,
- arch_flags = ctx.attr.arch_flags,
- ),
- )
- return [toolchain_info]
-
-bar_toolchain = rule(
- implementation = _bar_toolchain_impl,
- attrs = {
- "compiler_path": attr.string(),
- "system_lib": attr.string(),
- "arch_flags": attr.string_list(),
- },
-)
-```
-
-The rule must return a `ToolchainInfo` provider, which becomes the object that
-the consuming rule retrieves using `ctx.toolchains` and the label of the
-toolchain type. `ToolchainInfo`, like `struct`, can hold arbitrary field-value
-pairs. The specification of exactly what fields are added to the `ToolchainInfo`
-should be clearly documented at the toolchain type. In this example, the values
-return wrapped in a `BarcInfo` object to reuse the schema defined above; this
-style may be useful for validation and code reuse.
-
-Now you can define targets for specific `barc` compilers.
-
-```python
-bar_toolchain(
- name = "barc_linux",
- arch_flags = [
- "--arch=Linux",
- "--debug_everything",
- ],
- compiler_path = "/path/to/barc/on/linux",
- system_lib = "/usr/lib/libbarc.so",
-)
-
-bar_toolchain(
- name = "barc_windows",
- arch_flags = [
- "--arch=Windows",
- # Different flags, no debug support on windows.
- ],
- compiler_path = "C:\\path\\on\\windows\\barc.exe",
- system_lib = "C:\\path\\on\\windows\\barclib.dll",
-)
-```
-
-Finally, you create `toolchain` definitions for the two `bar_toolchain` targets.
-These definitions link the language-specific targets to the toolchain type and
-provide the constraint information that tells Bazel when the toolchain is
-appropriate for a given platform.
-
-```python
-toolchain(
- name = "barc_linux_toolchain",
- exec_compatible_with = [
- "@platforms//os:linux",
- "@platforms//cpu:x86_64",
- ],
- target_compatible_with = [
- "@platforms//os:linux",
- "@platforms//cpu:x86_64",
- ],
- toolchain = ":barc_linux",
- toolchain_type = ":toolchain_type",
-)
-
-toolchain(
- name = "barc_windows_toolchain",
- exec_compatible_with = [
- "@platforms//os:windows",
- "@platforms//cpu:x86_64",
- ],
- target_compatible_with = [
- "@platforms//os:windows",
- "@platforms//cpu:x86_64",
- ],
- toolchain = ":barc_windows",
- toolchain_type = ":toolchain_type",
-)
-```
-
-The use of relative path syntax above suggests these definitions are all in the
-same package, but there's no reason the toolchain type, language-specific
-toolchain targets, and `toolchain` definition targets can't all be in separate
-packages.
-
-See the [`go_toolchain`][Go toolchain] for a real-world example.
-
-### Toolchains and configurations
-
-An important question for rule authors is, when a `bar_toolchain` target is
-analyzed, what [configuration][Configuration] does it see, and what transitions
-should be used for dependencies? The example above uses string attributes, but
-what would happen for a more complicated toolchain that depends on other targets
-in the Bazel repository?
-
-Let's see a more complex version of `bar_toolchain`:
-
-```python
-def _bar_toolchain_impl(ctx):
- # The implementation is mostly the same as above, so skipping.
- pass
-
-bar_toolchain = rule(
- implementation = _bar_toolchain_impl,
- attrs = {
- "compiler": attr.label(
- executable = True,
- mandatory = True,
- cfg = "exec",
- ),
- "system_lib": attr.label(
- mandatory = True,
- cfg = "target",
- ),
- "arch_flags": attr.string_list(),
- },
-)
-```
-
-The use of [`attr.label`][Label attributes] is the same as for a standard rule,
-but the meaning of the `cfg` parameter is slightly different.
-
-The dependency from a target (called the "parent") to a toolchain via toolchain
-resolution uses a special configuration transition called the "toolchain
-transition". The toolchain transition keeps the configuration the same, except
-that it forces the execution platform to be the same for the toolchain as for
-the parent (otherwise, toolchain resolution for the toolchain could pick any
-execution platform, and wouldn't necessarily be the same as for parent). This
-allows any `exec` dependencies of the toolchain to also be executable for the
-parent's build actions. Any of the toolchain's dependencies which use `cfg =
-"target"` (or which don't specify `cfg`, since "target" is the default) are
-built for the same target platform as the parent. This allows toolchain rules to
-contribute both libraries (the `system_lib` attribute above) and tools (the
-`compiler` attribute) to the build rules which need them. The system libraries
-are linked into the final artifact, and so need to be built for the same
-platform, whereas the compiler is a tool invoked during the build, and needs to
-be able to run on the execution platform.
-
-## Registering and building with toolchains
-
-At this point all the building blocks are assembled, and you just need to make
-the toolchains available to Bazel's resolution procedure. This is done by
-registering the toolchain, either in a `WORKSPACE` file using
-`register_toolchains()`, or by passing the toolchains' labels on the command
-line using the `--extra_toolchains` flag.
-
-```python
-register_toolchains(
- "//bar_tools:barc_linux_toolchain",
- "//bar_tools:barc_windows_toolchain",
- # Target patterns are also permitted, so you could have also written:
- # "//bar_tools:all",
-)
-```
-
-Now when you build a target that depends on a toolchain type, an appropriate
-toolchain will be selected based on the target and execution platforms.
-
-```python
-# my_pkg/BUILD
-
-platform(
- name = "my_target_platform",
- constraint_values = [
- "@platforms//os:linux",
- ],
-)
-
-bar_binary(
- name = "my_bar_binary",
- ...
-)
-```
-
-```sh
-bazel build //my_pkg:my_bar_binary --platforms=//my_pkg:my_target_platform
-```
-
-Bazel will see that `//my_pkg:my_bar_binary` is being built with a platform that
-has `@platforms//os:linux` and therefore resolve the
-`//bar_tools:toolchain_type` reference to `//bar_tools:barc_linux_toolchain`.
-This will end up building `//bar_tools:barc_linux` but not
-`//bar_tools:barc_windows`.
-
-## Toolchain resolution
-
-**Note:** [Some Bazel rules][Rules status] do not yet support toolchain
-resolution.
-
-For each target that uses toolchains, Bazel's toolchain resolution procedure
-determines the target's concrete toolchain dependencies. The procedure takes as
-input a set of required toolchain types, the target platform, the list of
-available execution platforms, and the list of available toolchains. Its outputs
-are a selected toolchain for each toolchain type as well as a selected execution
-platform for the current target.
-
-The available execution platforms and toolchains are gathered from the
-`WORKSPACE` file via
-[`register_execution_platforms`][Workspace function register_execution_platforms]
-and [`register_toolchains`][Workspace function register_toolchains]. Additional
-execution platforms and toolchains may also be specified on the command line via
-[`--extra_execution_platforms`][Flag extra_execution_platforms] and
-[`--extra_toolchains`][Flag extra_toolchains]. The host platform is
-automatically included as an available execution platform. Available platforms
-and toolchains are tracked as ordered lists for determinism, with preference
-given to earlier items in the list.
-
-The resolution steps are as follows.
-
-1. A `target_compatible_with` or `exec_compatible_with` clause *matches* a
- platform iff, for each `constraint_value` in its list, the platform also has
- that `constraint_value` (either explicitly or as a default).
-
- If the platform has `constraint_value`s from `constraint_setting`s not
- referenced by the clause, these do not affect matching.
-
-1. If the target being built specifies the
- [`exec_compatible_with` attribute][Common exec_compatible_with attribute]
- (or its rule definition specifies the
- [`exec_compatible_with` argument][Rule exec_compatible_with argument]) the
- list of available execution platforms is filtered to remove any that do not
- match the execution constraints.
-
-1. For each available execution platform, you associate each toolchain type
- with the first available toolchain, if any, that is compatible with this
- execution platform and the target platform.
-
-1. Any execution platform that failed to find a compatible toolchain for one of
- its toolchain types is ruled out. Of the remaining platforms, the first one
- becomes the current target's execution platform, and its associated
- toolchains become dependencies of the target.
-
-The chosen execution platform is used to run all actions that the target
-generates.
-
-In cases where the same target can be built in multiple configurations (such as
-for different CPUs) within the same build, the resolution procedure is applied
-independently to each version of the target.
-
-## Debugging toolchains
-
-If you are adding toolchain support to an existing rule, use the
-`--toolchain_resolution_debug=regex` flag. During toolchain resolution, the flag
-provides verbose output for toolchain types or target names that match the regex
-variable. You can use `.*` to output all information. Bazel will output names of
-toolchains it checks and skips during the resolution process.
-
-If you'd like to see which [`cquery`][cquery] dependencies are from toolchain
-resolution, use `cquery`'s [`--transitions`][cquery-transitions] flag:
-
-```
-# Find all direct dependencies of //cc:my_cc_lib. This includes explicitly
-# declared dependencies, implicit dependencies, and toolchain dependencies.
-$ bazel cquery 'deps(//cc:my_cc_lib, 1)'
-//cc:my_cc_lib (96d6638)
-@bazel_tools//tools/cpp:toolchain (96d6638)
-@bazel_tools//tools/def_parser:def_parser (HOST)
-//cc:my_cc_dep (96d6638)
-@local_config_platform//:host (96d6638)
-@bazel_tools//tools/cpp:toolchain_type (96d6638)
-//:default_host_platform (96d6638)
-@local_config_cc//:cc-compiler-k8 (HOST)
-//cc:my_cc_lib.cc (null)
-@bazel_tools//tools/cpp:grep-includes (HOST)
-
-# Which of these are from toolchain resolution?
-$ bazel cquery 'deps(//cc:my_cc_lib, 1)' --transitions=lite | grep "toolchain dependency"
- [toolchain dependency]#@local_config_cc//:cc-compiler-k8#HostTransition -> b6df211
-```
-
-[Common exec_compatible_with attribute]: be/common-definitions.html#common.exec_compatible_with
-[Configurable attributes]: configurable-attributes.html
-[Configuration]: glossary.html#configuration
-[cquery]: cquery.html
-[cquery-transitions]: cquery.html#transitions
-[Flag extra_execution_platforms]: command-line-reference.html#flag--extra_execution_platforms
-[Flag extra_toolchains]: command-line-reference.html#flag--extra_toolchains
-[Go toolchain]: https://github.com/bazelbuild/rules_go/blob/master/go/private/go_toolchain.bzl
-[Label attributes]: skylark/lib/attr.html#label
-[Platforms]: platforms.html
-[Rule exec_compatible_with argument]: skylark/lib/globals.html#rule.exec_compatible_with
-[Rules]: skylark/rules.html
-[Rules status]: platforms-intro.html#status
-[ToolchainInfo]: skylark/lib/platform_common.html#ToolchainInfo
-[Toolchain rule]: be/platform.html#toolchain
-[Workspace function register_execution_platforms]: skylark/lib/globals.html#register_execution_platforms
-[Workspace function register_toolchains]: skylark/lib/globals.html#register_toolchains
diff --git a/site/docs/user-manual.html b/site/docs/user-manual.html
deleted file mode 100644
index 2cb2842..0000000
--- a/site/docs/user-manual.html
+++ /dev/null
@@ -1,3117 +0,0 @@
----
-layout: documentation
-title: User manual
----
-
-<div style="background-color: #EFCBCB; color: #AE2B2B; border: 1px solid #AE2B2B; border-radius: 5px; border-left: 10px solid #AE2B2B; padding: 0.5em;">
-<b>IMPORTANT:</b> The Bazel docs have moved! Please update your bookmark to <a href="https://bazel.build/docs/user-manual" style="color: #0000EE;">https://bazel.build/docs/user-manual</a>
-<p/>
-You can <a href="https://blog.bazel.build/2022/02/17/Launching-new-Bazel-site.html" style="color: #0000EE;">read about</a> the migration, and let us <a href="https://forms.gle/onkAkr2ZwBmcbWXj7" style="color: #0000EE;">know what you think</a>.
-</div>
-
-<h1>Commands and Options</h1>
-
-This page covers the options that are available with various Bazel commands,
-such as <code>bazel build</code>, <code>bazel run</code>, and
-<code>bazel test</code>. This page is a companion to the
-<a href="https://docs.bazel.build/versions/main/guide.html">Bazel user guide</a>,
-which lists Bazel's commands.
-<h2 id='target-patterns'>Target syntax</h2>
-
-Some commands, like <code>build</code> or <code>test</code>, can operate
-on a list of targets. They use a syntax more flexible than labels, which is
-documented in the "<a href="guide.html#specifying-targets-to-build">Specifying
-targets to build</a>" section of the User's Guide.
-
-<h2>Options</h2>
-
-<p>
- The following sections describe the options available during a
- build. When <code class='flag'>--long</code> is used on a help command, the on-line
- help messages provide summary information about the meaning, type and
- default value for each option.
-</p>
-
-<p>
- Most options can only be specified once. When specified multiple times, the
- last instance wins. Options that can be specified multiple times are
- identified in the on-line help with the text 'may be used multiple times'.
-</p>
-
-<h3>Package location</h3>
-
-<h4 id='flag--package_path'><code class='flag'>--package_path</code></h4>
-<p>
- This option specifies the set of directories that are searched to
- find the BUILD file for a given package.
-</p>
-
-<p>
- Bazel finds its packages by searching the package path. This is a colon
- separated ordered list of bazel directories, each being the root of a
- partial source tree.
-</p>
-
-<p>
- <i>To specify a custom package path</i> using the
- <code class='flag'>--package_path</code> option:
-</p>
-<pre>
- % bazel build --package_path %workspace%:/some/other/root
-</pre>
-<p>
-Package path elements may be specified in three formats:
-</p>
-<ol>
- <li>
- If the first character is <code>/</code>, the path is absolute.
- </li>
- <li>
- If the path starts with <code>%workspace%</code>, the path is taken relative
- to the nearest enclosing bazel directory.<br>
- For instance, if your working directory
- is <code>/home/bob/clients/bob_client/bazel/foo</code>, then the
- string <code>%workspace%</code> in the package-path is expanded
- to <code>/home/bob/clients/bob_client/bazel</code>.
- </li>
- <li>
- Anything else is taken relative to the working directory.<br> This is usually not what you mean to do,
- and may behave unexpectedly if you use Bazel from directories below the bazel workspace.
- For instance, if you use the package-path element <code>.</code>,
- and then cd into the directory
- <code>/home/bob/clients/bob_client/bazel/foo</code>, packages
- will be resolved from the
- <code>/home/bob/clients/bob_client/bazel/foo</code> directory.
- </li>
-</ol>
-<p>
- If you use a non-default package path, specify it in your
- <a href='guide.html#bazelrc'>Bazel configuration file</a> for
- convenience.
-</p>
-<p>
- <i>Bazel doesn't require any packages to be in the
- current directory</i>, so you can do a build from an empty bazel
- workspace if all the necessary packages can be found somewhere else
- on the package path.
-</p>
-<p>
- <i>Example</i>: Building from an empty client
-</p>
-<pre>
- % mkdir -p foo/bazel
- % cd foo/bazel
- % touch WORKSPACE
- % bazel build --package_path /some/other/path //foo
-</pre>
-<h3 id='checking-options'>Error checking</h3>
-<p>
- These options control Bazel's error-checking and/or warnings.
-</p>
-
-<h4 id='flag--check_visibility'><code class='flag'>--[no]check_visibility</code></h4>
-<p>
- If this option is set to false, visibility checks are demoted to warnings.
- The default value of this option is true, so that by default, visibility
- checking is done.
-
-</p>
-<h4 id='flag--output_filter'><code class='flag'>--output_filter=<var>regex</var></code></h4>
-<p>
- The <code class='flag'>--output_filter</code> option will only show build and compilation
- warnings for targets that match the regular expression. If a target does not
- match the given regular expression and its execution succeeds, its standard
- output and standard error are thrown away.
-</p>
-<p>
- Here are some typical values for this option:
-</p>
-<table>
- <tr>
- <td><code class='flag'>--output_filter='^//(first/project|second/project):'</code></td>
- <td>Show the output for the specified packages.</td>
- </tr>
- <tr>
- <td><code class='flag'>--output_filter='^//((?!(first/bad_project|second/bad_project):).)*$'</code></td>
- <td>Don't show output for the specified packages.</td>
- </tr>
- <tr>
- <td><code class='flag'>--output_filter=</code></td>
- <td>Show everything.
- </td>
- </tr>
- <tr>
- <td><code class='flag'>--output_filter=DONT_MATCH_ANYTHING</code></td>
- <td>Show nothing.
- </td>
- </tr>
-</table>
-
-<h3 id='flags-options'>Tool flags</h3>
-<p>
- These options control which options Bazel will pass to other tools.
-</p>
-
-<h4 id='flag--copt'><code class='flag'>--copt=<var>cc-option</var></code></h4>
-<p>
- This option takes an argument which is to be passed to the compiler.
- The argument will be passed to the compiler whenever it is invoked
- for preprocessing, compiling, and/or assembling C, C++, or
- assembler code. It will not be passed when linking.
-</p>
-<p>
- This option can be used multiple times.
- For example:
-</p>
-<pre>
- % bazel build --copt="-g0" --copt="-fpic" //foo
-</pre>
-<p>
- will compile the <code>foo</code> library without debug tables, generating
- position-independent code.
-</p>
-<p>
- Note that changing <code class='flag'>--copt</code> settings will force a recompilation
- of all affected object files. Also note that copts values listed in specific
- cc_library or cc_binary build rules will be placed on the compiler command line
- <em>after</em> these options.
-</p>
-<p>
- Warning: C++-specific options (such as <code>-fno-implicit-templates</code>)
- should be specified in <code class='flag'>--cxxopt</code>, not in
- <code class='flag'>--copt</code>. Likewise, C-specific options (such as -Wstrict-prototypes)
- should be specified in <code class='flag'>--conlyopt</code>, not in <code>copt</code>.
- Similarly, compiler options that only have an
- effect at link time (such as <code>-l</code>) should be specified in
- <code class='flag'>--linkopt</code>, not in <code class='flag'>--copt</code>.
-</p>
-
-<h4 id='flag--host_copt'><code class='flag'>--host_copt=<var>cc-option</var></code></h4>
-<p>
- This option takes an argument which is to be passed to the compiler for source files
- that are compiled in the host configuration. This is analogous to
- the <a href='#flag--copt'><code class='flag'>--copt</code></a> option, but applies only to the
- host configuration.
-</p>
-
-<h4 id='flag--host_conlyopt'><code class='flag'>--host_conlyopt=<var>cc-option</var></code></h4>
-<p>
- This option takes an argument which is to be passed to the compiler for C source files
- that are compiled in the host configuration. This is analogous to
- the <a href='#flag--conlyopt'><code class='flag'>--conlyopt</code></a> option, but applies only
- to the host configuration.
-</p>
-
-<h4 id='flag--host_cxxopt'><code class='flag'>--host_cxxopt=<var>cc-option</var></code></h4>
-<p>
- This option takes an argument which is to be passed to the compiler for C++ source files
- that are compiled in the host configuration. This is analogous to
- the <a href='#flag--cxxopt'><code class='flag'>--cxxopt</code></a> option, but applies only to the
- host configuration.
-</p>
-
-<h4 id='flag--host_linkopt'><code class='flag'>--host_linkopt=<var>linker-option</var></code></h4>
-<p>
- This option takes an argument which is to be passed to the linker for source files
- that are compiled in the host configuration. This is analogous to
- the <a href='#flag--linkopt'><code class='flag'>--linkopt</code></a> option, but applies only to
- the host configuration.
-</p>
-
-<h4 id='flag--conlyopt'><code class='flag'>--conlyopt=<var>cc-option</var></code></h4>
-<p>
- This option takes an argument which is to be passed to the compiler when compiling C source files.
-</p>
-<p>
- This is similar to <code class='flag'>--copt</code>, but only applies to C compilation,
- not to C++ compilation or linking. So you can pass C-specific options
- (such as <code>-Wno-pointer-sign</code>) using <code class='flag'>--conlyopt</code>.
-</p>
-<p>
- Note that copts parameters listed in specific cc_library or cc_binary build rules
- will be placed on the compiler command line <em>after</em> these options.
-</p>
-
-<h4 id='flag--cxxopt'><code class='flag'>--cxxopt=<var>cc-option</var></code></h4>
-<p>
- This option takes an argument which is to be passed to the compiler when compiling C++ source
- files.
-</p>
-<p>
- This is similar to <code class='flag'>--copt</code>, but only applies to C++ compilation,
- not to C compilation or linking. So you can pass C++-specific options
- (such as <code>-fpermissive</code> or <code>-fno-implicit-templates</code>) using <code class='flag'>--cxxopt</code>.
- For example:
-</p>
-<pre>
- % bazel build --cxxopt="-fpermissive" --cxxopt="-Wno-error" //foo/cruddy_code
-</pre>
-<p>
- Note that copts parameters listed in specific cc_library or cc_binary build rules
- will be placed on the compiler command line <em>after</em> these options.
-</p>
-
-<h4 id='flag--linkopt'><code class='flag'>--linkopt=<var>linker-option</var></code></h4>
-<p>
- This option takes an argument which is to be passed to the compiler when linking.
-</p>
-<p>
- This is similar to <code class='flag'>--copt</code>, but only applies to linking,
- not to compilation. So you can pass compiler options that only make sense
- at link time (such as <code>-lssp</code> or <code>-Wl,--wrap,abort</code>)
- using <code class='flag'>--linkopt</code>. For example:
-</p>
-<pre>
- % bazel build --copt="-fmudflap" --linkopt="-lmudflap" //foo/buggy_code
-</pre>
-<p>
- Build rules can also specify link options in their attributes. This option's
- settings always take precedence. Also see
- <a href="be/c-cpp.html#cc_library.linkopts">cc_library.linkopts</a>.
-</p>
-
-<h4 id='flag--strip'><code class='flag'>--strip (always|never|sometimes)</code></h4>
-<p>
- This option determines whether Bazel will strip debugging information from
- all binaries and shared libraries, by invoking the linker with the <code>-Wl,--strip-debug</code> option.
- <code class='flag'>--strip=always</code> means always strip debugging information.
- <code class='flag'>--strip=never</code> means never strip debugging information.
- The default value of <code class='flag'>--strip=sometimes</code> means strip if the <code class='flag'>--compilation_mode</code>
- is <code>fastbuild</code>.
-</p>
-<pre>
- % bazel build --strip=always //foo:bar
-</pre>
-<p>
- will compile the target while stripping debugging information from all generated
- binaries.
-</p>
-<p>
- Note that if you want debugging information, it's not enough to disable stripping; you also need to make
- sure that the debugging information was generated by the compiler, which you can do by using either
- <code>-c dbg</code> or <code class='flag'>--copt -g</code>.
-</p>
-<p>
- Note also that Bazel's <code class='flag'>--strip</code> option corresponds with ld's <code>--strip-debug</code> option:
- it only strips debugging information. If for some reason you want to strip <em>all</em> symbols,
- not just <em>debug</em> symbols, you would need to use ld's <code>--strip-all</code> option,
- which you can do by passing <code class='flag'>--linkopt=-Wl,--strip-all</code> to Bazel. Also be
- aware that setting Bazel's <code class='flag'>--strip</code> flag will override
- <code class='flag'>--linkopt=-Wl,--strip-all</code>, so you should only set one or the other.
-
- If you are only building a single binary and want all symbols stripped, you could also
- pass <code class='flag'>--stripopt=--strip-all</code> and explicitly build the
- <code>//foo:bar.stripped</code> version of the target. As described in the section on
- <code class='flag'>--stripopt</code>, this applies a strip action after the final binary is
- linked rather than including stripping in all of the build's link actions.
-</p>
-
-<h4 id='flag--stripopt'><code class='flag'>--stripopt=<var>strip-option</var></code></h4>
-<p>
- This is an additional option to pass to the <code>strip</code> command when generating
- a <a href="be/c-cpp.html#cc_binary_implicit_outputs"><code>*.stripped</code>
- binary</a>. The default is <code>-S -p</code>. This option can be used
- multiple times.
-</p>
-<p>
- Note that <code class='flag'>--stripopt</code> does not apply to the stripping of the main
- binary with <code><a href='#flag--strip'>--strip</a>=(always|sometimes)</code>.
-</p>
-
-<h4 id='flag--fdo_instrument'><code class='flag'>--fdo_instrument=<var>profile-output-dir</var></code></h4>
-<p>
- The <code class='flag'>--fdo_instrument</code> option enables the generation of
- FDO (feedback directed optimization) profile output when the
- built C/C++ binary is executed. For GCC, the argument provided is used as a
- directory prefix for a per-object file directory tree of .gcda files
- containing profile information for each .o file.
-</p>
-<p>
- Once the profile data tree has been generated, the profile tree
- should be zipped up, and provided to the
- <code class='flag'>--fdo_optimize=<var>profile-zip</var></code>
- Bazel option to enable the FDO-optimized compilation.
-
-</p>
-<p>
- For the LLVM compiler the argument is also the directory under which the raw LLVM profile
- data file(s) is dumped, e.g.
- <code class='flag'>--fdo_instrument=<var>/path/to/rawprof/dir/</var></code>.
-</p>
-<p>
- The options <code class='flag'>--fdo_instrument</code> and <code class='flag'>--fdo_optimize</code>
- cannot be used at the same time.
-</p>
-
-
-<h4 id='flag--fdo_optimize'><code class='flag'>--fdo_optimize=<var>profile-zip</var></code></h4>
-<p>
- The <code class='flag'>--fdo_optimize</code> option enables the use of the
- per-object file profile information to perform FDO (feedback
- directed optimization) optimizations when compiling. For GCC, the argument
- provided is the zip file containing the previously-generated file tree
- of .gcda files containing profile information for each .o file.
-</p>
-<p>
- Alternatively, the argument provided can point to an auto profile
- identified by the extension .afdo.
-
-</p>
-<p>
- Note that this option also accepts labels that resolve to source files. You
- may need to add an <code>exports_files</code> directive to the corresponding package to
- make the file visible to Bazel.
-</p>
-<p>
- For the LLVM compiler the argument provided should point to the indexed LLVM
- profile output file prepared by the llvm-profdata tool, and should have a .profdata
- extension.
-</p>
-<p>
- The options <code class='flag'>--fdo_instrument</code> and <code class='flag'>
- --fdo_optimize</code> cannot be used at the same time.
-</p>
-
-
-<h4 id='flag--output_symbol_counts'><code class='flag'>--[no]output_symbol_counts</code></h4>
-<p>
- If enabled, each gold-invoked link of a C++ executable binary will output
- a <i>symbol counts</i> file (via the <code>--print-symbol-counts</code> gold
- option). For each linker input, the file logs the number of symbols that were
- defined and the number of symbols that were used in the binary.
- This information can be used to track unnecessary link dependencies.
- The symbol counts file is written to the binary's output path with the name
- <code>[targetname].sc</code>.
-</p>
-<p>
- This option is disabled by default.
-</p>
-
-<h4 id='flag--java_language_version'><code class='flag'>--java_language_version=<var>version</var></code></h4>
-<p>
- This option specifies the version of Java sources. For example:
-</p>
-<pre>
- % bazel build --java_language_version=8 java/com/example/common/foo:all
-</pre>
-<p>
- compiles and allows only constructs compatible with Java 8 specification.
- Default value is 11. -->
- Possible values are: 8, 9, 10, --> 11 <!--begin-block:external , 14, and 15 and may be extended by registering custom Java
- toolchains using <code>default_java_toolchain</code> macro-->.
-</p>
-
-<h4 id='flag--tool_java_language_version'><code class='flag'>--tool_java_language_version=<var>version</var></code>
-</h4>
-<p>
- The Java language version used to build tools that are executed during a build.
- Default value is 11.
-</p>
-
-<h4 id='flag--java_runtime_version'><code class='flag'>--java_runtime_version=<var>version</var></code></h4>
-<p>
- This option specifies the version of JVM to use to execute the code and run the tests. For
- example:
-</p>
-<pre>
- % bazel run --java_runtime_version=remotejdk_11 java/com/example/common/foo:java_application
-</pre>
-<p>
- downloads JDK 11 from a remote repository and run the Java application using it.
-</p>
-<p>
- Default value is <code>localjdk</code>.
- Possible values are: <code>localjdk</code>, <code>localjdk_<var>version</var></code>,
- <code>remotejdk_11</code>,
- and <code>remote_jdk17</code>.
- You can extend the values by registering custom JVM using either
- <code>local_java_repository</code> or
- <code>remote_java_repostory</code> repository rules.
-</p>
-
-<h4 id='flag--tool_java_runtime_version'><code class='flag'>--tool_java_runtime_version=<var>version</var></code></h4>
-<p>
- The version of JVM used to execute tools that are needed during a build.
- Default value is <code>remotejdk_11</code>.
-</p>
--->
-
-<h4 id='flag--jvmopt'><code class='flag'>--jvmopt=<var>jvm-option</var></code></h4>
-<p>
- This option allows option arguments to be passed to the Java VM. It can be used
- with one big argument, or multiple times with individual arguments. For example:
-</p>
-<pre>
- % bazel build --jvmopt="-server -Xms256m" java/com/example/common/foo:all
-</pre>
-<p>
- will use the server VM for launching all Java binaries and set the
- startup heap size for the VM to 256 MB.
-</p>
-
-<h4 id='flag--javacopt'><code class='flag'>--javacopt=<var>javac-option</var></code></h4>
-<p>
- This option allows option arguments to be passed to javac. It can be used
- with one big argument, or multiple times with individual arguments. For example:
-</p>
-<pre>
- % bazel build --javacopt="-g:source,lines" //myprojects:prog
-</pre>
-<p>
- will rebuild a java_binary with the javac default debug info
- (instead of the bazel default).
-</p>
-<p>
- The option is passed to javac after the Bazel built-in default options for
- javac and before the per-rule options. The last specification of
- any option to javac wins. The default options for javac are:
-</p>
-
-<pre>
- -source 8 -target 8 -encoding UTF-8
-</pre>
-<p>
- Note that changing <code class='flag'>--javacopt</code> settings will force a recompilation
- of all affected classes. Also note that javacopts parameters listed in
- specific java_library or java_binary build rules will be placed on the javac
- command line <em>after</em> these options.
-</p>
-
-<h5 id='-extra_checks'><code>-extra_checks[:(off|on)]</code></h5>
-
-<p>
- This javac option enables extra correctness checks. Any problems found will
- be presented as errors.
- Either <code>-extra_checks</code> or <code>-extra_checks:on</code> may be used
- to force the checks to be turned on. <code>-extra_checks:off</code> completely
- disables the analysis.
- When this option is not specified, the default behavior is used.
-</p>
-
-<h4 id='flag--strict_java_deps'><code class='flag'>--strict_java_deps
- (default|strict|off|warn|error)</code></h4>
-<p>
- This option controls whether javac checks for missing direct dependencies.
- Java targets must explicitly declare all directly used targets as
- dependencies. This flag instructs javac to determine the jars actually used
- for type checking each java file, and warn/error if they are not the output
- of a direct dependency of the current target.
-</p>
-
-<ul>
- <li> <code>off</code> means checking is disabled.
- </li>
- <li> <code>warn</code> means javac will generate standard java warnings of
- type <code>[strict]</code> for each missing direct dependency.
- </li>
- <li> <code>default</code>, <code>strict</code> and <code>error</code> all
- mean javac will generate errors instead of warnings, causing the current
- target to fail to build if any missing direct dependencies are found.
- This is also the default behavior when the flag is unspecified.
- </li>
-</ul>
-
-<h3 id='semantics-options'>Build semantics</h3>
-<p>
- These options affect the build commands and/or the output file contents.
-</p>
-
-<h4 id='flag--compilation_mode'><code class='flag'>--compilation_mode (fastbuild|opt|dbg)</code> (-c)</h4>
-<p>
- The <code class="flag">--compilation_mode</code> option (often shortened to <code>-c</code>,
- especially <code>-c opt</code>) takes an argument of <code>fastbuild</code>, <code>dbg</code>
- or <code>opt</code>, and affects various C/C++ code-generation
- options, such as the level of optimization and the completeness of
- debug tables. Bazel uses a different output directory for each
- different compilation mode, so you can switch between modes without
- needing to do a full rebuild <i>every</i> time.
-</p>
-<ul>
- <li> <code>fastbuild</code> means build as fast as possible:
- generate minimal debugging information (<code>-gmlt
- -Wl,-S</code>), and don't optimize. This is the
- default. Note: <code>-DNDEBUG</code> will <b>not</b> be set.
- </li>
- <li> <code>dbg</code> means build with debugging enabled (<code>-g</code>),
- so that you can use gdb (or another debugger).
- </li>
- <li> <code>opt</code> means build with optimization enabled and
- with <code>assert()</code> calls disabled (<code>-O2 -DNDEBUG</code>).
- Debugging information will not be generated in <code>opt</code> mode
- unless you also pass <code class='flag'>--copt -g</code>.
- </li>
-</ul>
-
-<h4 id='flag--cpu'><code class='flag'>--cpu=<var>cpu</var></code></h4>
-<p>
-This option specifies the target CPU architecture to be used for
-the compilation of binaries during the build.
-</p>
-<p>
-
-</p>
-<p>
- Note that a particular combination of crosstool version, compiler version,
- and target CPU is allowed only if it has been specified in the currently
- used CROSSTOOL file.
-</p>
-
-<h4 id='flag--action_env'>
- <code class='flag'>--action_env=<var>VAR=VALUE</var></code>
-</h4>
-<p>
- Specifies the set of environment variables available during the execution of all actions.
- Variables can be either specified by name, in which case the value will be taken from the
- invocation environment, or by the <code>name=value</code> pair which sets the value independent of the
- invocation environment.
-
- This <code>--action_env</code> flag can be specified multiple times. If a value is assigned to the same
- variable across multiple <code>--action_env</code> flags, the latest assignment wins.
-</p>
-
-<h4 id='flag--experimental_action_listener'>
- <code class='flag'>--experimental_action_listener=<var>label</var></code>
-</h4>
-<p>
- <b>WARNING:</b> Extra actions are deprecated. Use
- <a href="https://docs.bazel.build/versions/main/skylark/aspects.html">aspects</a>
- instead.
-</p>
-<p>
- The <code>experimental_action_listener</code> option instructs Bazel to use
- details from the <a href="be/extra-actions.html#action_listener"
- ><code>action_listener</code></a> rule specified by <var>label</var> to
- insert <a href="be/extra-actions.html#extra_action"
- ><code>extra_actions</code></a> into the build graph.
-</p>
-
-<h4 id='flag--experimental_extra_action_top_level_only'>
- <code class='flag'>--[no]experimental_extra_action_top_level_only</code>
-</h4>
-<p>
- <b>WARNING:</b> Extra actions are deprecated. Use
- <a href="https://docs.bazel.build/versions/main/skylark/aspects.html">aspects</a>
- instead.
-</p>
-<p>
- If this option is set to true, extra actions specified by the
- <a href='#flag--experimental_action_listener'> <code>
- --experimental_action_listener</code></a> command line option will only be
- scheduled for top level targets.
-</p>
-
-<h4 id='flag--experimental_extra_action_filter'>
- <code class='flag'>--experimental_extra_action_filter=<var>regex</var></code>
-</h4>
-<p>
- <b>WARNING:</b> Extra actions are deprecated. Use
- <a href="https://docs.bazel.build/versions/main/skylark/aspects.html">aspects</a>
- instead.
-</p>
-<p>
- The <code>experimental_extra_action_filter</code> option instructs Bazel to
- filter the set of targets to schedule <code>extra_actions</code> for.
-</p>
-<p>
- This flag is only applicable in combination with the
- <a href='#flag--experimental_action_listener'
- ><code>--experimental_action_listener</code></a> flag.
-</p>
-<p>
- By default all <code>extra_actions</code> in the transitive closure of the
- requested targets-to-build get scheduled for execution.
- <code>--experimental_extra_action_filter</code> will restrict scheduling to
- <code>extra_actions</code> of which the owner's label matches the specified
- regular expression.
-</p>
-<p>
- The following example will limit scheduling of <code>extra_actions</code>
- to only apply to actions of which the owner's label contains '/bar/':
-</p>
-<pre>% bazel build --experimental_action_listener=//test:al //foo/... \
- --experimental_extra_action_filter=.*/bar/.*
-</pre>
-
-<h4 id='flag--host_cpu'><code class='flag'>--host_cpu=<var>cpu</var></code></h4>
-<p>
- This option specifies the name of the CPU architecture that should be
- used to build host tools.
-</p>
-
-<h4 id='flag--fat_apk_cpu'><code class='flag'>--fat_apk_cpu=<var>cpu[,cpu]*</var></code></h4>
-<p>
- The CPUs to build C/C++ libraries for in the transitive <code>deps</code> of
- <code>android_binary</code>
-
- rules. Other C/C++ rules are not affected. For example, if a <code>cc_library</code>
- appears in the transitive <code>deps</code> of an <code>android_binary</code> rule and a
- <code>cc_binary</code> rule, the <code>cc_library</code> will be built at least twice:
- once for each CPU specified with <code class='flag'>--fat_apk_cpu</code> for the
- <code>android_binary</code> rule, and once for the CPU specified with
- <code class='flag'>--cpu</code> for the <code>cc_binary</code> rule.
-</p>
-
-<p>
- The default is <code>armeabi-v7a</code>.
-</p>
-<p>
- One <code>.so</code> file is created and packaged in the APK for
- each CPU specified with <code class='flag'>--fat_apk_cpu</code>. The <code>.so</code> file's name
- prefixes the name of the <code>android_binary</code> rule with "lib". For example, if the name of
- the <code>android_binary</code> is "foo", then the file is <code>libfoo.so</code>.
-</p>
- <p>
- One <code>.so</code> file will be created and packaged in the APK for
- each CPU specified with <code class='flag'>--fat_apk_cpu</code>. The name of the <code>.so</code>
- file will be the name of the <code>android_binary</code> rule prefixed with "lib", e.g., if the name
- of the <code>android_binary</code> is "foo", then the file will be <code>libfoo.so</code>.
- </p>
-
- <p>
- Note that an Android-compatible crosstool must be selected.
- If an <code>android_ndk_repository</code> rule is defined in the
- WORKSPACE file, an Android-compatible crosstool is automatically selected.
- Otherwise, the crostool can be selected using the
- <a href='#flag--android_crosstool_top'><code class='flag'>--android_crosstool_top</code></a>
- or <a href='#flag--crosstool_top'><code class='flag'>--crosstool_top</code></a> flags.
- </p>
-
-
-<h4 id='flag--per_file_copt'><code class='flag'>--per_file_copt
- <var>[+-]regex[,[+-]regex]...@option[,option]...</var></code></h4>
-</p>
-
-<h4 id='flag--per_file_copt'><code class='flag'>--per_file_copt=
- <var>[+-]regex[,[+-]regex]...@option[,option]...</var></code></h4>
-<p>
- When present, any C++ file with a label or an execution path matching one of the inclusion regex
- expressions and not matching any of the exclusion expressions will be built
- with the given options. The label matching uses the canonical form of the label
- (i.e //<code>package</code>:<code>label_name</code>).
-
- The execution path is the relative path to your workspace directory including the base name
- (including extension) of the C++ file. It also includes any platform dependent prefixes.
- Note, that if only one of the label or the execution path matches the options will be used.
-</p>
-<p>
- <b>Notes</b>:
- To match the generated files (e.g. genrule outputs)
- Bazel can only use the execution path. In this case the regexp shouldn't start with '//'
- since that doesn't match any execution paths. Package names can be used like this:
- <code class='flag'>--per_file_copt=base/.*\.pb\.cc@-g0</code>. This will match every
- <code>.pb.cc</code> file under a directory called <code>base</code>.
-</p>
-<p>
- This option can be used multiple times.
-</p>
-<p>
- The option is applied regardless of the compilation mode used. I.e. it is possible
- to compile with <code class='flag'>--compilation_mode=opt</code> and selectively compile some
- files with stronger optimization turned on, or with optimization disabled.
-</p>
-<p>
- <b>Caveat</b>: If some files are selectively compiled with debug symbols the symbols
- might be stripped during linking. This can be prevented by setting
- <code class='flag'>--strip=never</code>.
-</p>
-<p>
- <b>Syntax</b>: <code>[+-]regex[,[+-]regex]...@option[,option]...</code> Where
- <code>regex</code> stands for a regular expression that can be prefixed with
- a <code>+</code> to identify include patterns and with <code>-</code> to identify
- exclude patterns. <code>option</code> stands for an arbitrary option that is passed
- to the C++ compiler. If an option contains a <code>,</code> it has to be quoted like so
- <code>\,</code>. Options can also contain <code>@</code>, since only the first
- <code>@</code> is used to separate regular expressions from options.
-</p>
-<p>
- <b>Example</b>:
- <code class='flag'>--per_file_copt=//foo:.*\.cc,-//foo:file\.cc@-O0,-fprofile-arcs</code>
- adds the <code>-O0</code> and the <code>-fprofile-arcs</code> options to the command
- line of the C++ compiler for all <code>.cc</code> files in <code>//foo/</code> except
- <code>file.cc</code>.
-</p>
-<h4 id='flag--dynamic_mode'><code class='flag'>--dynamic_mode=<var>mode</var></code></h4>
-<p>
- Determines whether C++ binaries will be linked dynamically, interacting with
- the <a href='be/c-cpp.html#cc_binary.linkstatic'>linkstatic
- attribute</a> on build rules.
-</p>
-
-<p>
- Modes:
-</p>
-<ul>
- <li><code>auto</code>: Translates to a platform-dependent mode;
- <code>default</code> for linux and <code>off</code> for cygwin.</li>
- <li><code>default</code>: Allows bazel to choose whether to link dynamically.
- See <a href='be/c-cpp.html#cc_binary.linkstatic'>linkstatic</a> for more
- information.</li>
- <li><code>fully</code>: Links all targets dynamically. This will speed up
- linking time, and reduce the size of the resulting binaries.
-
- </li>
- <li><code>off</code>: Links all targets in
- <a href='be/c-cpp.html#cc_binary.linkstatic'>mostly static</a> mode.
- If <code>-static</code> is set in linkopts, targets will change to fully
- static.</li>
-</ul>
-
-<h4 id='flag--fission'><code class='flag'>--fission (yes|no|[dbg][,opt][,fastbuild])</code></h4>
-<p>
- Enables
-
- <a href='https://gcc.gnu.org/wiki/DebugFission'>Fission</a>,
- which writes C++ debug information to dedicated .dwo files instead of .o files, where it would
- otherwise go. This substantially reduces the input size to links and can reduce link times.
-
-</p>
-<p>
- When set to <code class='flag'>[dbg][,opt][,fastbuild]</code> (example:
- <code class='flag'>--fission=dbg,fastbuild</code>), Fission is enabled
- only for the specified set of compilation modes. This is useful for bazelrc
- settings. When set to <code class='flag'>yes</code>, Fission is enabled
- universally. When set to <code class='flag'>no</code>, Fission is disabled
- universally.
-
- Default is <code class='flag'>no</code>.
-</p>
-
-<h4 id='flag--force_ignore_dash_static'><code class='flag'>--force_ignore_dash_static</code></h4>
-<p>
- If this flag is set, any <code>-static</code> options in linkopts of
- <code>cc_*</code> rules BUILD files are ignored. This is only intended as a
- workaround for C++ hardening builds.
-</p>
-
-<h4 id='flag--force_pic'><code class='flag'>--[no]force_pic</code></h4>
-<p>
- If enabled, all C++ compilations produce position-independent code ("-fPIC"),
- links prefer PIC pre-built libraries over non-PIC libraries, and links produce
- position-independent executables ("-pie"). Default is disabled.
-</p>
-<p>
- Note that dynamically linked binaries (i.e. <code>--dynamic_mode fully</code>)
- generate PIC code regardless of this flag's setting. So this flag is for cases
- where users want PIC code explicitly generated for static links.
-</p>
-
-<h4 id='flag--android_resource_shrinking'><code class='flag'>--android_resource_shrinking</code></h4>
-<p>
- Selects whether to perform resource shrinking for android_binary rules. Sets the default for the
- <a href='be/android.html#android_binary.shrink_resources'>shrink_resources attribute</a> on
- android_binary rules; see the documentation for that rule for further details. Defaults to off.
-</p>
-
-<h4 id='flag--custom_malloc'><code class='flag'>--custom_malloc=<var>malloc-library-target</var></code></h4>
-<p>
- When specified, always use the given malloc implementation, overriding all
- <code>malloc="target"</code> attributes, including in those targets that use the
- default (by not specifying any <code>malloc</code>).
-</p>
-
-<h4 id='flag--crosstool_top'><code class='flag'>--crosstool_top=<var>label</var></code></h4>
-<p>
- This option specifies the location of the crosstool compiler suite
- to be used for all C++ compilation during a build. Bazel will look in that
- location for a CROSSTOOL file and uses that to automatically determine
- settings for
-
- <code class='flag'>--compiler</code>.
-</p>
-
-<h4 id='flag--host_crosstool_top'><code class='flag'>--host_crosstool_top=<var>label</var></code></h4>
-<p>
- If not specified, bazel uses the value of <code class='flag'>--crosstool_top</code> to compile
- code in the host configuration, i.e., tools run during the build. The main purpose of this flag
- is to enable cross-compilation.
-</p>
-
-<h4 id='flag--apple_crosstool_top'><code class='flag'>--apple_crosstool_top=<var>label</var></code></h4>
-<p>
- The crosstool to use for compiling C/C++ rules in the transitive <code>deps</code> of
- objc_*, ios__*, and apple_* rules. For those targets, this flag overwrites
- <code class='flag'>--crosstool_top</code>.
-</p>
-
-<h4 id='flag--android_crosstool_top'><code class='flag'>--android_crosstool_top=<var>label</var></code></h4>
-<p>
- The crosstool to use for compiling C/C++ rules in the transitive <code>deps</code> of
- <code>android_binary</code> rules. This is useful if other targets in the
- build require a different crosstool. The default is to use the crosstool
- generated by the <code>android_ndk_repository</code> rule in the WORKSPACE file.
- See also <a href='#flag--fat_apk_cpu'><code class='flag'>--fat_apk_cpu</code></a>.
-</p>
-<h4 id='flag--compiler'><code class='flag'>--compiler=<var>version</var></code></h4>
-<p>
- This option specifies the C/C++ compiler version (e.g. <code>gcc-4.1.0</code>)
- to be used for the compilation of binaries during the build. If you want to
- build with a custom crosstool, you should use a CROSSTOOL file instead of
- specifying this flag.
-</p>
-<p>
- Note that only certain combinations of crosstool version, compiler version,
- and target CPU are allowed.
-</p>
-
-<h4 id='flag--android_sdk'><code class='flag'>--android_sdk=<var>label</var></code></h4>
-<p>
- This option specifies the Android SDK/platform toolchain
- and Android runtime library that will be used to build any Android-related
- rule.
-
- The Android SDK will be automatically selected if an <code>android_sdk_repository</code>
- rule is defined in the WORKSPACE file.
-</p>
-
-<h4 id='flag--java_toolchain'><code class='flag'>--java_toolchain=<var>label</var></code></h4>
-<p>
- This option specifies the label of the java_toolchain used to compile Java
- source files.
-</p>
-
-<h4 id='flag--host_java_toolchain'><code class='flag'>--host_java_toolchain=<var>label</var></code></h4>
-<p>
- If not specified, bazel uses the value of <code class='flag'>--java_toolchain</code> to compile
- code in the host configuration, i.e., tools run during the build. The main purpose of this flag
- is to enable cross-compilation.
-</p>
-
-<h4 id='flag--javabase'><code class='flag'>--javabase=(<var>label</var>)</code></h4>
-<p>
- This option sets the <i>label</i> of the base Java installation to use for <i>bazel run</i>,
- <i>bazel test</i>, and for Java binaries built by <code>java_binary</code> and
- <code>java_test</code> rules. The <code>JAVABASE</code> and <code>JAVA</code>
- <a href='be/make-variables.html'>"Make" variables</a> are derived from this option.
-</p>
-
-<h4 id='flag--host_javabase'><code class='flag'>--host_javabase=<var>label</var></code></h4>
-<p>
- This option sets the <i>label</i> of the base Java installation to use in the host configuration,
- for example for host build tools including JavaBuilder and Singlejar.
-</p>
-<p>
- This does not select the Java compiler that is used to compile Java
- source files. The compiler can be selected by settings the
- <a href="#flag--java_toolchain"><code class='flag'>--java_toolchain</code></a>
- option.
-</p>
-
-<h3 id='strategy-options'>Execution strategy</h3>
-<p>
- These options affect how Bazel will execute the build.
- They should not have any significant effect on the output files
- generated by the build. Typically their main effect is on the
- speed of the build.
-</p>
-
-<h4 id='flag--spawn_strategy'><code class='flag'>--spawn_strategy=<var>strategy</var></code></h4>
-<p>
- This option controls where and how commands are executed.
-</p>
-<ul>
-
- <li>
- <code>standalone</code> causes commands to be executed as local subprocesses. This value is
- deprecated. Please use <code>local</code> instead.
- </li>
- <li>
- <code>sandboxed</code> causes commands to be executed inside a sandbox on the local machine.
- This requires that all input files, data dependencies and tools are listed as direct
- dependencies in the <code>srcs</code>, <code>data</code> and <code>tools</code> attributes.
-
-
- Bazel enables local sandboxing by default, on systems that support sandboxed execution.
- </li>
-
- <li>
- <code>local</code> causes commands to be executed as local subprocesses.
- </li>
-
- <li>
- <code>worker</code> causes commands to be executed using a persistent worker, if available.
- </li>
-
- <li>
- <code>docker</code> causes commands to be executed inside a docker sandbox on the local machine.
- This requires that docker is installed.
- </li>
-
- <li>
- <code>remote</code> causes commands to be executed remotely; this is only available if a
- remote executor has been configured separately.
- </li>
-</ul>
-
-<h4 id='flag--strategy'><code class='flag'>--strategy <var>mnemonic</var>=<var>strategy</var></code></h4>
-<p>
- This option controls where and how commands are executed, overriding the
- <code class='flag'><a href="#flag--spawn_strategy">--spawn_strategy</a></code> (and
- <code class='flag'><a href="#flag--genrule_strategy">--genrule_strategy</a></code> with mnemonic
- Genrule) on a per-mnemonic basis. See
- <code class='flag'><a href="#flag--spawn_strategy">--spawn_strategy</a></code> for the supported
- strategies and their effects.
-</p>
-
-<h4 id='flag--strategy_regexp'><code class='flag'>--strategy_regexp=<var><filter,filter,...>=<strategy></var></code></h4>
-<p>
- This option specifies which strategy should be used to execute commands that have descriptions
- matching a certain <code>regex_filter</code>. See
- <code class='flag'><a href="#flag--per_file_copt">--per_file_copt</a></code> for details on
- regex_filter matching. See
- <code class='flag'><a href="#flag--spawn_strategy">--spawn_strategy</a></code> for the supported
- strategies and their effects.
-</p>
-<p>
-The last <code>regex_filter</code> that matches the description is used. This option overrides
-other flags for specifying strategy.
-</p>
-<ul>
- <li>
- Example: <code>--strategy_regexp=//foo.*\\.cc,-//foo/bar=local</code> means to run actions using
- <code>local</code> strategy if their descriptions match //foo.*.cc but not //foo/bar.
- </li>
- <li>
- Example:
- <code>--strategy_regexp='Compiling.*/bar=local' --strategy_regexp=Compiling=sandboxed</code>
- will run 'Compiling //foo/bar/baz' with the <code>sandboxed</code> strategy, but reversing
- the order would run it with <code>local</code>.
- </li>
- <li>
- Example:
- <code>--strategy_regexp='Compiling.*/bar=local,sandboxed'</code>
- will run 'Compiling //foo/bar/baz' with the <code>local</code> strategy and fall back to
- <code>sandboxed</code> if fails.
- </li>
-</ul>
-
-<h4 id='flag--genrule_strategy'><code class='flag'>--genrule_strategy=<var>strategy</var></code></h4>
-<p>
- This is a deprecated short-hand for
- <code class='flag'>--strategy=Genrule=<var>strategy</var></code>.
-</p>
-
-<h4 id='flag--jobs'><code class='flag'>--jobs=<var>n</var></code> (-j)</h4>
-<p>
- This option, which takes an integer argument, specifies a limit on
- the number of jobs that should be executed concurrently during the
- execution phase of the build.
-</p>
-<p>
- Note that the number of concurrent jobs that Bazel will run
- is determined not only by the <code class='flag'>--jobs</code> setting, but also
- by Bazel's scheduler, which tries to avoid running concurrent jobs
- that will use up more resources (RAM or CPU) than are available,
- based on some (very crude) estimates of the resource consumption
- of each job. The behavior of the scheduler can be controlled by
- the <code class='flag'>--local_ram_resources</code> option.
-</p>
-
-<h4 id='flag--progress_report_interval'><code class='flag'>--progress_report_interval=<var>n</var></code></h4>
-<p>
-
- Bazel periodically prints a progress report on jobs that are not
- finished yet (e.g. long running tests). This option sets the
- reporting frequency, progress will be printed every <code>n</code>
- seconds.
-</p>
-<p>
- The default is 0, that means an incremental algorithm: the first
- report will be printed after 10 seconds, then 30 seconds and after
- that progress is reported once every minute.
-</p>
-
-<h4 id='flag--local_{ram,cpu}_resources'><code class='flag'>--local_{ram,cpu}_resources</code>
- <var>resources or resource expression</var></h4>
-<p>
- These options specify the amount of local resources (RAM in MB and number of CPU logical cores)
- that Bazel can take into consideration when scheduling build and test activities to run locally.
- They take an integer, or a keyword (HOST_RAM or HOST_CPUS) optionally followed by [-|*<code>float</code>]
- (for example, <code class='flag'>--local_cpu_resources=2</code>,
- <code class='flag'>--local_ram_resources=HOST_RAM*.5</code>,
- <code class='flag'>--local_cpu_resources=HOST_CPUS-1</code>).
- The flags are independent; one or both may be set. By default Bazel will estimate the amount of
- RAM and number of CPU cores directly from the local system's configuration.
-</p>
-
-<h4 id='flag--build_runfile_links'><code class='flag'>--[no]build_runfile_links</code></h4>
-<p>
- This option, which is enabled by default, specifies whether the runfiles
- symlinks for tests and binaries should be built in the output directory.
- Using <code class='flag'>--nobuild_runfile_links</code> can be useful
- to validate if all targets compile without incurring the overhead
- for building the runfiles trees.
-
-</p>
-
-<p>
- When tests (or applications) are executed, their run-time data
- dependencies are gathered together in one place. Within Bazel's
- output tree, this "runfiles" tree is typically rooted as a sibling of
- the corresponding binary or test.
- During test execution, runfiles may be accessed using paths of the form
- <code>$TEST_SRCDIR/workspace/<var>packagename</var>/<var>filename</var></code>.
- The runfiles tree ensures that tests have access to all the files
- upon which they have a declared dependence, and nothing more. By
- default, the runfiles tree is implemented by constructing a set of
- symbolic links to the required files. As the set of links grows, so
- does the cost of this operation, and for some large builds it can
- contribute significantly to overall build time, particularly because
- each individual test (or application) requires its own runfiles tree.
-</p>
-
-<h4 id='flag--build_runfile_manifests'><code class='flag'>--[no]build_runfile_manifests</code></h4>
-<p>
- This option, which is enabled by default, specifies whether runfiles manifests
- should be written to the output tree.
- Disabling it implies <code class='flag'>--nobuild_runfile_links</code>.
-
- It can be disabled when executing tests remotely, as runfiles trees will
- be created remotely from in-memory manifests.
-
-<h4 id='flag--discard_analysis_cache'>
- <code class='flag'>--[no]discard_analysis_cache</code></h4>
-<p>
- When this option is enabled, Bazel will discard the analysis cache
- right before execution starts, thus freeing up additional memory
- (around 10%) for the <a href="guide.html#execution-phase">execution phase</a>.
- The drawback is that further incremental builds will be slower. See also
- <a href="/versions/{{ current_version }}/memory-saving-mode.html">
-memory-saving mode</a>.
-</p>
-
-<h4 id='flag--keep_going'><code class='flag'>--[no]keep_going</code> (-k)</h4>
-<p>
- As in GNU Make, the execution phase of a build stops when the first
- error is encountered. Sometimes it is useful to try to build as
- much as possible even in the face of errors. This option enables
- that behavior, and when it is specified, the build will attempt to
- build every target whose prerequisites were successfully built, but
- will ignore errors.
-</p>
-<p>
- While this option is usually associated with the execution phase of
- a build, it also affects the analysis phase: if several targets are
- specified in a build command, but only some of them can be
- successfully analyzed, the build will stop with an error
- unless <code class='flag'>--keep_going</code> is specified, in which case the
- build will proceed to the execution phase, but only for the targets
- that were successfully analyzed.
-</p>
-
-<h4 id='flag--use_ijars'><code class='flag'>--[no]use_ijars</code></h4>
-<p>
- This option changes the way <code>java_library</code> targets are
- compiled by Bazel. Instead of using the output of a
- <code>java_library</code> for compiling dependent
- <code>java_library</code> targets, Bazel will create interface jars
- that contain only the signatures of non-private members (public,
- protected, and default (package) access methods and fields) and use
- the interface jars to compile the dependent targets. This makes it
- possible to avoid recompilation when changes are only made to
- method bodies or private members of a class.
-</p>
-<p>
- Note that using <code class='flag'>--use_ijars</code> might give you a different
- error message when you are accidentally referring to a non visible
- member of another class: Instead of getting an error that the member
- is not visible you will get an error that the member does not exist.
-</p>
-<p>
- Note that changing the <code class='flag'>--use_ijars</code> setting will force
- a recompilation of all affected classes.
-</p>
-
-<h4 id='flag--interface_shared_objects'>
- <code class='flag'>--[no]interface_shared_objects</code>
-</h4>
-<p>
- This option enables <i>interface shared objects</i>, which makes binaries and
- other shared libraries depend on the <i>interface</i> of a shared object,
- rather than its implementation. When only the implementation changes, Bazel
- can avoid rebuilding targets that depend on the changed shared library
- unnecessarily.
-</p>
-
-<h3 id='output-selection-options'>Output selection</h3>
-<p>
- These options determine what to build or test.
-</p>
-
-<h4 id="nobuild"><code class='flag'>--[no]build</code></h4>
-<p>
- This option causes the execution phase of the build to occur; it is
- on by default. When it is switched off, the execution phase is
- skipped, and only the first two phases, loading and analysis, occur.
-</p>
-<p>
- This option can be useful for validating BUILD files and detecting
- errors in the inputs, without actually building anything.
-</p>
-
-<h4 id='flag--build_tests_only'><code class='flag'>--[no]build_tests_only</code></h4>
-<p>
- If specified, Bazel will build only what is necessary to run the *_test
- and test_suite rules that were not filtered due to their
- <a href='#flag--test_size_filters'>size</a>,
- <a href='#flag--test_timeout_filters'>timeout</a>,
- <a href='#flag--test_tag_filters'>tag</a>, or
- <a href='#flag--test_lang_filters'>language</a>.
- If specified, Bazel will ignore other targets specified on the command line.
- By default, this option is disabled and Bazel will build everything
- requested, including *_test and test_suite rules that are filtered out from
- testing. This is useful because running
- <code>bazel test --build_tests_only foo/...</code> may not detect all build
- breakages in the <code>foo</code> tree.
-</p>
-
-<h4 id='flag--check_up_to_date'><code class='flag'>--[no]check_up_to_date</code></h4>
-<p>
- This option causes Bazel not to perform a build, but merely check
- whether all specified targets are up-to-date. If so, the build
- completes successfully, as usual. However, if any files are out of
- date, instead of being built, an error is reported and the build
- fails. This option may be useful to determine whether a build has
- been performed more recently than a source edit (e.g. for pre-submit
- checks) without incurring the cost of a build.
-</p>
-<p>
- See also <a href="#flag--check_tests_up_to_date"><code class='flag'>--check_tests_up_to_date</code></a>.
-</p>
-
-<h4 id='flag--compile_one_dependency'><code class='flag'>--[no]compile_one_dependency</code></h4>
-<p>
- Compile a single dependency of the argument files. This is useful for
- syntax checking source files in IDEs, for example, by rebuilding a single
- target that depends on the source file to detect errors as early as
- possible in the edit/build/test cycle. This argument affects the way all
- non-flag arguments are interpreted: each argument must be a
- file target label or a plain filename relative to the current working
- directory, and one rule that depends on each source filename is built. For
-
- C++ and Java
- sources, rules in the same language space are preferentially chosen. For
- multiple rules with the same preference, the one that appears first in the
- BUILD file is chosen. An explicitly named target pattern which does not
- reference a source file results in an error.
-</p>
-
-<h4 id='flag--save_temps'><code class='flag'>--save_temps</code></h4>
-<p>
- The <code class='flag'>--save_temps</code> option causes temporary outputs from the compiler to be
- saved. These include .s files (assembler code), .i (preprocessed C) and .ii
- (preprocessed C++) files. These outputs are often useful for debugging. Temps will only be
- generated for the set of targets specified on the command line.
-</p>
-<p>
- Note that the implementation of <code class='flag'>--save_temps</code> does not use the compiler's
- <code>-save-temps</code> flag. Instead, there are two passes, one with <code>-S</code>
- and one with <code>-E</code>. A consequence of this is that if your build fails,
- Bazel may not yet have produced the ".i" or ".ii" and ".s" files.
- If you're trying to use <code class='flag'>--save_temps</code> to debug a failed compilation,
- you may need to also use <code class='flag'>--keep_going</code> so that Bazel will still try to
- produce the preprocessed files after the compilation fails.
-</p>
-<p>
- The <code class='flag'>--save_temps</code> flag currently works only for cc_* rules.
-</p>
-<p>
- To ensure that Bazel prints the location of the additional output files, check that
- your <a href='#flag--show_result'><code class='flag'>--show_result <var>n</var></code></a>
- setting is high enough.
-</p>
-
-<h4 id='flag--build_tag_filters'><code class='flag'>--build_tag_filters=<var>tag[,tag]*</var></code></h4>
-<p>
- If specified, Bazel will build only targets that have at least one required tag
- (if any of them are specified) and does not have any excluded tags. Build tag
- filter is specified as comma delimited list of tag keywords, optionally
- preceded with '-' sign used to denote excluded tags. Required tags may also
- have a preceding '+' sign.
-</p>
-<p>
- When running tests, Bazel ignores <code class='flag'>--build_tag_filters</code> for test targets,
- which are built and run even if they do not match this filter. To avoid building them, filter
- test targets using <code class='flag'>--test_tag_filters</code> or by explicitly excluding them.
-</p>
-
-<h4 id='flag--test_size_filters'><code class='flag'>--test_size_filters=<var>size[,size]*</var></code></h4>
-<p>
- If specified, Bazel will test (or build if <code class='flag'>--build_tests_only</code>
- is also specified) only test targets with the given size. Test size filter
- is specified as comma delimited list of allowed test size values (small,
- medium, large or enormous), optionally preceded with '-' sign used to denote
- excluded test sizes. For example,
-</p>
-<pre>
- % bazel test --test_size_filters=small,medium //foo:all
-</pre>
- and
-<pre>
- % bazel test --test_size_filters=-large,-enormous //foo:all
-</pre>
-<p>
- will test only small and medium tests inside //foo.
-</p>
-<p>
- By default, test size filtering is not applied.
-</p>
-
-<h4 id='flag--test_timeout_filters'><code class='flag'>--test_timeout_filters=<var>timeout[,timeout]*</var></code></h4>
-<p>
- If specified, Bazel will test (or build if <code class='flag'>--build_tests_only</code>
- is also specified) only test targets with the given timeout. Test timeout filter
- is specified as comma delimited list of allowed test timeout values (short,
- moderate, long or eternal), optionally preceded with '-' sign used to denote
- excluded test timeouts. See <a href='#flag--test_size_filters'>--test_size_filters</a>
- for example syntax.
-</p>
-<p>
- By default, test timeout filtering is not applied.
-</p>
-
-
-<h4 id='flag--test_tag_filters'><code class='flag'>--test_tag_filters=<var>tag[,tag]*</var></code></h4>
-<p>
- If specified, Bazel will test (or build if <code class='flag'>--build_tests_only</code>
- is also specified) only test targets that have at least one required tag
- (if any of them are specified) and does not have any excluded tags. Test tag
- filter is specified as comma delimited list of tag keywords, optionally
- preceded with '-' sign used to denote excluded tags. Required tags may also
- have a preceding '+' sign.
-</p>
-<p>
- For example,
-<pre>
- % bazel test --test_tag_filters=performance,stress,-flaky //myproject:all
-</pre>
-<p>
- will test targets that are tagged with either <code>performance</code> or
- <code>stress</code> tag but are <b>not</b> tagged with the <code>flaky</code>
- tag.
-</p>
-<p>
- By default, test tag filtering is not applied. Note that you can also filter
- on test's <code>size</code> and <code>local</code> tags in
- this manner.
-</p>
-
-<h4 id='flag--test_lang_filters'><code class='flag'>--test_lang_filters=<var>lang[,lang]*</var></code></h4>
-<p>
- Specifies a comma-separated list of test languages for languages with an official <code>*_test</code> rule the
- (see <a href="be/overview.html">build encyclopedia</a> for a full list of these). Each
- language can be optionally preceded with '-' to specify excluded
- languages. The name used for each language should be the same as
- the language prefix in the <code>*_test</code> rule, for example,
- <code>cc</code>, <code>java</code> or <code>sh</code>.
-</p>
-<p>
- If specified, Bazel will test (or build if <code class='flag'>--build_tests_only</code>
- is also specified) only test targets of the specified language(s).
-</p>
-<p>
- For example,
-</p>
-<pre>
- % bazel test --test_lang_filters=cc,java foo/...
-</pre>
-<p>
- will test only the C/C++ and Java tests (defined using
- <code>cc_test</code> and <code>java_test</code> rules, respectively)
- in <code>foo/...</code>, while
-</p>
-<pre>
- % bazel test --test_lang_filters=-sh,-java foo/...
-</pre>
-<p>
- will run all of the tests in <code>foo/...</code> except for the
- <code>sh_test</code> and <code>java_test</code> tests.
-</p>
-<p>
- By default, test language filtering is not applied.
-</p>
-
-<h4 id="flag--test_filter"><code class='flag'>--test_filter=<var>filter-expression</var></code></h4>
-<p>
- Specifies a filter that the test runner may use to pick a subset of tests for
- running. All targets specified in the invocation are built, but depending on
- the expression only some of them may be executed; in some cases, only certain
- test methods are run.
-</p>
-<p>
- The particular interpretation of <var>filter-expression</var> is up to
- the test framework responsible for running the test. It may be a glob,
- substring, or regexp. <code class='flag'>--test_filter</code> is a convenience
- over passing different <code class='flag'>--test_arg</code> filter arguments,
- but not all frameworks support it.
-</p>
-
-<h3 id='verbosity'>Verbosity</h3>
-
-These options control the verbosity of Bazel's output,
-either to the terminal, or to additional log files.
-
-<h4 id='flag--explain'><code class='flag'>--explain=<var>logfile</var></code></h4>
-<p>
- This option, which requires a filename argument, causes the
- dependency checker in <code>bazel build</code>'s execution phase to
- explain, for each build step, either why it is being executed, or
- that it is up-to-date. The explanation is written
- to <i>logfile</i>.
-</p>
-<p>
- If you are encountering unexpected rebuilds, this option can help to
- understand the reason. Add it to your <code>.bazelrc</code> so that
- logging occurs for all subsequent builds, and then inspect the log
- when you see an execution step executed unexpectedly. This option
- may carry a small performance penalty, so you might want to remove
- it when it is no longer needed.
-</p>
-
-<h4 id='flag--verbose_explanations'><code class='flag'>--verbose_explanations</code></h4>
-<p>
- This option increases the verbosity of the explanations generated
- when the <a href='#flag--explain'>--explain</a> option is enabled.
-</p>
-<p>
- In particular, if verbose explanations are enabled,
- and an output file is rebuilt because the command used to
- build it has changed, then the output in the explanation file will
- include the full details of the new command (at least for most
- commands).
-</p>
-<p>
- Using this option may significantly increase the length of the
- generated explanation file and the performance penalty of using
- <code class='flag'>--explain</code>.
-</p>
-<p>
- If <code class='flag'>--explain</code> is not enabled, then
- <code class='flag'>--verbose_explanations</code> has no effect.
-</p>
-
-<h4 id='flag--profile'><code class='flag'>--profile=<var>file</var></code></h4>
-<p>
- This option, which takes a filename argument, causes Bazel to write
- profiling data into a file. The data then can be analyzed or parsed using the
- <code>bazel analyze-profile</code> command. The Build profile can be useful in
- understanding where Bazel's <code>build</code> command is spending its time.
-</p>
-
-<h4 id='flag--show_loading_progress'><code class='flag'>--[no]show_loading_progress</code></h4>
-<p>
- This option causes Bazel to output package-loading progress
- messages. If it is disabled, the messages won't be shown.
-</p>
-
-<h4 id='flag--show_progress'><code class='flag'>--[no]show_progress</code></h4>
-<p>
- This option causes progress messages to be displayed; it is on by
- default. When disabled, progress messages are suppressed.
-</p>
-
-<h4 id='flag--show_progress_rate_limit'><code class='flag'>--show_progress_rate_limit=
- <var>n</var></code></h4>
-<p>
- This option causes bazel to display only
- one progress message per <code>n</code> seconds, where <var>n</var> is a real number.
- If <code>n</code> is -1, all progress messages will be displayed.
- The default value for this option is 0.2, meaning bazel will limit the progress messages to one
- per every 0.2 seconds.
-</p>
-
-<h4 id='flag--show_result'><code class='flag'>--show_result=<var>n</var></code></h4>
-<p>
- This option controls the printing of result information at the end
- of a <code>bazel build</code> command. By default, if a single
- build target was specified, Bazel prints a message stating whether
- or not the target was successfully brought up-to-date, and if so,
- the list of output files that the target created. If multiple
- targets were specified, result information is not displayed.
-</p>
-<p>
- While the result information may be useful for builds of a single
- target or a few targets, for large builds (e.g. an entire top-level
- project tree), this information can be overwhelming and distracting;
- this option allows it to be controlled. <code class='flag'>--show_result</code>
- takes an integer argument, which is the maximum number of targets
- for which full result information should be printed. By default,
- the value is 1. Above this threshold, no result information is
- shown for individual targets. Thus zero causes the result
- information to be suppressed always, and a very large value causes
- the result to be printed always.
-</p>
-<p>
- Users may wish to choose a value in-between if they regularly
- alternate between building a small group of targets (for example,
- during the compile-edit-test cycle) and a large group of targets
- (for example, when establishing a new workspace or running
- regression tests). In the former case, the result information is
- very useful whereas in the latter case it is less so. As with all
- options, this can be specified implicitly via
- the <a href='guide.html#bazelrc'><code>.bazelrc</code></a> file.
-</p>
-<p>
- The files are printed so as to make it easy to copy and paste the
- filename to the shell, to run built executables. The "up-to-date"
- or "failed" messages for each target can be easily parsed by scripts
- which drive a build.
-</p>
-
-<h4 id='flag--sandbox_debug'><code class='flag'>--sandbox_debug</code></h4>
-<p>
- This option causes Bazel to print extra debugging information when using sandboxing for action
- execution. This option also preserves sandbox directories, so that the files visible to actions
- during execution can be examined.
-</p>
-
-<h4 id='flag--subcommands'><code class='flag'>--subcommands</code> (<code>-s</code>)</h4>
-<p>
- This option causes Bazel's execution phase to print the full command line
- for each command prior to executing it.
-</p>
-
-<pre>
- >>>>> # //examples/cpp:hello-world [action 'Linking examples/cpp/hello-world']
- (cd /home/johndoe/.cache/bazel/_bazel_johndoe/4c084335afceb392cfbe7c31afee3a9f/bazel && \
- exec env - \
- /usr/bin/gcc -o bazel-out/local-fastbuild/bin/examples/cpp/hello-world -B/usr/bin/ -Wl,-z,relro,-z,now -no-canonical-prefixes -pass-exit-codes -Wl,-S -Wl,@bazel-out/local_linux-fastbuild/bin/examples/cpp/hello-world-2.params)
-</pre>
-<p>
- Where possible, commands are printed in a Bourne shell compatible syntax,
- so that they can be easily copied and pasted to a shell command prompt.
- (The surrounding parentheses are provided to protect your shell from the
- <code>cd</code> and <code>exec</code> calls; be sure to copy them!)
- However some commands are implemented internally within Bazel, such as
- creating symlink trees. For these there's no command line to display.
-
-</p>
-
-<p>
- <code class='flag'>--subcommands=pretty_print</code> may be passed to print
- the arguments of the command as a list rather than as a single line. This may
- help make long command lines more readable.
-</p>
-
-<p>
- See also <a href="#flag--verbose_failures">--verbose_failures</a>, below.
-</p>
-
-<p>
- For logging subcommands to a file in a tool-friendly format, see
- <a href="command-line-reference.html#flag--execution_log_json_file">
- <code>--execution_log_json_file</code></a> and
- <a href="command-line-reference.html#flag--execution_log_binary_file">
- <code>--execution_log_binary_file</code></a>.
-</p>
-
-<h4 id='flag--verbose_failures'><code class='flag'>--verbose_failures</code></h4>
-<p>
- This option causes Bazel's execution phase to print the full command line
- for commands that failed. This can be invaluable for debugging a
- failing build.
-</p>
-<p>
- Failing commands are printed in a Bourne shell compatible syntax, suitable
- for copying and pasting to a shell prompt.
-</p>
-
-<h3 id='workspace_status'>Workspace status</h3>
-
-<p>
- Use these options to "stamp" Bazel-built binaries: to embed additional information into the
- binaries, such as the source control revision or other workspace-related information. You can use
- this mechanism with rules that support the <code>stamp</code> attribute, such as
- <code>genrule</code>, <code>cc_binary</code>, and more.
-</p>
-
-<h4 id='flag--workspace_status_command'><code class='flag'>--workspace_status_command=<var>program</var></code></h4>
-<p>
- This flag lets you specify a binary that Bazel runs before each build. The program can report
- information about the status of the workspace, such as the current source control revision.
-</p>
-<p>
- The flag's value must be a path to a native program. On Linux/macOS this may be any executable.
- On Windows this must be a native binary, typically an ".exe", ".bat", or a ".cmd" file.
-</p>
-
-<p>
- The program should print zero or more key/value pairs to standard output, one entry on each line,
- then exit with zero (otherwise the build fails). The key names can be anything but they may only
- use upper case letters and underscores. The first space after the key name separates it from the
- value. The value is the rest of the line (including additional whitespaces). Neither the key nor
- the value may span multiple lines. Keys must not be duplicated.
-</p>
-<p>
- Bazel partitions the keys into two buckets: "stable" and "volatile". (The names "stable" and
- "volatile" are a bit counter-intuitive, so don't think much about them.)
-</p>
-
-<p>Bazel then writes the key-value pairs into two files:</p>
-<ul>
- <li>
- <code>bazel-out/stable-status.txt</code>
- contains all keys and values where the key's name starts with <code>STABLE_</code>
- </li>
- <li>
- <code>bazel-out/volatile-status.txt</code>
- contains the rest of the keys and their values
- </li>
-</ul>
-
-<p>The contract is:</p>
-<ul>
- <li>
- <p>
- "stable" keys' values should change rarely, if possible. If the contents of
- <code>bazel-out/stable-status.txt</code>
- change, Bazel invalidates the actions that depend on them. In
- other words, if a stable key's value changes, Bazel will rerun stamped actions.
- Therefore the stable status should not contain things like timestamps, because they change all
- the time, and would make Bazel rerun stamped actions with each build.
- </p>
- <p>Bazel always outputs the following stable keys:</p>
- <ul>
- <li><code>BUILD_EMBED_LABEL</code>: value of <code class='flag'>--embed_label</code></li>
- <li><code>BUILD_HOST</code>: the name of the host machine that Bazel is running on</li>
- <li><code>BUILD_USER</code>: the name of the user that Bazel is running as</li>
- </ul>
- </li>
- <li>
- <p>
- "volatile" keys' values may change often. Bazel expects them to change all the time, like
- timestamps do, and duly updates the
- <code>bazel-out/volatile-status.txt</code>
- file. In order to avoid
- rerunning stamped actions all the time though, <b>Bazel pretends that the volatile file never
- changes</b>. In other words, if the volatile status file is the only file whose contents has
- changed, Bazel will not invalidate actions that depend on it. If other inputs of the actions
- have changed, then Bazel reruns that action, and the action will see the updated volatile
- status, but just the volatile status changing alone will not invalidate the action.
- </p>
- <p>Bazel always outputs the following volatile keys:</p>
- <ul>
- <li>
- <code>BUILD_TIMESTAMP</code>: time of the build in seconds since the Unix Epoch (the value
- of <code>System.currentTimeMillis()</code> divided by a thousand)
- </li>
- </ul>
- </li>
-</ul>
-
-<p>
- On Linux/macOS you can pass <code class='flag'>--workspace_status_command=/bin/true</code> to
- disable retrieving workspace status, because <code>true</code> does nothing, successfully (exits
- with zero) and prints no output. On Windows you can pass the path of MSYS's <code>true.exe</code>
- for the same effect.
-</p>
-
-<p>If the workspace status command fails (exits non-zero) for any reason, the build will fail.</p>
-
-<p>Example program on Linux using Git:</p>
-
-<pre>
-#!/bin/bash
-echo "CURRENT_TIME $(date +%s)"
-echo "RANDOM_HASH $(cat /proc/sys/kernel/random/uuid)"
-echo "STABLE_GIT_COMMIT $(git rev-parse HEAD)"
-echo "STABLE_USER_NAME $USER"
-</pre>
-
-<p>
- Pass this program's path with <code>--workspace_status_command</code>, and the stable status file
- will include the STABLE lines and the volatile status file will include the rest of the lines.
-</p>
-
-<h4 id='flag--stamp'><code class='flag'>--[no]stamp</code></h4>
-<p>
- This option, in conjunction with the <code>stamp</code> rule attribute, controls whether to embed
- build information in binaries.
-</p>
-<p>
- Stamping can be enabled or disabled explicitly on a per-rule basis using the <code>stamp</code>
- attribute. Please refer to the <a href="be/overview.html">build encyclopedia</a> for details. When
- a rule sets <code>stamp = -1</code> (the default for <code>*_binary</code> rules), this option
- determines whether stamping is enabled.
-</p>
-<p>
- Bazel never stamps binaries that are built for the host configuration, regardless of this option
- or the <code>stamp</code> attribute. By default, stamping is disabled for all tests. Specifying
- <code class='flag'>--stamp</code> does not force targets to be rebuilt if their dependencies have
- not changed.
-</p>
-<p>
- Setting <code class='flag'>--nostamp</code> is generally desireable for build performance, as it
- reduces input volatility and maximizes build caching.
-</p>
-
-<h3 id='platform_build_options'>Platform</h3>
-
-<p>
- Use these options to control the host and target platforms that configure how builds work, and to
- control what execution platforms and toolchains are available to Bazel rules.
-</p>
-
-<p>
- Please see background information on
- <a href="platforms.html">Platforms</a> and <a href="toolchains.html">Toolchains</a>.
-</p>
-
-<h4 id="flag--platforms"><code class='flag'>--platforms=<var>labels</var></code></h4>
-<p>
- The labels of the platform rules describing the target platforms for the
- current command.
-</p>
-
-<h4 id="flag--host_platform"><code class='flag'>--host_platform=<var>label</var></code></h4>
-<p>
- The label of a platform rule that describes the host system.
-</p>
-
-<h4 id="flag--extra_execution_platforms"><code class='flag'>--extra_execution_platforms=<var>labels</var></code></h4>
-<p>
- The platforms that are available as execution platforms to run actions.
- Platforms can be specified by exact target, or as a target pattern. These
- platforms will be considered before those declared in the WORKSPACE file by
- <a href="skylark/lib/globals.html#register_execution_platforms">
- register_execution_platforms()</a>.
-</p>
-
-<h4 id="flag--extra_toolchains"><code class='flag'>--extra_toolchains=<var>labels</var></code></h4>
-<p>
- The toolchain rules to be considered during toolchain resolution. Toolchains
- can be specified by exact target, or as a target pattern. These toolchains will
- be considered before those declared in the WORKSPACE file by
- <a href="skylark/lib/globals.html#register_toolchains">
- register_toolchains()</a>.
-</p>
-
-<h4 id="flag--toolchain_resolution_debug"><code class='flag'>--toolchain_resolution_debug=<var>regex</var></code></h4>
-<p>
- Print debug information while finding toolchains if the toolchain type matches
- the regex. Multiple regexes can be separated by commas. The regex can be
- negated by using a <code>-</code> at the beginning. This might help developers
- of Bazel or Starlark rules with debugging failures due to missing toolchains.
-</p>
-
-<h3 id='misc_build_options'>Miscellaneous</h3>
-
-<h4 id='flag--flag_alias'><code class='flag'>--flag_alias=<var>alias_name=target_path</var></code></h4>
-<p>
- A convenience flag used to bind longer Starlark build settings to a shorter name. For more
- details, see the
- <a href=https://docs.bazel.build/versions/main/skylark/config.html#using-build-setting-aliases">Starlark Configurations</a>.
-</p>
-
-<h4 id='flag--symlink_prefix'><code class='flag'>--symlink_prefix=<var>string</var></code></h4>
-<p>
- Changes the prefix of the generated convenience symlinks. The
- default value for the symlink prefix is <code>bazel-</code> which
- will create the symlinks <code>bazel-bin</code>, <code>bazel-testlogs</code>, and
- <code>bazel-genfiles</code>.
-</p>
-<p>
- If the symbolic links cannot be created for any reason, a warning is
- issued but the build is still considered a success. In particular,
- this allows you to build in a read-only directory or one that you have no
- permission to write into. Any paths printed in informational
- messages at the conclusion of a build will only use the
- symlink-relative short form if the symlinks point to the expected
- location; in other words, you can rely on the correctness of those
- paths, even if you cannot rely on the symlinks being created.
-</p>
-<p>
- Some common values of this option:
-</p>
-<ul>
-
- <li>
- <p><b>Suppress symlink creation:</b>
- <code class='flag'>--symlink_prefix=/</code> will cause Bazel to not
- create or update any symlinks, including the <code>bazel-out</code> and
-
- <code>bazel-<workspace></code>
- symlinks. Use this option to suppress symlink creation entirely.
- </p>
- </li>
- <li>
- <p><b>Reduce clutter:</b>
- <code class='flag'>--symlink_prefix=.bazel/</code> will cause Bazel to create
- symlinks called <code>bin</code> (etc) inside a hidden directory <code>.bazel</code>.
- </p>
- </li>
-</ul>
-
-<h4 id='flag--platform_suffix'><code class='flag'>--platform_suffix=<var>string</var></code></h4>
-<p>
- Adds a suffix to the configuration short name, which is used to determine the
- output directory. Setting this option to different values puts the files into
- different directories, for example to improve cache hit rates for builds that
- otherwise clobber each others output files, or to keep the output files around
- for comparisons.
-</p>
-
-<h4 id='flag--default_visibility'><code class='flag'>--default_visibility=<var>(private|public)</var></code></h4>
-<p>
- Temporary flag for testing bazel default visibility changes. Not intended for general use
- but documented for completeness' sake.
-</p>
-
-<h4 id='flag--use_action_cache'><code class='flag'>--[no]use_action_cache</code></h4>
-<p>
- This option is enabled by default. If disabled, Bazel will not use its local action cache.
- Disabling the local action cache saves memory and disk space for clean builds, but will make
- incremental builds slower.
-</p>
-
-<h4 id='flag--starlark_cpu_profile'><code class='flag'>--starlark_cpu_profile=<i>file</i></code></h4>
-<p>
- This flag, whose value is the name of a file, causes Bazel to gather
- statistics about CPU usage by all Starlark threads,
- and write the profile, in <a href='https://github.com/google/pprof'>pprof</a> format,
- to the named file.
-
- Use this option to help identify Starlark functions that
- make loading and analysis slow due to excessive computation. For example:
-</p>
-<pre>
-$ bazel build --nobuild --starlark_cpu_profile=/tmp/pprof.gz my/project/...
-$ pprof /tmp/pprof.gz
-(pprof) top
-Type: CPU
-Time: Feb 6, 2020 at 12:06pm (PST)
-Duration: 5.26s, Total samples = 3.34s (63.55%)
-Showing nodes accounting for 3.34s, 100% of 3.34s total
- flat flat% sum% cum cum%
- 1.86s 55.69% 55.69% 1.86s 55.69% sort_source_files
- 1.02s 30.54% 86.23% 1.02s 30.54% expand_all_combinations
- 0.44s 13.17% 99.40% 0.44s 13.17% range
- 0.02s 0.6% 100% 3.34s 100% sorted
- 0 0% 100% 1.38s 41.32% my/project/main/BUILD
- 0 0% 100% 1.96s 58.68% my/project/library.bzl
- 0 0% 100% 3.34s 100% main
-</pre>
-<p>
- For different views of the same data, try the <code>pprof</code> commands <code>svg</code>,
- <code>web</code>, and <code>list</code>.
-</p>
-
-<h2 id='bazel-releng'>Using Bazel for releases</h2>
-<p>
- Bazel is used both by software engineers during the development
- cycle, and by release engineers when preparing binaries for deployment
- to production. This section provides a list of tips for release
- engineers using Bazel.
-
-</p>
-
-<h3>Significant options</h3>
-
-<p>
- When using Bazel for release builds, the same issues arise as for
- other scripts that perform a build, so you should read
- the <a href='guide.html#scripting'>scripting</a> section of this manual.
- In particular, the following options are strongly recommended:
-</p>
-<ul>
- <li><a href='guide.html#bazelrc'><code class='flag'>--bazelrc=/dev/null</code></a></li>
- <li><a href='#flag--keep_state_after_build'><code class='flag'>--nokeep_state_after_build</code></a></li>
-</ul>
-
-<p>
- These options are also important:
-</p>
-
-<ul>
-
- <li><a href='#flag--package_path'><code class='flag'>--package_path</code></a></li>
- <li><a href='#flag--symlink_prefix'><code class='flag'>--symlink_prefix</code></a>:
- for managing builds for multiple configurations,
- it may be convenient to distinguish each build
- with a distinct identifier, e.g. "64bit" vs. "32bit". This option
- differentiates the <code>bazel-bin</code> (etc.) symlinks.
- </li>
-</ul>
-
-<h2 id='test'>Running tests</h2>
-<p>
- To build and run tests with bazel, type <code>bazel test</code> followed by
- the name of the test targets.
-</p>
-<p>
- By default, this command performs simultaneous build and test
- activity, building all specified targets (including any non-test
- targets specified on the command line) and testing
- <code>*_test</code> and <code>test_suite</code> targets as soon as
- their prerequisites are built, meaning that test execution is
- interleaved with building. Doing so usually results in significant
- speed gains.
-
-</p>
-
-<h3>Options for <code>bazel test</code></h3>
-
-<h4 id="flag--cache_test_results"><code class='flag'>--cache_test_results=(yes|no|auto)</code> (<code>-t</code>)</h4>
-<p>
- If this option is set to 'auto' (the default) then Bazel will only rerun a test if any of the
- following conditions applies:
-</p>
-<ul>
- <li>Bazel detects changes in the test or its dependencies</li>
- <li>the test is marked as <code>external</code></li>
- <li>multiple test runs were requested with <code class='flag'>--runs_per_test</code></li>
- <li>the test failed.</li>
-</ul>
-<p>
- If 'no', all tests will be executed unconditionally.
-</p>
-<p>
- If 'yes', the caching behavior will be the same as auto
- except that it may cache test failures and test runs with
- <code class='flag'>--runs_per_test</code>.
-</p>
-<p>
- Note that test results are <em>always</em> saved in Bazel's output tree,
- regardless of whether this option is enabled, so
- you needn't have used <code class='flag'>--cache_test_results</code> on the
- prior run(s) of <code>bazel test</code> in order to get cache hits.
- The option only affects whether Bazel will <em>use</em> previously
- saved results, not whether it will save results of the current run.
-</p>
-<p>
- Users who have enabled this option by default in
- their <code>.bazelrc</code> file may find the
- abbreviations <code>-t</code> (on) or <code>-t-</code> (off)
- convenient for overriding the default on a particular run.
-</p>
-
-<h4 id="flag--check_tests_up_to_date"><code class='flag'>--check_tests_up_to_date</code></h4>
-<p>
- This option tells Bazel not to run the tests, but to merely check and report
- the cached test results. If there are any tests which have not been
- previously built and run, or whose tests results are out-of-date (e.g. because
- the source code or the build options have changed), then Bazel will report
- an error message ("test result is not up-to-date"), will record the test's
- status as "NO STATUS" (in red, if color output is enabled), and will return
- a non-zero exit code.
-</p>
-<p>
- This option also implies
- <code><a href="#flag--check_up_to_date">--check_up_to_date</a></code> behavior.
-</p>
-<p>
- This option may be useful for pre-submit checks.
-</p>
-
-<h4 id="flag--test_verbose_timeout_warnings"><code class='flag'>--test_verbose_timeout_warnings</code></h4>
-<p>
- This option tells Bazel to explicitly warn the user if a test's timeout is
-significantly longer than the test's actual execution time. While a test's
-timeout should be set such that it is not flaky, a test that has a highly
-over-generous timeout can hide real problems that crop up unexpectedly.
-</p>
-<p>
-For instance, a test that normally executes in a minute or two should not have
-a timeout of ETERNAL or LONG as these are much, much too generous.
-
- This option is useful to help users decide on a good timeout value or
- sanity check existing timeout values.
-</p>
-<p>
-Note that each test shard is allotted the timeout of the entire
-<code>XX_test</code> target. Using this option does not affect a test's timeout
-value, merely warns if Bazel thinks the timeout could be restricted further.
-</p>
-
-<h4 id='flag--test_keep_going'><code class='flag'>--[no]test_keep_going</code></h4>
-<p>
- By default, all tests are run to completion. If this flag is disabled,
- however, the build is aborted on any non-passing test. Subsequent build steps
- and test invocations are not run, and in-flight invocations are canceled.
- Do not specify both <code class='flag'>--notest_keep_going</code> and
- <code class='flag'>--keep_going</code>.
-</p>
-
-<h4 id='flag--flaky_test_attempts'><code class='flag'>--flaky_test_attempts=<var>attempts</var></code></h4>
-<p>
- This option specifies the maximum number of times a test should be attempted
- if it fails for any reason. A test that initially fails but eventually
- succeeds is reported as <code>FLAKY</code> on the test summary. It is,
- however, considered to be passed when it comes to identifying Bazel exit code
- or total number of passed tests. Tests that fail all allowed attempts are
- considered to be failed.
-</p>
-<p>
- By default (when this option is not specified, or when it is set to
- "default"), only a single attempt is allowed for regular tests, and
- 3 for test rules with the <code>flaky</code> attribute set. You can specify
- an integer value to override the maximum limit of test attempts. Bazel allows
- a maximum of 10 test attempts in order to prevent abuse of the system.
-</p>
-
-<h4 id='flag--runs_per_test'><code class='flag'>--runs_per_test=<var>[regex@]number</var></code></h4>
-<p>
- This option specifies the number of times each test should be executed. All
- test executions are treated as separate tests (e.g. fallback functionality
- will apply to each of them independently).
-</p>
-<p>
- The status of a target with failing runs depends on the value of the
- <code>--runs_per_test_detects_flakes</code> flag:
-</p>
-<ul>
- <li>If absent, any failing run causes the entire test to fail.</li>
- <li>If present and two runs from the same shard return PASS and FAIL, the test
- will receive a status of flaky (unless other failing runs cause it to
- fail).</li>
-</ul>
-
-<p>
- If a single number is specified, all tests will run that many times.
- Alternatively, a regular expression may be specified using the syntax
- regex@number. This constrains the effect of --runs_per_test to targets
- which match the regex (e.g. "--runs_per_test=^//pizza:.*@4" runs all tests
- under //pizza/ 4 times).
- This form of --runs_per_test may be specified more than once.
-</p>
-
-<h4 id='flag--runs_per_test_detects_flakes'><code
- class='flag'>--[no]runs_per_test_detects_flakes</code></h4>
-<p>
- If this option is specified (by default it is not), Bazel will detect flaky
- test shards through --runs_per_test. If one or more runs for a single shard
- fail and one or more runs for the same shard pass, the target will be
- considered flaky with the flag. If unspecified, the target will report a
- failing status.
-</p>
-
-<h4 id='flag--test_summary'><code class='flag'>--test_summary=<var>output_style</var></code></h4>
-<p>
- Specifies how the test result summary should be displayed.
-</p>
-<ul>
- <li><code>short</code> prints the results of each test along with the name of
- the file containing the test output if the test failed. This is the default
- value.
- </li>
- <li><code>terse</code> like <code>short</code>, but even shorter: only print
- information about tests which did not pass.
- </li>
- <li><code>detailed</code> prints each individual test case that failed, not
- only each test. The names of test output files are omitted.
- </li>
- <li><code>none</code> does not print test summary.
- </li>
-</ul>
-
-<h4 id='flag--test_output'><code class='flag'>--test_output=<var>output_style</var></code></h4>
-<p>
- Specifies how test output should be displayed:
-</p>
-<ul>
- <li><code>summary</code> shows a summary of whether each test passed or
- failed. Also shows the output log file name for failed tests. The summary
- will be printed at the end of the build (during the build, one would see
- just simple progress messages when tests start, pass or fail).
- This is the default behavior.
- </li>
- <li><code>errors</code> sends combined stdout/stderr output from failed tests
- only into the stdout immediately after test is completed, ensuring that
- test output from simultaneous tests is not interleaved with each other.
- Prints a summary at the build as per summary output above.
- </li>
- <li><code>all</code> is similar to <code>errors</code> but prints output for
- all tests, including those which passed.
- </li>
- <li><code>streamed</code> streams stdout/stderr output from each test in
- real-time.
-
- </li>
-</ul>
-
-<h4 id='flag--java_debug'><code class='flag'>--java_debug</code></h4>
-<p>
- This option causes the Java virtual machine of a java test to wait for a connection from a
- JDWP-compliant debugger before starting the test. This option implies --test_output=streamed.
-</p>
-
-<h4 id='flag--verbose_test_summary'><code class='flag'>--[no]verbose_test_summary</code></h4>
-<p>
- By default this option is enabled, causing test times and other additional
- information (such as test attempts) to be printed to the test summary. If
- <code class='flag'>--noverbose_test_summary</code> is specified, test summary will
- include only test name, test status and cached test indicator and will
- be formatted to stay within 80 characters when possible.
-</p>
-
-<h4 id='flag--test_tmpdir'><code class='flag'>--test_tmpdir=<var>path</var></code></h4>
-<p>
- Specifies temporary directory for tests executed locally. Each test will be
- executed in a separate subdirectory inside this directory. The directory will
- be cleaned at the beginning of the each <code>bazel test</code> command.
- By default, bazel will place this directory under Bazel output base directory.
- Note that this is a directory for running tests, not storing test results
- (those are always stored under the <code>bazel-out</code> directory).
-</p>
-
-<h4 id='flag--test_timeout'>
- <code class='flag'>--test_timeout=
- <var>seconds</var></code>
- OR
- <code class='flag'>--test_timeout=
- <var>seconds</var>,<var>seconds</var>,<var>seconds</var>,<var>seconds</var>
- </code>
-</h4>
-<p>
- Overrides the timeout value for all tests by using specified number of
- seconds as a new timeout value. If only one value is provided, then it will
- be used for all test timeout categories.
- </p>
- <p>
- Alternatively, four comma-separated values may be provided, specifying
- individual timeouts for short, moderate, long and eternal tests (in that
- order).
- In either form, zero or a negative value for any of the test sizes will
- be substituted by the default timeout for the given timeout categories as
- defined by the page
- <a href="test-encyclopedia.html">Writing Tests</a>.
- By default, Bazel will use these timeouts for all tests by
- inferring the timeout limit from the test's size whether the size is
- implicitly or explicitly set.
-</p>
-<p>
- Tests which explicitly state their timeout category as distinct from their
- size will receive the same value as if that timeout had been implicitly set by
- the size tag. So a test of size 'small' which declares a 'long' timeout will
- have the same effective timeout that a 'large' tests has with no explicit
- timeout.
-</p>
-
-<h4 id='flag--test_arg'><code class='flag'>--test_arg=<var>arg</var></code></h4>
-<p>
- Passes command-line options/flags/arguments to each test process. This
- option can be used multiple times to pass several arguments, e.g.
- <code class='flag'>--test_arg=--logtostderr --test_arg=--v=3</code>.
-</p>
-
-<h4 id='flag--test_env'><code class='flag'>--test_env=<var>variable</var>=<i>value</i></code>
- OR
- <code class='flag'>--test_env=<var>variable</var></code></h4>
-<p>
- Specifies additional variables that must be injected into the test
- environment for each test. If <var>value</var> is not specified it will be
- inherited from the shell environment used to start the <code>bazel test</code>
- command.
-</p>
-<p>
- The environment can be accessed from within a test by using
- <code>System.getenv("var")</code> (Java),
- <code>getenv("var")</code> (C or C++),
-
-</p>
-
-<h4 id="flag--run_under"><code class='flag'>--run_under=<var>command-prefix</var></code></h4>
-<p>
- This specifies a prefix that the test runner will insert in front
- of the test command before running it. The
- <var>command-prefix</var> is split into words using Bourne shell
- tokenization rules, and then the list of words is prepended to the
- command that will be executed.
-</p>
-<p>
- If the first word is a fully-qualified label (i.e. starts with
- <code>//</code>) it is built. Then the label is substituted by the
- corresponding executable location that is prepended to the command
- that will be executed along with the other words.
-</p>
-
-<p>
-Some caveats apply:
-</p>
-<ul>
- <li>
- The PATH used for running tests may be different than the PATH in your environment,
- so you may need to use an <b>absolute path</b> for the <code class='flag'>--run_under</code>
- command (the first word in <var>command-prefix</var>).
- </li>
- <li>
- <b><code>stdin</code> is not connected</b>, so <code class='flag'>--run_under</code>
- can't be used for interactive commands.
- </li>
-
-</ul>
-<p>
-Examples:
-</p>
-<pre>
- --run_under=/usr/bin/strace
- --run_under='/usr/bin/strace -c'
- --run_under=/usr/bin/valgrind
- --run_under='/usr/bin/valgrind --quiet --num-callers=20'
-</pre>
-
-<h4>Test selection</h4>
-<p>
- As documented under <a href='#output-selection-options'>Output selection options</a>,
- you can filter tests by <a href='#flag--test_size_filters'>size</a>,
- <a href='#flag--test_timeout_filters'>timeout</a>,
- <a href='#flag--test_tag_filters'>tag</a>, or
- <a href='#flag--test_lang_filters'>language</a>. A convenience
- <a href='#flag--test_filter'>general name filter</a> can forward particular
- filter args to the test runner.
-</p>
-
-<h4 id="other_options_for_bazel_test">Other options for <code>bazel test</code></h4>
-<p>
- The syntax and the remaining options are exactly like
- <a href='guide.html#build'>bazel build</a>.
-</p>
-
-
-<h3 id='clean'>Cleaning build outputs</h3>
-
-<h4>The <code>clean</code> command</h4>
-
-<p>
- Bazel has a <code>clean</code> command, analogous to that of Make.
- It deletes the output directories for all build configurations performed
- by this Bazel instance, or the entire working tree created by this
- Bazel instance, and resets internal caches. If executed without any
- command-line options, then the output directory for all configurations
- will be cleaned.
-</p>
-
-<p>Recall that each Bazel instance is associated with a single workspace, thus the
- <code>clean</code> command will delete all outputs from all builds you've done
- with that Bazel instance in that workspace.
-</p>
-<p>
- To completely remove the entire working tree created by a Bazel
- instance, you can specify the <code class='flag'>--expunge</code> option. When
- executed with <code class='flag'>--expunge</code>, the clean command simply
- removes the entire output base tree which, in addition to the build
- output, contains all temp files created by Bazel. It also
- stops the Bazel server after the clean, equivalent to the <a
- href='#shutdown'><code>shutdown</code></a> command. For example, to
- clean up all disk and memory traces of a Bazel instance, you could
- specify:
-</p>
-<pre>
- % bazel clean --expunge
-</pre>
-<p>
- Alternatively, you can expunge in the background by using
- <code class='flag'>--expunge_async</code>. It is safe to invoke a Bazel command
- in the same client while the asynchronous expunge continues to run.
- Note, however, that this may introduce IO contention.
-</p>
-
-<p>
- The <code>clean</code> command is provided primarily as a means of
- reclaiming disk space for workspaces that are no longer needed.
- Bazel's incremental rebuilds may not be
- perfect so <code>clean</code> can be used to recover a consistent
- state when problems arise.
-</p>
-<p>
- Bazel's design is such that these problems are fixable and
- these bugs are a high priority to be fixed. If you
- ever find an incorrect incremental build, file a bug report, and report bugs in the tools
- rather than using <code>clean</code>.
-</p>
-
-<h2 id='run'>Running executables</h2>
-<p>
- The <code>bazel run</code> command is similar to <code>bazel build</code>, except
- it is used to build <em>and run</em> a single target. Here is a typical session:
-</p>
-<pre>
- % bazel run java/myapp:myapp -- --arg1 --arg2
- Welcome to Bazel
- INFO: Loading package: java/myapp
- INFO: Loading package: foo/bar
- INFO: Loading complete. Analyzing...
- INFO: Found 1 target...
- ...
- Target //java/myapp:myapp up-to-date:
- bazel-bin/java/myapp:myapp
- INFO: Elapsed time: 0.638s, Critical Path: 0.34s
-
- INFO: Running command line: bazel-bin/java/myapp:myapp --arg1 --arg2
- Hello there
- $EXEC_ROOT/java/myapp/myapp
- --arg1
- --arg2
-</pre>
-
-<p>
- Note the use of the <code>--</code>. This is needed so that Bazel
- does not interpret <code>--arg1</code> and <code>--arg2</code> as
- Bazel options, but rather as part of the command line for running the binary.
- (The program being run simply says hello and prints out its args.)
-</p>
-
-<p><code>bazel run</code> is similar, but not identical, to directly invoking
-the binary built by Bazel and its behavior is different depending on whether the
-binary to be invoked is a test or not.
-
-When the binary is not a test, the current working directory will be the
-runfiles tree of the binary.
-
-When the binary is a test, the current working directory will be the exec root
-and a good-faith attempt is made to replicate the environment tests are usually
-run in. The emulation is not perfect, though, and tests that have multiple
-shards cannot be run this way (the
-<code>--test_sharding_strategy=disabled</code> command line option can be used
-to work around this)
-
-The following extra environment variables are also available to the binary:
-<ul>
- <li>
- <code>BUILD_WORKSPACE_DIRECTORY</code>: the root of the workspace where the
- build was run.
- </li>
- <li>
- <code>BUILD_WORKING_DIRECTORY</code>: the current working directory where
- Bazel was run from.
- </li>
-</ul>
-
-These can be used, for example, to interpret file names on the command line in
-a user-friendly way.
-
-<h3>Options for <code>bazel run</code></h3>
-
-<h4 id='flag--run_under_run'><code class='flag'>--run_under=<var>command-prefix</var></code></h4>
-<p>
- This has the same effect as the <code class='flag'>--run_under</code> option for
- <code>bazel test</code> (<a href='#flag--run_under'>see above</a>),
- except that it applies to the command being run by <code>bazel
- run</code> rather than to the tests being run by <code>bazel test</code>.
-</p>
-
-<h4>Filtering logging outputs from Bazel</h4>
-
-<p>
- When invoking a binary with <code>bazel run</code>, Bazel prints logging output from Bazel itself
- and the binary under invocation. To make the logs less noisy, you can suppress the outputs from
- Bazel itself with the <code>--ui_event_filters</code> and <code>--noshow_progress</code> flags.
- For example:
-
- <pre>
- bazel run --ui_event_filters=-info,-stdout,-stderr --noshow_progress //java/myapp:myapp
- </pre>
-</p>
-
-<h3>Executing tests</h3>
-
-<p>
- <code>bazel run</code> can also execute test binaries, which has the effect of
- running the test in a close approximation of the environment described at
- <a href='test-encyclopedia.html'>Writing Tests</a>. Note that none of the
- <code>--test_*</code> arguments have an effect when running a test in this manner except
- <code>--test_arg</code> .
-</p>
-
-<h2 id='query'>Querying the dependency graph</h2>
-
-<p>
- Bazel includes a query language for asking questions about the
- dependency graph used during the build. The query language is used
- by two commands: query and cquery. The major difference between the
- two commands is that query runs after the <a href='guide.html#loading-phase'>loading phase</a>
- and cquery runs after the <a href='guide.html#analysis-phase'>analysis phase</a>. These tools are an
- invaluable aid to many software engineering tasks.
-</p>
-<p>
- The query language is based on the idea of
- algebraic operations over graphs; it is documented in detail in
-
- <a href="query.html">Bazel Query Reference</a>.
- Please refer to that document for reference, for
- examples, and for query-specific command-line options.
-</p>
-
-<p>
- The query tool accepts several command-line
- option. <code class='flag'>--output</code> selects the output format.
- <code class='flag'>--[no]keep_going</code> (disabled by default) causes the query
- tool to continue to make progress upon errors; this behavior may be
- disabled if an incomplete result is not acceptable in case of errors.
-</p>
-<p>
- The <code class='flag'>--[no]tool_deps</code> option,
- enabled by default, causes dependencies in non-target configurations to be included in the
- dependency graph over which the query operates.
-
-</p>
-<p>
- The <code class='flag'>--[no]implicit_deps</code> option, enabled by default, causes
- implicit dependencies to be included in the dependency graph over which the query operates. An
- implicit dependency is one that is not explicitly specified in the BUILD file
- but added by bazel.
-</p>
-<p>
- Example: "Show the locations of the definitions (in BUILD files) of
- all genrules required to build all the tests in the PEBL tree."
-</p>
-<pre>
- bazel query --output location 'kind(genrule, deps(kind(".*_test rule", foo/bar/pebl/...)))'
-</pre>
-
-<h2 id='aquery'>Querying the action graph</h2>
-
-<b>Caution</b>: The aquery command is still experimental and its API will change.
-
-<p>
- The <code>aquery</code> command allows you to query for actions in your build graph.
- It operates on the post-analysis configured target graph and exposes
- information about actions, artifacts and their relationships.
-</p>
-
-<p>
- The tool accepts several command-line options.
- <code class='flag'>--output</code> selects the output format. The default output format
- (<code>text</code>) is human-readable, use <code>proto</code> or <code>textproto</code> for
- machine-readable format.
- Notably, the aquery command runs on top of a regular Bazel build and inherits
- the set of options available during a build.
-</p>
-
-<p>
- It supports the same set of functions that is also available to traditional
- <code>query</code> but <code>siblings</code>, <code>buildfiles</code> and
- <code>tests</code>.
-</p>
-
-<p>
- More details on aquery can be found <a href="aquery.html">here</a>.
-</p>
-
-<h2 id='misc'>Miscellaneous commands and options</h2>
-
-<h3 id='help'><code>help</code></h3>
-
-<p>
- The <code>help</code> command provides on-line help. By default, it
- shows a summary of available commands and help topics, as shown in
- the <a href='guide.html#overview'><i>Bazel overview</i></a> section above.
- Specifying an argument displays detailed help for a particular
- topic. Most topics are Bazel commands, e.g. <code>build</code>
- or <code>query</code>, but there are some additional help topics
- that do not correspond to commands.
-</p>
-
-<h4 id='flag--long'><code class='flag'>--[no]long</code> (<code>-l</code>)</h4>
-<p>
- By default, <code>bazel help [<var>topic</var>]</code> prints only a
- summary of the relevant options for a topic. If
- the <code class='flag'>--long</code> option is specified, the type, default value
- and full description of each option is also printed.
-</p>
-
-<h3 id='shutdown'><code>shutdown</code></h3>
-
-<p>
- Bazel server processes (see <a href='guide.html#client/server'>Client/server
- implementation</a>) may be stopped by using the <code>shutdown</code>
- command. This command causes the Bazel server to exit as soon as it
- becomes idle (i.e. after the completion of any builds or other
- commands that are currently in progress).
-
- Bazel servers stop themselves after an idle timeout, so this command
- is rarely necessary; however, it can be useful in scripts when it is
- known that no further builds will occur in a given workspace.
-</p>
-<p>
- <code>shutdown</code> accepts one
- option, <code class='flag'>--iff_heap_size_greater_than <i>n</i></code>, which
- requires an integer argument (in MB). If specified, this makes the shutdown
- conditional on the amount of memory already consumed. This is
- useful for scripts that initiate a lot of builds, as any memory
- leaks in the Bazel server could cause it to crash spuriously on
- occasion; performing a conditional restart preempts this condition.
-</p>
-
-<h3 id='info'><code>info</code></h3>
-
-<p>
- The <code>info</code> command prints various values associated with
- the Bazel server instance, or with a specific build configuration.
- (These may be used by scripts that drive a build.)
-</p>
-
-<p>
- The <code>info</code> command also permits a single (optional)
- argument, which is the name of one of the keys in the list below.
- In this case, <code>bazel info <var>key</var></code> will print only
- the value for that one key. (This is especially convenient when
- scripting Bazel, as it avoids the need to pipe the result
- through <code>sed -ne /key:/s/key://p</code>:
-</p>
-
-<h4>Configuration-independent data</h4>
-<ul>
- <li><code>release</code>: the release label for this Bazel
- instance, or "development version" if this is not a released
- binary.
- </li>
- <li><code>workspace</code> the absolute path to the base workspace
- directory.
- </li>
- <li><code>install_base</code>: the absolute path to the installation
- directory used by this Bazel instance for the current user. Bazel
- installs its internally required executables below this directory.
-
- </li>
- <li><code>output_base</code>: the absolute path to the base output
- directory used by this Bazel instance for the current user and
- workspace combination. Bazel puts all of its scratch and build
- output below this directory.
- </li>
- <li><code>execution_root</code>: the absolute path to the execution
- root directory under output_base. This directory is the root for all files
- accessible to commands executed during the build, and is the working
- directory for those commands. If the workspace directory is writable, a
- symlink named
-
- <code>bazel-<workspace></code>
- is placed there pointing to this directory.
- </li>
- <li><code>output_path</code>: the absolute path to the output
- directory beneath the execution root used for all files actually
- generated as a result of build commands. If the workspace directory is
- writable, a symlink named <code>bazel-out</code> is placed there pointing
- to this directory.
- </li>
- <li><code>server_pid</code>: the process ID of the Bazel server
- process.
- </li>
- <li><code>server_log</code>: the absolute path to the Bazel server's debug log file.
- This file contains debugging information for all commands over the lifetime of the
- Bazel server, and is intended for human consumption by Bazel developers and power users.
- </li>
- <li><code>command_log</code>: the absolute path to the command log file;
- this contains the interleaved stdout and stderr streams of the most recent
- Bazel command. Note that running <code>bazel info</code> will overwrite the
- contents of this file, since it then becomes the most recent Bazel command.
- However, the location of the command log file will not change unless you
- change the setting of the <code class='flag'>--output_base</code> or
- <code class='flag'>--output_user_root</code> options.
- </li>
-
- <li><code>used-heap-size</code>,
- <code>committed-heap-size</code>,
- <code>max-heap-size</code>: reports various JVM heap size
- parameters. Respectively: memory currently used, memory currently
- guaranteed to be available to the JVM from the system, maximum
- possible allocation.
- </li>
- <li><code>gc-count</code>, <code>gc-time</code>: The cumulative count of
- garbage collections since the start of this Bazel server and the time spent
- to perform them. Note that these values are not reset at the start of every
- build.
- </li>
- <li><code>package_path</code>: A colon-separated list of paths which would be
- searched for packages by bazel. Has the same format as the
- <code class='flag'>--package_path</code> build command line argument.
- </li>
-</ul>
-<p>
- Example: the process ID of the Bazel server.
-</p>
-<pre>% bazel info server_pid
-1285
-</pre>
-
-<h4>Configuration-specific data</h4>
-<p>
- These data may be affected by the configuration options passed
- to <code>bazel info</code>, for
- example <code class='flag'>--cpu</code>, <code class='flag'>--compilation_mode</code>,
- etc. The <code>info</code> command accepts all
- the <a href='#analysis-options'>options that control dependency
- analysis</a>, since some of these determine the location of the
- output directory of a build, the choice of compiler, etc.
-</p>
-<ul>
- <li>
- <code>bazel-bin</code>, <code>bazel-testlogs</code>,
- <code>bazel-genfiles</code>: reports the absolute path to
- the <code>bazel-*</code> directories in which programs generated by the
- build are located. This is usually, though not always, the same as
- the <code>bazel-*</code> symlinks created in the base workspace directory after a
- successful build. However, if the workspace directory is read-only,
- no <code>bazel-*</code> symlinks can be created. Scripts that use
- the value reported by <code>bazel info</code>, instead of assuming the
- existence of the symlink, will be more robust.
- </li>
- <li>
- The complete
- <a href='be/make-variables.html'
- >"Make" environment</a>. If the <code class='flag'>--show_make_env</code> flag is
- specified, all variables in the current configuration's "Make" environment
- are also displayed (e.g. <code>CC</code>, <code>GLIBC_VERSION</code>, etc).
- These are the variables accessed using the <code>$(CC)</code>
- or <code>varref("CC")</code> syntax inside BUILD files.
- </li>
-</ul>
-
-<p>
- Example: the C++ compiler for the current configuration.
- This is the <code>$(CC)</code> variable in the "Make" environment,
- so the <code class='flag'>--show_make_env</code> flag is needed.
-</p>
-
-<pre>
- % bazel info --show_make_env -c opt COMPILATION_MODE
- opt
-</pre>
-
-<p>
- Example: the <code>bazel-bin</code> output directory for the current
- configuration. This is guaranteed to be correct even in cases where
- the <code>bazel-bin</code> symlink cannot be created for some reason
- (e.g. you are building from a read-only directory).
-</p>
-
-<pre>% bazel info --cpu=piii bazel-bin
-/var/tmp/_bazel_johndoe/fbd0e8a34f61ce5d491e3da69d959fe6/execroot/io_bazel/bazel-out/piii-opt/bin
-% bazel info --cpu=k8 bazel-bin
-/var/tmp/_bazel_johndoe/fbd0e8a34f61ce5d491e3da69d959fe6/execroot/io_bazel/bazel-out/k8-opt/bin
-</pre>
-<h3 id='version'><code>version</code> and <code>--version</code></h3>
-
-<p>
- The version command prints version details about the built Bazel
- binary, including the changelist at which it was built and the date.
- These are particularly useful in determining if you have the latest
- Bazel, or if you are reporting bugs. Some of the interesting values
- are:
-</p>
-<ul>
- <li><code>changelist</code>: the changelist at which this version of
- Bazel was released.
- </li>
- <li><code>label</code>: the release label for this Bazel
- instance, or "development version" if this is not a released
- binary. Very useful when reporting bugs.
- </li>
-</ul>
-
-<p>
- <code>bazel --version</code>, with no other args, will emit the same output as
- <code>bazel version --gnu_format</code>, except without the side-effect of potentially starting
- a Bazel server or unpacking the server archive. <code>bazel --version</code> can be run from
- anywhere - it does not require a workspace directory.
-</p>
-
-<h3 id='mobile-install'><code>mobile-install</code></h3>
-<p>
- The <code>mobile-install</code> command installs apps to mobile devices.
- Currently only Android devices running ART are supported.
-
- See <a href="mobile-install.html">bazel mobile-install</a>
- for more information.
-</p>
-<p>
- Note that this command does not install the same thing that
- <code>bazel build</code> produces: Bazel tweaks the app so that it can be
- built, installed and re-installed quickly. This should, however, be mostly
- transparent to the app.
-</p>
-<p>
- The following options are supported:
-</p>
-<h4 id='flag--incremental'><code class='flag'>--incremental</code></h4>
-<p>
- If set, Bazel tries to install the app incrementally, that is, only those
- parts that have changed since the last build. This cannot update resources
- referenced from <code>AndroidManifest.xml</code>, native code or Java
- resources (i.e. ones referenced by <code>Class.getResource()</code>). If these
- things change, this option must be omitted. Contrary to the spirit of Bazel
- and due to limitations of the Android platform, it is the
- <b>responsibility of the user</b> to know when this command is good enough and
- when a full install is needed.
-
- If you are using a device with Marshmallow or later, consider the
- <a href='#flag--split_apks'><code class='flag'>--split_apks</code></a> flag.
-</p>
-<h4 id='flag--split_apks'><code class='flag'>--split_apks</code></h4>
-<p>
- Whether to use split apks to install and update the application on the device.
- Works only with devices with Marshmallow or later. Note that the
- <a href='#flag--incremental'><code class='flag'>--incremental</code></a> flag
- is not necessary when using <code class='flag'>--split_apks</code>.
-</p>
-<h4 id='flag--start_app'><code class='flag'>--start_app</code></h4>
-<p>
- Starts the app in a clean state after installing. Equivalent to
- <code>--start=COLD</code>.
-</p>
-<h4 id='flag--debug_app'><code class='flag'>--debug_app</code></h4>
-<p>
- Waits for debugger to be attached before starting the app in a clean state after installing.
- Equivalent to <code>--start=DEBUG</code>.
-</p>
-<h4 id='flag--start'><code class='flag'>--start=<i>start_type</i></code></h4>
-<p>
- How the app should be started after installing it. Supported <i>start_type</i>s are:
-</p>
-<ul>
- <li><code>NO</code> Does not start the app. This is the default.</li>
- <li><code>COLD</code> Starts the app from a clean state after install.</li>
- <li><code>WARM</code> Preserves and restores the application state on incremental installs.</li>
- <li><code>DEBUG</code> Waits for the debugger before starting the app in a clean state after
- install.
- </li>
-</ul>
-<p>
- Note that if more than one of <code class='flag'>--start=<i>start_type</i></code>,
- <code class='flag'>--start_app</code> or
- <code class='flag'>--debug_app</code> is set, the last value is used.
-</p>
-<h4 id='flag--adb'><code class='flag'>--adb=<var>path</var></code></h4>
-<p>
- Indicates the <code>adb</code> binary to be used.
-
- The default is to use the adb in the Android SDK specified by
- <a href='#flag--android_sdk'><code class='flag'>--android_sdk</code></a>.
-
-</p>
-<h4 id='flag--adb_arg'><code class='flag'>--adb_arg=<var>serial</var></code></h4>
-<p>
- Extra arguments to <code>adb</code>. These come before the subcommand in the
- command line and are typically used to specify which device to install to.
- For example, to select the Android device or emulator to use:
-</p>
-<pre>% bazel mobile-install --adb_arg=-s --adb_arg=deadbeef
-</pre>
-<p>
- invokes <code>adb</code> as
-</p>
-<pre>
-adb -s deadbeef install ...
-</pre>
-<h4 id='flag--incremental_install_verbosity'><code class='flag'>--incremental_install_verbosity=<var>number</var></code></h4>
-<p>
- The verbosity for incremental install. Set to 1 for debug logging to be
- printed to the console.
-</p>
-
-
-<h3 id='dump'><code>dump</code></h3>
-
-<p>
- The <code>dump</code> command prints to stdout a dump of the
- internal state of the Bazel server. This command is intended
- primarily for use by Bazel developers, so the output of this command
- is not specified, and is subject to change.
-</p>
-
-<p>
- By default, command will just print help message outlining possible
- options to dump specific areas of the Bazel state. In order to dump
- internal state, at least one of the options must be specified.
-</p>
-<p>
- Following options are supported:
-</p>
-<ul>
- <li><code class='flag'>--action_cache</code> dumps action cache content.</li>
- <li><code class='flag'>--packages</code> dumps package cache content.</li>
- <li><code class='flag'>--skyframe</code> dumps state of internal Bazel dependency graph.</li>
- <li><code class='flag'>--rules</code> dumps rule summary for each rule and aspect class,
- including counts and action counts. This includes both native and Starlark rules.
- If memory tracking is enabled, then the rules' memory consumption is also printed.</li>
- <li><code class='flag'>--skylark_memory</code> dumps a
- <a href=https://github.com/google/pprof>pprof</a> compatible .gz file to the specified path.
- You must enable memory tracking for this to work.
- </li>
-</ul>
-
- <h4 id='memory-tracking'>Memory tracking</h4>
- <p>
- Some <code>dump</code> commands require memory tracking. To turn this on, you have to pass
- startup flags to Bazel:
- </p>
- <ul>
- <li><code>--host_jvm_args=-javaagent:$BAZEL/third_party/allocation_instrumenter/java-allocation-instrumenter-3.3.0.jar</code></li>
- <li><code>--host_jvm_args=-DRULE_MEMORY_TRACKER=1</code></li>
- </ul>
- <p>
- The java-agent is checked into Bazel at
- third_party/allocation_instrumenter/java-allocation-instrumenter-3.3.0.jar, so make
- sure you adjust <code>$BAZEL</code> for where you keep your Bazel repository.
-
- Do not forget to keep passing these options to Bazel for every command or the server will
- restart.
- </p>
- <p>Example:</p>
- <pre>
- % bazel --host_jvm_args=-javaagent:$BAZEL/third_party/allocation_instrumenter/java-allocation-instrumenter-3.3.0.jar \
- --host_jvm_args=-DRULE_MEMORY_TRACKER=1 \
- build --nobuild <targets>
-
- # Dump rules
- % bazel --host_jvm_args=-javaagent:$BAZEL/third_party/allocation_instrumenter/java-allocation-instrumenter-3.3.0.jar \
- --host_jvm_args=-DRULE_MEMORY_TRACKER=1 \
- dump --rules
-
- # Dump Starlark heap and analyze it with pprof
- % bazel --host_jvm_args=-javaagent:$BAZEL/third_party/allocation_instrumenter/java-allocation-instrumenter-3.3.0.jar \
- --host_jvm_args=-DRULE_MEMORY_TRACKER=1 \
- dump --skylark_memory=$HOME/prof.gz
- % pprof -flame $HOME/prof.gz
- </pre>
-<h3 id='analyze-profile'><code>analyze-profile</code></h3>
-
-<p>
- The <code>analyze-profile</code> command analyzes data previously gathered
- during the build using <code class='flag'>--profile</code> option. It provides several
- options to either perform analysis of the build execution or export data in
- the specified format.
-
-</p>
-<p>
- The following options are supported:
-</p>
-<ul>
- <li><code id='flag--dump'>--dump</code> displays all gathered data in a
- <a href='guide.html#dump-text-format'>human-readable format</a>. However,
- this it does not support other formats yet.</li>
-</ul>
-
-<p>
- See the section on <a href='guide.html#profiling'>Troubleshooting performance by profiling</a> for
- format details and usage help.
-
-</p>
-
-<h3 id='canonicalize'><code>canonicalize-flags</code></h3>
-
-<p>
- The <a href="https://docs.bazel.build/command-line-reference.html#canonicalize-flags-options">
- <code>canonicalize-flags</code></a> command, which takes a list of options for
- a Bazel command and returns a list of options that has the same effect. The
- new list of options is canonical, i.e., two lists of options with the same
- effect are canonicalized to the same new list.
-</p>
-<p>
- The <code class='flag'>--for_command</code> option can be used to select between different
- commands. At this time, only <code>build</code> and <code>test</code> are
- supported. Options that the given command does not support cause an error.
-</p>
-<p>
- Note that a small number of options cannot be reordered, because Bazel cannot
- ensure that the effect is identical. Also note that this command
- <i>does not</i> expand flags from <code>--config</code>.
-</p>
-<p>
- As an example:
-</p>
-<pre>
- % bazel canonicalize-flags -- --config=any_name --test_tag_filters="-lint"
- --config=any_name
- --test_tag_filters=-lint
-</pre>
-
-<h3 id='startup_options'>Startup options</h3>
-
-<p>
- The options described in this section affect the startup of the Java
- virtual machine used by Bazel server process, and they apply to all
- subsequent commands handled by that server. If there is an already
- running Bazel server and the startup options do not match, it will
- be restarted.
-</p>
-<p>
- All of the options described in this section must be specified using the
- <code class='flag'>--key=value</code> or <code class='flag'>--key value</code>
- syntax. Also, these options must appear <i>before</i> the name of the Bazel
- command. Use <code>startup --key=value</code> to list these in a <code>.bazelrc</code> file.
-</p>
-
-<h4 id='flag--output_base'><code class='flag'>--output_base=<var>dir</var></code></h4>
-<p>
- This option requires a path argument, which must specify a
- writable directory. Bazel will use this location to write all its
- output. The output base is also the key by which the client locates
- the Bazel server. By changing the output base, you change the server
- which will handle the command.
-</p>
-<p>
- By default, the output base is derived from the user's login name,
- and the name of the workspace directory (actually, its MD5 digest),
- so a typical value looks like:
-
- <code>/var/tmp/google/_bazel_johndoe/d41d8cd98f00b204e9800998ecf8427e</code>.
- Note that the client uses the output base to find the Bazel server
- instance, so if you specify a different output base in a Bazel
- command, a different server will be found (or started) to handle the
- request. It's possible to perform two concurrent builds in the same
- workspace directory by varying the output base.
-</p>
-
-<p>For example:</p>
-<pre><code>
- OUTPUT_BASE=/var/tmp/google/_bazel_johndoe/custom_output_base
- % bazel --output_base ${OUTPUT_BASE}1 build //foo & bazel --output_base ${OUTPUT_BASE}2 build //bar
-</code></pre>
-<p>
- In this command, the two Bazel commands run concurrently (because of
- the shell <code>&</code> operator), each using a different Bazel
- server instance (because of the different output bases).
- In contrast, if the default output base was used in both commands,
- then both requests would be sent to the same server, which would
- handle them sequentially: building <code>//foo</code> first, followed
- by an incremental build of <code>//bar</code>.
-</p>
-<p>
- <b>Tip:</b>We recommend you do not use an NFS or similar networked file system for the root
- directory, as the higher access latency will cause noticeably slower builds.
-</p>
-
-<h4 id='flag--output_user_root'><code class='flag'>--output_user_root=<var>dir</var></code></h4>
-<p>
- Points to the root directory where output and install bases are created. The directory
- must either not exist or be owned by the calling user. In the past,
- this was allowed to point to a directory shared among various users
- but it's not allowed any longer. This may be allowed once
- <a href='https://github.com/bazelbuild/bazel/issues/11100'>issue #11100</a> is addressed.
-</p>
-<p>
- If the <code class='flag'>--output_base</code> option is specified, it overrides
- using <code class='flag'>--output_user_root</code> to calculate the output base.
-</p>
-<p>
- The install base location is calculated based on
- <code class='flag'>--output_user_root</code>, plus the MD5 identity of the Bazel embedded
- binaries.
-</p>
-<p>
- You can use the <code class='flag'>--output_user_root</code> option to choose an
- alternate base location for all of Bazel's output (install base and output
- base) if there is a better location in your filesystem layout.</p>
-<p>
- <b>Tip:</b>We recommend you do not use an NFS or similar networked file system for the root
- directory, as the higher access latency will cause noticeably slower builds.
-</p>
-
-<a name="startup_flag--host_javabase"></a>
-<h4 id='startup_flag--server_javabase'><code class='flag'>--server_javabase=<var>dir</var></code></h4>
-<p>
- Specifies the Java virtual machine in which <i>Bazel itself</i> runs. The value must be a path to
- the directory containing a JDK or JRE. It should not be a label.
- This option should appear before any Bazel command, for example:
-</p>
-<pre>
- % bazel --server_javabase=/usr/local/buildtools/java/jdk11 build //foo
-</pre>
-<p>
- This flag does <i>not</i> affect the JVMs used by Bazel subprocesses such as applications, tests,
- tools, and so on. Use build options <a href='#flag--javabase'>--javabase</a> or
- <a href='#flag--host_javabase'>--host_javabase</a> instead.
-</p>
-<p>
- This flag was previously named <code>--host_javabase</code> (sometimes referred to as the
- 'left-hand side' <code>--host_javabase</code>), but was renamed to avoid confusion with the
- build flag <a href='#flag--host_javabase'>--host_javabase</a> (sometimes referred to as the
- 'right-hand side' <code>--host_javabase</code>).
-</p>
-
-<h4 id='flag--host_jvm_args'><code class='flag'>--host_jvm_args=<var>string</var></code></h4>
-<p>
- Specifies a startup option to be passed to the Java virtual machine in which <i>Bazel itself</i>
- runs. This can be used to set the stack size, for example:
-</p>
-<pre>
- % bazel --host_jvm_args="-Xss256K" build //foo
-</pre>
-<p>
- This option can be used multiple times with individual arguments. Note that
- setting this flag should rarely be needed. You can also pass a space-separated list of strings,
- each of which will be interpreted as a separate JVM argument, but this feature will soon be
- deprecated.
-
-</p>
-<p>
- That this does <i>not</i> affect any JVMs used by
- subprocesses of Bazel: applications, tests, tools, and so on. To pass
- JVM options to executable Java programs, whether run by <code>bazel
- run</code> or on the command-line, you should use
- the <code>--jvm_flags</code> argument which
- all <code>java_binary</code> and <code>java_test</code> programs
- support. Alternatively for tests, use <code>bazel
- test --test_arg=--jvm_flags=foo ...</code>.
-</p>
-
-<h4 id='flag--host_jvm_debug'><code class='flag'>--host_jvm_debug</code></h4>
-<p>
- This option causes the Java virtual machine to wait for a connection
- from a JDWP-compliant debugger before
- calling the main method of <i>Bazel itself</i>. This is primarily
- intended for use by Bazel developers.
-</p>
-<p>
- (Please note that this does <i>not</i> affect any JVMs used by
- subprocesses of Bazel: applications, tests, tools, etc.)
-</p>
-
-<h4 id='flag--autodetect_server_javabase'><code class='flag'>--autodetect_server_javabase</code></h4>
-<p>
- This option causes Bazel to automatically search for an installed JDK on startup,
- and to fall back to the installed JRE if the embedded JRE isn't available.
- <code>--explicit_server_javabase</code> can be used to pick an explicit JRE to
- run bazel with.
-</p>
-
-<h4 id='flag--batch'><code class='flag'>--batch</code></h4>
-
-<p>
- Batch mode causes Bazel to not use the standard client/server mode described
- <a href='guide.html#client/server'>above</a>, instead running a bazel java process for a
- single command, which has been used for more predictable semantics with respect
- to signal handling, job control, and environment variable inheritance, and is
- necessary for running bazel in a chroot jail.
-</p>
-
-<p>
- Batch mode retains proper queueing semantics within the same output_base.
- That is, simultaneous invocations will be processed in order, without overlap.
- If a batch mode Bazel is run on a client with a running server, it first
- kills the server before processing the command.
-</p>
-
-<p>
- Bazel will run slower in batch mode, or with the alternatives described above.
- This is because, among other things, the build file cache is memory-resident, so it is not
- preserved between sequential batch invocations.
- Therefore, using batch mode often makes more sense in cases where performance
- is less critical, such as continuous builds.
-</p>
-
-<p>
- <i>WARNING:</i> <code class='flag'>--batch</code> is sufficiently slower than standard
- client/server mode. Additionally it might not support all of the features and optimizations which
- are made possible by a persistent Bazel server. If you're using <code class='flag'>--batch</code>
- for the purpose of build isolation, you should use the command option
- <code class='flag'>--nokeep_state_after_build</code>, which guarantees that no incremental
- in-memory state is kept between builds. In order to restart the Bazel server and JVM after a
- build, please explicitly do so using the "shutdown" command.
-</p>
-
-
-<h4 id='flag--max_idle_secs'><code class='flag'>--max_idle_secs=<var>n</var></code></h4>
-<p>
- This option specifies how long, in seconds, the Bazel server process
- should wait after the last client request, before it exits. The
- default value is 10800 (3 hours). <code class='flag'>--max_idle_secs=0</code> will cause the
- Bazel server process to persist indefinitely. <i>NOTE:</i> this flag is only read if Bazel needs
- to start a new server. Changing this option will not cause the server to restart.
-</p>
-<p>
- This option may be used by scripts that invoke Bazel to ensure that
- they do not leave Bazel server processes on a user's machine when they
- would not be running otherwise.
- For example, a presubmit script might wish to
- invoke <code>bazel query</code> to ensure that a user's pending
- change does not introduce unwanted dependencies. However, if the
- user has not done a recent build in that workspace, it would be
- undesirable for the presubmit script to start a Bazel server just
- for it to remain idle for the rest of the day.
- By specifying a small value of <code class='flag'>--max_idle_secs</code> in the
- query request, the script can ensure that <i>if</i> it caused a new
- server to start, that server will exit promptly, but if instead
- there was already a server running, that server will continue to run
- until it has been idle for the usual time. Of course, the existing
- server's idle timer will be reset.
-</p>
-<h4 id='flag--shutdown_on_low_sys_mem'><code class='flag'>--[no]shutdown_on_low_sys_mem</code></h4>
-<p>
- If enabled and <code class='flag'>--max_idle_secs</code> is set to a positive duration,
- after the build server has been idle for a while, shut down the server when the system is
- low on memory. Linux only.
-</p>
-<p>
- In addition to running an idle check corresponding to max_idle_secs, the build server will
- starts monitoring available system memory after the server has been idle for some time.
- If the available system memory becomes critically low, the server will exit.
-</p>
-
-<h4 id='flag--block_for_lock'><code class='flag'>--[no]block_for_lock</code></h4>
-<p>
- If enabled, Bazel will wait for other Bazel commands holding the
- server lock to complete before progressing. If disabled, Bazel will
- exit in error if it cannot immediately acquire the lock and
- proceed.
-
- Developers might use this in presubmit checks to avoid long waits caused
- by another Bazel command in the same client.
-</p>
-
-<h4 id='flag--io_nice_level'><code class='flag'>--io_nice_level=<var>n</var></code></h4>
-<p>
- Sets a level from 0-7 for best-effort IO scheduling. 0 is highest priority,
- 7 is lowest. The anticipatory scheduler may only honor up to priority 4.
- Negative values are ignored.
-</p>
-
-<h4 id='flag--batch_cpu_scheduling'><code class='flag'>--batch_cpu_scheduling</code></h4>
-<p>
- Use <code>batch</code> CPU scheduling for Bazel. This policy is useful for
- workloads that are non-interactive, but do not want to lower their nice value.
- See 'man 2 sched_setscheduler'. This policy may provide for better system
- interactivity at the expense of Bazel throughput.
-</p>
-
-<h3 id='misc_options'>Miscellaneous options</h3>
-
-<h4 id='flag--announce_rc'><code class='flag'>--[no]announce_rc</code></h4>
-<p>
- Controls whether Bazel announces command options read from the bazelrc file when
- starting up. (Startup options are unconditionally announced.)
-</p>
-
-<h4 id='flag--color'><code class='flag'>--color (yes|no|auto)</code></h4>
-<p>
- This option determines whether Bazel will use colors to highlight
- its output on the screen.
-</p>
-<p>
- If this option is set to <code>yes</code>, color output is enabled.
- If this option is set to <code>auto</code>, Bazel will use color output only if
- the output is being sent to a terminal and the TERM environment variable
- is set to a value other than <code>dumb</code>, <code>emacs</code>, or <code>xterm-mono</code>.
- If this option is set to <code>no</code>, color output is disabled,
- regardless of whether the output is going to a terminal and regardless
- of the setting of the TERM environment variable.
-</p>
-
-<h4 id='flag--config'><code class='flag'>--config=<var>name</var></code></h4>
-<p>
- Selects additional config section from
- <a href="guide#where-are-the-bazelrc-files">the rc files</a>; for the current <code>command</code>,
- it also pulls in the options from <code>command:name</code> if such a section exists. Can be
- specified multiple times to add flags from several config sections. Expansions can refer to other
- definitions (i.e. expansions can be chained).
-</p>
-
-<h4 id='flag--curses'><code class='flag'>--curses (yes|no|auto)</code></h4>
-<p>
- This option determines whether Bazel will use cursor controls
- in its screen output. This results in less scrolling data, and a more
- compact, easy-to-read stream of output from Bazel. This works well with
- <code class='flag'>--color</code>.
-</p>
-<p>
- If this option is set to <code>yes</code>, use of cursor controls is enabled.
- If this option is set to <code>no</code>, use of cursor controls is disabled.
- If this option is set to <code>auto</code>, use of cursor controls will be
- enabled under the same conditions as for <code class='flag'>--color=auto</code>.
-</p>
-
-<h4 id='flag--show_timestamps'><code class='flag'>--[no]show_timestamps</code></h4>
-<p>
- If specified, a timestamp is added to each message generated by
- Bazel specifying the time at which the message was displayed.
-</p>
diff --git a/site/docs/visibility.md b/site/docs/visibility.md
deleted file mode 100644
index 1c88f04..0000000
--- a/site/docs/visibility.md
+++ /dev/null
@@ -1,222 +0,0 @@
----
-layout: documentation
-title: Visibility
-category: getting-started
----
-
-<div style="background-color: #EFCBCB; color: #AE2B2B; border: 1px solid #AE2B2B; border-radius: 5px; border-left: 10px solid #AE2B2B; padding: 0.5em;">
-<b>IMPORTANT:</b> The Bazel docs have moved! Please update your bookmark to <a href="https://bazel.build/concepts/visibility" style="color: #0000EE;">https://bazel.build/concepts/visibility</a>
-<p/>
-You can <a href="https://blog.bazel.build/2022/02/17/Launching-new-Bazel-site.html" style="color: #0000EE;">read about</a> the migration, and let us <a href="https://forms.gle/onkAkr2ZwBmcbWXj7" style="color: #0000EE;">know what you think</a>.
-</div>
-
-# Visibility
-
-
-This page covers visibility specifications, best practices, and examples.
-
-Visibility controls whether a target can be used (depended on) by targets in
-other packages. This helps other people distinguish between your library's
-public API and its implementation details, and is an important tool to help
-enforce structure as your workspace grows.
-
-If you need to disable the visibility check (for example when experimenting),
-use `--check_visibility=false`.
-
-
-For more details on package and subpackages, see
-<a href="build-ref.html">Concepts and terminology</a>.
-
-## Visibility specifications
-
-All rule targets have a `visibility` attribute that takes a list of labels. One
-target is visible to another if they are in the same package, or if they are
-granted visibility by one of the labels.
-
-Each label has one of the following forms:
-
-* `"//visibility:public"`: Anyone can use this target. (May not be combined
- with any other specification.)
-
-* `"//visibility:private"`: Only targets in this package can use this
- target. (May not be combined with any other specification.)
-
-* `"//foo/bar:__pkg__"`: Grants access to targets defined in `//foo/bar` (but
- not its subpackages). Here, `__pkg__` is a special piece of syntax
- representing all of the targets in a package.
-
-* `"//foo/bar:__subpackages__"`: Grants access to targets defined in
- `//foo/bar`, or any of its direct or indirect subpackages. Again,
- `__subpackages__` is special syntax.
-
-* `"//foo/bar:my_package_group"`: Grants access to all of the packages named
- by the given [package group](be/functions.html#package_group).
-
- * Package groups do not support the special `__pkg__` and
- `__subpackages__` syntax. Within a package group, `"//foo/bar"` is
- equivalent to `"//foo/bar:__pkg__"` and `"//foo/bar/..."` is equivalent
- to `"//foo/bar:__subpackages__"`.
-
-For example, if `//some/package:mytarget` has its `visibility` set to
-`[":__subpackages__", "//tests:__pkg__"]`, then it could be used by any target
-that is part of the `//some/package/...` source tree, as well as targets defined
-in `//tests/BUILD`, but not by targets defined in `//tests/integration/BUILD`.
-
-As a special case, `package_group` targets themselves do not have a `visibility`
-attribute; they are always publicly visible.
-
-Visibility cannot be set to specific non-package_group targets. That triggers a "Label does not refer to a package group" or "cycle in dependency graph" error.
-
-## Visibility of a rule target
-
-If a rule target does not set the `visibility` attribute, its visibility is
-given by the
-[`default_visibility`](be/functions.html#package.default_visibility) that was
-specified in the [`package`](be/functions.html#package) statement of the
-target's BUILD file. If there is no such `default_visibility` declaration, the
-visibility is `//visibility:private`.
-
-`config_setting` visibility has historically not been enforced.
-`--incompatible_enforce_config_setting_visibility` and
-`--incompatible_config_setting_private_default_visibility` provide migration
-logic for converging with other rules.
-
-If `--incompatible_enforce_config_setting_visibility=false`, every
-`config_setting` is unconditionally visible to all targets.
-
-Else if `--incompatible_config_setting_private_default_visibility=false`, any
-`config_setting` that doesn't explicitly set visibility is `//visibility:public`
-(ignoring package [`default_visibility`](be/functions.html#package.default_visibility)).
-
-Else if `--incompatible_config_setting_private_default_visibility=true`,
-`config_setting` uses the same visibility logic as all other rules.
-
-Best practice is to treat all `config_setting` targets like other rules:
-explicitly set `visibility` on any `config_setting` used anywhere outside its
-package.
-
-### Example
-
-File `//frobber/bin/BUILD`:
-
-```python
-# This target is visible to everyone
-cc_binary(
- name = "executable",
- visibility = ["//visibility:public"],
- deps = [":library"],
-)
-
-# This target is visible only to targets declared in the same package
-cc_library(
- name = "library",
- # No visibility -- defaults to private since no
- # package(default_visibility = ...) was used.
-)
-
-# This target is visible to targets in package //object and //noun
-cc_library(
- name = "subject",
- visibility = [
- "//noun:__pkg__",
- "//object:__pkg__",
- ],
-)
-
-# See package group "//frobber:friends" (below) for who can
-# access this target.
-cc_library(
- name = "thingy",
- visibility = ["//frobber:friends"],
-)
-```
-
-File `//frobber/BUILD`:
-
-```python
-# This is the package group declaration to which target
-# //frobber/bin:thingy refers.
-#
-# Our friends are packages //frobber, //fribber and any
-# subpackage of //fribber.
-package_group(
- name = "friends",
- packages = [
- "//fribber/...",
- "//frobber",
- ],
-)
-```
-
-## Visibility of a file target
-
-By default, file targets are visible only from the same package. To make a file
-accessible from another package, use
-[`exports_files`](be/functions.html#exports_files).
-
-If the call to `exports_files` specifies the visibility attribute, that
-visibility applies. Otherwise, the file is public (the `default_visibility`
-is ignored).
-
-When possible, prefer exposing a library or another type of rule instead of a
-source file. For example, declare a `java_library` instead of exporting a
-`.java` file. It's good form for a rule target to only directly include sources
-in its own package.
-
-### Example
-
-File `//frobber/data/BUILD`:
-
-```python
-exports_files(["readme.txt"])
-```
-
-File `//frobber/bin/BUILD`:
-
-```python
-cc_binary(
- name = "my-program",
- data = ["//frobber/data:readme.txt"],
-)
-```
-
-### Legacy behavior
-
-If the flag [`--incompatible_no_implicit_file_export`](https://github.com/bazelbuild/bazel/issues/10225)
-is not set, a legacy behavior applies instead.
-
-With the legacy behavior, files used by at least one rule target in the package
-are implicitly exported using the `default_visibility` specification. See the
-[design proposal](https://github.com/bazelbuild/proposals/blob/master/designs/2019-10-24-file-visibility.md#example-and-description-of-the-problem)
-for more details.
-
-## Visibility of bzl files
-
-`load` statements are currently not subject to visibility. It is possible to
-load a `bzl` file anywhere in the workspace.
-
-However, users may choose to run the Buildifier linter.
-The [bzl-visibility](https://github.com/bazelbuild/buildtools/blob/master/WARNINGS.md#bzl-visibility) check
-provides a warning if users `load` from beneath a subdirectory named `internal` or `private`.
-
-## Visibility of implicit dependencies
-
-Some rules have implicit dependencies. For example, a C++ rule might implicitly
-depend on a C++ compiler.
-
-Currently, implicit dependencies are treated like normal dependencies. They need
-to be visible by all instances of the rule. This behavior can be changed using
-[`--incompatible_visibility_private_attributes_at_definition`](https://github.com/bazelbuild/proposals/blob/master/designs/2019-10-15-tool-visibility.md).
-
-## Best practices
-
-* Avoid setting the default visibility to public. It may be convenient for
-prototyping or in small codebases, but it is discouraged in large codebases: try
-to be explicit about which targets are part of the public interface.
-
-* Use `package_group` to share the visibility specifications among multiple
- targets. This is especially useful when targets in many BUILD files should be
- exposed to the same set of packages.
-
-* Use fine-grained visibility specifications when deprecating a target. Restrict
- the visibility to the current users to avoid new dependencies.
diff --git a/site/en/BUILD b/site/en/BUILD
new file mode 100644
index 0000000..47cf127
--- /dev/null
+++ b/site/en/BUILD
@@ -0,0 +1,14 @@
+licenses(["notice"])
+
+exports_files(
+ ["docs/user-manual.md"],
+ visibility = [
+ "//src/test/java/com/google/devtools/build/lib/packages:__pkg__",
+ ],
+)
+
+filegroup(
+ name = "srcs",
+ srcs = glob(["**"]),
+ visibility = ["//:__pkg__"],
+)
diff --git a/src/test/java/com/google/devtools/build/lib/packages/BUILD b/src/test/java/com/google/devtools/build/lib/packages/BUILD
index e417405..4f392fd 100644
--- a/src/test/java/com/google/devtools/build/lib/packages/BUILD
+++ b/src/test/java/com/google/devtools/build/lib/packages/BUILD
@@ -110,9 +110,7 @@
name = "BazelDocumentationTests",
size = "medium",
srcs = ["BazelDocumentationTest.java"],
- data = [
- "//site:docs/user-manual.html",
- ],
+ data = ["//site/en:docs/user-manual.md"],
test_class = "com.google.devtools.build.lib.packages.BazelDocumentationTest",
deps = [
":DocumentationTestUtil",
diff --git a/src/test/java/com/google/devtools/build/lib/packages/BazelDocumentationTest.java b/src/test/java/com/google/devtools/build/lib/packages/BazelDocumentationTest.java
index 05a63d3..c68badc 100644
--- a/src/test/java/com/google/devtools/build/lib/packages/BazelDocumentationTest.java
+++ b/src/test/java/com/google/devtools/build/lib/packages/BazelDocumentationTest.java
@@ -39,7 +39,8 @@
@Test
public void testBazelUserManual() throws Exception {
Runfiles runfiles = Runfiles.create();
- String documentationFilePath = runfiles.rlocation("io_bazel/site/docs/user-manual.html");
+ String documentationFilePath =
+ runfiles.rlocation("io_bazel/site/en/docs/user-manual.md");
final File documentationFile = new File(documentationFilePath);
DocumentationTestUtil.validateUserManual(
Bazel.BAZEL_MODULES,
