diff --git a/about/faq.mdx b/about/faq.mdx
index fa5a4d0c..dd5be8a9 100644
--- a/about/faq.mdx
+++ b/about/faq.mdx
@@ -157,6 +157,10 @@ Bazel returns a non-zero exit code if the build or test invocation fails, and th
Further details on exit codes are in the [User Manual](/docs/user-manual).
+## What future features can we expect in Bazel?
+
+See our [Roadmaps](/about/roadmap).
+
## Can I use Bazel for my INSERT LANGUAGE HERE project?
Bazel is extensible. Anyone can add support for new languages. Many languages are supported: see the [build encyclopedia](/reference/be/overview) for a list of recommendations and [awesomebazel.com](https://awesomebazel.com/) for a more comprehensive list.
diff --git a/about/intro.mdx b/about/intro.mdx
index 242a7993..a531ac2a 100644
--- a/about/intro.mdx
+++ b/about/intro.mdx
@@ -9,7 +9,7 @@ It uses a human-readable, high-level build language. Bazel supports projects in
multiple languages and builds outputs for multiple platforms. Bazel supports
large codebases across multiple repositories, and large numbers of users.
-## Benefits {#benefits}
+## Benefits
Bazel offers the following advantages:
@@ -38,7 +38,7 @@ Bazel offers the following advantages:
supported, and you can extend Bazel to support any other language or
framework.
-## Using Bazel {#using-bazel}
+## Using Bazel
To build or test a project with Bazel, you typically do the following:
@@ -71,7 +71,7 @@ In addition to building, you can also use Bazel to run
[tests](/reference/test-encyclopedia) and [query](/query/guide) the build
to trace dependencies in your code.
-## Bazel build process {#bazel-build-process}
+## Bazel build process
When running a build or a test, Bazel does the following:
@@ -91,7 +91,7 @@ correctness, you can set up Bazel to run builds and tests
[hermetically](/basics/hermeticity) through sandboxing, minimizing skew
and maximizing [reproducibility](/run/build#correct-incremental-rebuilds).
-### Action graph {#action-graph}
+### Action graph
The action graph represents the build artifacts, the relationships between them,
and the build actions that Bazel will perform. Thanks to this graph, Bazel can
@@ -100,7 +100,7 @@ file content as well as changes to actions, such as build or test commands, and
know what build work has previously been done. The graph also enables you to
easily [trace dependencies](/query/guide) in your code.
-## Getting started tutorials {#getting-started-tutorials}
+## Getting started tutorials
To get started with Bazel, see [Getting Started](/start/) or jump
directly to the Bazel tutorials:
diff --git a/about/vision.mdx b/about/vision.mdx
index dafc64b6..da0ed02d 100644
--- a/about/vision.mdx
+++ b/about/vision.mdx
@@ -45,7 +45,7 @@ Bazel's abstraction layer — instructions specific to languages, platforms, and
toolchains implemented in a simple extensibility language — allows it to be
easily applied to any context.
-## Bazel core competencies {#bazel-core-competencies}
+## Bazel core competencies
1. Bazel supports **multi-language, multi-platform** builds and tests. You can
run a single command to build and test your entire source tree, no matter
@@ -62,7 +62,7 @@ easily applied to any context.
possible. Bazel interfaces with de-facto standard tools for a given
language/platform.
-## Serving language communities {#language-communities}
+## Serving language communities
Software engineering evolves in the context of language communities — typically,
self-organizing groups of people who use common tools and practices.
@@ -73,7 +73,7 @@ available that integrate with the workflows and conventions of that community.
Bazel is committed to be extensible and open, and to support good rulesets for
any language.
-### Requirements of a good ruleset {#ruleset-requirements}
+### Requirements of a good ruleset
1. The rules need to support efficient **building and testing** for the
language, including code coverage.
diff --git a/about/why.mdx b/about/why.mdx
index 6ddd3225..6224abf6 100644
--- a/about/why.mdx
+++ b/about/why.mdx
@@ -9,7 +9,7 @@ build tool with [integrated testing](#integrated-testing) that supports multiple
[languages](#multi-language), [repositories](#multi-repository), and
[platforms](#multi-platform) in an industry-leading [ecosystem](#ecosystem).
-## Bazel is fast {#fast}
+## Bazel is fast
Bazel knows exactly what input files each build command needs, avoiding
unnecessary work by re-running only when the set of input files have
@@ -22,7 +22,7 @@ This is supported by multiple caching layers, in memory, on disk and on the
remote build farm, if available. At Google, we routinely achieve cache hit rates
north of 99%.
-## Bazel is correct {#correct}
+## Bazel is correct
Bazel ensures that your binaries are built *only* from your own
source code. Bazel actions run in individual sandboxes and Bazel tracks
@@ -34,7 +34,7 @@ by bit.
Say goodbye to endless `make clean` invocations and to chasing phantom bugs
that were in fact resolved in source code that never got built.
-## Bazel is extensible {#extensible}
+## Bazel is extensible
Harness the full power of Bazel by writing your own rules and macros to
customize Bazel for your specific needs across a wide range of projects.
@@ -44,7 +44,7 @@ in-house programming language that's a subset of Python. Starlark makes
rule-writing accessible to most developers, while also creating rules that can
be used across the ecosystem.
-## Integrated testing {#integrated-testing}
+## Integrated testing
Bazel's [integrated test runner](/docs/user-manual#running-tests)
knows and runs only those tests needing to be re-run, using remote execution
@@ -55,28 +55,28 @@ Bazel [provides facilities](/remote/bep) to upload test results to a central
location, thereby facilitating efficient communication of test outcomes, be it
on CI or by individual developers.
-## Multi-language support {#multi-language}
+## Multi-language support
Bazel supports many common programming languages including C++, Java,
Kotlin, Python, Go, and Rust. You can build multiple binaries (for example,
backend, web UI and mobile app) in the same Bazel invocation without being
constrained to one language's idiomatic build tool.
-## Multi-repository support {#multi-repository}
+## Multi-repository support
Bazel can [gather source code from multiple locations](/external/overview): you
don't need to vendor your dependencies (but you can!), you can instead point
Bazel to the location of your source code or prebuilt artifacts (e.g. a git
repository or Maven Central), and it takes care of the rest.
-## Multi-platform support {#multi-platform}
+## Multi-platform support
Bazel can simultaneously build projects for multiple platforms including Linux,
macOS, Windows, and Android. It also provides powerful
[cross-compilation capabilities](/extending/platforms) to build code for one
platform while running the build on another.
-## Wide ecosystem {#ecosystem}
+## Wide ecosystem
[Industry leaders](/community/users) love Bazel, building a large
community of developers who use and contribute to Bazel. Find a tools, services
diff --git a/advanced/performance/build-performance-metrics.mdx b/advanced/performance/build-performance-metrics.mdx
index 46a77324..8391ea87 100644
--- a/advanced/performance/build-performance-metrics.mdx
+++ b/advanced/performance/build-performance-metrics.mdx
@@ -23,7 +23,7 @@ how you can use these metrics to detect and fix build performance issues.
There are a few main ways to extract metrics from your Bazel builds, namely:
-## Build Event Protocol (BEP) {#build-event-protocol}
+## Build Event Protocol (BEP)
Bazel outputs a variety of protocol buffers
[`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)
@@ -32,7 +32,7 @@ can be aggregated by a backend specified by you. Depending on your use cases,
you might decide to aggregate the metrics in various ways, but here we will go
over some concepts and proto fields that would be useful in general to consider.
-## Bazel’s query / cquery / aquery commands {#bazel-commands-query-cquery-aquery}
+## Bazel’s query / cquery / aquery commands
Bazel provides 3 different query modes ([query](/query/quickstart),
[cquery](/query/cquery) and [aquery](/query/aquery)) that allow users
@@ -41,14 +41,14 @@ respectively. The query language provides a
[suite of functions](/query/language#functions) usable across the different
query modes, that allows you to customize your queries according to your needs.
-## JSON Trace Profiles {#json-trace-profiles}
+## JSON Trace Profiles
For every build-like Bazel invocation, Bazel writes a trace profile in JSON
format. The [JSON trace profile](/advanced/performance/json-trace-profile) can
be very useful to quickly understand what Bazel spent time on during the
invocation.
-## Execution Log {#execution-log}
+## Execution Log
The [execution log](/remote/cache-remote) can help you to troubleshoot and fix
missing remote cache hits due to machine and environment differences or
@@ -60,7 +60,7 @@ make comparisons between local and remote machine performance or to find out
which part of the spawn execution is consistently slower than expected (for
example due to queuing).
-## Execution Graph Log {#execution-graph-log}
+## Execution Graph Log
While the JSON trace profile contains the critical path information, sometimes
you need additional information on the dependency graph of the executed actions.
@@ -76,7 +76,7 @@ by removing a particular node from the execution graph.
The data helps you predict the impact of changes to the build and action graph
before you actually do them.
-## Benchmarking with bazel-bench {#bazel-bench}
+## Benchmarking with bazel-bench
[Bazel bench](https://github.com/bazelbuild/bazel-bench) is a
benchmarking tool for Git projects to benchmark build performance in the
diff --git a/advanced/performance/iteration-speed.mdx b/advanced/performance/iteration-speed.mdx
index 763af9c9..2bbf8398 100644
--- a/advanced/performance/iteration-speed.mdx
+++ b/advanced/performance/iteration-speed.mdx
@@ -7,7 +7,7 @@ title: 'Optimize Iteration Speed'
This page describes how to optimize Bazel's build performance when running Bazel
repeatedly.
-## Bazel's Runtime State {#bazel-runtime-state}
+## Bazel's Runtime State
A Bazel invocation involves several interacting parts.
@@ -32,7 +32,7 @@ A Bazel invocation involves several interacting parts.
* The result of the Bazel invocation is made available in the output tree.
-## Running Bazel Iteratively {#run-iteratively}
+## Running Bazel Iteratively
In a typical developer workflow, it is common to build (or run) a piece of code
repeatedly, often at a very high frequency (e.g. to resolve some compilation
@@ -64,7 +64,7 @@ cache can be kept locally
[remotely](https://bazel.build/remote/caching). The cache can be shared among
Bazel servers, and indeed among developers.
-## Avoid discarding the analysis cache {#avoid-discarding-cache}
+## Avoid discarding the analysis cache
Bazel will print a warning if either the analysis cache was discarded or the
server was restarted. Either of these should be avoided during iterative use:
diff --git a/advanced/performance/json-trace-profile.mdx b/advanced/performance/json-trace-profile.mdx
index 0e936455..80c698c0 100644
--- a/advanced/performance/json-trace-profile.mdx
+++ b/advanced/performance/json-trace-profile.mdx
@@ -76,7 +76,7 @@ $ zcat $(../bazel-6.0.0rc1-linux-x86_64 info output_base)/command.profile.gz | j
[...]
```
-## Profile information {#profile-information}
+## Profile information
The profile contains multiple rows. Usually the bulk of rows represent Bazel
threads and their corresponding events, but some special rows are also included.
@@ -99,7 +99,7 @@ Figure 1 shows a profile created with Bazel v5.3.1 and includes these rows:
* `Garbage Collector`: Displays minor and major Garbage Collection (GC)
pauses.
-## Common performance issues {#common-performance-issues}
+## Common performance issues
When analyzing performance profiles, look for:
@@ -117,7 +117,7 @@ When analyzing performance profiles, look for:
or Bazel itself to introduce more parallelism. This can also happen when
there is an unusual amount of GC.
-## Profile file format {#profile-file-format}
+## 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
diff --git a/advanced/performance/memory.mdx b/advanced/performance/memory.mdx
index 017d9cb3..844e691b 100644
--- a/advanced/performance/memory.mdx
+++ b/advanced/performance/memory.mdx
@@ -6,14 +6,14 @@ title: 'Optimize Memory'
This page describes how to limit and reduce the memory Bazel uses.
-## Running Bazel with Limited RAM {#running-bazel}
+## Running Bazel with Limited RAM
In certain situations, you may want Bazel to use minimal memory. You can set the
maximum heap via the startup flag
[`--host_jvm_args`](/docs/user-manual#host-jvm-args),
like `--host_jvm_args=-Xmx2g`.
-### Trade incremental build speeds for memory {#trade-incremental}
+### Trade incremental build speeds for memory
If your builds are too big, Bazel may throw an `OutOfMemoryError` (OOM) when
it doesn't have enough memory. You can make Bazel use less memory, at the cost
@@ -40,7 +40,7 @@ prevent most re-execution).
incremental builds have to build from scratch (except for the on-disk action
cache). Alone, it does not affect the high-water mark of the current build.
-### Trade build flexibility for memory with Skyfocus (Experimental) {#trade-flexibility}
+### Trade build flexibility for memory with Skyfocus (Experimental)
If you want to make Bazel use less memory *and* retain incremental build speeds,
you can tell Bazel the working set of files that you will be modifying, and
@@ -59,11 +59,11 @@ changes to files outside of the working set will be disallowed, until you issue
`bazel clean` or restart the Bazel server.
If you want to specify an exact set of files or directories, use the
-`--experimental_active_directories` flag, like so:
+`--experimental_working_set` flag, like so:
```sh
bazel build //pkg:target --experimental_enable_skyfocus
---experimental_active_directories=path/to/another/dir,path/to/tests/dir
+--experimental_working_set=path/to/another/dir,path/to/tests/dir
```
You can also pass `--experimental_skyfocus_dump_post_gc_stats` to show the
@@ -72,7 +72,7 @@ memory reduction amount:
Putting it altogether, you should see something like this:
```none
-$ bazel test //pkg:target //tests/... --experimental_enable_skyfocus --experimental_active_directories=dir1,dir2,dir3/subdir --experimental_skyfocus_dump_post_gc_stats
+$ bazel test //pkg:target //tests/... --experimental_enable_skyfocus --experimental_working_set dir1,dir2,dir3/subdir --experimental_skyfocus_dump_post_gc_stats
INFO: --experimental_enable_skyfocus is enabled. Blaze will reclaim memory not needed to build the working set. Run 'blaze dump --skyframe=working_set' to show the working set, after this command.
WARNING: Changes outside of the working set will cause a build error.
INFO: Analyzed 149 targets (4533 packages loaded, 169438 targets configured).
@@ -89,7 +89,7 @@ and incremental builds to handle changes to files under `dir1`, `dir2`, and
`dir3/subdir` will retain their fast speeds, with the tradeoff that Bazel cannot
rebuild changed files outside of these directories.
-## Memory Profiling {#memory-profiling}
+## Memory Profiling
Bazel comes with a built-in memory profiler that can help you check your rule’s
memory use. Read more about this process on the
diff --git a/basics/dependencies.mdx b/basics/dependencies.mdx
index 79d73e45..1d3bf8f1 100644
--- a/basics/dependencies.mdx
+++ b/basics/dependencies.mdx
@@ -67,7 +67,8 @@ targets, we’ve made some strides in mitigating the downside by investing in
tooling to automatically manage `BUILD` files to avoid burdening developers.
Some of these tools, such as `buildifier` and `buildozer`, are available with
-Bazel in the [`buildtools` directory](https://github.com/bazelbuild/buildtools).
+Bazel in the [`buildtools`
+directory](https://github.com/bazelbuild/buildtools).
## Minimizing Module Visibility
@@ -107,7 +108,8 @@ transitive dependencies (Figure 1). Suppose target A depends on target B, which
depends on a common library target C. Should target A be able to use classes
defined in target C?
-[](/images/transitive-dependencies.png)
+[](/images/transitive-dependencies.png)
**Figure 1**. Transitive dependencies
@@ -141,7 +143,9 @@ dependencies and adding them to a `BUILD` files without any developer
intervention. But even without such tools, we’ve found the trade-off to be well
worth it as the codebase scales: explicitly adding a dependency to `BUILD` file
is a one-time cost, but dealing with implicit transitive dependencies can cause
-ongoing problems as long as the build target exists. Bazel [enforces strict transitive dependencies](https://blog.bazel.build/2017/06/28/sjd-unused_deps.html)
+ongoing problems as long as the build target exists. Bazel [enforces strict
+transitive
+dependencies](https://blog.bazel.build/2017/06/28/sjd-unused_deps.html)
on Java code by default.
### External dependencies
@@ -190,7 +194,8 @@ so in theory there’s no reason that different versions of the same external
dependency couldn’t both be declared in the build system under different names.
That way, each target could choose which version of the dependency it wanted to
use. This causes a lot of problems in practice, so Google enforces a strict
-[One-Version Rule](https://opensource.google/docs/thirdparty/oneversion/) for
+[One-Version
+Rule](https://opensource.google/docs/thirdparty/oneversion/) for
all third-party dependencies in our codebase.
The biggest problem with allowing multiple versions is the diamond dependency
@@ -229,7 +234,8 @@ Bazel did not use to automatically download transitive dependencies. It used to
employ a `WORKSPACE` file that required all transitive dependencies to be
listed, which led to a lot of pain when managing external dependencies. Bazel
has since added support for automatic transitive external dependency management
-in the form of the `MODULE.bazel` file. See [external dependency overview](/external/overview) for more details.
+in the form of the `MODULE.bazel` file. See [external dependency
+overview](/external/overview) for more details.
Yet again, the choice here is one between convenience and scalability. Small
projects might prefer not having to worry about managing transitive dependencies
diff --git a/basics/hermeticity.mdx b/basics/hermeticity.mdx
index 8f165a21..dcee3a9e 100644
--- a/basics/hermeticity.mdx
+++ b/basics/hermeticity.mdx
@@ -7,7 +7,7 @@ title: 'Hermeticity'
This page covers hermeticity, the benefits of using hermetic builds, and
strategies for identifying non-hermetic behavior in your builds.
-## Overview {#overview}
+## Overview
When given the same input source code and product configuration, a hermetic
build system always returns the same output by isolating the build from changes
@@ -30,7 +30,7 @@ The two important aspects of hermeticity are:
unique hash code. Hermetic build systems use this hash to identify changes to
the build's input.
-## Benefits {#benefits}
+## Benefits
The major benefits of hermetic builds are:
@@ -45,7 +45,7 @@ The major benefits of hermetic builds are:
* **Reproducibility**: Hermetic builds are good for troubleshooting because you
know the exact conditions that produced the build.
-## Identifying non-hermeticity {#nonhermeticity}
+## Identifying non-hermeticity
If you are preparing to switch to Bazel, migration is easier if you improve
your existing builds' hermeticity in advance. Some common sources of
@@ -61,7 +61,7 @@ non-hermeticity in builds are:
tree, fixing the source tree for target A. Then trying to build target B may
fail.
-## Troubleshooting non-hermetic builds {#troubleshooting-nonhermeticity}
+## Troubleshooting non-hermetic builds
Starting with local execution, issues that affect local cache hits reveal
non-hermetic actions.
@@ -94,7 +94,7 @@ Note: Make your build fully hermetic when mixing remote and local execution,
using Bazel’s “dynamic strategy” functionality. Running Bazel inside the remote
Docker container will enable the build to execute the same in both environments.
-## Hermeticity with Bazel {#hermeticity-bazel}
+## Hermeticity with Bazel
For more information about how other projects have had success using hermetic
builds with Bazel, see these BazelCon talks:
diff --git a/brand/index.mdx b/brand/index.mdx
index 0386d939..2a21cd43 100644
--- a/brand/index.mdx
+++ b/brand/index.mdx
@@ -10,7 +10,7 @@ the Apache-licensed Bazel repositories on GitHub. Any use of the Bazel
Trademarks other than those permitted in these guidelines must be approved in
advance.
-## Purpose of the Brand Guidelines {#purpose-brand}
+## Purpose of the Brand Guidelines
These guidelines exist to ensure that the Bazel project can share its technology
under open source licenses while making sure that the "Bazel" brand is protected
@@ -18,7 +18,7 @@ as a meaningful source identifier in a way that's consistent with trademark law.
By adhering to these guidelines, you help to promote the freedom to use and
develop high-quality Bazel technology.
-## Acceptable Uses {#acceptable-uses}
+## Acceptable Uses
Given the open nature of Bazel, you may use the Bazel trademark to refer to the
project without prior written permission. Examples of these approved references
@@ -38,7 +38,7 @@ Examples:
* \[Your Product\] is compatible with Bazel
* \[XYZ\] Conference for Bazel Users
-## General Guidelines {#general-guidelines}
+## General Guidelines
* The Bazel name may never be used or registered in a manner that would cause
confusion as to Google's sponsorship, affiliation, or endorsement.
@@ -57,7 +57,7 @@ Examples:
materials without prior written permission from
[product@bazel.build](mailto:product@bazel.build).
-## Usage for Events and Community Groups {#usage-events}
+## Usage for Events and Community Groups
The Bazel word mark may be used referentially in events, community groups, or
other gatherings related to the Bazel build system, but it may not be used in a
@@ -79,7 +79,7 @@ Examples of naming conventions that require prior written permission:
* BazelCon
* Bazel Conference
-## Contact Us {#contact-us}
+## Contact Us
Please do not hesitate to contact us at
[product@bazel.build](mailto:product@bazel.build) if you are unsure whether your
diff --git a/build/style-guide.mdx b/build/style-guide.mdx
index 3502de48..cfc3cf86 100644
--- a/build/style-guide.mdx
+++ b/build/style-guide.mdx
@@ -4,7 +4,7 @@ title: 'BUILD Style Guide'
-## Prefer DAMP BUILD files over DRY {#prefer-damp-build-files-over-dry}
+## Prefer DAMP BUILD files over DRY
The DRY principle — "Don't Repeat Yourself" — encourages uniqueness by
introducing abstractions such as variables and functions to avoid redundancy in
@@ -18,7 +18,7 @@ maintain.
code, but do need to be maintained by people and tools. That makes DAMP better
for them than DRY.
-## BUILD.bazel file formatting {#formatting}
+## BUILD.bazel file formatting
`BUILD` file formatting follows the same approach as Go, where a standardized
tool takes care of most formatting issues.
@@ -30,7 +30,7 @@ generate `BUILD` files.
`BUILD` file formatting must match the output of `buildifier`.
-### Formatting example {#formatting-example}
+### Formatting example
```python
# Test code implementing the Foo controller.
@@ -55,7 +55,7 @@ py_test(
)
```
-## File structure {#file-structure}
+## File structure
**Recommendation**: Use the following order (every element is optional):
@@ -79,7 +79,7 @@ changes (for example, to keep or remove a comment when deleting a rule).
cc_library(name = "cc")
```
-## References to targets in the current package {#targets-current-package}
+## 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
@@ -102,7 +102,7 @@ genrule(
)
```
-## Target naming {#target-naming}
+## 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 (for example, a
@@ -146,7 +146,7 @@ recommendations that are broadly used at Google:
* **`java_proto_library`**: `_java_proto`
* **`java_lite_proto_library`**: `_java_proto_lite`
-## Visibility {#visibility}
+## Visibility
Visibility should be scoped as tightly as possible, while still allowing access
by tests and reverse dependencies. Use `__pkg__` and `__subpackages__` as
@@ -158,7 +158,7 @@ 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}
+## Dependencies
Dependencies should be restricted to direct dependencies (dependencies
needed by the sources listed in the rule). Do not list transitive dependencies.
@@ -173,12 +173,12 @@ 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 {#globs}
+## 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 {#recursive}
+### Recursive
Do not use recursive globs to match source files (for example,
`glob(["**/*.java"])`).
@@ -193,11 +193,11 @@ 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}
+### Non-recursive
Non-recursive globs are generally acceptable.
-## Avoid list comprehensions {#list-comprehensions}
+## Avoid list comprehensions
Avoid using list comprehensions at the top level of a `BUILD.bazel` file.
Automate repetitive calls by creating each named target with a separate
@@ -239,7 +239,7 @@ my_java_test(name = "test_fake_10",
...
```
-## Don't use deps variables {#no-dep-vars}
+## Don't use deps variables
Don't use list variables to encapsulate common dependencies:
@@ -289,7 +289,7 @@ Let [Gazelle](https://github.com/bazel-contrib/bazel-gazelle) and other tools
maintain them. There will be repetition, but you won't have to think about how
to manage the dependencies.
-## Prefer literal strings {#literal-strings}
+## Prefer literal strings
Although Starlark provides string operators for concatenation (`+`) and
formatting (`%`), use them with caution. It is tempting to factor out common
@@ -340,7 +340,7 @@ proto_library(
[buildozer]: https://github.com/bazelbuild/buildtools/blob/main/buildozer/README.md
-## Limit the symbols exported by each `.bzl` file {#limit-symbols}
+## Limit the symbols exported by each `.bzl` file
Minimize the number of symbols (rules, macros, constants, functions) exported by
each public `.bzl` (Starlark) file. We recommend that a file should export
@@ -352,7 +352,7 @@ symbols, causing changes to single files to force Bazel to rebuild many targets.
[bzl_library]: https://github.com/bazelbuild/bazel-skylib/blob/main/README.md#bzl_library
-## Other conventions {#other-conventions}
+## Other conventions
* Use uppercase and underscores to declare constants (such as `GLOBAL_CONSTANT`),
use lowercase and underscores to declare variables (such as `my_variable`).
@@ -371,7 +371,7 @@ symbols, causing changes to single files to force Bazel to rebuild many targets.
"deflake this target by rerunning it once". `flaky = True` unambiguously says
"this test is flaky".
-## Differences with Python style guide {#differences-python-style-guide}
+## Differences with Python style guide
Although compatibility with
[Python style guide](https://www.python.org/dev/peps/pep-0008/)
diff --git a/community/recommended-rules.mdx b/community/recommended-rules.mdx
index 7f5eef81..86daa056 100644
--- a/community/recommended-rules.mdx
+++ b/community/recommended-rules.mdx
@@ -11,7 +11,7 @@ This is a set of high quality rules, which will provide a good experience to our
users. We make a distinction between the supported rules, and the hundreds of
rules you can find on the Internet.
-## Nomination {#nomination}
+## Nomination
If a ruleset meets the requirements below, a rule maintainer can nominate it
to be part of the _recommended rules_ by filing a
@@ -20,7 +20,7 @@ to be part of the _recommended rules_ by filing a
After a review by the [Bazel core team](/contribute/policy), it
will be recommended on the Bazel website.
-## Requirements for the rule maintainers {#requirements-rule-maintainers}
+## Requirements for the rule maintainers
* The ruleset provides an important feature, useful to a large number of Bazel
users (for example, support for a widely popular language).
@@ -37,14 +37,14 @@ will be recommended on the Bazel website.
should be fixed within two weeks. Migration issues should be reported to the
Bazel team quickly.
-## Requirements for Bazel developers {#requirements-dev}
+## Requirements for Bazel developers
* Recommended rules are frequently tested with Bazel at head (at least once a
day).
* No change in Bazel may break a recommended rule (with the default set of
flags). If it happens, the change should be fixed or rolled back.
-## Demotion {#demotion}
+## Demotion
If there is a concern that a particular ruleset is no longer meeting the
requirements, a [GitHub issue](https://github.com/bazelbuild/bazel/) should be
diff --git a/community/sig.mdx b/community/sig.mdx
index 3b4d6635..ae5f9189 100644
--- a/community/sig.mdx
+++ b/community/sig.mdx
@@ -5,7 +5,8 @@ title: 'Bazel Special Interest Groups'
Bazel hosts Special Interest Groups (SIGs) to focus collaboration on particular
-areas and to support communication and coordination between [Bazel owners, maintainers, and contributors](/contribute/policy). This policy
+areas and to support communication and coordination between [Bazel owners,
+maintainers, and contributors](/contribute/policy). This policy
applies to [`bazelbuild`](http://github.com/bazelbuild).
SIGs do their work in public. The ideal scope for a SIG covers a well-defined
diff --git a/community/users.mdx b/community/users.mdx
index 227ee4bb..3f027c01 100644
--- a/community/users.mdx
+++ b/community/users.mdx
@@ -11,7 +11,7 @@ contact [product@bazel.build](mailto:product@bazel.build).
This page lists companies and OSS projects that are known to use Bazel.
This does not constitute an endorsement.
-## Companies using Bazel {#companies-using-bazel}
+## Companies using Bazel
### [acqio](https://acqio.com.br)
@@ -320,9 +320,11 @@ safety systems_.
Pigweed is an open-source solution for sustained, robust, and rapid embedded
product development for large teams. Pigweed has shipped in millions of
devices, including Google's suite of Pixel devices, Nest thermostats,
-[satellites](https://www.spinlaunch.com/), and [autonomous aerial drones](https://www.flyzipline.com/).
+[satellites](https://www.spinlaunch.com/), and [autonomous aerial
+drones](https://www.flyzipline.com/).
-Pigweed [uses Bazel as its primary build system](https://pigweed.dev/seed/0111-build-systems.html). The [Bazel for
+Pigweed [uses Bazel as its primary build
+system](https://pigweed.dev/seed/0111-build-systems.html). The [Bazel for
Embedded][pw-bazel-great] blog post discusses why we think it's a great build
system for embedded projects!
@@ -379,10 +381,6 @@ Snap, the developer of Snapchat messaging app, has migrated from Buck to Bazel
in 2020 ([source](https://twitter.com/wew/status/1326957862816509953)). For more
details about their process, see their [engineering blog](https://eng.snap.com/blog/).
-### [Spotify](https://spotify.com)
-
-Spotify is using Bazel to build their iOS and Android Apps ([source](https://twitter.com/BalestraPatrick/status/1573355078995566594)).
-
### [Stripe](https://stripe.com)
@@ -493,7 +491,7 @@ Zenly is a live map of your friends and family. It’s the most fun way to meet
***
-## Open source projects using Bazel {#open-source-projects-using-Bazel}
+## Open source projects using Bazel
### [Abseil](https://abseil.io/)
@@ -723,6 +721,10 @@ networks.
Sorbet is a fast, powerful type checker for a subset of Ruby. It scales to
codebases with millions of lines of code and can be adopted incrementally.
+### [Spotify](https://spotify.com)
+
+Spotify is using Bazel to build their iOS and Android Apps ([source](https://twitter.com/BalestraPatrick/status/1573355078995566594)).
+
### [Tink](https://github.com/google/tink)
Tink is a multi-language, cross-platform, open source library that provides
@@ -750,4 +752,4 @@ architecture.
### [ZhihuDailyPurify](https://github.com/izzyleung/ZhihuDailyPurify)
ZhihuDailyPurify is a light weight version of Zhihu Daily, a Chinese
-question-and-answer webs.
+question-and-answer webs.
\ No newline at end of file
diff --git a/concepts/build-files.mdx b/concepts/build-files.mdx
index b85f472c..66d01f8c 100644
--- a/concepts/build-files.mdx
+++ b/concepts/build-files.mdx
@@ -50,7 +50,7 @@ team. `BUILD` file authors should comment 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.
-## Loading an extension {#load}
+## Loading an extension
Bazel extensions are files ending in `.bzl`. Use the `load` statement to import
a symbol from an extension.
@@ -92,7 +92,7 @@ loaded from another file.
You can use [load visibility](/concepts/visibility#load-visibility) to restrict
who may load a `.bzl` file.
-## Types of build rules {#types-of-build-rules}
+## Types of build rules
The majority of build rules come in families, grouped together by
language. For example, `cc_binary`, `cc_library`
@@ -132,6 +132,23 @@ for anyone to create new rules.
and binaries and tests can depend on libraries, with the expected
separate-compilation behavior.
+
+
## File encoding
`BUILD` and `.bzl` files should be encoded in UTF-8, of which ASCII is a valid
diff --git a/concepts/build-ref.mdx b/concepts/build-ref.mdx
index ee67bcc6..e8839d40 100644
--- a/concepts/build-ref.mdx
+++ b/concepts/build-ref.mdx
@@ -11,7 +11,7 @@ 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.
-### Repositories {#repositories}
+### Repositories
Source files used in a Bazel build are organized in _repositories_ (often
shortened to _repos_). A repo is a directory tree with a boundary marker file at
@@ -19,9 +19,10 @@ its root; such a boundary marker file could be `MODULE.bazel`, `REPO.bazel`, or
in legacy contexts, `WORKSPACE` or `WORKSPACE.bazel`.
The repo in which the current Bazel command is being run is called the _main
-repo_. Other, (external) repos are defined by _repo rules_; see [external dependencies overview](/external/overview) for more information.
+repo_. Other, (external) repos are defined by _repo rules_; see [external
+dependencies overview](/external/overview) for more information.
-## Workspace {#workspace}
+## Workspace
A _workspace_ is the environment shared by all Bazel commands run from the same
main repo. It encompasses the main repo and the set of all defined external
@@ -31,7 +32,7 @@ Note that historically the concepts of "repository" and "workspace" have been
conflated; the term "workspace" has often been used to refer to the main
repository, and sometimes even used as a synonym of "repository".
-## Packages {#packages}
+## Packages
The primary unit of code organization in a repository is the _package_. A
package is a collection of related files and a specification of how they can be
@@ -55,7 +56,7 @@ src/my/app/tests/BUILD
src/my/app/tests/test.cc
```
-## Targets {#targets}
+## Targets
A package is a container of _targets_, which are defined in the package's
`BUILD` file. Most targets are one of two principal kinds, _files_ and _rules_.
@@ -96,4 +97,9 @@ 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
`visibility` attribute of rules or from the `default_visibility` attribute of
the `package` function; they do not generate or consume files. For more
-information, refer to the [`package_group` documentation](/reference/be/functions#package_group).
+information, refer to the [`package_group`
+documentation](/reference/be/functions#package_group).
+
+
+ Labelsarrow_forward
+
diff --git a/concepts/dependencies.mdx b/concepts/dependencies.mdx
index e03c1af7..bdb65f04 100644
--- a/concepts/dependencies.mdx
+++ b/concepts/dependencies.mdx
@@ -18,7 +18,7 @@ of _actual dependencies_ and the graph of _declared dependencies_. 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.
-## Actual and declared dependencies {#actual-and-declared-dependencies}
+## Actual and declared dependencies
A target `X` is _actually dependent_ on target `Y` if `Y` must be present,
built, and up-to-date in order for `X` to be built correctly. _Built_ could
@@ -59,7 +59,7 @@ dependencies don't appear in the `BUILD` file. Because the rule doesn't
directly depend on the provider, there is no way to track changes, as shown in
the following example timeline:
-### 1. Declared dependencies match actual dependencies {#this-is-fine}
+### 1. Declared dependencies match actual dependencies
At first, everything works. The code in package `a` uses code in package `b`.
The code in package `b` uses code in package `c`, and thus `a` transitively
@@ -131,7 +131,7 @@ function foo() {
The declared dependencies overapproximate the actual dependencies. All is well.
-### 2. Adding an undeclared dependency {#undeclared-dependency}
+### 2. Adding an undeclared dependency
A latent hazard is introduced when someone adds code to `a` that creates a
direct _actual_ dependency on `c`, but forgets to declare it in the build file
@@ -177,7 +177,7 @@ 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: `a` has an actual but undeclared dependency on `c`.
-### 3. Divergence between declared and actual dependency graphs {#divergence}
+### 3. Divergence between declared and actual dependency graphs
The hazard is revealed when someone refactors `b` so that it no longer depends on
`c`, inadvertently breaking `a` through no
@@ -241,7 +241,7 @@ dependencies, even when transitively closed; the build is likely to fail.
The problem could have been averted by ensuring that the actual dependency from
`a` to `c` introduced in Step 2 was properly declared in the `BUILD` file.
-## Types of dependencies {#types-of-dependencies}
+## Types of dependencies
Most build rules have three attributes for specifying different kinds of
generic dependencies: `srcs`, `deps` and `data`. These are explained below. For
@@ -252,16 +252,16 @@ Many rules also have additional attributes for rule-specific kinds of
dependencies, for example, `compiler` or `resources`. These are detailed in the
[Build Encyclopedia](/reference/be/).
-### `srcs` dependencies {#srcs-dependencies}
+### `srcs` dependencies
Files consumed directly by the rule or rules that output source files.
-### `deps` dependencies {#deps-dependencies}
+### `deps` dependencies
Rule pointing to separately-compiled modules providing header files,
symbols, libraries, data, etc.
-### `data` dependencies {#data-dependencies}
+### `data` dependencies
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
@@ -298,7 +298,7 @@ you can refer to these files by joining the paths of the test's source
directory and the workspace-relative path, for example,
`${TEST_SRCDIR}/workspace/path/to/data/file`.
-## Using labels to reference directories {#using-labels-reference-directories}
+## Using labels to reference directories
As you look over our `BUILD` files, you might notice that some `data` labels
refer to directories. These labels end with `/.` or `/` like these examples,
@@ -366,3 +366,21 @@ filegroup(
```
You can then reference the label `my_data` as the data dependency in your test.
+
+
+
diff --git a/concepts/labels.mdx b/concepts/labels.mdx
index 3f14e001..b221e34f 100644
--- a/concepts/labels.mdx
+++ b/concepts/labels.mdx
@@ -12,7 +12,8 @@ form looks like:
```
The first part of the label is the repository name, `@@myrepo`. The double-`@`
-syntax signifies that this is a [*canonical* repo name](/external/overview#canonical-repo-name), which is unique within
+syntax signifies that this is a [*canonical* repo
+name](/external/overview#canonical-repo-name), which is unique within
the workspace. Labels with canonical repo names unambiguously identify a target
no matter which context they appear in.
@@ -116,7 +117,7 @@ used from external repositories.
For information about the different ways you can refer to targets, see
[target patterns](/run/build#specifying-build-targets).
-### Lexical specification of a label {#labels-lexical-specification}
+### Lexical specification of a label
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
@@ -125,7 +126,7 @@ construct tools and scripts that manipulate labels, such as the
The precise details of allowed target names are below.
-### Target names — `package-name:target-name` {#target-names}
+### Target names — `package-name:target-name`
`target-name` is the name of the target within the package. The name of a rule
is the value of the `name` attribute in the rule's declaration in a `BUILD`
@@ -156,7 +157,7 @@ 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.
-### Package names — `//package-name:target-name` {#package-names}
+### Package names — `//package-name:target-name`
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.
@@ -187,7 +188,7 @@ On a practical level:
`//:foo`), it's best to leave that package empty so all meaningful packages
have descriptive names.
-## Rules {#rules}
+## Rules
A rule specifies the relationship between inputs and outputs, and the
steps to build the outputs. Rules can be of one of many different
@@ -240,3 +241,20 @@ the build.
This directed acyclic graph over targets is called the _target graph_ or
_build dependency graph_, and is the domain over which the
[Bazel Query tool](/query/guide) operates.
+
+
diff --git a/concepts/platforms.mdx b/concepts/platforms.mdx
index 09cede52..e560ea4d 100644
--- a/concepts/platforms.mdx
+++ b/concepts/platforms.mdx
@@ -20,9 +20,9 @@ See also:
* [Toolchains][Toolchains]
* [Background][Background]
-## Status {#status}
+## Status
-### C++ {#cxx}
+### C++
C++ rules use platforms to select toolchains when
`--incompatible_enable_cc_toolchain_resolution` is set.
@@ -45,7 +45,7 @@ To test your C++ project with platforms, see
[Migrating Your Project](#migrating-your-project) and
[Configuring C++ toolchains].
-### Java {#java}
+### Java
Java rules use platforms to select toolchains.
@@ -54,7 +54,7 @@ This replaces legacy flags `--java_toolchain`, `--host_java_toolchain`,
See [Java and Bazel](/docs/bazel-and-java) for details.
-### Android {#android}
+### Android
Android rules use platforms to select toolchains when
`--incompatible_enable_android_toolchain_resolution` is set.
@@ -73,15 +73,16 @@ This will be enabled by default in Bazel 7.0 ([#16285](https://github.com/bazelb
To test your Android project with platforms, see
[Migrating Your Project](#migrating-your-project).
-### Apple {#apple}
+### Apple
[Apple rules] do not support platforms and are not yet scheduled
for support.
You can still use platform APIs with Apple builds (for example, when building
-with a mixture of Apple rules and pure C++) with [platform mappings](#platform-mappings).
+with a mixture of Apple rules and pure C++) with [platform
+mappings](#platform-mappings).
-### Other languages {#other-languages}
+### Other languages
* [Go rules] fully support platforms
* [Rust rules] fully support platforms.
@@ -89,7 +90,7 @@ with a mixture of Apple rules and pure C++) with [platform mappings](#platform-m
If you own a language rule set, see [Migrating your rule set] for adding
support.
-## Background {#background}
+## Background
*Platforms* and *toolchains* were introduced to standardize how software
projects target different architectures and cross-compile.
@@ -109,7 +110,7 @@ Bazel is intended for large, multi-language, multi-platform projects. This
demands more principled support for these concepts, including a clear
standard API.
-### Need for migration {#migration}
+### Need for migration
Upgrading to the new API requires two efforts: releasing the API and upgrading
rule logic to use it.
@@ -124,7 +125,7 @@ plus fair warning for project owners to test against upcoming changes.
This is why this is an ongoing migration.
-### Goal {#goal}
+### Goal
This migration is complete when all projects build with the form:
@@ -150,7 +151,7 @@ deprecated and removed as soon as it's safe to do so.
Ultimately, this will be the *sole* way to configure architectures.
-## Migrating your project {#migrating-your-project}
+## Migrating your project
If you build with languages that support platforms, your build should already
work with an invocation like:
@@ -184,7 +185,7 @@ For your project to build, you need to check the following:
If you still have problems, [reach out](#questions) for support.
-### Default platforms {#default-platforms}
+### Default platforms
Project owners should define explicit
[platforms][Defining Constraints and Platforms] to describe the architectures
@@ -197,7 +198,7 @@ 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).
-### `select()` {#select}
+### `select()`
Projects can [`select()`][select()] on
[`constraint_value` targets][constraint_value Rule] but not complete
@@ -234,7 +235,7 @@ When migrating your project to platforms, you must either convert them to
`constraint_values` or use [platform mappings](#platform-mappings) to support
both styles during migration.
-### Transitions {#transitions}
+### Transitions
[Starlark transitions][Starlark transitions] change
flags down parts of your build graph. If your project uses a transition that
@@ -243,10 +244,11 @@ sets `--cpu`, `--crossstool_top`, or other legacy flags, rules that read
When migrating your project to platforms, you must either convert changes like
`return { "//command_line_option:cpu": "arm" }` to `return {
-"//command_line_option:platforms": "//:my_arm_platform" }` or use [platform mappings](#platform-mappings) to support both styles during migration.
+"//command_line_option:platforms": "//:my_arm_platform" }` or use [platform
+mappings](#platform-mappings) to support both styles during migration.
window.
-## Migrating your rule set {#migrating-your-rule-set}
+## Migrating your rule set
If you own a rule set and want to support platforms, you need to:
@@ -271,7 +273,7 @@ If you own a rule set and want to support platforms, you need to:
If you need to mix with rules that don't support platforms, you may need
[platform mappings](#platform-mappings) to bridge the gap.
-### Common platform properties {#common-platform-properties}
+### Common platform properties
Common, cross-language platform properties like `OS` and `CPU` should be
declared in [`@platforms`](https://github.com/bazelbuild/platforms).
@@ -285,7 +287,7 @@ If your rules use custom-purpose OSes or CPUs, these should be declared in your
rule's repo vs.
[`@platforms`](https://github.com/bazelbuild/platforms).
-## Platform mappings {#platform-mappings}
+## Platform mappings
*Platform mappings* is a temporary API that lets platform-aware logic mix with
legacy logic in the same build. This is a blunt tool that's only intended to
@@ -325,7 +327,7 @@ workspace root. You can also set
See the [platform mappings design] for details.
-## API review {#api-review}
+## API review
A [`platform`][platform Rule] is a collection of
[`constraint_value` targets][constraint_value Rule]:
@@ -362,8 +364,10 @@ attributes declare a language's tools (like `compiler =
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"]`).
+[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
@@ -375,7 +379,7 @@ command line with [`--extra_toolchains`][extra_toolchains Flag].
For more information see [here][Toolchains].
-## Questions {#questions}
+## Questions
For general support and questions about the migration timeline, contact
[bazel-discuss] or the owners of the appropriate rules.
@@ -383,7 +387,7 @@ For general support and questions about the migration timeline, contact
For discussions on the design and evolution of the platform/toolchain APIs,
contact [bazel-dev].
-## See also {#see-also}
+## See also
* [Configurable Builds - Part 1]
* [Platforms]
diff --git a/concepts/visibility.mdx b/concepts/visibility.mdx
index 45ad798f..fa5cf3aa 100644
--- a/concepts/visibility.mdx
+++ b/concepts/visibility.mdx
@@ -13,7 +13,7 @@ library's public API and its implementation details, and help enforce structure
as your workspace grows. You can also use visibility when deprecating a public
API to allow current users while denying new ones.
-## Target visibility {#target-visibility}
+## Target visibility
**Target visibility** controls who may depend on your target — that is, who may
use your target's label inside an attribute such as `deps`. A target will fail
@@ -39,7 +39,7 @@ The following subsections describe the attribute's format, how to apply it to
various kinds of targets, and the interaction between the visibility system and
symbolic macros.
-### Visibility specifications {#visibility-specifications}
+### Visibility specifications
All rule targets have a `visibility` attribute that takes a list of labels. Each
label has one of the following forms. With the exception of the last form, these
@@ -86,7 +86,7 @@ Note: The `visibility` attribute may not specify non-`package_group` targets.
Doing so triggers a "Label does not refer to a package group" or "Cycle in
dependency graph" error.
-### Rule target visibility {#rule-target-visibility}
+### Rule target visibility
A rule target's visibility is determined by taking its `visibility` attribute
-- or a suitable default if not given -- and appending the location where the
@@ -136,7 +136,7 @@ convenient for prototyping or in small codebases, but the risk of inadvertently
creating public targets increases as the codebase grows. It's better to be
explicit about which targets are part of a package's public interface.
-### Generated file target visibility {#generated-file-target-visibility}
+### Generated file target visibility
A generated file target has the same visibility as the rule target that
generates it.
@@ -167,7 +167,7 @@ some_rule(
)
```
-### Source file target visibility {#source-file-target-visibility}
+### Source file target visibility
Source file targets can either be explicitly declared using
[`exports_files`](/reference/be/functions#exports_files), or implicitly created
@@ -200,7 +200,7 @@ source file. For example, instead of calling `exports_files` on a `.java` file,
wrap the file in a non-private `java_library` target. Generally, rule targets
should only directly reference source files that live in the same package.
-#### Example {#source-file-visibility-example}
+#### Example
File `//frobber/data/BUILD`:
@@ -217,7 +217,7 @@ cc_binary(
)
```
-### Config setting visibility {#config-setting-visibility}
+### Config setting visibility
Historically, Bazel has not enforced visibility for
[`config_setting`](/reference/be/general#config_setting) targets that are
@@ -239,12 +239,12 @@ Avoid relying on the legacy behavior. Any `config_setting` that is intended to
be used outside the current package should have an explicit `visibility`, if the
package does not already specify a suitable `default_visibility`.
-### Package group target visibility {#package-group-target-visibility}
+### Package group target visibility
`package_group` targets do not have a `visibility` attribute. They are always
publicly visible.
-### Visibility of implicit dependencies {#visibility-implicit-dependencies}
+### Visibility of implicit dependencies
Some rules have [implicit dependencies](/extending/rules#private_attributes_and_implicit_dependencies) —
dependencies that are not spelled out in a `BUILD` file but are inherent to
@@ -262,12 +262,12 @@ respect to the `cc_library` target.
If you want to restrict the usage of a rule to certain packages, use
[load visibility](#load-visibility) instead.
-### Visibility and symbolic macros {#symbolic-macros}
+### Visibility and symbolic macros
This section describes how the visibility system interacts with
[symbolic macros](/extending/macros).
-#### Locations within symbolic macros {#locations-within-symbolic-macros}
+#### Locations within symbolic macros
A key detail of the visibility system is how we determine the location of a
declaration. For targets that are not declared in a symbolic macro, the location
@@ -304,7 +304,7 @@ composes, in the sense that a chain of nested calls to submacros may each pass
the caller at each level, without exposing any of the macros' implementation
details.
-#### Delegating privileges to a submacro {#delegating-privileges-to-a-submacro}
+#### Delegating privileges to a submacro
The visibility model has a special feature to allow a macro to delegate its
permissions to a submacro. This is important for factoring and composing macros.
@@ -380,7 +380,7 @@ label-typed attributes.
Note: Visibility delegation does not work for labels that were not passed into
the macro, such as labels derived by string manipulation.
-#### Finalizers {#finalizers}
+#### Finalizers
Targets declared in a rule finalizer (a symbolic macro with `finalizer = True`),
in addition to seeing targets following the usual symbolic macro visibility
@@ -399,7 +399,7 @@ finalizer, the finalizer cannot see such a target. Note, however, that a
`native.existing_rules()`-based legacy macro will also be unable to see such a
target.
-## Transitive visibility {#transitive-visibility}
+## Transitive visibility
**Transitive visibility** is a way of restricting who may depend on a target,
including when the dependency is only indirect. It applies separately from the
@@ -461,7 +461,7 @@ Transitive visibility also applies to targets that are declared in symbolic
macros. However, unlike ordinary target visibility, it only considers the
package these targets live in, not the package that defined the symbolic macro.
-## Load visibility {#load-visibility}
+## Load visibility
**Load visibility** controls whether a `.bzl` file may be loaded from other
`BUILD` or `.bzl` files outside the current package.
@@ -486,7 +486,7 @@ not be done for submitted code.
Load visibility is available as of Bazel 6.0.
-### Declaring load visibility {#declaring-load-visibility}
+### Declaring load visibility
To set the load visibility of a `.bzl` file, call the
[`visibility()`](/rules/lib/globals/bzl#visibility) function from within the file.
@@ -503,7 +503,7 @@ that do not call `visibility()` are always loadable from anywhere in the
workspace. It is a good idea to add `visibility("private")` to the top of any
new `.bzl` file that is not specifically intended for use outside the package.
-### Example {#load-visibility-example}
+### Example
```starlark
# //mylib/internal_defs.bzl
@@ -537,11 +537,11 @@ load("//mylib:internal_defs.bzl", "helper") # error
...
```
-### Load visibility practices {#load-visibility-practices}
+### Load visibility practices
This section describes tips for managing load visibility declarations.
-#### Factoring visibilities {#factoring-visibilities}
+#### Factoring visibilities
When multiple `.bzl` files should have the same visibility, it can be helpful to
factor their package specifications into a common list. For example:
@@ -579,7 +579,7 @@ visibility(clients)
This helps prevent accidental skew between the various `.bzl` files'
visibilities. It also is more readable when the `clients` list is large.
-#### Composing visibilities {#composing-visibilities}
+#### Composing visibilities
Sometimes a `.bzl` file might need to be visible to an allowlist that is
composed of multiple smaller allowlists. This is analogous to how a
@@ -599,7 +599,7 @@ load("//some_big_client:defs.bzl", "their_remaining_uses")
visibility(our_packages + their_remaining_uses)
```
-#### Deduplicating with package groups {#deduplicating-with-package-groups}
+#### Deduplicating with package groups
Unlike target visibility, you cannot define a load visibility in terms of a
`package_group`. If you want to reuse the same allowlist for both target
@@ -622,7 +622,7 @@ package_group(
This only works if the list does not contain any negative package
specifications.
-#### Protecting individual symbols {#protecting-individual-symbols}
+#### Protecting individual symbols
Any Starlark symbol whose name begins with an underscore cannot be loaded from
another file. This makes it easy to create private symbols, but does not allow
@@ -664,7 +664,7 @@ visibility("public")
public_util = _public_util
```
-#### bzl-visibility Buildifier lint {#bzl-visibility-buildifier-lint}
+#### bzl-visibility Buildifier lint
There is a [Buildifier lint](https://github.com/bazelbuild/buildtools/blob/master/WARNINGS.md#bzl-visibility)
that provides a warning if users load a file from a directory named `internal`
diff --git a/configure/attributes.mdx b/configure/attributes.mdx
index 4f03c453..7bc3f41e 100644
--- a/configure/attributes.mdx
+++ b/configure/attributes.mdx
@@ -4,14 +4,15 @@ title: 'Configurable Build Attributes'
-**_Configurable attributes_**, commonly known as [`select()`](/reference/be/functions#select), is a Bazel feature that lets users toggle the values
+**_Configurable attributes_**, commonly known as [`select()`](
+/reference/be/functions#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 {#configurable-build-example}
+## Example
```python
# myapp/BUILD
@@ -86,7 +87,7 @@ are *non-configurable*, and these are clearly annotated. For example,
`config_setting`'s own
[`values`](/reference/be/general#config_setting.values) attribute is non-configurable.
-## `select()` and dependencies {#select-and-dependencies}
+## `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
@@ -142,7 +143,7 @@ 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 {#configuration-conditions}
+## Configuration conditions
Each key in a configurable attribute is a label reference to a
[`config_setting`](/reference/be/general#config_setting) or
@@ -154,7 +155,7 @@ easy to maintain "standard" conditions users can reference from multiple places.
`constraint_value` provides support for [multi-platform behavior](#platforms).
-### Built-in flags {#built-in-flags}
+### 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
@@ -188,7 +189,7 @@ 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 {#custom-flags}
+### Custom flags
You can model your own project-specific flags with
[Starlark build settings][BuildSettings]. Unlike built-in flags, these are
@@ -224,7 +225,7 @@ 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 {#default-condition}
+## The default condition
The built-in condition `//conditions:default` matches when no other condition
matches.
@@ -260,7 +261,7 @@ Conditions checked:
For even clearer errors, you can set custom messages with `select()`'s
[`no_match_error`](#custom-error-messages) attribute.
-## Platforms {#platforms}
+## 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
@@ -362,7 +363,7 @@ check against single values.
Platforms are still under development. See the
[documentation](/concepts/platforms) for details.
-## Combining `select()`s {#combining-selects}
+## Combining `select()`s
`select` can appear multiple times in the same attribute:
@@ -408,9 +409,10 @@ sh_library(
)
```
-If you need a `select` to match when multiple conditions match, consider [AND chaining](#and-chaining).
+If you need a `select` to match when multiple conditions match, consider [AND
+chaining](#and-chaining).
-## OR chaining {#or-chaining}
+## OR chaining
Consider the following:
@@ -453,7 +455,7 @@ duplication.
For more direct support, use one of the following:
-### `selects.with_or` {#selects-with-or}
+### `selects.with_or`
The
[with_or](https://github.com/bazelbuild/bazel-skylib/blob/main/docs/selects_doc.md#selectswith_or)
@@ -476,7 +478,7 @@ sh_binary(
)
```
-### `selects.config_setting_group` {#selects-config-setting-or-group}
+### `selects.config_setting_group`
The
@@ -519,7 +521,7 @@ different attributes.
It's an error for multiple conditions to match unless one is an unambiguous
"specialization" of the others or they all resolve to the same value. See [here](#configurable-build-example) for details.
-## AND chaining {#and-chaining}
+## AND chaining
If you need a `select` branch to match when multiple conditions match, use the
[Skylib](https://github.com/bazelbuild/bazel-skylib) macro
@@ -551,7 +553,7 @@ sh_binary(
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 {#custom-error-messages}
+## Custom error messages
By default, when no condition matches, the target the `select()` is attached to
fails with the error:
@@ -586,7 +588,7 @@ ERROR: Configurable attribute "deps" doesn't match this configuration: Please
build with an Android or Windows toolchain
```
-## Rules compatibility {#rules-compatibility}
+## Rules compatibility
Rule implementations receive the *resolved values* of configurable
attributes. For example, given:
@@ -634,7 +636,7 @@ 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.
-## Bazel query and cquery {#query-and-cquery}
+## Bazel query and cquery
Bazel [`query`](/query/guide) operates over Bazel's
[loading phase](/reference/glossary#loading-phase).
@@ -695,9 +697,9 @@ $ bazel cquery 'deps(//myapp:my_lib)' --//myapp:dog_type=pug
//myapp:bar_dep
```
-## FAQ {#faq}
+## FAQ
-### Why doesn't select() work in macros? {#faq-select-macro}
+### Why doesn't select() work in macros?
select() *does* work in rules! See [Rules compatibility](#rules-compatibility) for
details.
@@ -809,7 +811,7 @@ 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.
```
-### Why does select() always return true? {#faq-boolean-select}
+### Why does select() always return true?
Because *macros* (but not rules) by definition
[can't evaluate `select()`s](#faq-select-macro), any attempt to do so
@@ -855,7 +857,7 @@ So what they're really evaluting is the `select()` object itself. According to
standards, all objects aside from a very small number of exceptions
automatically return true.
-### Can I read select() like a dict? {#faq-inspectable-select}
+### Can I read select() like a dict?
Macros [can't](#faq-select-macro) evaluate select(s) because macros evaluate before
Bazel knows what the build's command line parameters are. Can they at least read
@@ -911,7 +913,7 @@ def selecty_genrule(name, select_cmd):
)
```
-### Why doesn't select() work with bind()? {#faq-select-bind}
+### Why doesn't select() work with bind()?
First of all, do not use `bind()`. It is deprecated in favor of `alias()`.
@@ -957,7 +959,7 @@ located at `@alternative//:ssl`.
But really, stop using `bind()`.
-### Why doesn't my select() choose what I expect? {#faq-select-choose-condition}
+### 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](/query/cquery) and `bazel config` to debug:
@@ -1008,7 +1010,7 @@ 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.
-### Why doesn't `select()` work with platforms? {#faq-select-platforms}
+### Why doesn't `select()` work with platforms?
Bazel doesn't support configurable attributes checking whether a given platform
is the target platform because the semantics are unclear.
diff --git a/configure/best-practices.mdx b/configure/best-practices.mdx
index 7f9f57fe..deecf9dd 100644
--- a/configure/best-practices.mdx
+++ b/configure/best-practices.mdx
@@ -23,7 +23,7 @@ should make a project more readable, less error-prone, and faster to build.
This page uses the requirement levels described in
[this RFC](https://www.ietf.org/rfc/rfc2119.txt).
-## Running builds and tests {#running-builds-tests}
+## Running builds and tests
A project should always be able to run `bazel build //...` and
`bazel test //...` successfully on its stable branch. Targets that are necessary
@@ -34,14 +34,14 @@ tagging allows targets to be filtered at a more fine-grained level than the
"manual" tag and allows someone inspecting the `BUILD` file to understand what
a target's restrictions are.
-## Third-party dependencies {#third-party-dependencies}
+## Third-party dependencies
You may declare third-party dependencies:
* Either declare them as remote repositories in the `MODULE.bazel` file.
* Or put them in a directory called `third_party/` under your workspace directory.
-## Depending on binaries {#binaries}
+## Depending on binaries
Everything should be built from source whenever possible. Generally this means
that, instead of depending on a library `some-library.so`, you'd create a
@@ -53,7 +53,7 @@ was built with incompatible flags or a different architecture. There are also
some features like coverage, static analysis, or dynamic analysis that only
work on the source.
-## Versioning {#versioning}
+## Versioning
Prefer building all code from head whenever possible. When versions must be
used, avoid including the version in the target name (for example, `//guava`,
@@ -64,7 +64,7 @@ you could end up with a library that tries to depend on two different versions.
If you created a misleading alias to point both targets to one `guava` library,
then the `BUILD` files are misleading.
-## Using the `.bazelrc` file {#bazelrc-file}
+## Using the `.bazelrc` file
For project-specific options, use the configuration file your
`workspace/.bazelrc` (see [bazelrc format](/run/bazelrc)).
@@ -84,7 +84,7 @@ The open-source
generates a custom bazelrc file that matches your Bazel version and provides a
preset of recommended flags.
-## Packages {#packages}
+## Packages
Every directory that contains buildable files should be a package. If a `BUILD`
file refers to files in subdirectories (such as, `srcs = ["a/b/C.java"]`) it's
diff --git a/configure/coverage.mdx b/configure/coverage.mdx
index 1eacadfc..f8e3e7b6 100644
--- a/configure/coverage.mdx
+++ b/configure/coverage.mdx
@@ -21,7 +21,7 @@ While a lot of customization is possible, this document focuses on
producing and consuming [`lcov`][lcov] reports, which is currently the
most well-supported route.
-## Creating a coverage report {#creating-a-coverage-report}
+## Creating a coverage report
### Preparation
@@ -85,7 +85,7 @@ To view the result, simply open the `index.html` file produced in the
For further help and information around the `genhtml` tool, or the
`lcov` coverage format, see [the lcov project][lcov].
-## Remote execution {#remote-execution}
+## Remote execution
Running with remote test execution currently has a few caveats:
diff --git a/configure/integrate-cpp.mdx b/configure/integrate-cpp.mdx
index 599fbd8f..107ab810 100644
--- a/configure/integrate-cpp.mdx
+++ b/configure/integrate-cpp.mdx
@@ -4,7 +4,7 @@ title: 'Integrating with C++ Rules'
This page describes how to integrate with C++ rules on various levels.
-## Accessing the C++ toolchain {#access-c-toolchain}
+## Accessing the C++ toolchain
You should use the helper functions available at
[`@rules_cc//cc:find_cc_toolchain.bzl`](https://github.com/bazelbuild/rules_cc/blob/main/cc/find_cc_toolchain.bzl)
@@ -14,9 +14,10 @@ To depend on a C++ toolchain in your rule, set the `toolchains` parameter to
`use_cc_toolchain()`. Then, in the rule implementation, use
`find_cpp_toolchain(ctx)` to get the
[`CcToolchainInfo`](/rules/lib/providers/CcToolchainInfo). A complete working
-example can be found [in the rules_cc examples](https://github.com/bazelbuild/rules_cc/blob/main/examples/write_cc_toolchain_cpu/write_cc_toolchain_cpu.bzl).
+example can be found [in the rules_cc
+examples](https://github.com/bazelbuild/rules_cc/blob/main/examples/write_cc_toolchain_cpu/write_cc_toolchain_cpu.bzl).
-## Generating command lines and environment variables using the C++ toolchain {#generate-command-lines-toolchain}
+## Generating command lines and environment variables using the C++ toolchain
Typically, you would integrate with the C++ toolchain to have the same
command line flags as C++ rules do, but without using C++ actions directly.
@@ -24,7 +25,8 @@ This is because when writing our own actions, they must behave
consistently with the C++ toolchain - for example, passing C++ command line
flags to a tool that invokes the C++ compiler behind the scenes.
-C++ rules use a special way of constructing command lines based on [feature configuration](/docs/cc-toolchain-config-reference). To construct a command line,
+C++ rules use a special way of constructing command lines based on [feature
+configuration](/docs/cc-toolchain-config-reference). To construct a command line,
you need the following:
* `features` and `action_configs` - these come from the `CcToolchainConfigInfo`
@@ -43,7 +45,7 @@ eventually be removed.
A complete working example can be found
[in the rules_cc examples](https://github.com/bazelbuild/rules_cc/blob/main/examples/my_c_compile/my_c_compile.bzl).
-## Implementing Starlark rules that depend on C++ rules and/or that C++ rules can depend on {#implement-starlark-rules}
+## Implementing Starlark rules that depend on C++ rules and/or that C++ rules can depend on
Most C++ rules provide
[`CcInfo`](/rules/lib/providers/CcInfo),
@@ -65,7 +67,7 @@ it should wrap it in, for example, `JavaCcInfo`.
A complete working example can be found
[in the rules_cc examples](https://github.com/bazelbuild/rules_cc/blob/main/examples/my_c_archive/my_c_archive.bzl).
-## Reusing logic and actions of C++ rules {#reuse-logic-c-rules}
+## Reusing logic and actions of C++ rules
_Not stable yet; This section will be updated once the API stabilizes. Follow
[#4570](https://github.com/bazelbuild/bazel/issues/4570) for up-to-date
diff --git a/configure/windows.mdx b/configure/windows.mdx
index 573f660d..67a36c83 100644
--- a/configure/windows.mdx
+++ b/configure/windows.mdx
@@ -7,16 +7,16 @@ title: 'Using Bazel on Windows'
This page covers Best Practices for using Bazel on Windows. For installation
instructions, see [Install Bazel on Windows](/install/windows).
-## Known issues {#known-issues}
+## Known issues
Windows-related Bazel issues are marked with the "area-Windows" label on GitHub.
[GitHub-Windows].
[GitHub-Windows]: https://github.com/bazelbuild/bazel/issues?q=is%3Aopen+is%3Aissue+label%3Aarea-Windows
-## Best practices {#best-practices}
+## Best practices
-### Avoid long path issues {#long-path-issues}
+### Avoid long path issues
Some tools have the [Maximum Path Length Limitation](https://docs.microsoft.com/en-us/windows/win32/fileio/naming-a-file#maximum-path-length-limitation) on Windows, including the MSVC compiler.
To avoid hitting this issue, you can specify a short output directory for Bazel by the [\-\-output_user_root](/reference/command-line-reference#flag--output_user_root) flag.
@@ -27,7 +27,7 @@ For example, add the following line to your bazelrc file:
startup --output_user_root=C:/tmp
```
-### Enable symlink support {#symlink}
+### Enable symlink support
Some features require Bazel to be able to create file symlinks on Windows,
either by enabling
@@ -51,7 +51,7 @@ build --enable_runfiles
{/* TODO(pcloudy): https://github.com/bazelbuild/bazel/issues/6402
Write a doc about runfiles library and add a link to it here */}
-### Running Bazel: MSYS2 shell vs. command prompt vs. PowerShell {#running-bazel-shells}
+### Running Bazel: MSYS2 shell vs. command prompt vs. PowerShell
**Recommendation:** Run Bazel from the command prompt (`cmd.exe`) or from
PowerShell.
@@ -66,9 +66,9 @@ that _look like_ Unix paths (such as `//foo:bar`) into Windows paths. See
[this StackOverflow answer](https://stackoverflow.com/a/49004265/7778502)
for details.
-### Using Bazel without Bash (MSYS2) {#using-bazel-without-bash}
+### Using Bazel without Bash (MSYS2)
-#### Using bazel build without Bash {#bazel-build-without-bash}
+#### Using bazel build without Bash
Bazel versions before 1.0 used to require Bash to build some rules.
@@ -86,7 +86,7 @@ in the
[bazel-skylib repository](https://github.com/bazelbuild/bazel-skylib/tree/main/rules).
When built on Windows, **these rules do not require Bash**.
-#### Using bazel test without Bash {#bazel-test-without-bash}
+#### Using bazel test without Bash
Bazel versions before 1.0 used to require Bash to `bazel test` anything.
@@ -95,7 +95,7 @@ Starting with Bazel 1.0, you can test any rule without Bash, except when:
- you use `--run_under`
- the test rule itself requires Bash (because its executable is a shell script)
-#### Using bazel run without Bash {#bazel-run-without-bash}
+#### Using bazel run without Bash
Bazel versions before 1.0 used to require Bash to `bazel run` anything.
@@ -104,7 +104,7 @@ Starting with Bazel 1.0, you can run any rule without Bash, except when:
- you use `--run_under` or `--script_path`
- the test rule itself requires Bash (because its executable is a shell script)
-#### Using sh\_binary and sh\_* rules, and ctx.actions.run_shell() without Bash {#sh-rules-without-bash}
+#### Using sh\_binary and sh\_* rules, and ctx.actions.run_shell() without Bash
You need Bash to build and test `sh_*` rules, and to build and test Starlark
rules that use `ctx.actions.run_shell()` and `ctx.resolve_command()`. This
@@ -115,7 +115,7 @@ In the future, there may be an option to use Windows Subsystem for
Linux (WSL) to build these rules, but currently it is not a priority for
the Bazel-on-Windows subteam.
-### Setting environment variables {#set-environment-variables}
+### Setting environment variables
Environment variables you set in the Windows Command Prompt (`cmd.exe`) are only
set in that command prompt session. If you start a new `cmd.exe`, you need to
@@ -123,9 +123,9 @@ set the variables again. To always set the variables when `cmd.exe` starts, you
can add them to the User variables or System variables in the `Control Panel >
System Properties > Advanced > Environment Variables...` dialog box.
-## Build on Windows {#using}
+## Build on Windows
-### Build C++ with MSVC {#build_cpp}
+### Build C++ with MSVC
To build C++ targets with MSVC, you need:
@@ -162,7 +162,8 @@ To build C++ targets with MSVC, you need:
set BAZEL_VC=C:\Program Files (x86)\Microsoft Visual Studio 14.0\VC
```
-* The [Windows SDK](https://developer.microsoft.com/en-us/windows/downloads/windows-10-sdk).
+* The [Windows
+ SDK](https://developer.microsoft.com/en-us/windows/downloads/windows-10-sdk).
The Windows SDK contains header files and libraries you need when building
Windows applications, including Bazel itself. By default, the latest Windows SDK installed will
@@ -181,7 +182,8 @@ To build C++ targets with MSVC, you need:
If everything is set up, you can build a C++ target now!
-Try building a target from one of our [sample projects](https://github.com/bazelbuild/bazel/tree/master/examples):
+Try building a target from one of our [sample
+projects](https://github.com/bazelbuild/bazel/tree/master/examples):
```
bazel-bin\examples\java-native\src\main\java\com\example\myproject\hello-world.exe
```
-### Build Python {#python}
+### Build Python
To build Python targets, you need:
@@ -401,7 +406,8 @@ On Windows, Bazel builds two output files for `py_binary` rules:
You can either run the executable file (it has a `.exe` extension) or you can run
Python with the self-extracting zip file as the argument.
-Try building a target from one of our [sample projects](https://github.com/bazelbuild/bazel/tree/master/examples):
+Try building a target from one of our [sample
+projects](https://github.com/bazelbuild/bazel/tree/master/examples):
```
Yes: Preserving graph order
- No: On the preservation of graph order
-### Names {#names}
+### Names
- Capitalize proper nouns, such as Bazel and Starlark.
@@ -59,7 +59,7 @@ This section contains basic writing tips.
- For example, if you're writing about issuing commands on a
terminal, don't use both terminal and command line on the page.
-### Page scope {#page-scope}
+### Page scope
- Each page should have one purpose and that should be defined at the
beginning. This helps readers find what they need quicker.
@@ -71,7 +71,7 @@ This section contains basic writing tips.
there is no clear action, you can include links to similar concepts,
examples, or other avenues for exploration.
-### Subject {#subject}
+### Subject
In Bazel documentation, the audience should primarily be users—the people using
Bazel to build their software.
@@ -94,7 +94,7 @@ Bazel to build their software.
- No: Bazel is evolving, and we will make changes to Bazel that at
times will be incompatible and require some changes from Bazel users.
-### Temporal {#temporal}
+### Temporal
Where possible, avoid terms that orient things in time, such as referencing
specific dates (Q2 2022) or saying "now", "currently", or "soon." These go
@@ -107,7 +107,7 @@ specify a version level instead, such as "Bazel X.x and higher supports
- No: Bazel will soon support remote
caching, likely in October 2017.
-### Tense {#tense}
+### Tense
- Use present tense. Avoid past or future tense unless absolutely necessary
for clarity.
@@ -125,7 +125,7 @@ specify a version level instead, such as "Bazel X.x and higher supports
- No: X is initiated by Bazel and then
afterward Y will be built with the output.
-### Tone {#tone}
+### Tone
Write with a business friendly tone.
@@ -137,9 +137,9 @@ Write with a business friendly tone.
- Avoid overly formal language. Write as though you're explaining the
concept to someone who is curious about tech, but doesn't know the details.
-## Formatting {#format}
+## Formatting
-### File type {#file-type}
+### File type
For readability, wrap lines at 80 characters. Long links or code snippets
may be longer, but should start on a new line. For example:
@@ -148,7 +148,7 @@ Note: Where possible, use Markdown instead of HTML in your files. Follow the
[GitHub Markdown Syntax Guide](https://guides.github.com/features/mastering-markdown/#syntax)
for recommended Markdown style.
-### Links {#links}
+### Links
- Use descriptive link text instead of "here" or "below". This practice
makes it easier to scan a doc and is better for screen readers.
@@ -159,7 +159,7 @@ for recommended Markdown style.
- Yes: For more details, see [link].
- No: See [link] for more information.
-### Lists {#lists}
+### Lists
- Use an ordered list to describe how to accomplish a task with steps
- Use an unordered list to list things that aren't task based. (There should
@@ -169,7 +169,7 @@ for recommended Markdown style.
1. Start with verbs that are the same tense.
1. Use an ordered list if there are steps to follow.
-### Placeholders {#placeholders}
+### Placeholders
- Use angle brackets to denote a variable that users should change.
In Markdown, escape the angle brackets with a back slash: `\`.
@@ -181,11 +181,11 @@ for recommended Markdown style.
- Especially for complicated code samples, use placeholders that make sense
in context.
-### Table of contents {#toc}
+### Table of contents
Use the auto-generated TOC supported by the site. Don't add a manual TOC.
-## Code {#code}
+## Code
Code samples are developers' best friends. You probably know how to write these
already, but here are a few tips.
@@ -194,7 +194,7 @@ If you're referencing a small snippet of code, you can embed it in a sentence.
If you want the reader to use the code, such as copying a command, use a code
block.
-### Code blocks {#code-blocks}
+### Code blocks
- Keep it short. Eliminate all redundant or unnecessary text from a code
sample.
@@ -207,7 +207,7 @@ block.
- Separate commands and output into different code blocks.
-### Inline code formatting {#code-format}
+### Inline code formatting
- Use code style for filenames, directories, paths, and small bits of code.
- Use inline code styling instead of _italics_, "quotes," or **bolding**.
diff --git a/contribute/index.mdx b/contribute/index.mdx
index a0a279a7..ee667729 100644
--- a/contribute/index.mdx
+++ b/contribute/index.mdx
@@ -6,28 +6,31 @@ title: 'Contributing to Bazel'
There are many ways to help the Bazel project and ecosystem.
-## Provide feedback {#feedback}
+## Provide feedback
As you use Bazel, you may find things that can be improved.
You can help by [reporting issues](http://github.com/bazelbuild/bazel/issues)
when:
- - Bazel crashes or you encounter a bug that can [only be resolved using `bazel clean`](/run/build#correct-incremental-rebuilds).
+ - Bazel crashes or you encounter a bug that can [only be resolved using `bazel
+ clean`](/run/build#correct-incremental-rebuilds).
- The documentation is incomplete or unclear. You can also report issues
from the page you are viewing by using the "Create issue"
link at the top right corner of the page.
- An error message could be improved.
-## Participate in the community {#community}
+## Participate in the community
You can engage with the Bazel community by:
- - Answering questions [on Stack Overflow](https://stackoverflow.com/questions/tagged/bazel).
+ - Answering questions [on Stack Overflow](
+ https://stackoverflow.com/questions/tagged/bazel).
- Helping other users [on Slack](https://slack.bazel.build).
- - Improving documentation or [contributing examples](https://github.com/bazelbuild/examples).
+ - Improving documentation or [contributing examples](
+ https://github.com/bazelbuild/examples).
- Sharing your experience or your tips, for example, on a blog or social media.
-## Contribute code {#contribute-code}
+## Contribute code
Bazel is a large project and making a change to the Bazel source code
can be difficult.
@@ -39,7 +42,8 @@ You can contribute to the Bazel ecosystem by:
- Contributing to Bazel-related tools, for example, migration tools.
- Improving Bazel integration with other IDEs and tools.
-Before making a change, [create a GitHub issue](http://github.com/bazelbuild/bazel/issues)
+Before making a change, [create a GitHub
+issue](http://github.com/bazelbuild/bazel/issues)
or email [bazel-discuss@](mailto:bazel-discuss@googlegroups.com).
The most helpful contributions fix bugs or add features (as opposed
@@ -50,7 +54,7 @@ portability, and the impact on memory usage and performance.
To learn about how to submit a change, see the
[patch acceptance process](/contribute/patch-acceptance).
-## Bazel's code description {#code-description}
+## Bazel's code description
Bazel has a large codebase with code in multiple locations. See the [codebase guide](/contribute/codebase) for more details.
@@ -69,7 +73,7 @@ Bazel is organized as follows:
[compiling Bazel](/install/compile-source) section.
-### Searching Bazel's source code {#search-code}
+### Searching Bazel's source code
To quickly search through Bazel's source code, use
[Bazel Code Search](https://source.bazel.build/). You can navigate Bazel's
diff --git a/contribute/maintainers-guide.mdx b/contribute/maintainers-guide.mdx
index a2331742..30cf9780 100644
--- a/contribute/maintainers-guide.mdx
+++ b/contribute/maintainers-guide.mdx
@@ -6,7 +6,8 @@ title: 'Guide for Bazel Maintainers'
This is a guide for the maintainers of the Bazel open source project.
-If you are looking to contribute to Bazel, read [Contributing to Bazel](/contribute) instead.
+If you are looking to contribute to Bazel, read [Contributing to
+Bazel](/contribute) instead.
The objectives of this page are to:
@@ -23,22 +24,23 @@ subteams to manage aspects of the open source project. These are:
* **Developer Experience Gardeners**: Encourage external contributions, review
issues and pull requests, and make our development workflow more open.
-## Releases {#releases}
+## Releases
* [Release Playbook](https://github.com/bazelbuild/continuous-integration/blob/master/docs/release-playbook.md)
* [Testing local changes with downstream projects](https://github.com/bazelbuild/continuous-integration/blob/master/docs/downstream-testing.md)
-## Continuous Integration {#integration}
+## Continuous Integration
Read the Green team's guide to Bazel's CI infrastructure on the
[bazelbuild/continuous-integration](https://github.com/bazelbuild/continuous-integration/blob/master/buildkite/README.md)
repository.
-## Lifecycle of an Issue {#lifecycle-issue}
+## Lifecycle of an Issue
1. A user creates an issue by choosing one of the
[issue templates](https://github.com/bazelbuild/bazel/issues/new/choose)
- and it enters the pool of [unreviewed open issues](https://github.com/bazelbuild/bazel/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+-label%3Auntriaged+-label%3Ap2+-label%3Ap1+-label%3Ap3+-label%3Ap4+-label%3Ateam-Starlark+-label%3Ateam-Rules-CPP+-label%3Ateam-Rules-Java+-label%3Ateam-XProduct+-label%3Ateam-Android+-label%3Ateam-Apple+-label%3Ateam-Configurability++-label%3Ateam-Performance+-label%3Ateam-Rules-Server+-label%3Ateam-Core+-label%3Ateam-Rules-Python+-label%3Ateam-Remote-Exec+-label%3Ateam-Local-Exec+-label%3Ateam-Bazel).
+ and it enters the pool of [unreviewed open
+ issues](https://github.com/bazelbuild/bazel/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+-label%3Auntriaged+-label%3Ap2+-label%3Ap1+-label%3Ap3+-label%3Ap4+-label%3Ateam-Starlark+-label%3Ateam-Rules-CPP+-label%3Ateam-Rules-Java+-label%3Ateam-XProduct+-label%3Ateam-Android+-label%3Ateam-Apple+-label%3Ateam-Configurability++-label%3Ateam-Performance+-label%3Ateam-Rules-Server+-label%3Ateam-Core+-label%3Ateam-Rules-Python+-label%3Ateam-Remote-Exec+-label%3Ateam-Local-Exec+-label%3Ateam-Bazel).
1. A member on the Developer Experience (DevEx) subteam rotation reviews the
issue.
1. If the issue is **not a bug** or a **feature request**, the DevEx member
@@ -58,22 +60,25 @@ repository.
1. After reviewing the issue, the DevEx member decides if the issue requires
immediate attention. If it does, they will assign the **P0**
[priority](#priority) label and an owner from the list of team leads.
-1. The DevEx member assigns the `untriaged` label and exactly one [team label](#team-labels) for routing.
+1. The DevEx member assigns the `untriaged` label and exactly one [team
+ label](#team-labels) for routing.
1. The DevEx member also assigns exactly one `type:` label, such as `type: bug`
or `type: feature request`, according to the type of the issue.
1. For platform-specific issues, the DevEx member assigns one `platform:` label,
such as `platform:apple` for Mac-specific issues.
1. If the issue is low priority and can be worked on by a new community
contributor, the DevEx member assigns the `good first issue` label.
-At this stage, the issue enters the pool of [untriaged open issues](https://github.com/bazelbuild/bazel/issues?q=is%3Aissue+is%3Aopen+label%3Auntriaged).
+At this stage, the issue enters the pool of [untriaged open
+issues](https://github.com/bazelbuild/bazel/issues?q=is%3Aissue+is%3Aopen+label%3Auntriaged).
Each Bazel subteam will triage all issues under labels they own, preferably on a
weekly basis. The subteam will review and evaluate the issue and provide a
-resolution, if possible. If you are an owner of a team label, see [this section](#label-own) for more information.
+resolution, if possible. If you are an owner of a team label, see [this section
+](#label-own) for more information.
When an issue is resolved, it can be closed.
-## Lifecycle of a Pull Request {#lifecycle-pull-request}
+## Lifecycle of a Pull Request
1. A user creates a pull request.
1. If you a member of a Bazel team and sending a PR against your own area,
@@ -93,12 +98,12 @@ When an issue is resolved, it can be closed.
1. When the commit merges into master, GitHub automatically closes the PR.
-## My team owns a label. What should I do? {#label-own}
+## My team owns a label. What should I do?
Subteams need to triage all issues in the [labels they own](#team-labels),
preferably on a weekly basis.
-### Issues {#issues}
+### Issues
1. Filter the list of issues by your team label **and** the `untriaged` label.
1. Review the issue.
@@ -109,9 +114,10 @@ preferably on a weekly basis.
issue is either P0 or P1 we assume that is actively worked on.
1. Remove the `untriaged` label.
-Note that you need to be in the [bazelbuild organization](https://github.com/bazelbuild) to be able to add or remove labels.
+Note that you need to be in the [bazelbuild
+organization](https://github.com/bazelbuild) to be able to add or remove labels.
-### Pull Requests {#pull-requests}
+### Pull Requests
Pull requests (PRs) are a primary way that external contributors add value to
Bazel. As an open source project, it is important to ensure that PRs are
@@ -152,7 +158,7 @@ reviewed and handled in a timely and efficient manner.
When closing a PR, be polite and explain the reason for closure.
-## Priority {#priority}
+## Priority
The following definitions for priority will be used by the maintainers to triage
issues.
@@ -162,7 +168,8 @@ issues.
unusable, or a downed service that severely impacts development of the Bazel
project. This includes regressions introduced in a new release that blocks a
significant number of users, or an incompatible breaking change that was not
- compliant to the [Breaking Change](https://docs.google.com/document/d/1q5GGRxKrF_mnwtaPKI487P8OdDRh2nN7jX6U-FXnHL0/edit?pli=1#heading=h.ceof6vpkb3ik)
+ compliant to the [Breaking
+ Change](https://docs.google.com/document/d/1q5GGRxKrF_mnwtaPKI487P8OdDRh2nN7jX6U-FXnHL0/edit?pli=1#heading=h.ceof6vpkb3ik)
policy. No practical workaround exists.
* [**P1**](https://github.com/bazelbuild/bazel/labels/P1) - Critical defect or
feature which should be addressed in the next release, or a serious issue that
@@ -180,7 +187,7 @@ issues.
or feature request that is unlikely to get closed. Can also be kept open for a
potential re-prioritization if more users are impacted.
-## Team labels {#team-labels}
+## Team labels
* [`team-Android`](https://github.com/bazelbuild/bazel/labels/team-Android): Issues for Android team
* Contact: [ahumesky](https://github.com/ahumesky)
diff --git a/contribute/naming.mdx b/contribute/naming.mdx
index 5c71e429..144b08af 100644
--- a/contribute/naming.mdx
+++ b/contribute/naming.mdx
@@ -6,17 +6,18 @@ title: 'Naming a Bazel related project'
First, thank you for contributing to the Bazel ecosystem! Please reach out to
the Bazel community on the
-[bazel-discuss mailing list](https://groups.google.com/forum/#!forum/bazel-discuss) to share your project and its suggested name.
+[bazel-discuss mailing list](https://groups.google.com/forum/#!forum/bazel-discuss
+) to share your project and its suggested name.
If you are building a Bazel related tool or sharing your Skylark rules,
we recommend following these guidelines for the name of your project:
-## Naming Starlark rules {#name-starlark-rules}
+## Naming Starlark rules
See [Deploying new Starlark rules](/rules/deploying)
in the docs.
-## Naming other Bazel related tools {#name-related-tools}
+## Naming other Bazel related tools
This section applies if you are building a tool to enrich the Bazel ecosystem.
For example, a new IDE plugin or a new build system migrator.
diff --git a/contribute/patch-acceptance.mdx b/contribute/patch-acceptance.mdx
index 2fca9f1a..867c046f 100644
--- a/contribute/patch-acceptance.mdx
+++ b/contribute/patch-acceptance.mdx
@@ -13,16 +13,19 @@ code base.
need a corresponding issue for tracking.
1. If you're proposing significant changes, write a
[design document](/contribute/design-documents).
-1. Ensure you've signed a [Contributor License Agreement](https://cla.developers.google.com).
+1. Ensure you've signed a [Contributor License
+ Agreement](https://cla.developers.google.com).
1. Prepare a git commit that implements the feature. Don't forget to add tests
and update the documentation. If your change has user-visible effects, please
[add release notes](/contribute/release-notes). If it is an incompatible change,
read the [guide for rolling out breaking changes](/contribute/breaking-changes).
1. Create a pull request on
[GitHub](https://github.com/bazelbuild/bazel/pulls). If you're new to GitHub,
- read [about pull requests](https://help.github.com/articles/about-pull-requests/). Note that
+ read [about pull
+ requests](https://help.github.com/articles/about-pull-requests/). Note that
we restrict permissions to create branches on the main Bazel repository, so
- you will need to push your commit to [your own fork of the repository](https://help.github.com/articles/working-with-forks/).
+ you will need to push your commit to [your own fork of the
+ repository](https://help.github.com/articles/working-with-forks/).
1. A Bazel maintainer should assign you a reviewer within 7 business days
(excluding holidays in the USA and Germany). If you aren't assigned a
reviewer in that time, you can ping `@bazelbuild/triage` on the PR.
diff --git a/contribute/policy.mdx b/contribute/policy.mdx
index 557955f3..1bf00290 100644
--- a/contribute/policy.mdx
+++ b/contribute/policy.mdx
@@ -48,7 +48,7 @@ rule sets. Contributors with a record of consistent, responsible past
contributions who are planning major contributions in the future could be
considered to become qualified Maintainers.
-## Contribution policy {#contribution-policy}
+## Contribution policy
The Bazel project accepts contributions from external contributors. Here are the
contribution policies for Google-managed and Community-managed areas of code.
diff --git a/contribute/release-notes.mdx b/contribute/release-notes.mdx
index fd78602a..83e1d75b 100644
--- a/contribute/release-notes.mdx
+++ b/contribute/release-notes.mdx
@@ -10,7 +10,7 @@ Commit descriptions in Bazel include a `RELNOTES:` tag followed by a release
note. This is used by the Bazel team to track changes in each release and write
the release announcement.
-## Overview {#overview}
+## Overview
* Is your change a bugfix? In that case, you don't need a release note. Please
include a reference to the GitHub issue.
@@ -18,9 +18,10 @@ the release announcement.
* If the change adds / removes / changes Bazel in a user-visible way, then it
may be advantageous to mention it.
-If the change is significant, follow the [design document policy](/contribute/design-documents) first.
+If the change is significant, follow the [design document
+policy](/contribute/design-documents) first.
-## Guidelines {#guidelines}
+## Guidelines
The release notes will be read by our users, so it should be short (ideally one
sentence), avoid jargon (Bazel-internal terminology), should focus on what the
@@ -59,10 +60,12 @@ change is about.
the user will wonder is "when?" and we don't want them to start worrying about
their current builds breaking at some unknown time.
-## Process {#process}
+## Process
-As part of the [release process](https://github.com/bazelbuild/continuous-integration/blob/master/docs/release-playbook.md),
-we collect the `RELNOTES` tags of every commit. We copy everything in a [Google Doc](https://docs.google.com/document/d/1wDvulLlj4NAlPZamdlEVFORks3YXJonCjyuQMUQEmB0/edit)
+As part of the [release
+process](https://github.com/bazelbuild/continuous-integration/blob/master/docs/release-playbook.md),
+we collect the `RELNOTES` tags of every commit. We copy everything in a [Google
+Doc](https://docs.google.com/document/d/1wDvulLlj4NAlPZamdlEVFORks3YXJonCjyuQMUQEmB0/edit)
where we review, edit, and organize the notes.
The release manager sends an email to the
@@ -70,4 +73,6 @@ The release manager sends an email to the
Bazel contributors are invited to contribute to the document and make sure
their changes are correctly reflected in the announcement.
-Later, the announcement will be submitted to the [Bazel blog](https://blog.bazel.build/), using the [bazel-blog repository](https://github.com/bazelbuild/bazel-blog/tree/master/_posts).
+Later, the announcement will be submitted to the [Bazel
+blog](https://blog.bazel.build/), using the [bazel-blog
+repository](https://github.com/bazelbuild/bazel-blog/tree/master/_posts).
diff --git a/contribute/search.mdx b/contribute/search.mdx
index 7bbea560..43c90754 100644
--- a/contribute/search.mdx
+++ b/contribute/search.mdx
@@ -2,14 +2,14 @@
title: 'Searching the codebase'
---
-## Product overview {#product-overview}
+## Product overview
Bazel's [code search and source browsing interface](https://source.bazel.build)
is a web-based tool for browsing Bazel source code repositories. You can
use these features to navigate among different repositories, branches, and
files. You can also view history, diffs, and blame information.
-## Getting started {#getting-started}
+## Getting started
Note: For the best experience, use the latest version of Chrome, Safari, or
Firefox.
@@ -29,9 +29,9 @@ commit.
At the top of the screen is a search box. You can use this box to search for
specific files and code.
-## Working with repositories {#working-with-repositories}
+## Working with repositories
-### Opening a repository {#opening-a-repository}
+### Opening a repository
To open a repository, click its name from the main screen.
@@ -41,11 +41,11 @@ repository and allows you to move quickly to another location such as another
repository, or another location within a repository, such as a file, branch, or
commit.
-### Switch repositories {#switch-repositories}
+### Switch repositories
To switch to a different repository, select the repository from the Breadcrumb toolbar.
-### View a repository at a specific commit {#view-a-repository-at-a-specific-commit}
+### View a repository at a specific commit
To view a repository at a specific commit:
@@ -56,7 +56,7 @@ To view a repository at a specific commit:
The interface now shows the repository as it existed at that commit.
-### Open a branch, commit, or tag {#open-a-branch-commit-or-tag}
+### Open a branch, commit, or tag
By default, the code search and source browsing interface opens a repository to
the default branch. To open a different branch, from the Breadcrumb toolbar,
@@ -72,7 +72,7 @@ branch using a branch name, a tag name, or through a search box.
* To search for a branch, commit, or tag, select the corresponding item and
type a search term in the search box.
-## Working with files {#working-with-files}
+## Working with files
When you select a repository from the main screen, the screen changes to display
a view of that repository. If a README file exists, its contents appear in the
@@ -90,13 +90,13 @@ three components:
* A **File path** box, which displays the name of the current file or folder
and its corresponding path
-### Open a file {#open-a-file}
+### Open a file
You can open a file by browsing to its directory and selecting it. The view of
the repository updates to show the contents of the file in the file pane, and
its location in the repository in the tree pane.
-### View file changes {#view-file-changes}
+### View file changes
To view file changes:
@@ -105,7 +105,7 @@ To view file changes:
The file pane updates to display who made changes to the file and when.
-### View change history {#view-change-history}
+### View change history
To view the change history of a file:
@@ -113,7 +113,7 @@ To view the change history of a file:
1. Click **HISTORY**, located in the upper-right corner.
The **Change history** pane appears, showing the commits for this file.
-### View code reviews {#view-code-reviews}
+### View code reviews
For Gerrit code reviews, you can open the tool directly from the Change History pane.
@@ -128,7 +128,7 @@ To view the code review for a file:
The Gerrit Code Review tool opens in a new browser window.
-### Open a file at a specific commit {#open-a-file-at-a-specific-commit}
+### Open a file at a specific commit
To open a file at a specific commit:
@@ -138,7 +138,7 @@ To open a file at a specific commit:
1. Hover over a commit. A **VIEW** button appears.
1. Click the **VIEW** button.
-### Compare a file to a different commit {#compare-a-file-to-a-different-commit}
+### Compare a file to a different commit
To compare a file at a different commit:
@@ -157,7 +157,7 @@ To change either file, hover over the commit in the Change History pane. Then,
click either the **Left** or **Right** button to have the open the commit on the
left or right side of the diff.
-### Browsing cross references {#browsing-cross-references}
+### Browsing cross references
Another way to browse source repositories is through the use of cross
references. These references appear automatically as hyperlinks within a given
@@ -188,7 +188,7 @@ You can continue to browse cross references using the Cross Reference pane, just
as you can in the File pane. When you do, the pane displays a breadcrumb trail,
which you can use to navigate between different cross references.
-## Searching for code {#search}
+## Searching for code
You can search for specific files or code snippets using the search box located
at the top of the screen. Searches are always against the default branch.
@@ -272,7 +272,7 @@ f:
-## Additional Support {#additional-support}
+## Additional Support
To report an issue, click the **Feedback** button that appears in the top
right-hand corner of the screen and enter your feedback in the provided form.
diff --git a/contribute/statemachine-guide.mdx b/contribute/statemachine-guide.mdx
index 4db66dfa..e98a96e8 100644
--- a/contribute/statemachine-guide.mdx
+++ b/contribute/statemachine-guide.mdx
@@ -52,7 +52,7 @@ virtually all recomputation when a SkyFunction restarts (assuming that
`SkyKeyComputeState` does not fall out of cache) by exposing suspend and resume
execution hooks.
-### Stateful computations inside `SkyKeyComputeState` {#stateful-computations}
+### Stateful computations inside `SkyKeyComputeState`
From an object-oriented design standpoint, it makes sense to consider storing
computational objects inside `SkyKeyComputeState` instead of pure data values.
@@ -164,7 +164,7 @@ subtasks, those lookups and subtasks will complete before the next state begins.
Tip: (Corollary) If subtasks are complex `StateMachine`s or recursively create
subtasks, they all *transitively* complete before the next state begins.
-### SkyValue lookups {#skyvalue-lookups}
+### SkyValue lookups
`StateMachine`s use `Tasks.lookUp` overloads to look up SkyValues. They are
analogous to `SkyFunction.Environment.getValue` and
@@ -174,7 +174,8 @@ instead, batches[^4] as many lookups as possible before doing so. The value
might not be immediately available, for example, requiring a Skyframe restart,
so the caller specifies what to do with the resulting value using a callback.
-The `StateMachine` processor ([`Driver`s and bridging to SkyFrame](#drivers-and-bridging)) guarantees that the value is available before
+The `StateMachine` processor ([`Driver`s and bridging to
+SkyFrame](#drivers-and-bridging)) guarantees that the value is available before
the next state begins. An example follows.
```
@@ -260,7 +261,7 @@ Though `Subtask1` and `Subtask2` are logically concurrent, everything runs in a
single thread so the "concurrent" update of `i` does not need any
synchronization.
-### Structured concurrency {#structured-concurrency}
+### Structured concurrency
Since every `lookUp` and `enqueue` must resolve before advancing to the next
state, it means that concurrency is naturally limited to tree-structures. It's
@@ -285,7 +286,8 @@ and solutions to certain control flow problems.
### Sequential states
This is the most common and straightforward control flow pattern. An example of
-this is shown in [Stateful computations inside `SkyKeyComputeState`](#stateful-computations).
+this is shown in [Stateful computations inside
+`SkyKeyComputeState`](#stateful-computations).
### Branching
@@ -384,7 +386,7 @@ class M2 implements StateMachine {
}
```
-#### `runAfter` injection {#runafter-injection}
+#### `runAfter` injection
Sometimes, abusing `Tasks.enqueue` is impossible because there are other
parallel subtasks or `Tasks.lookUp` calls that must be completed before *S*
@@ -545,10 +547,11 @@ section describes the propagation of data values.
### Implementing `Tasks.lookUp` callbacks
-There’s an example of implementing a `Tasks.lookUp` callback in [SkyValue lookups](#skyvalue-lookups). This section provides rationale and suggests
+There’s an example of implementing a `Tasks.lookUp` callback in [SkyValue
+lookups](#skyvalue-lookups). This section provides rationale and suggests
approaches for handling multiple SkyValues.
-#### `Tasks.lookUp` callbacks {#tasks-lookup-callbacks}
+#### `Tasks.lookUp` callbacks
The `Tasks.lookUp` method takes a callback, `sink`, as a parameter.
@@ -669,7 +672,7 @@ because the value types are different. When that’s not the case, falling back
lambda-based implementations or full inner-class instances that implement the
appropriate callbacks is viable.
-### Propagating values between `StateMachine`s {#propagating-values}
+### Propagating values between `StateMachine`s
So far, this document has only explained how to arrange work in a subtask, but
subtasks also need to report a values back to the caller. Since subtasks are
@@ -709,7 +712,8 @@ class BarProducer implements StateMachine {
Tip: It would be tempting to use the more concise signature void `accept(Bar
value)` rather than the stuttery `void acceptBarValue(Bar value)` above.
However, `Consumer` is a common overload of `void accept(Bar value)`,
-so doing this often leads to violations of the [Overloads: never split](https://google.github.io/styleguide/javaguide.html#s3.4.2-ordering-class-contents)
+so doing this often leads to violations of the [Overloads: never
+split](https://google.github.io/styleguide/javaguide.html#s3.4.2-ordering-class-contents)
style-guide rule.
Tip: Using a custom `ResultSink` type instead of a generic one from
@@ -772,11 +776,14 @@ pattern after accepting output from either a subtask or SkyValue lookup.
Note that the implementation of `acceptBarError` eagerly forwards the result to
the `Caller.ResultSink`, as required by [Error bubbling](#error-bubbling).
-Alternatives for top-level `StateMachine`s are described in [`Driver`s and bridging to SkyFunctions](#drivers-and-bridging).
+Alternatives for top-level `StateMachine`s are described in [`Driver`s and
+bridging to SkyFunctions](#drivers-and-bridging).
-### Error handling {#error-handling}
+### Error handling
-There's a couple of examples of error handling already in [`Tasks.lookUp` callbacks](#tasks-lookup-callbacks) and [Propagating values between `StateMachines`](#propagating-values). Exceptions, other than
+There's a couple of examples of error handling already in [`Tasks.lookUp`
+callbacks](#tasks-lookup-callbacks) and [Propagating values between
+`StateMachines`](#propagating-values). Exceptions, other than
`InterruptedException` are not thrown, but instead passed around through
callbacks as values. Such callbacks often have exclusive-or semantics, with
exactly one of a value or error being passed.
@@ -784,7 +791,7 @@ exactly one of a value or error being passed.
The next section describes a a subtle, but important interaction with Skyframe
error handling.
-#### Error bubbling (--nokeep\_going) {#error-bubbling}
+#### Error bubbling (--nokeep\_going)
Warning: Errors need to be eagerly propagated all the way back to the
SkyFunction for error bubbling to function correctly.
@@ -807,7 +814,7 @@ If a `Driver` is being utilized directly, it is essential to check for
propagated errors from the SkyFunction, even if the machine has not finished
processing.
-### Event Handling {#event-handling}
+### Event Handling
For SkyFunctions that need to emit events, a `StoredEventHandler` is injected
into SkyKeyComputeState and further injected into `StateMachine`s that require
@@ -816,7 +823,7 @@ certain events unless they are replayed but this was subsequently fixed.
`StoredEventHandler` injection is preserved because it simplifies the
implementation of events emitted from error handling callbacks.
-## `Driver`s and bridging to SkyFunctions {#drivers-and-bridging}
+## `Driver`s and bridging to SkyFunctions
A `Driver` is responsible for managing the execution of `StateMachine`s,
beginning with a specified root `StateMachine`. As `StateMachine`s can
@@ -931,7 +938,7 @@ private Result computeResult(State state, Skyfunction.Environment env)
}
```
-### Embedding `Driver` {#embedding-driver}
+### Embedding `Driver`
If the `StateMachine` produces a value and raises no exceptions, embedding
`Driver` is another possible implementation, as shown in the following example.
@@ -1054,7 +1061,7 @@ performance that approaches hand-written callback code.
## Appendix
-### Callback Hell {#callback-hell}
+### Callback Hell
Callback hell is an infamous problem in asynchronous code that uses callbacks.
It stems from the fact that the continuation for a subsequent step is nested
@@ -1107,7 +1114,7 @@ Callback hell may also occur if the [`runAfter` injection](#runafter-injection)
pattern is used too densely, but this can be avoided by interspersing injections
with sequential steps.
-#### Example: Chained SkyValue lookups {#chained-skyvalue-lookups}
+#### Example: Chained SkyValue lookups
It is often the case that the application logic requires dependent chains of
SkyValue lookups, for example, if a second SkyKey depends on the first SkyValue.
@@ -1179,7 +1186,8 @@ states. Where it is possible, local stack `step` variables are young generation
variables and efficiently GC'd.
For `StateMachine` variables, breaking things down into subtasks and following
-the recommended pattern for [Propagating values between `StateMachine`s](#propagating-values) is also helpful. Observe that when
+the recommended pattern for [Propagating values between
+`StateMachine`s](#propagating-values) is also helpful. Observe that when
following the pattern, only child `StateMachine`s have references to parent
`StateMachine`s and not vice versa. This means that as children complete and
update the parents using result callbacks, the children naturally fall out of
@@ -1199,9 +1207,10 @@ state sequence `foo`, followed by `bar`. `foo` no longer includes the behavior
`bar`. As a result, method names for states tend to be narrower in scope,
potentially reflecting local behavior.
-### Concurrency tree diagram {#concurrency-tree-diagram}
+### Concurrency tree diagram
-The following is an alternative view of the diagram in [Structured concurrency](#structured-concurrency) that better depicts the tree structure.
+The following is an alternative view of the diagram in [Structured
+concurrency](#structured-concurrency) that better depicts the tree structure.
The blocks form a small tree.
diff --git a/contribute/windows-chocolatey-maintenance.mdx b/contribute/windows-chocolatey-maintenance.mdx
index d961d471..c6aee8fb 100644
--- a/contribute/windows-chocolatey-maintenance.mdx
+++ b/contribute/windows-chocolatey-maintenance.mdx
@@ -7,7 +7,7 @@ title: 'Maintaining Bazel Chocolatey package on Windows'
Note: The Chocolatey package is experimental; please provide feedback
(`@petemounce` in issue tracker).
-## Prerequisites {#prerequisites}
+## Prerequisites
You need:
@@ -19,7 +19,7 @@ You need:
* (to publish) to have set up that API key for the chocolatey source locally
via `choco apikey -k -s https://chocolatey.org/`
-## Build {#build}
+## Build
Compile bazel with msys2 shell and `compile.sh`.
@@ -34,7 +34,7 @@ created.
The `build.ps1` script supports `mode` values `local`, `rc` and `release`.
-## Test {#test}
+## Test
0. Build the package (with `-mode local`)
@@ -56,7 +56,7 @@ The `build.ps1` script supports `mode` values `local`, `rc` and `release`.
Chocolatey's moderation process automates checks here as well.
-## Release {#release}
+## Release
Modify `tools/parameters.json` for the new release's URI and checksum once the
release has been published to github releases.
diff --git a/contribute/windows-scoop-maintenance.mdx b/contribute/windows-scoop-maintenance.mdx
index eb607de8..58e2a6c4 100644
--- a/contribute/windows-scoop-maintenance.mdx
+++ b/contribute/windows-scoop-maintenance.mdx
@@ -7,7 +7,7 @@ title: 'Maintaining Bazel Scoop package on Windows'
Note: The Scoop package is experimental. To provide feedback, go to
`@excitoon` in issue tracker.
-## Prerequisites {#prerequisites}
+## Prerequisites
You need:
@@ -19,7 +19,7 @@ You need:
[e-mail](mailto:vladimir.chebotarev@gmail.com) or
[Telegram](http://telegram.me/excitoon).
-## Release process {#release-process}
+## Release process
Scoop packages are very easy to maintain. Once you have the URL of released
Bazel, you need to make appropriate changes in
diff --git a/docs/android-build-performance.mdx b/docs/android-build-performance.mdx
index e94f77e6..0d5edc77 100644
--- a/docs/android-build-performance.mdx
+++ b/docs/android-build-performance.mdx
@@ -8,7 +8,7 @@ This page contains information on optimizing build performance for Android
apps specifically. For general build performance optimization with Bazel, see
[Optimizing Performance](/rules/performance).
-## Recommended flags {#recommended-flags}
+## Recommended flags
The flags are in the
[`bazelrc` configuration syntax](/run/bazelrc#bazelrc-syntax-semantics), so
diff --git a/docs/android-instrumentation-test.mdx b/docs/android-instrumentation-test.mdx
index e7be4e54..14d95bd3 100644
--- a/docs/android-instrumentation-test.mdx
+++ b/docs/android-instrumentation-test.mdx
@@ -4,7 +4,8 @@ title: 'Android Instrumentation Tests'
-_If you're new to Bazel, start with the [Building Android with Bazel](/start/android-app) tutorial._
+_If you're new to Bazel, start with the [Building Android with
+Bazel](/start/android-app ) tutorial._
@@ -19,11 +20,13 @@ emulators in a sandbox, ensuring that tests always run from a clean state. Each
test gets an isolated emulator instance, allowing tests to run in parallel
without passing states between them.
-For more information on Android instrumentation tests, check out the [Android developer documentation](https://developer.android.com/training/testing/unit-testing/instrumented-unit-tests.html).
+For more information on Android instrumentation tests, check out the [Android
+developer
+documentation](https://developer.android.com/training/testing/unit-testing/instrumented-unit-tests.html).
Please file issues in the [GitHub issue tracker](https://github.com/bazelbuild/bazel/issues).
-## How it works {#how-it-works}
+## How it works
When you run `bazel test` on an `android_instrumentation_test` target for the
first time, Bazel performs the following steps:
@@ -40,7 +43,7 @@ In subsequent test runs, Bazel boots the emulator from the clean, cached state
created in step 2, so there are no leftover states from previous runs. Caching
emulator state also speeds up test runs.
-## Prerequisites {#prerequisites}
+## Prerequisites
Ensure your environment satisfies the following prerequisites:
@@ -57,7 +60,8 @@ This results in output similar to the following:
release 4.1.0
```
-- **KVM**. Bazel requires emulators to have [hardware acceleration](https://developer.android.com/studio/run/emulator-acceleration.html#accel-check)
+- **KVM**. Bazel requires emulators to have [hardware
+ acceleration](https://developer.android.com/studio/run/emulator-acceleration.html#accel-check)
with KVM on Linux. You can follow these
[installation instructions](https://help.ubuntu.com/community/KVM/Installation)
for Ubuntu.
@@ -103,7 +107,7 @@ The output is the following:
sudo apt-get install libc6:i386 libncurses5:i386 libstdc++6:i386 lib32z1 libbz2-1.0:i386
```
-## Getting started {#getting-started}
+## Getting started
Here is a typical target dependency graph of an `android_instrumentation_test`:
@@ -112,7 +116,7 @@ Here is a typical target dependency graph of an `android_instrumentation_test`:
**Figure 2.** Target dependency graph of an `android_instrumentation_test`.
-### BUILD file {#build-file}
+### BUILD file
The graph translates into a `BUILD` file like this:
@@ -172,9 +176,11 @@ The main attributes of the rule `android_instrumentation_test` are:
- `target_device`: An `android_device` target. This target describes the
specifications of the Android emulator which Bazel uses to create, launch and
- run the tests. See the [section on choosing an Android device](#android-device-target) for more information.
+ run the tests. See the [section on choosing an Android
+ device](#android-device-target) for more information.
-The test app's `AndroidManifest.xml` must include [an `` tag](https://developer.android.com/studio/test/#configure_instrumentation_manifest_settings).
+The test app's `AndroidManifest.xml` must include [an ``
+tag](https://developer.android.com/studio/test/#configure_instrumentation_manifest_settings).
This tag must specify the attributes for the **package of the target app** and
the **fully qualified class name of the instrumentation test runner**,
`androidx.test.runner.AndroidJUnitRunner`.
@@ -203,7 +209,7 @@ Here is an example `AndroidTestManifest.xml` for the test app:
```
-### WORKSPACE dependencies {#workspace-dependencies}
+### WORKSPACE dependencies
In order to use this rule, your project needs to depend on these external
repositories:
@@ -211,7 +217,8 @@ repositories:
- `@androidsdk`: The Android SDK. Download this through Android Studio.
- `@android_test_support`: Hosts the test runner, emulator launcher, and
- `android_device` targets. You can find the [latest release here](https://github.com/android/android-test/releases).
+ `android_device` targets. You can find the [latest release
+ here](https://github.com/android/android-test/releases).
Enable these dependencies by adding the following lines to your `WORKSPACE`
file:
@@ -235,16 +242,17 @@ load("@android_test_support//:repo.bzl", "android_test_repositories")
android_test_repositories()
```
-## Maven dependencies {#maven-dependencies}
+## Maven dependencies
-For managing dependencies on Maven artifacts from repositories, such as [Google Maven](https://maven.google.com) or [Maven Central](https://central.maven.org),
+For managing dependencies on Maven artifacts from repositories, such as [Google
+Maven](https://maven.google.com) or [Maven Central](https://central.maven.org),
you should use a Maven resolver, such as
[`rules_jvm_external`](https://github.com/bazelbuild/rules_jvm_external).
The rest of this page shows how to use `rules_jvm_external` to
resolve and fetch dependencies from Maven repositories.
-## Choosing an android_device target {#android-device-target}
+## Choosing an android_device target
`android_instrumentation_test.target_device` specifies which Android device to
run the tests on. These `android_device` targets are defined in
@@ -299,7 +307,7 @@ bazel query 'filter("x86_qemu2$", kind(android_device, @android_test_support//to
Bazel currently supports x86-based emulators only. For better performance, use
`QEMU2` `android_device` targets instead of `QEMU` ones.
-## Running tests {#running-tests}
+## Running tests
To run tests, add these lines to your project's
`project root:/.bazelrc` file.
@@ -334,7 +342,7 @@ Then, use one of the configurations to run tests:
Use __only one configuration__ or tests will fail.
-### Headless testing {#headless-testing}
+### Headless testing
With `Xvfb`, it is possible to test with emulators without the graphical
interface, also known as headless testing. To disable the graphical interface
@@ -344,7 +352,7 @@ when running tests, pass the test argument `--enable_display=false` to Bazel:
bazel test //my/test:target --test_arg=--enable_display=false
```
-### GUI testing {#gui-testing}
+### GUI testing
If the `$DISPLAY` environment variable is set, it's possible to enable the
graphical interface of the emulator while the test is running. To do this, pass
@@ -354,7 +362,7 @@ these test arguments to Bazel:
bazel test //my/test:target --test_arg=--enable_display=true --test_env=DISPLAY
```
-### Testing with a local emulator or device {#testing-local-emulator}
+### Testing with a local emulator or device
Bazel also supports testing directly on a locally launched emulator or connected
device. Pass the flags
@@ -364,12 +372,13 @@ If there is more than one connected device, pass the flag
`--test_arg=--device_serial_number=$device_id` where `$device_id` is the id of
the device/emulator listed in `adb devices`.
-## Sample projects {#sample-projects}
+## Sample projects
-If you are looking for canonical project samples, see the [Android testing samples](https://github.com/googlesamples/android-testing#experimental-bazel-support)
+If you are looking for canonical project samples, see the [Android testing
+samples](https://github.com/googlesamples/android-testing#experimental-bazel-support)
for projects using Espresso and UIAutomator.
-## Espresso setup {#espresso-setup}
+## Espresso setup
If you write UI tests with [Espresso](https://developer.android.com/training/testing/espresso/)
(`androidx.test.espresso`), you can use the following snippets to set up your
@@ -451,9 +460,9 @@ android_binary(
)
```
-## Tips {#tips}
+## Tips
-### Reading test logs {#reading-test-logs}
+### Reading test logs
Use `--test_output=errors` to print logs for failing tests, or
`--test_output=all` to print all test output. If you're looking for an
@@ -521,7 +530,7 @@ $ tree bazel-testlogs/ui/espresso/BasicSample/BasicSampleInstrumentationTest
4 directories, 41 files
```
-### Reading emulator logs {#reading-emulator-logs}
+### Reading emulator logs
The emulator logs for `android_device` targets are stored in the `/tmp/`
directory with the name `emulator_xxxxx.log`, where `xxxxx` is a
@@ -533,7 +542,7 @@ Use this command to find the latest emulator log:
ls -1t /tmp/emulator_*.log | head -n 1
```
-### Testing against multiple API levels {#testing-multiple-apis}
+### Testing against multiple API levels
If you would like to test against multiple API levels, you can use a list
comprehension to create test targets for each API level. For example:
@@ -553,9 +562,10 @@ API_LEVELS = [
) for API_LEVEL in API_LEVELS]
```
-## Known issues {#known-issues}
+## Known issues
-- [Forked adb server processes are not terminated after tests](https://github.com/bazelbuild/bazel/issues/4853)
+- [Forked adb server processes are not terminated after
+ tests](https://github.com/bazelbuild/bazel/issues/4853)
- While APK building works on all platforms (Linux, macOS, Windows), testing
only works on Linux.
- Even with `--config=local_adb`, users still need to specify
diff --git a/docs/android-ndk.mdx b/docs/android-ndk.mdx
index abd76409..00b73162 100644
--- a/docs/android-ndk.mdx
+++ b/docs/android-ndk.mdx
@@ -4,9 +4,10 @@ title: 'Using the Android Native Development Kit with Bazel'
-_If you're new to Bazel, please start with the [Building Android with Bazel](/start/android-app) tutorial._
+_If you're new to Bazel, please start with the [Building Android with
+Bazel](/start/android-app ) tutorial._
-## Overview {#overview}
+## Overview
Bazel can run in many different build configurations, including several that use
the Android Native Development Kit (NDK) toolchain. This means that normal
@@ -21,11 +22,11 @@ Android apps and uses
[`rules_android_ndk`](https://github.com/bazelbuild/rules_android_ndk) for NDK
toolchain discovery and registration.
-## Prerequisites {#prerequisites}
+## Prerequisites
Please ensure that you have installed the Android SDK and NDK.
-### NDK and SDK setup {#ndk-sdk-setup}
+### NDK and SDK setup
External repository setup varies depending on whether you are using WORKSPACE
or bzlmod (MODULE.bazel). *Bzlmod is the preferred solution for Bazel 7+.*
@@ -34,7 +35,7 @@ each other.
If you are using one dependency management solution, you don't need to add
the boilerplate for the other.
-#### Bzlmod MODULE.bazel setup {#ndk-sdk-setup-bzlmod}
+#### Bzlmod MODULE.bazel setup
Add the following snippet to your MODULE.bazel:
@@ -56,7 +57,7 @@ use_repo(android_sdk_repository_extension, "androidsdk")
register_toolchains("@androidsdk//:sdk-toolchain", "@androidsdk//:all")
```
-#### Legacy WORKSPACE setup {#ndk-sdk-setup-workspace}
+#### Legacy WORKSPACE setup
Add the following snippet to your `WORKSPACE`:
@@ -84,7 +85,7 @@ Compatibility notes for WORKSPACE:
For more information about the `android_ndk_repository` rule, see its
[docstring](https://github.com/bazelbuild/rules_android_ndk/blob/7b4300f6d731139ca097f3332a5aebae5b0d91d0/rules.bzl#L18-L25).
-## Quick start {#quick-start}
+## Quick start
To build C++ for Android, simply add `cc_library` dependencies to your
`android_binary` or `android_library` rules.
@@ -154,9 +155,10 @@ targeted the architectures specified by `--android_platforms`.
See the section on [configuring the target ABI](#configuring-target-abi) for
more details.
-## Example setup {#example-setup}
+## Example setup
-This example is available in the [Bazel examples repository](https://github.com/bazelbuild/examples/tree/master/android/ndk).
+This example is available in the [Bazel examples
+repository](https://github.com/bazelbuild/examples/tree/master/android/ndk).
In the `BUILD.bazel` file, three targets are defined with the `android_binary`,
`android_library`, and `cc_library` rules.
@@ -207,7 +209,7 @@ public class MainActivity extends AppCompatActivity {
Note: The name of the native library is derived from the name of the top
level `android_binary` target. In this example, it is `app`.
-## Configuring the target ABI {#configuring-target-abi}
+## Configuring the target ABI
To configure the target ABI, use the `--android_platforms` flag as follows:
@@ -263,7 +265,7 @@ for more information on these ABIs.
Multi-ABI Fat APKs are not recommended for release builds since they increase
the size of the APK, but can be useful for development and QA builds.
-## Selecting a C++ standard {#selecting-c-standard}
+## Selecting a C++ standard
Use the following flags to build according to a C++ standard:
@@ -295,7 +297,7 @@ cc_library(
)
```
-## Building a `cc_library` for Android without using `android_binary` {#cclibrary-android}
+## Building a `cc_library` for Android without using `android_binary`
To build a standalone `cc_binary` or `cc_library` for Android without using an
`android_binary`, use the `--platforms` flag.
diff --git a/docs/bazel-and-android.mdx b/docs/bazel-and-android.mdx
index d447f3f9..bf3625c9 100644
--- a/docs/bazel-and-android.mdx
+++ b/docs/bazel-and-android.mdx
@@ -8,17 +8,17 @@ This page contains resources that help you use Bazel with Android projects. It
links to a tutorial, build rules, and other information specific to building
Android projects with Bazel.
-## Getting started {#getting-started}
+## Getting started
The following resources will help you work with Bazel on Android projects:
-* [Tutorial: Building an Android app](/start/android-app). This
+* [Tutorial: Building an Android app](/start/android-app ). This
tutorial is a good place to start learning about Bazel commands and concepts,
and how to build Android apps with Bazel.
* [Codelab: Building Android Apps with Bazel](https://developer.android.com/codelabs/bazel-android-intro#0).
This codelab explains how to build Android apps with Bazel.
-## Features {#features}
+## Features
Bazel has Android rules for building and testing Android apps, integrating with
the SDK/NDK, and creating emulator images. There are also Bazel plugins for
@@ -39,7 +39,7 @@ Android Studio and IntelliJ.
* [Android build performance](/docs/android-build-performance). This page
provides information on optimizing build performance for Android apps.
-## Further reading {#further-reading}
+## Further reading
* Integrating with dependencies from Google Maven and Maven Central with [rules_jvm_external](https://github.com/bazelbuild/rules_jvm_external).
* Learn [How Android Builds Work in Bazel](https://blog.bazel.build/2018/02/14/how-android-builds-work-in-bazel.html).
diff --git a/docs/bazel-and-apple.mdx b/docs/bazel-and-apple.mdx
index 3024f4ea..6e4a06fe 100644
--- a/docs/bazel-and-apple.mdx
+++ b/docs/bazel-and-apple.mdx
@@ -8,7 +8,7 @@ This page contains resources that help you use Bazel to build macOS and iOS
projects. It links to a tutorial, build rules, and other information specific to
using Bazel to build and test for those platforms.
-## Working with Bazel {#working-with-bazel}
+## Working with Bazel
The following resources will help you work with Bazel on macOS and iOS projects:
@@ -17,14 +17,14 @@ The following resources will help you work with Bazel on macOS and iOS projects:
* [General Apple rules](https://github.com/bazelbuild/rules_apple)
* [Integration with Xcode](/install/ide)
-## Migrating to Bazel {#migrating-to-bazel}
+## Migrating to Bazel
If you currently build your macOS and iOS projects with Xcode, follow the steps
in the migration guide to start building them with Bazel:
* [Migrating from Xcode to Bazel](/migrate/xcode)
-## Apple apps and new rules {#apple-apps-new-rules}
+## Apple apps and new rules
**Note**: Creating new rules is for advanced build and test scenarios.
You do not need it when getting started with Bazel.
@@ -50,7 +50,7 @@ when building your macOS and iOS projects:
* [`ObjcProvider`](/rules/lib/providers/ObjcProvider)
* [`XcodeVersionConfig`](/rules/lib/providers/XcodeVersionConfig)
-## Xcode selection {#xcode-selection}
+## Xcode selection
If your build requires Xcode, Bazel will select an appropriate version based on
the `--xcode_config` and `--xcode_version` flags. The `--xcode_config` consumes
diff --git a/docs/bazel-and-cpp.mdx b/docs/bazel-and-cpp.mdx
index ee12316b..73e502cb 100644
--- a/docs/bazel-and-cpp.mdx
+++ b/docs/bazel-and-cpp.mdx
@@ -8,7 +8,7 @@ This page contains resources that help you use Bazel with C++ projects. It links
to a tutorial, build rules, and other information specific to building C++
projects with Bazel.
-## Working with Bazel {#working-with-bazel}
+## Working with Bazel
The following resources will help you work with Bazel on C++ projects:
@@ -23,12 +23,12 @@ The following resources will help you work with Bazel on C++ projects:
* [Tutorial: Configuring C++ toolchains](/tutorials/ccp-toolchain-config)
* [Integrating with C++ rules](/configure/integrate-cpp)
-## Best practices {#best-practices}
+## Best practices
In addition to [general Bazel best practices](/configure/best-practices), below are
best practices specific to C++ projects.
-### BUILD files {#build-files}
+### BUILD files
Follow the guidelines below when creating your BUILD files:
@@ -64,7 +64,7 @@ Follow the guidelines below when creating your BUILD files:
)
```
-### Include paths {#include-paths}
+### Include paths
Follow these guidelines for include paths:
@@ -82,7 +82,7 @@ Follow these guidelines for include paths:
[`strip_include_prefix`](/reference/be/c-cpp#cc_library.strip_include_prefix)
arguments on the `cc_library` rule target.
-### Toolchain features {#toolchain-features}
+### Toolchain features
The following optional [features](/docs/cc-toolchain-config-reference#features)
can improve the hygiene of a C++ project. They can be enabled using the
diff --git a/docs/bazel-and-java.mdx b/docs/bazel-and-java.mdx
index cc456800..bd5af010 100644
--- a/docs/bazel-and-java.mdx
+++ b/docs/bazel-and-java.mdx
@@ -8,21 +8,21 @@ This page contains resources that help you use Bazel with Java projects. It
links to a tutorial, build rules, and other information specific to building
Java projects with Bazel.
-## Working with Bazel {#working-with-bazel}
+## Working with Bazel
The following resources will help you work with Bazel on Java projects:
* [Tutorial: Building a Java Project](/start/java)
* [Java rules](/reference/be/java)
-## Migrating to Bazel {#migrating-to-bazel}
+## Migrating to Bazel
If you currently build your Java projects with Maven, follow the steps in the
migration guide to start building your Maven projects with Bazel:
* [Migrating from Maven to Bazel](/migrate/maven)
-## Java versions {#java-versions}
+## Java versions
There are two relevant versions of Java that are set with configuration flags:
@@ -30,7 +30,7 @@ There are two relevant versions of Java that are set with configuration flags:
* the version of the Java runtime that is used to execute the code and to test
it
-### Configuring the version of the source code in your repository {#config-source-code}
+### Configuring the version of the source code in your repository
Without an additional configuration, Bazel assumes all Java source files in the
repository are written in a single Java version. To specify the version of the
@@ -40,7 +40,7 @@ should set this flag so that Bazel and its users can reference the source code's
Java version number. For more details, see
[Java language version flag](/docs/user-manual#java-language-version).
-### Configuring the JVM used to execute and test the code {#config-jvm}
+### Configuring the JVM used to execute and test the code
Bazel uses one JDK for compilation and another JVM to execute and test the code.
@@ -55,14 +55,14 @@ machine.
To configure the JVM used for execution and testing use `--java_runtime_version`
flag. The default value is `local_jdk`.
-### Hermetic testing and compilation {#hermetic-testing}
+### Hermetic testing and compilation
To create a hermetic compile, you can use command line flag
`--java_runtime_version=remotejdk_11`. The code is compiled for, executed, and
tested on the JVM downloaded from a remote repository. For more details, see
[Java runtime version flag](/docs/user-manual#java_runtime_version).
-### Configuring compilation and execution of build tools in Java {#config-build-tools-java}
+### Configuring compilation and execution of build tools in Java
There is a second pair of JDK and JVM used to build and execute tools, which are
used in the build process, but are not in the build results. That JDK and JVM
@@ -70,7 +70,7 @@ are controlled using `--tool_java_language_version` and
`--tool_java_runtime_version`. Default values are `11` and `remotejdk_11`,
respectively.
-#### Compiling using locally installed JDK {#compile-using-jdk}
+#### Compiling using locally installed JDK
Bazel by default compiles using remote JDK, because it is overriding JDK's
internals. The compilation toolchains using locally installed JDK are configured,
@@ -83,17 +83,17 @@ however, mind that this may not work on JDK of arbitrary vendors.
For more details, see
[configuring Java toolchains](#config-java-toolchains).
-## Best practices {#best-practices}
+## Best practices
In addition to [general Bazel best practices](/configure/best-practices), below are
best practices specific to Java projects.
-### Directory structure {#directory-structure}
+### Directory structure
Prefer Maven's standard directory layout (sources under `src/main/java`, tests
under `src/test/java`).
-### BUILD files {#build-files}
+### BUILD files
Follow these guidelines when creating your `BUILD` files:
@@ -121,7 +121,7 @@ Follow these guidelines when creating your `BUILD` files:
* Tests should be in a matching directory under `src/test` and depend on this
library.
-## Creating new rules for advanced Java builds {#rules-advanced-java-builds}
+## Creating new rules for advanced Java builds
**Note**: Creating new rules is for advanced build and test scenarios. You do
not need it when getting started with Bazel.
@@ -141,7 +141,7 @@ projects:
* [`JavaRuntimeInfo`](/rules/lib/providers/JavaRuntimeInfo)
* [`JavaToolchainInfo`](/rules/lib/providers/JavaToolchainInfo)
-## Configuring the Java toolchains {#config-java-toolchains}
+## Configuring the Java toolchains
Bazel uses two types of Java toolchains:
@@ -150,7 +150,7 @@ Bazel uses two types of Java toolchains:
* compilation, used to compile Java sources, controlled with the
`--java_language_version` flag
-### Configuring additional execution toolchains {#config-execution-toolchains}
+### Configuring additional execution toolchains
Execution toolchain is the JVM, either local or from a repository, with some
additional information about its version, operating system, and CPU
@@ -197,7 +197,7 @@ use_repo(custom_jdk, "openjdk_canary_linux_arm", "openjdk_canary_linux_arm_toolc
register_toolchains("@openjdk_canary_linux_arm_toolchain_config_repo//:all")
```
-### Configuring additional compilation toolchains {#config-compilation-toolchains}
+### Configuring additional compilation toolchains
Compilation toolchain is composed of JDK and multiple tools that Bazel uses
during the compilation and that provides additional features, such as: Error
@@ -279,7 +279,7 @@ Predefined configurations:
built from sources (this may be useful on operating system with different
libc)
-#### Configuring JVM and Java compiler flags {#config-jvm-flags}
+#### Configuring JVM and Java compiler flags
You may configure JVM and javac flags either with flags or with
`default_java_toolchain` attributes.
@@ -290,7 +290,7 @@ The relevant flags are `--jvmopt`, `--host_jvmopt`, `--javacopt`, and
The relevant `default_java_toolchain` attributes are `javacopts`, `jvm_opts`,
`javabuilder_jvm_opts`, and `turbine_jvm_opts`.
-#### Package specific Java compiler flags configuration {#package-java-compiler-flags}
+#### Package specific Java compiler flags configuration
You can configure different Java compiler flags for specific source
files using `package_configuration` attribute of `default_java_toolchain`.
@@ -327,7 +327,7 @@ package_group(
)
```
-#### Multiple versions of Java source code in a single repository {#java-source-single-repo}
+#### Multiple versions of Java source code in a single repository
Bazel only supports compiling a single version of Java sources in a build.
build. This means that when building a Java test or an application, all
diff --git a/docs/cc-toolchain-config-reference.mdx b/docs/cc-toolchain-config-reference.mdx
index dade7b66..e34eb846 100644
--- a/docs/cc-toolchain-config-reference.mdx
+++ b/docs/cc-toolchain-config-reference.mdx
@@ -2,7 +2,7 @@
title: 'C++ Toolchain Configuration'
---
-## Overview {#overview}
+## Overview
To invoke the compiler with the right options, Bazel needs some knowledge about
the compiler internals, such as include directories and important flags.
@@ -59,7 +59,7 @@ The artifacts to be shipped to the sandbox are declared in the `cc_toolchain`
target. For example, with the `cc_toolchain.linker_files` attribute you can
specify the linker binary and toolchain libraries to ship into the sandbox.
-## Toolchain selection {#toolchain-selection}
+## Toolchain selection
The toolchain selection logic operates as follows:
@@ -93,7 +93,7 @@ fully fledged C++ features in Bazel without modifying the
Bazel binary. C++ rules support multiple unique actions documented in detail
[in the Bazel source code](https://source.bazel.build/bazel/+/4f547a7ea86df80e4c76145ffdbb0c8b75ba3afa:tools/build_defs/cc/action_names.bzl).
-## Features {#features}
+## Features
A feature is an entity that requires command-line flags, actions,
constraints on the execution environment, or dependency alterations. A feature
@@ -121,7 +121,7 @@ A feature is enabled in one of the following ways:
Features can have interdependencies, depend on command line flags, `BUILD` file
settings, and other variables.
-### Feature relationships {#feature-relationships}
+### Feature relationships
Dependencies are typically managed directly with Bazel, which simply enforces
the requirements and manages conflicts intrinsic to the nature of the features
@@ -130,25 +130,23 @@ constraints for use directly within the Starlark rule that govern feature
support and expansion. These are:
- Feature-level. The feature is supported only if the specified required
+
Feature-level. The feature is supported only if the specified required
features are enabled. For example, when a feature is only supported in
certain build modes (opt, dbg, or
fastbuild). If `requires` contains multiple `feature_set`s
@@ -157,47 +155,35 @@ requires = [
-
implies = ['feature']
-
-
- Feature-level. This feature implies the specified feature(s).
+
implies = ['feature']
+
+
Feature-level. This feature implies the specified feature(s).
Enabling a feature also implicitly enables all features implied by it
- (that is, it functions recursively).
-
-
- Also provides the ability to factor common subsets of functionality out of
+ (that is, it functions recursively).
+
Also provides the ability to factor common subsets of functionality out of
a set of features, such as the common parts of sanitizers. Implied
- features cannot be disabled.
-
+ features cannot be disabled.
-
provides = ['feature']
-
-
- Feature-level. Indicates that this feature is one of several mutually
+
provides = ['feature']
+
+
Feature-level. Indicates that this feature is one of several mutually
exclusive alternate features. For example, all of the sanitizers could
- specify provides = ["sanitizer"].
-
-
- This improves error handling by listing the alternatives if the user asks
- for two or more mutually exclusive features at once.
-
+ specify provides = ["sanitizer"].
+
This improves error handling by listing the alternatives if the user asks
+ for two or more mutually exclusive features at once.
- Flag set-level. A feature can specify multiple flag sets with multiple.
+
Flag set-level. A feature can specify multiple flag sets with multiple.
When with_features is specified, the flag set will only expand
to the build command if there is at least one with_feature_set
for which all of the features in the specified features set
@@ -209,7 +195,7 @@ with_features = [
-## Actions {#actions}
+## Actions
Actions provide the flexibility to modify the circumstances under
which an action executes without assuming how the action will be run. An
@@ -230,117 +216,149 @@ that implements an action (such as `CppCompileAction`). In particular, the
"assembler actions" and "compiler actions" in the table below are
`CppCompileAction`, while the link actions are `CppLinkAction`.
-### Assembler actions {#assembler-actions}
+### Assembler actions
-
-
+
+
-
Action
-
Description
+
Action
+
+
Description
+
-
preprocess-assemble
-
Assemble with preprocessing. Typically for .S files.
+
preprocess-assemble
+
+
Assemble with preprocessing. Typically for .S files.
+
-
assemble
-
Assemble without preprocessing. Typically for .s files.
+
assemble
+
+
Assemble without preprocessing. Typically for .s files.
+
- Run the compiler's parser on a header file to ensure that the header is
+
c++-header-parsing
+
+
Run the compiler's parser on a header file to ensure that the header is
self-contained, as it will otherwise produce compilation errors. Applies
only to toolchains that support modules.
-### Link actions {#link-actions}
+### Link actions
-
-
+
+
-
Action
-
Description
+
Action
+
+
Description
+
-
c++-link-dynamic-library
-
Link a shared library containing all of its dependencies.
+
c++-link-dynamic-library
+
+
Link a shared library containing all of its dependencies.
+
-
c++-link-nodeps-dynamic-library
-
Link a shared library only containing cc_library sources.
+
c++-link-nodeps-dynamic-library
+
+
Link a shared library only containing cc_library sources.
+
-
c++-link-executable
-
Link a final ready-to-run library.
+
c++-link-executable
+
+
Link a final ready-to-run library.
+
-### AR actions {#ar-actions}
+### AR actions
AR actions assemble object files into archive libraries (`.a` files) via `ar`
and encode some semantics into the name.
-
-
+
+
-
Action
-
Description
+
Action
+
+
Description
+
-
c++-link-static-library
-
Create a static library (archive).
+
c++-link-static-library
+
+
Create a static library (archive).
+
-### LTO actions {#lto-actions}
+### LTO actions
-
-
+
+
-
Action
-
Description
+
Action
+
+
Description
+
-
lto-backend
-
ThinLTO action compiling bitcodes into native objects.
+
lto-backend
+
+
ThinLTO action compiling bitcodes into native objects.
+
-
lto-index
-
ThinLTO action generating global index.
+
lto-index
+
+
ThinLTO action generating global index.
+
-## Using action_config {#using-action-config}
+## Using action_config
The `action_config` is a Starlark struct that describes a Bazel
action by specifying the tool (binary) to invoke during the action and sets of
@@ -350,39 +368,41 @@ execution.
The `action_config()` constructor has the following parameters:
-
-
+
+
-
Attribute
-
Description
+
Attribute
+
+
Description
+
-
action_name
-
- The Bazel action to which this action corresponds.
+
action_name
+
+
The Bazel action to which this action corresponds.
Bazel uses this attribute to discover per-action tool and execution
requirements.
-
tools
-
- The executable to invoke. The tool applied to the action will be the
+
tools
+
+
The executable to invoke. The tool applied to the action will be the
first tool in the list with a feature set that matches the feature
configuration. Default value must be provided.
-
flag_sets
-
- A list of flags that applies to a group of actions. Same as for a
+
flag_sets
+
+
A list of flags that applies to a group of actions. Same as for a
feature.
-
env_sets
-
- A list of environment constraints that applies to a group of actions.
+
env_sets
+
+
A list of environment constraints that applies to a group of actions.
Same as for a feature.
@@ -404,28 +424,30 @@ within the same toolchain. This prevents ambiguity in tool paths
and enforces the intention behind `action_config` - that an action's properties
are clearly described in a single place in the toolchain.
-### Using tool constructor {#using-tool-constructor}
+### Using tool constructor
An`action_config` can specify a set of tools via its `tools` parameter.
The `tool()` constructor takes in the following parameters:
-
-
+
+
-
Field
-
Description
+
Field
+
+
Description
+
-
path
-
- Path to the tool in question (relative to the current location).
+
path
+
+
Path to the tool in question (relative to the current location).
-
with_features
-
- A list of feature sets out of which at least one must be satisfied
+
with_features
+
+
A list of feature sets out of which at least one must be satisfied
for this tool to apply.
@@ -439,7 +461,7 @@ with a `with_feature` set matching the feature configuration is found
for more information). You should end your tool lists with a default
tool that corresponds to an empty feature configuration.
-### Example usage {#example-usage}
+### Example usage
Features and actions can be used together to implement Bazel actions
with diverse cross-platform semantics. For example, debug symbol generation on
@@ -531,7 +553,7 @@ follows:
),
]
-### Flag groups {#flag-groups}
+### Flag groups
`CcToolchainConfigInfo` allows you to bundle flags into groups that serve a
specific purpose. You can specify a flag within using pre-defined variables
@@ -577,9 +599,7 @@ A variable can repeat multiple times. For example:
expands to:
-```
-iprefix= -isystem= -iprefix= -isystem=
-```
Variables can correspond to structures accessible using dot-notation. For
example:
@@ -602,7 +622,7 @@ example:
],
)
-### Conditional expansion {#conditional-expansion}
+### Conditional expansion
Flag groups support conditional expansion based on the presence of a particular
variable or its field using the `expand_if_available`, `expand_if_not_available`,
@@ -634,12 +654,12 @@ Note: The `--whole_archive` and `--no_whole_archive` options are added to
the build command only when a currently iterated library has an
`is_whole_archive` field.
-## CcToolchainConfigInfo reference {#cctoolchainconfiginfo-reference}
+## CcToolchainConfigInfo reference
This section provides a reference of build variables, features, and other
information required to successfully configure C++ rules.
-### CcToolchainConfigInfo build variables {#cctoolchainconfiginfo-build-variables}
+### CcToolchainConfigInfo build variables
The following is a reference of `CcToolchainConfigInfo` build variables.
@@ -647,313 +667,365 @@ Note: The **Action** column indicates the relevant action type, if applicable.
-
Variable
-
Action
-
Description
+
Variable
+
+
Action
+
+
Description
+
-
source_file
+
source_file
+
compile
-
Source file to compile.
+
Source file to compile.
+
-
input_file
+
input_file
+
strip
-
Artifact to strip.
+
Artifact to strip.
+
-
output_file
+
output_file
+
compile, strip
-
Compilation output.
+
Compilation output.
+
-
output_assembly_file
+
output_assembly_file
+
compile
-
- Emitted assembly file. Applies only when the
+
Emitted assembly file. Applies only when the
compile action emits assembly text, typically when using the
--save_temps flag. The contents are the same as for
output_file.
-
output_preprocess_file
+
output_preprocess_file
+
compile
-
- Preprocessed output. Applies only to compile
+
Preprocessed output. Applies only to compile
actions that only preprocess the source files, typically when using the
--save_temps flag. The contents are the same as for
output_file.
-
includes
+
includes
+
compile
-
- Sequence of files the compiler must
+
Sequence of files the compiler must
unconditionally include in the compiled source.
-
include_paths
+
include_paths
+
compile
-
- Sequence directories in which the compiler
+
Sequence directories in which the compiler
searches for headers included using #include<foo.h>
and #include "foo.h".
-
quote_include_paths
+
quote_include_paths
+
compile
-
- Sequence of -iquote includes -
+
Sequence of -iquote includes -
directories in which the compiler searches for headers included using
#include "foo.h".
-
system_include_paths
+
system_include_paths
+
compile
-
- Sequence of -isystem includes -
+
Sequence of -isystem includes -
directories in which the compiler searches for headers included using
#include <foo.h>.
-
dependency_file
+
dependency_file
+
compile
-
The .d dependency file generated by the compiler.
+
The .d dependency file generated by the compiler.
+
-
preprocessor_defines
+
preprocessor_defines
+
compile
-
Sequence of defines, such as --DDEBUG.
+
Sequence of defines, such as --DDEBUG.
+
-
pic
+
pic
+
compile
-
Compiles the output as position-independent code.
+
Compiles the output as position-independent code.
+
-
gcov_gcno_file
+
gcov_gcno_file
+
compile
-
The gcov coverage file.
+
The gcov coverage file.
+
-
per_object_debug_info_file
+
per_object_debug_info_file
+
compile
-
The per-object debug info (.dwp) file.
+
The per-object debug info (.dwp) file.
+
-
stripopts
+
stripopts
+
strip
-
Sequence of stripopts.
+
Sequence of stripopts.
+
-
legacy_compile_flags
+
legacy_compile_flags
+
compile
-
- Sequence of flags from legacy
+
Sequence of flags from legacy
CROSSTOOL fields such as compiler_flag,
optional_compiler_flag, cxx_flag, and
optional_cxx_flag.
-
user_compile_flags
+
user_compile_flags
+
compile
-
- Sequence of flags from either the
+
Sequence of flags from either the
copt rule attribute or the --copt,
--cxxopt, and --conlyopt flags.
-
unfiltered_compile_flags
+
unfiltered_compile_flags
+
compile
-
- Sequence of flags from the
- unfiltered_cxx_flag legacy CROSSTOOL field or the
+
Sequence of flags from the
+ unfiltered_cxx_flag legacy CROSSTOOL field or the
unfiltered_compile_flags feature. These are not filtered by
the nocopts rule attribute.
-
sysroot
+
sysroot
+
-
The sysroot.
+
The sysroot.
+
-
runtime_library_search_directories
+
runtime_library_search_directories
+
link
-
- Entries in the linker runtime search path (usually
+
Entries in the linker runtime search path (usually
set with the -rpath flag).
-
library_search_directories
+
library_search_directories
+
link
-
- Entries in the linker search path (usually set with
+
Entries in the linker search path (usually set with
the -L flag).
-
libraries_to_link
+
libraries_to_link
+
link
-
Flags providing files to link as inputs in the linker invocation.
+
Flags providing files to link as inputs in the linker invocation.
+
-
def_file_path
+
def_file_path
+
link
-
Location of def file used on Windows with MSVC.
+
Location of def file used on Windows with MSVC.
+
-
linker_param_file
+
linker_param_file
+
link
-
- Location of linker param file created by bazel to
+
Location of linker param file created by bazel to
overcome command line length limit.
-
output_execpath
+
output_execpath
+
link
-
Execpath of the output of the linker.
+
Execpath of the output of the linker.
+
-
generate_interface_library
+
generate_interface_library
+
link
-
- "yes" or "no" depending on whether interface library should
+
"yes" or "no" depending on whether interface library should
be generated.
-
interface_library_builder_path
+
interface_library_builder_path
+
link
-
Path to the interface library builder tool.
+
Path to the interface library builder tool.
+
-
interface_library_input_path
+
interface_library_input_path
+
link
-
Input for the interface library ifso builder tool.
+
Input for the interface library ifso builder tool.
+
-
interface_library_output_path
+
interface_library_output_path
+
link
-
Path where to generate interface library using the ifso builder tool.
+
Path where to generate interface library using the ifso builder tool.
+
-
legacy_link_flags
+
legacy_link_flags
+
link
-
Linker flags coming from the legacy CROSSTOOL fields.
+
Linker flags coming from the legacy CROSSTOOL fields.
+
-
user_link_flags
+
user_link_flags
+
link
-
- Linker flags coming from the --linkopt
+
Linker flags coming from the --linkopt
or linkopts attribute.
-
linkstamp_paths
+
linkstamp_paths
+
link
-
A build variable giving linkstamp paths.
+
A build variable giving linkstamp paths.
+
-
force_pic
+
force_pic
+
link
-
- Presence of this variable indicates that PIC/PIE code should
+
Presence of this variable indicates that PIC/PIE code should
be generated (Bazel option `--force_pic` was passed).
-
strip_debug_symbols
+
strip_debug_symbols
+
link
-
- Presence of this variable indicates that the debug
+
Presence of this variable indicates that the debug
symbols should be stripped.
-
is_cc_test
link
-
- Truthy when current action is a cc_test
+
is_cc_test
+
+
link
+
Truthy when current action is a cc_test
linking action, false otherwise.
-
is_using_fission
+
is_using_fission
+
compile, link
-
- Presence of this variable indicates that fission (per-object debug info)
- is activated. Debug info will be in .dwo files instead
+
Presence of this variable indicates that fission (per-object debug info)
+ is activated. Debug info will be in .dwo files instead
of .o files and the compiler and linker need to know this.
-
fdo_instrument_path
+
fdo_instrument_path
+
compile, link
-
Path to the directory that stores FDO instrumentation profile.
+
Path to the directory that stores FDO instrumentation profile.
+
-
fdo_profile_path
+
fdo_profile_path
+
compile
-
Path to FDO profile.
+
Path to FDO profile.
+
-
fdo_prefetch_hints_path
+
fdo_prefetch_hints_path
+
compile
-
Path to the cache prefetch profile.
+
Path to the cache prefetch profile.
+
-
cs_fdo_instrument_path
+
cs_fdo_instrument_path
+
compile, link
-
- Path to the directory that stores context sensitive FDO
- instrumentation profile.
+
Path to the directory that stores context sensitive FDO
+ instrumentation profile.
-### Well-known features {#wellknown-features}
+### Well-known features
The following is a reference of features and their activation
conditions.
-
-
+
+
-
Feature
-
Documentation
+
Feature
+
+
Documentation
+
-
opt | dbg | fastbuild
-
Enabled by default based on compilation mode.
+
opt | dbg | fastbuild
+
+
Enabled by default based on compilation mode.
+
-
static_linking_mode | dynamic_linking_mode
-
Enabled by default based on linking mode.
+
static_linking_mode | dynamic_linking_mode
+
+
Enabled by default based on linking mode.
+
-
per_object_debug_info
-
- Enabled if the supports_fission feature is specified and
+
per_object_debug_info
+
+
Enabled if the supports_fission feature is specified and
enabled and the current compilation mode is specified in the
--fission flag.
-
supports_start_end_lib
-
- If enabled (and the option --start_end_lib is set), Bazel
+
supports_start_end_lib
+
+
If enabled (and the option --start_end_lib is set), Bazel
will not link against static libraries but instead use the
--start-lib/--end-lib linker options to link against objects
directly. This speeds up the build since Bazel doesn't have to build
@@ -961,25 +1033,25 @@ conditions.
-
supports_interface_shared_libraries
-
- If enabled (and the option --interface_shared_objects is
+
supports_interface_shared_libraries
+
+
If enabled (and the option --interface_shared_objects is
set), Bazel will link targets that have linkstatic set to
False (cc_tests by default) against interface shared
libraries. This makes incremental relinking faster.
-
supports_dynamic_linker
-
- If enabled, C++ rules will know the toolchain can produce shared
+
supports_dynamic_linker
+
+
If enabled, C++ rules will know the toolchain can produce shared
libraries.
-
static_link_cpp_runtimes
-
- If enabled, Bazel will link the C++ runtime statically in static linking
+
static_link_cpp_runtimes
+
+
If enabled, Bazel will link the C++ runtime statically in static linking
mode and dynamically in dynamic linking mode. Artifacts
specified in the cc_toolchain.static_runtime_lib or
cc_toolchain.dynamic_runtime_lib attribute (depending on the
@@ -987,21 +1059,24 @@ conditions.
-
supports_pic
-
- If enabled, toolchain will know to use PIC objects for dynamic libraries.
+
supports_pic
+
+
If enabled, toolchain will know to use PIC objects for dynamic libraries.
The `pic` variable is present whenever PIC compilation is needed. If not enabled
by default, and `--force_pic` is passed, Bazel will request `supports_pic` and
validate that the feature is enabled. If the feature is missing, or couldn't
- be enabled, `--force_pic` cannot be used.
+ be enabled, `--force_pic` cannot be used.
-
static_linking_mode | dynamic_linking_mode
+
+ static_linking_mode | dynamic_linking_mode
+
Enabled by default based on linking mode.
-
no_legacy_features
+
no_legacy_features
+
Prevents Bazel from adding legacy features to
the C++ configuration when present. See the complete list of
@@ -1009,14 +1084,15 @@ conditions.
-
shorten_virtual_includes
+
shorten_virtual_includes
+
If enabled, virtual include header files are linked under bin/_virtual_includes/<hash of target path> instead of bin/<target package path>/_virtual_includes/<target name>. Useful on Windows to avoid long path issue with MSVC.
-#### Legacy features patching logic {#legacy-features-patching-logic}
+#### Legacy features patching logic
Bazel applies the following changes to the toolchain's features for backwards
diff --git a/docs/configurable-attributes.mdx b/docs/configurable-attributes.mdx
index 8048f3a6..367317fb 100644
--- a/docs/configurable-attributes.mdx
+++ b/docs/configurable-attributes.mdx
@@ -4,14 +4,15 @@ title: 'Configurable Build Attributes'
-**_Configurable attributes_**, commonly known as [`select()`](/reference/be/functions#select), is a Bazel feature that lets users toggle the values
+**_Configurable attributes_**, commonly known as [`select()`](
+/reference/be/functions#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 {#configurable-build-example}
+## Example
```python
# myapp/BUILD
@@ -87,7 +88,7 @@ are *non-configurable*, and these are clearly annotated. For example,
`config_setting`'s own
[`values`](/reference/be/general#config_setting.values) attribute is non-configurable.
-## `select()` and dependencies {#select-and-dependencies}
+## `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
@@ -143,7 +144,7 @@ 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 {#configuration-conditions}
+## Configuration conditions
Each key in a configurable attribute is a label reference to a
[`config_setting`](/reference/be/general#config_setting) or
@@ -155,7 +156,7 @@ easy to maintain "standard" conditions users can reference from multiple places.
`constraint_value` provides support for [multi-platform behavior](#platforms).
-### Built-in flags {#built-in-flags}
+### 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
@@ -189,7 +190,7 @@ 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 {#custom-flags}
+### Custom flags
You can model your own project-specific flags with
[Starlark build settings][BuildSettings]. Unlike built-in flags, these are
@@ -225,7 +226,7 @@ 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 {#default-condition}
+## The default condition
The built-in condition `//conditions:default` matches when no other condition
matches.
@@ -261,7 +262,7 @@ Conditions checked:
For even clearer errors, you can set custom messages with `select()`'s
[`no_match_error`](#custom-error-messages) attribute.
-## Platforms {#platforms}
+## 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
@@ -363,7 +364,7 @@ check against single values.
Platforms are still under development. See the
[documentation](/concepts/platforms) for details.
-## Combining `select()`s {#combining-selects}
+## Combining `select()`s
`select` can appear multiple times in the same attribute:
@@ -409,9 +410,10 @@ sh_library(
)
```
-If you need a `select` to match when multiple conditions match, consider [AND chaining](#and-chaining).
+If you need a `select` to match when multiple conditions match, consider [AND
+chaining](#and-chaining).
-## OR chaining {#or-chaining}
+## OR chaining
Consider the following:
@@ -454,7 +456,7 @@ duplication.
For more direct support, use one of the following:
-### `selects.with_or` {#selects-with-or}
+### `selects.with_or`
The
[with_or](https://github.com/bazelbuild/bazel-skylib/blob/main/docs/selects_doc.md#selectswith_or)
@@ -477,7 +479,7 @@ sh_binary(
)
```
-### `selects.config_setting_group` {#selects-config-setting-or-group}
+### `selects.config_setting_group`
The
@@ -520,7 +522,7 @@ different attributes.
It's an error for multiple conditions to match unless one is an unambiguous
"specialization" of the others or they all resolve to the same value. See [here](#configurable-build-example) for details.
-## AND chaining {#and-chaining}
+## AND chaining
If you need a `select` branch to match when multiple conditions match, use the
[Skylib](https://github.com/bazelbuild/bazel-skylib) macro
@@ -552,7 +554,7 @@ sh_binary(
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 {#custom-error-messages}
+## Custom error messages
By default, when no condition matches, the target the `select()` is attached to
fails with the error:
@@ -587,7 +589,7 @@ ERROR: Configurable attribute "deps" doesn't match this configuration: Please
build with an Android or Windows toolchain
```
-## Rules compatibility {#rules-compatibility}
+## Rules compatibility
Rule implementations receive the *resolved values* of configurable
attributes. For example, given:
@@ -635,7 +637,7 @@ 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.
-## Bazel query and cquery {#query-and-cquery}
+## Bazel query and cquery
Bazel [`query`](/query/guide) operates over Bazel's
[loading phase](/reference/glossary#loading-phase).
@@ -696,9 +698,9 @@ $ bazel cquery 'deps(//myapp:my_lib)' --//myapp:dog_type=pug
//myapp:bar_dep
```
-## FAQ {#faq}
+## FAQ
-### Why doesn't select() work in macros? {#faq-select-macro}
+### Why doesn't select() work in macros?
select() *does* work in rules! See [Rules compatibility](#rules-compatibility) for
details.
@@ -810,7 +812,7 @@ 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.
```
-### Why does select() always return true? {#faq-boolean-select}
+### Why does select() always return true?
Because *macros* (but not rules) by definition
[can't evaluate `select()`s](#faq-select-macro), any attempt to do so
@@ -856,7 +858,7 @@ So what they're really evaluting is the `select()` object itself. According to
standards, all objects aside from a very small number of exceptions
automatically return true.
-### Can I read select() like a dict? {#faq-inspectable-select}
+### Can I read select() like a dict?
Macros [can't](#faq-select-macro) evaluate select(s) because macros evaluate before
Bazel knows what the build's command line parameters are. Can they at least read
@@ -912,7 +914,7 @@ def selecty_genrule(name, select_cmd):
)
```
-### Why doesn't select() work with bind()? {#faq-select-bind}
+### Why doesn't select() work with bind()?
First of all, do not use `bind()`. It is deprecated in favor of `alias()`.
@@ -961,7 +963,7 @@ located at `@alternative//:ssl`.
But really, stop using `bind()`.
-### Why doesn't my select() choose what I expect? {#faq-select-choose-condition}
+### 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](/query/cquery) and `bazel config` to debug:
@@ -1012,7 +1014,7 @@ 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.
-### Why doesn't `select()` work with platforms? {#faq-select-platforms}
+### Why doesn't `select()` work with platforms?
Bazel doesn't support configurable attributes checking whether a given platform
is the target platform because the semantics are unclear.
diff --git a/docs/mobile-install.mdx b/docs/mobile-install.mdx
index 5039aa75..8bc4a679 100644
--- a/docs/mobile-install.mdx
+++ b/docs/mobile-install.mdx
@@ -11,7 +11,7 @@ This page describes how `bazel mobile-install` makes iterative development
for Android much faster. It describes the benefits of this approach versus the
drawbacks of separate build and install steps.
-## Summary {#summary}
+## Summary
To install small changes to an Android app very quickly, do the following:
@@ -36,7 +36,7 @@ When in doubt, look at the
contact us on [Google Groups](https://groups.google.com/forum/#!forum/bazel-discuss),
or [file a GitHub issue](https://github.com/bazelbuild/rules_android/issues)
-## Introduction {#introduction}
+## Introduction
One of the most important attributes of a developer's toolchain is speed: there
is a world of difference between changing the code and seeing it run within a
@@ -52,7 +52,7 @@ change was not unusual on larger projects like Google Maps.
using a combination of change pruning, work sharding, and clever manipulation of
Android internals, all without changing any of your app's code.
-## Problems with traditional app installation {#problems-app-install}
+## Problems with traditional app installation
Building an Android app has some issues, including:
@@ -73,7 +73,7 @@ time. This is a good tradeoff for users because they typically install an app
once and use it many times, but results in slower development where an app is
installed many times and each version is run at most a handful of times.
-## The approach of `bazel mobile-install` {#approach-mobile-install}
+## The approach of `bazel mobile-install`
`bazel mobile-install `makes the following improvements:
@@ -94,7 +94,7 @@ installed many times and each version is run at most a handful of times.
tool to combine sharded APKs on the connected device and provide a cohesive
experience.
-### Sharded Dexing {#sharded-dexing}
+### Sharded Dexing
Sharded dexing is reasonably straightforward: once the .jar files are built, a
[tool](https://github.com/bazelbuild/rules_android/blob/main/src/tools/java/com/google/devtools/build/android/ziputils/DexMapper.java)
@@ -122,7 +122,7 @@ app. Generally speaking, the more shards, the faster the build and the
installation will be, but the slower app startup becomes, because the dynamic
linker has to do more work. The sweet spot is usually between 10 and 50 shards.
-### Incremental deployment {#incremental-deployment}
+### Incremental deployment
Incremental APK shard transfer and installation is now handled by the
`apkdeployer` utility described in ["The approach of mobile-install"](#approach-mobile-install).
@@ -145,9 +145,9 @@ See the [`ApkPreInstaller`](https://cs.android.com/android-studio/platform/tools
and [`ApkInstaller`](https://cs.android.com/android-studio/platform/tools/base/+/mirror-goog-studio-main:deploy/deployer/src/main/java/com/android/tools/deployer/ApkInstaller.java)
classes for implementation details.
-## Results {#results}
+## Results
-### Performance {#performance}
+### Performance
In general, `bazel mobile-install` results in a 4x to 10x speedup of building
and installing large apps after a small change.
@@ -159,7 +159,7 @@ The following numbers were computed for a few Google products:
This, of course, depends on the nature of the change: recompilation after
changing a base library takes more time.
-### Limitations {#limitations}
+### Limitations
The tricks the stub application plays don't work in every case.
The following cases highlight where it does not work as expected:
@@ -180,7 +180,7 @@ The following cases highlight where it does not work as expected:
flags inform Bazel where the Starlark mobile-install aspect is and which
rules are supported.
-### A brief history of mobile-install {#mobile-install-history}
+### A brief history of mobile-install
Earlier Bazel versions _natively_ included built-in build and test rules for
popular languages and ecosystems such as C++, Java, and Android. These rules
were therefore referred to as _native_ rules. Bazel 8 (released in 2024) removed
diff --git a/docs/sandboxing.mdx b/docs/sandboxing.mdx
index aaadcd79..68697953 100644
--- a/docs/sandboxing.mdx
+++ b/docs/sandboxing.mdx
@@ -28,7 +28,7 @@ generated outputs. Bazel then uses an operating-system-provided technique,
containers on Linux and `sandbox-exec` on macOS, to constrain the action within
`execroot/`.
-## Reasons for sandboxing {#sandboxing-reasons}
+## Reasons for sandboxing
- Without action sandboxing, Bazel doesn't know if a tool uses undeclared
input files (files that are not explicitly listed in the dependencies of an
@@ -47,10 +47,10 @@ containers on Linux and `sandbox-exec` on macOS, to constrain the action within
having to install the tools on every machine in the cluster every time you
want to try out a new compiler or make a change to an existing tool.
-## What sandbox strategy to use {#sandboxing-strategies}
+## What sandbox strategy to use
You can choose which kind of sandboxing to use, if any, with the
-[strategy flags](/docs/user-manual#strategy-options). Using the `sandboxed`
+[strategy flags](user-manual.html#strategy-options). Using the `sandboxed`
strategy makes Bazel pick one of the sandbox implementations listed below,
preferring an OS-specific sandbox to the less hermetic generic one.
[Persistent workers](/remote/persistent) run in a generic sandbox if you pass
@@ -100,7 +100,7 @@ Dynamic execution usually requires sandboxing for local execution. To opt out,
pass the `--experimental_local_lockfree_output` flag. Dynamic execution silently
sandboxes [persistent workers](/remote/persistent).
-## Downsides to sandboxing {#sandboxing_downsides}
+## Downsides to sandboxing
- Sandboxing incurs extra setup and teardown cost. How big this cost is
depends on many factors, including the shape of the build and the
@@ -116,11 +116,11 @@ sandboxes [persistent workers](/remote/persistent).
to be sandboxed. Workers that do not support multiplex sandboxing run as
singleplex workers under dynamic execution, which can cost extra memory.
-## Debugging {#debugging}
+## Debugging
Follow the strategies below to debug issues with sandboxing.
-### Deactivated namespaces {#deactivated-namespaces}
+### Deactivated namespaces
On some platforms, such as
[Google Kubernetes Engine](https://cloud.google.com/kubernetes-engine/)
@@ -132,14 +132,14 @@ exists and contains a 0, you can activate user namespaces by running:
sudo sysctl kernel.unprivileged_userns_clone=1
```
-### Rule execution failures {#rule-failures}
+### Rule execution failures
The sandbox may fail to execute rules because of the system setup. If you see a
message like `namespace-sandbox.c:633: execvp(argv[0], argv): No such file or
directory`, try to deactivate the sandbox with `--strategy=Genrule=local` for
genrules, and `--spawn_strategy=local` for other rules.
-### Detailed debugging for build failures {#debugging-build-failures}
+### Detailed debugging for build failures
If your build failed, use `--verbose_failures` and `--sandbox_debug` to make
Bazel show the exact command it ran when your build failed, including the part
diff --git a/docs/user-manual.mdx b/docs/user-manual.mdx
index e901366a..94c6d99a 100644
--- a/docs/user-manual.mdx
+++ b/docs/user-manual.mdx
@@ -6,13 +6,13 @@ This page covers the options that are available with various Bazel commands,
such as `bazel build`, `bazel run`, and `bazel test`. This page is a companion
to the list of Bazel's commands in [Build with Bazel](/run/build).
-## Target syntax {#target-syntax}
+## Target syntax
Some commands, like `build` or `test`, can operate on a list of targets. They
use a syntax more flexible than labels, which is documented in
[Specifying targets to build](/run/build#specifying-build-targets).
-## Options {#build-options}
+## Options
The following sections describe the options available during a
build. When `--long` is used on a help command, the on-line
@@ -23,9 +23,9 @@ 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'.
-### Package location {#package-location}
+### Package location
-#### `--package_path` {#package-path}
+#### `--package_path`
**WARNING:** The `--package_path` option is deprecated. Bazel prefers packages
in the main repository to be under the workspace root.
@@ -78,7 +78,7 @@ Example: Building from an empty client
% bazel build --package_path /some/other/path //foo
-#### `--deleted_packages` {#flag--deleted_packages}
+#### `--deleted_packages`
This option specifies a comma-separated list of packages which Bazel
should consider deleted, and not attempt to load from any directory
@@ -86,17 +86,17 @@ on the package path. This can be used to simulate the deletion of packages witho
actually deleting them. This option can be passed multiple times, in which case
the individual lists are concatenated.
-### Error checking {#error-checking}
+### Error checking
These options control Bazel's error-checking and/or warnings.
-#### `--[no]check_visibility` {#check-visibility}
+#### `--[no]check_visibility`
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.
-#### `--output_filter=regex` {#output-filter}
+#### `--output_filter=regex`
The `--output_filter` option will only show build and compilation
warnings for targets that match the regular expression. If a target does not
@@ -116,19 +116,21 @@ Here are some typical values for this option:
`--output_filter=`
-
Show everything.
+
Show everything.
+
`--output_filter=DONT_MATCH_ANYTHING`
-
Show nothing.
+
Show nothing.
+
-### Tool flags {#tool-flags}
+### Tool flags
These options control which options Bazel will pass to other tools.
-#### `--copt=cc-option` {#copt}
+#### `--copt=cc-option`
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
@@ -157,35 +159,35 @@ Similarly, compiler options that only have an
effect at link time (such as `-l`) should be specified in
`--linkopt`, not in `--copt`.
-#### `--host_copt=cc-option` {#host-copt}
+#### `--host_copt=cc-option`
This option takes an argument which is to be passed to the compiler for source files
that are compiled in the exec configuration. This is analogous to
the [`--copt`](#copt) option, but applies only to the
exec configuration.
-#### `--host_conlyopt=cc-option` {#host-conlyopt}
+#### `--host_conlyopt=cc-option`
This option takes an argument which is to be passed to the compiler for C source files
that are compiled in the exec configuration. This is analogous to
the [`--conlyopt`](#cconlyopt) option, but applies only
to the exec configuration.
-#### `--host_cxxopt=cc-option` {#host-cxxopt}
+#### `--host_cxxopt=cc-option`
This option takes an argument which is to be passed to the compiler for C++ source files
that are compiled in the exec configuration. This is analogous to
the [`--cxxopt`](#cxxopt) option, but applies only to the
exec configuration.
-#### `--host_linkopt=linker-option` {#host-linkopt}
+#### `--host_linkopt=linker-option`
This option takes an argument which is to be passed to the linker for source files
that are compiled in the exec configuration. This is analogous to
the [`--linkopt`](#linkopt) option, but applies only to
the exec configuration.
-#### `--conlyopt=cc-option` {#cconlyopt}
+#### `--conlyopt=cc-option`
This option takes an argument which is to be passed to the compiler when compiling C source files.
@@ -196,7 +198,7 @@ not to C++ compilation or linking. So you can pass C-specific options
Note: copts parameters listed in specific cc_library or cc_binary build rules
are placed on the compiler command line _after_ these options.
-#### `--cxxopt=cc-option` {#cxxopt}
+#### `--cxxopt=cc-option`
This option takes an argument which is to be passed to the compiler when
compiling C++ source files.
@@ -214,7 +216,7 @@ For example:
Note: copts parameters listed in specific cc_library or cc_binary build rules
are placed on the compiler command line _after_ these options.
-#### `--linkopt=linker-option` {#linkopt}
+#### `--linkopt=linker-option`
This option takes an argument which is to be passed to the compiler when linking.
@@ -231,7 +233,7 @@ Build rules can also specify link options in their attributes. This option's
settings always take precedence. Also see
[cc_library.linkopts](/reference/be/c-cpp#cc_library.linkopts).
-#### `--strip (always|never|sometimes)` {#strip}
+#### `--strip (always|never|sometimes)`
This option determines whether Bazel will strip debugging information from
all binaries and shared libraries, by invoking the linker with the `-Wl,--strip-debug` option.
@@ -264,7 +266,7 @@ pass `--stripopt=--strip-all` and explicitly build the
`--stripopt`, this applies a strip action after the final binary is
linked rather than including stripping in all of the build's link actions.
-#### `--stripopt=strip-option` {#stripopt}
+#### `--stripopt=strip-option`
This is an additional option to pass to the `strip` command when generating
a [`*.stripped` binary](/reference/be/c-cpp#cc_binary_implicit_outputs). The default
@@ -273,7 +275,7 @@ is `-S -p`. This option can be used multiple times.
Note: `--stripopt` does not apply to the stripping of the main
binary with `[--strip](#flag--strip)=(always|sometimes)`.
-#### `--fdo_instrument=profile-output-dir` {#fdo-instrument}
+#### `--fdo_instrument=profile-output-dir`
The `--fdo_instrument` option enables the generation of
FDO (feedback directed optimization) profile output when the
@@ -292,7 +294,7 @@ data file(s) is dumped. For example:
The options `--fdo_instrument` and `--fdo_optimize` cannot be used at the same time.
-#### `--fdo_optimize=profile-zip` {#fdo-optimize}
+#### `--fdo_optimize=profile-zip`
The `--fdo_optimize` option enables the use of the
per-object file profile information to perform FDO (feedback
@@ -313,7 +315,7 @@ extension.
The options `--fdo_instrument` and `--fdo_optimize` cannot be used at the same time.
-#### `--java_language_version=version` {#java-language-version}
+#### `--java_language_version=version`
This option specifies the version of Java sources. For example:
@@ -326,12 +328,12 @@ Default value is 11.
Possible values are: 8, 9, 10, 11, 17, and 21 and may be extended by
registering custom Java toolchains using `default_java_toolchain`.
-#### `--tool_java_language_version=version` {#tool-java-language-version}
+#### `--tool_java_language_version=version`
The Java language version used to build tools that are executed during a build.
Default value is 11.
-#### `--java_runtime_version=version` {#java-runtime-version}
+#### `--java_runtime_version=version`
This option specifies the version of JVM to use to execute the code and run the tests. For
example:
@@ -348,12 +350,12 @@ Possible values are: `local_jdk`, `local_jdk_version`,
You can extend the values by registering custom JVM using either
`local_java_repository` or `remote_java_repository` repository rules.
-#### `--tool_java_runtime_version=version` {#tool-java-runtime-version}
+#### `--tool_java_runtime_version=version`
The version of JVM used to execute tools that are needed during a build.
Default value is `remotejdk_11`.
-#### `--jvmopt=jvm-option` {#jvmopt}
+#### `--jvmopt=jvm-option`
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:
@@ -365,7 +367,7 @@ with one big argument, or multiple times with individual arguments. For example:
will use the server VM for launching all Java binaries and set the
startup heap size for the VM to 256 MB.
-#### `--javacopt=javac-option` {#javacopt}
+#### `--javacopt=javac-option`
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:
@@ -390,7 +392,7 @@ 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 _after_ these options.
-#### `--strict_java_deps (default|strict|off|warn|error)` {#strict-java-deps}
+#### `--strict_java_deps (default|strict|off|warn|error)`
This option controls whether javac checks for missing direct dependencies.
Java targets must explicitly declare all directly used targets as
@@ -406,11 +408,11 @@ of a direct dependency of the current target.
target to fail to build if any missing direct dependencies are found.
This is also the default behavior when the flag is unspecified.
-### Build semantics {#build-semantics}
+### Build semantics
These options affect the build commands and/or the output file contents.
-#### `--compilation_mode (fastbuild|opt|dbg)` (-c) {#compilation-mode}
+#### `--compilation_mode (fastbuild|opt|dbg)` (-c)
The `--compilation_mode` option (often shortened to `-c`,
especially `-c opt`) takes an argument of `fastbuild`, `dbg`
@@ -431,7 +433,7 @@ needing to do a full rebuild _every_ time.
Debugging information will not be generated in `opt` mode
unless you also pass `--copt -g`.
-#### `--cpu=cpu` {#cpu}
+#### `--cpu=cpu`
This option specifies the target CPU architecture to be used for
the compilation of binaries during the build.
@@ -440,7 +442,7 @@ Note: 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.
-#### `--action_env=VAR=VALUE` {#action-env}
+#### `--action_env=VAR=VALUE`
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
@@ -450,7 +452,7 @@ invocation environment.
This `--action_env` flag can be specified multiple times. If a value is assigned to the same
variable across multiple `--action_env` flags, the latest assignment wins.
-#### `--experimental_action_listener=label` {#experimental-action-listener}
+#### `--experimental_action_listener=label`
Warning: Extra actions are deprecated. Use
[aspects](/extending/aspects)
@@ -460,7 +462,7 @@ The `experimental_action_listener` option instructs Bazel to use
details from the [`action_listener`](/reference/be/extra-actions#action_listener) rule specified by label to
insert [`extra_actions`](/reference/be/extra-actions#extra_action) into the build graph.
-#### `--[no]experimental_extra_action_top_level_only` {#experimental-extra-action-top-level-only}
+#### `--[no]experimental_extra_action_top_level_only`
Warning: Extra actions are deprecated. Use
[aspects](/extending/aspects) instead.
@@ -469,7 +471,7 @@ If this option is set to true, extra actions specified by the
[ `--experimental_action_listener`](#experimental-action-listener) command
line option will only be scheduled for top level targets.
-#### `--experimental_extra_action_filter=regex` {#experimental-extra-action-filter}
+#### `--experimental_extra_action_filter=regex`
Warning: Extra actions are deprecated. Use
[aspects](/extending/aspects) instead.
@@ -489,17 +491,16 @@ regular expression.
The following example will limit scheduling of `extra_actions`
to only apply to actions of which the owner's label contains '/bar/':
-
-#### `--host_cpu=cpu` {#host-cpu}
+#### `--host_cpu=cpu`
This option specifies the name of the CPU architecture that should be
used to build host tools.
-#### `--android_platforms=platform[,platform]*` {#android-platforms}
+#### `--android_platforms=platform[,platform]*`
The platforms to build the transitive `deps` of
`android_binary` rules (specifically for native dependencies like C++). For
@@ -516,7 +517,7 @@ with `--android_platforms`. The `.so` file's name prefixes the name of the
`android_binary` rule with "lib". For example, if the name of the
`android_binary` is "foo", then the file is `libfoo.so`.
-#### `--per_file_copt=[+-]regex[,[+-]regex]...@option[,option]...` {#per-file-copt}
+#### `--per_file_copt=[+-]regex[,[+-]regex]...@option[,option]...`
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
@@ -557,7 +558,7 @@ to the C++ compiler. If an option contains a `,` it has to be quoted like so
adds the `-O0` and the `-fprofile-arcs` options to the command
line of the C++ compiler for all `.cc` files in `//foo/` except `file.cc`.
-#### `--dynamic_mode=mode` {#dynamic-mode}
+#### `--dynamic_mode=mode`
Determines whether C++ binaries will be linked dynamically, interacting with
the [linkstatic attribute](/reference/be/c-cpp#cc_binary.linkstatic) on build rules.
@@ -573,7 +574,7 @@ Modes:
[mostly static](/reference/be/c-cpp#cc_binary.linkstatic) mode.
If `-static` is set in linkopts, targets will change to fully static.
-#### `--fission (yes|no|[dbg][,opt][,fastbuild])` {#fission}
+#### `--fission (yes|no|[dbg][,opt][,fastbuild])`
Enables [Fission](https://gcc.gnu.org/wiki/DebugFission),
which writes C++ debug information to dedicated .dwo files instead of .o files, where it would
@@ -586,13 +587,13 @@ settings. When set to `yes`, Fission is enabled
universally. When set to `no`, Fission is disabled
universally. Default is no.
-#### `--force_ignore_dash_static` {#force-ignore-dash-static}
+#### `--force_ignore_dash_static`
If this flag is set, any `-static` options in linkopts of
`cc_*` rules BUILD files are ignored. This is only intended as a
workaround for C++ hardening builds.
-#### `--[no]force_pic` {#force-pic}
+#### `--[no]force_pic`
If enabled, all C++ compilations produce position-independent code ("-fPIC"),
links prefer PIC pre-built libraries over non-PIC libraries, and links produce
@@ -602,38 +603,38 @@ Note: Dynamically linked binaries (for example `--dynamic_mode fully`)
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.
-#### `--android_resource_shrinking` {#flag--android_resource_shrinking}
+#### `--android_resource_shrinking`
Selects whether to perform resource shrinking for android_binary rules. Sets the default for the
[shrink_resources attribute](/reference/be/android#android_binary.shrink_resources) on
android_binary rules; see the documentation for that rule for further details. Defaults to off.
-#### `--custom_malloc=malloc-library-target` {#custom-malloc}
+#### `--custom_malloc=malloc-library-target`
When specified, always use the given malloc implementation, overriding all
`malloc="target"` attributes, including in those targets that use the
default (by not specifying any `malloc`).
-#### `--crosstool_top=label` {#crosstool-top}
+#### `--crosstool_top=label`
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 `--compiler`.
-#### `--host_crosstool_top=label` {#host-crosstool-top}
+#### `--host_crosstool_top=label`
If not specified, Bazel uses the value of `--crosstool_top` to compile
code in the exec configuration, such as tools run during the build. The main purpose of this flag
is to enable cross-compilation.
-#### `--apple_crosstool_top=label` {#apple-crosstool-top}
+#### `--apple_crosstool_top=label`
The crosstool to use for compiling C/C++ rules in the transitive `deps` of
objc_*, ios__*, and apple_* rules. For those targets, this flag overwrites
`--crosstool_top`.
-#### `--compiler=version` {#compiler}
+#### `--compiler=version`
This option specifies the C/C++ compiler version (such as `gcc-4.1.0`)
to be used for the compilation of binaries during the build. If you want to
@@ -643,7 +644,7 @@ specifying this flag.
Note: Only certain combinations of crosstool version, compiler version,
and target CPU are allowed.
-#### `--android_sdk=label` {#android-sdk}
+#### `--android_sdk=label`
Deprecated. This shouldn't be directly specified.
@@ -654,30 +655,30 @@ rule.
The Android SDK will be automatically selected if an `android_sdk_repository`
rule is defined in the WORKSPACE file.
-#### `--java_toolchain=label` {#java-toolchain}
+#### `--java_toolchain=label`
No-op. Kept only for backwards compatibility.
-#### `--host_java_toolchain=label` {#host-java-toolchain}
+#### `--host_java_toolchain=label`
No-op. Kept only for backwards compatibility.
-#### `--javabase=(label)` {#javabase}
+#### `--javabase=(label)`
No-op. Kept only for backwards compatibility.
-#### `--host_javabase=label` {#host-javabase}
+#### `--host_javabase=label`
No-op. Kept only for backwards compatibility.
-### Execution strategy {#execution-strategy}
+### Execution strategy
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.
-#### `--spawn_strategy=strategy` {#spawn-strategy}
+#### `--spawn_strategy=strategy`
This option controls where and how commands are executed.
@@ -694,7 +695,7 @@ This option controls where and how commands are executed.
* `remote` causes commands to be executed remotely; this is only available if a
remote executor has been configured separately.
-#### `--strategy mnemonic=strategy` {#strategy}
+#### `--strategy mnemonic=strategy`
This option controls where and how commands are executed, overriding the
[--spawn_strategy](#spawn-strategy) (and
@@ -703,7 +704,7 @@ Genrule) on a per-mnemonic basis. See
[--spawn_strategy](#spawn-strategy) for the supported
strategies and their effects.
-#### `--strategy_regexp==` {#strategy-regexp}
+#### `--strategy_regexp==`
This option specifies which strategy should be used to execute commands that have descriptions
matching a certain `regex_filter`. See
@@ -725,11 +726,11 @@ other flags for specifying strategy.
'Compiling //foo/bar/baz' with the `local` strategy and falls back to
`sandboxed` if it fails.
-#### `--genrule_strategy=strategy` {#genrule-strategy}
+#### `--genrule_strategy=strategy`
This is a deprecated short-hand for `--strategy=Genrule=strategy`.
-#### `--jobs=n` (-j) {#jobs}
+#### `--jobs=n` (-j)
This option, which takes an integer argument, specifies a limit on
the number of jobs that should be executed concurrently during the
@@ -743,7 +744,7 @@ based on some (very crude) estimates of the resource consumption
of each job. The behavior of the scheduler can be controlled by
the `--local_resources` option.
-#### `--progress_report_interval=n` {#progress-report-interval}
+#### `--progress_report_interval=n`
Bazel periodically prints a progress report on jobs that are not
finished yet (such as long running tests). This option sets the
@@ -757,7 +758,7 @@ that progress is reported once every minute.
When bazel is using cursor control, as specified by
[`--curses`](#curses), progress is reported every second.
-#### `--local_resources resources or resource expression` {#local-resources}
+#### `--local_resources resources or resource expression`
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
@@ -767,7 +768,7 @@ an float, or a keyword (HOST_RAM or HOST_CPUS) optionally followed by `[-|*`floa
The flags are independent; one or both may be set. By default, Bazel estimates
the amount of RAM and number of CPU cores directly from the local system's configuration.
-#### `--[no]build_runfile_links` {#build-runfile-links}
+#### `--[no]build_runfile_links`
This option, which is enabled by default, specifies whether the runfiles
symlinks for tests and binaries should be built in the output directory.
@@ -789,7 +790,7 @@ 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.
-#### `--[no]build_runfile_manifests` {#build-runfile-manifests}
+#### `--[no]build_runfile_manifests`
This option, which is enabled by default, specifies whether runfiles manifests
should be written to the output tree.
@@ -798,7 +799,7 @@ Disabling it implies `--nobuild_runfile_links`.
It can be disabled when executing tests remotely, as runfiles trees will
be created remotely from in-memory manifests.
-#### `--[no]discard_analysis_cache` {#discard-analysis-cache}
+#### `--[no]discard_analysis_cache`
When this option is enabled, Bazel will discard the analysis cache
right before execution starts, thus freeing up additional memory
@@ -806,7 +807,7 @@ right before execution starts, thus freeing up additional memory
The drawback is that further incremental builds will be slower. See also
[memory-saving mode](/configure/memory).
-#### `--[no]keep_going` (-k) {#keep-going}
+#### `--[no]keep_going` (-k)
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
@@ -823,7 +824,7 @@ unless `--keep_going` is specified, in which case the
build will proceed to the execution phase, but only for the targets
that were successfully analyzed.
-#### `--[no]use_ijars` {#use-ijars}
+#### `--[no]use_ijars`
This option changes the way `java_library` targets are
compiled by Bazel. Instead of using the output of a
@@ -842,7 +843,7 @@ is not visible you will get an error that the member does not exist.
Changing the `--use_ijars` setting will force a recompilation of all affected
classes.
-#### `--[no]interface_shared_objects` {#interface-shared-objects}
+#### `--[no]interface_shared_objects`
This option enables _interface shared objects_, which makes binaries and
other shared libraries depend on the _interface_ of a shared object,
@@ -850,11 +851,11 @@ rather than its implementation. When only the implementation changes, Bazel
can avoid rebuilding targets that depend on the changed shared library
unnecessarily.
-### Output selection {#output-selection}
+### Output selection
These options determine what to build or test.
-#### `--[no]build` {#build}
+#### `--[no]build`
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
@@ -863,7 +864,7 @@ skipped, and only the first two phases, loading and analysis, occur.
This option can be useful for validating BUILD files and detecting
errors in the inputs, without actually building anything.
-#### `--[no]build_tests_only` {#build-tests-only}
+#### `--[no]build_tests_only`
If specified, Bazel will build only what is necessary to run the `*_test`
and `test_suite` rules that were not filtered due to their
@@ -878,7 +879,7 @@ testing. This is useful because running
`bazel test --build_tests_only foo/...` may not detect all build
breakages in the `foo` tree.
-#### `--[no]check_up_to_date` {#check-up-to-date}
+#### `--[no]check_up_to_date`
This option causes Bazel not to perform a build, but merely check
whether all specified targets are up-to-date. If so, the build
@@ -890,7 +891,7 @@ checks) without incurring the cost of a build.
See also [`--check_tests_up_to_date`](#check-tests-up-to-date).
-#### `--[no]compile_one_dependency` {#compile-one-dependency}
+#### `--[no]compile_one_dependency`
Compile a single dependency of the argument files. This is useful for
syntax checking source files in IDEs, for example, by rebuilding a single
@@ -905,7 +906,7 @@ 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.
-#### `--save_temps` {#save-temps}
+#### `--save_temps`
The `--save_temps` option causes temporary outputs from the compiler to be
saved. These include .s files (assembler code), .i (preprocessed C) and .ii
@@ -926,7 +927,7 @@ To ensure that Bazel prints the location of the additional output files, check t
your [`--show_result n`](#show-result)
setting is high enough.
-#### `--build_tag_filters=tag[,tag]*` {#build-tag-filters}
+#### `--build_tag_filters=tag[,tag]*`
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
@@ -938,7 +939,7 @@ When running tests, Bazel ignores `--build_tag_filters` for test targets,
which are built and run even if they do not match this filter. To avoid building them, filter
test targets using `--test_tag_filters` or by explicitly excluding them.
-#### `--test_size_filters=size[,size]*` {#test-size-filters}
+#### `--test_size_filters=size[,size]*`
If specified, Bazel will test (or build if `--build_tests_only`
is also specified) only test targets with the given size. Test size filter
@@ -960,7 +961,7 @@ will test only small and medium tests inside //foo.
By default, test size filtering is not applied.
-#### `--test_timeout_filters=timeout[,timeout]*` {#test-timeout-filters}
+#### `--test_timeout_filters=timeout[,timeout]*`
If specified, Bazel will test (or build if `--build_tests_only`
is also specified) only test targets with the given timeout. Test timeout filter
@@ -971,7 +972,7 @@ for example syntax.
By default, test timeout filtering is not applied.
-#### `--test_tag_filters=tag[,tag]*` {#test-tag-filters}
+#### `--test_tag_filters=tag[,tag]*`
If specified, Bazel will test (or build if `--build_tests_only`
is also specified) only test targets that have at least one required tag
@@ -993,7 +994,7 @@ By default, test tag filtering is not applied. Note that you can also filter
on test's `size` and `local` tags in
this manner.
-#### `--test_lang_filters=string[,string]*` {#test-lang-filters}
+#### `--test_lang_filters=string[,string]*`
Specifies a comma-separated list of strings referring to names of test rule
classes. To refer to the rule class `foo_test`, use the string "foo". Bazel will
@@ -1001,7 +1002,7 @@ test (or build if `--build_tests_only` is also specified) only
targets of the referenced rule classes. To instead exclude those targets, use
the string "-foo". For example,
-
+
% bazel test --test_lang_filters=foo,bar //baz/...
@@ -1027,7 +1028,7 @@ Warning: The option name "--test_lang_filter" is vestigal and is therefore
unfortunately misleading; don't make assumptions about the semantics based on
the name.
-#### `--test_filter=filter-expression` {#test-filter}
+#### `--test_filter=filter-expression`
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
@@ -1040,12 +1041,12 @@ substring, or regexp. `--test_filter` is a convenience
over passing different `--test_arg` filter arguments,
but not all frameworks support it.
-### Verbosity {#verbosity}
+### Verbosity
These options control the verbosity of Bazel's output,
either to the terminal, or to additional log files.
-#### `--explain=logfile` {#explain}
+#### `--explain=logfile`
This option, which requires a filename argument, causes the
dependency checker in `bazel build`'s execution phase to
@@ -1060,7 +1061,7 @@ 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.
-#### `--verbose_explanations` {#verbose-explanations}
+#### `--verbose_explanations`
This option increases the verbosity of the explanations generated
when the [--explain](#explain) option is enabled.
@@ -1078,31 +1079,31 @@ generated explanation file and the performance penalty of using
If `--explain` is not enabled, then
`--verbose_explanations` has no effect.
-#### `--profile=file` {#profile}
+#### `--profile=file`
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
`bazel analyze-profile` command. The Build profile can be useful in
understanding where Bazel's `build` command is spending its time.
-#### `--[no]show_loading_progress` {#show-loading-progress}
+#### `--[no]show_loading_progress`
This option causes Bazel to output package-loading progress
messages. If it is disabled, the messages won't be shown.
-#### `--[no]show_progress` {#show-progress}
+#### `--[no]show_progress`
This option causes progress messages to be displayed; it is on by
default. When disabled, progress messages are suppressed.
-#### `--show_progress_rate_limit=n` {#show-progress-rate}
+#### `--show_progress_rate_limit=n`
This option causes bazel to display at most one progress message per `n` seconds,
where n is a real number.
The default value for this option is 0.02, meaning bazel will limit the progress
messages to one per every 0.02 seconds.
-#### `--show_result=n` {#show-result}
+#### `--show_result=n`
This option controls the printing of result information at the end
of a `bazel build` command. By default, if a single
@@ -1136,23 +1137,23 @@ 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.
-#### `--sandbox_debug` {#sandbox-debug}
+#### `--sandbox_debug`
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.
-#### `--subcommands` (`-s`) {#subcommands}
+#### `--subcommands` (`-s`)
This option causes Bazel's execution phase to print the full command line
for each command prior to executing it.
-```
- >>>> # //examples/cpp:hello-world [action 'Linking examples/cpp/hello-world']
+
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.
@@ -1172,7 +1173,7 @@ For logging subcommands to a file in a tool-friendly format, see
and
[--execution_log_binary_file](/reference/command-line-reference#flag--execution_log_binary_file).
-#### `--verbose_failures` {#verbose-failures}
+#### `--verbose_failures`
This option causes Bazel's execution phase to print the full command line
for commands that failed. This can be invaluable for debugging a
@@ -1181,14 +1182,14 @@ failing build.
Failing commands are printed in a Bourne shell compatible syntax, suitable
for copying and pasting to a shell prompt.
-### Workspace status {#workspace-status}
+### Workspace status
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 `stamp` attribute, such as
`genrule`, `cc_binary`, and more.
-#### `--workspace_status_command=program` {#workspace-status-command}
+#### `--workspace_status_command=program`
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.
@@ -1261,7 +1262,7 @@ echo "STABLE_USER_NAME $USER"
Pass this program's path with `--workspace_status_command`, and the stable status file
will include the STABLE lines and the volatile status file will include the rest of the lines.
-#### `--[no]stamp` {#stamp}
+#### `--[no]stamp`
This option, in conjunction with the `stamp` rule attribute, controls whether to
embed build information in binaries.
@@ -1280,23 +1281,23 @@ their dependencies have not changed.
Setting `--nostamp` is generally desireable for build performance, as it
reduces input volatility and maximizes build caching.
-### Platform {#platform}
+### Platform
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.
Please see background information on [Platforms](/extending/platforms) and [Toolchains](/extending/toolchains).
-#### `--platforms=labels` {#platforms}
+#### `--platforms=labels`
The labels of the platform rules describing the target platforms for the
current command.
-#### `--host_platform=label` {#host-platform}
+#### `--host_platform=label`
The label of a platform rule that describes the host system.
-#### `--extra_execution_platforms=labels` {#extra-execution-platforms}
+#### `--extra_execution_platforms=labels`
The platforms that are available as execution platforms to run actions.
Platforms can be specified by exact target, or as a target pattern. These
@@ -1305,29 +1306,29 @@ platforms will be considered before those declared in MODULE.bazel files by
This option accepts a comma-separated list of platforms in order of priority.
If the flag is passed multiple times, the most recent overrides.
-#### `--extra_toolchains=labels` {#extra-toolchains}
+#### `--extra_toolchains=labels`
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 MODULE.bazel files by
[register_toolchains()](/rules/lib/globals/module#register_toolchains).
-#### `--toolchain_resolution_debug=regex` {#toolchain-resolution-debug}
+#### `--toolchain_resolution_debug=regex`
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 `-` at the beginning. This might help developers
of Bazel or Starlark rules with debugging failures due to missing toolchains.
-### Miscellaneous {#miscellaneous}
+### Miscellaneous
-#### `--flag_alias=alias_name=target_path` {#flag-alias}
+#### `--flag_alias=alias_name=target_path`
A convenience flag used to bind longer Starlark build settings to a shorter name. For more
details, see the
[Starlark Configurations](/extending/config#using-build-setting-aliases).
-#### `--symlink_prefix=string` {#symlink-prefix}
+#### `--symlink_prefix=string`
Changes the prefix of the generated convenience symlinks. The
default value for the symlink prefix is `bazel-` which
@@ -1355,7 +1356,7 @@ Some common values of this option:
`--symlink_prefix=.bazel/` will cause Bazel to create
symlinks called `bin` (etc) inside a hidden directory `.bazel`.
-#### `--platform_suffix=string` {#platform-suffix}
+#### `--platform_suffix=string`
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
@@ -1363,12 +1364,12 @@ 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.
-#### `--default_visibility=(private|public)` {#default-visibility}
+#### `--default_visibility=(private|public)`
Temporary flag for testing bazel default visibility changes. Not intended for general use
but documented for completeness' sake.
-#### `--starlark_cpu_profile=_file_` {#starlark-cpu-profile}
+#### `--starlark_cpu_profile=_file_`
This flag, whose value is the name of a file, causes Bazel to gather
statistics about CPU usage by all Starlark threads,
@@ -1399,14 +1400,14 @@ Showing nodes accounting for 3.34s, 100% of 3.34s total
For different views of the same data, try the `pprof` commands `svg`,
`web`, and `list`.
-## Using Bazel for releases {#bazel-for-releases}
+## Using Bazel for releases
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.
-### Significant options {#significant-options}
+### Significant options
When using Bazel for release builds, the same issues arise as for other scripts
that perform a build. For more details, see
@@ -1425,7 +1426,7 @@ These options are also important:
with a distinct identifier, such as "64bit" vs. "32bit". This option
differentiates the `bazel-bin` (etc.) symlinks.
-## Running tests {#running-tests}
+## Running tests
To build and run tests with bazel, type `bazel test` followed by
the name of the test targets.
@@ -1438,9 +1439,9 @@ their prerequisites are built, meaning that test execution is
interleaved with building. Doing so usually results in significant
speed gains.
-### Options for `bazel test` {#bazel-test-options}
+### Options for `bazel test`
-#### `--cache_test_results=(yes|no|auto)` (`-t`) {#cache-test-results}
+#### `--cache_test_results=(yes|no|auto)` (`-t`)
If this option is set to 'auto' (the default) then Bazel will only rerun a test if any of the
following conditions applies:
@@ -1468,7 +1469,7 @@ their `.bazelrc` file may find the
abbreviations `-t` (on) or `-t-` (off)
convenient for overriding the default on a particular run.
-#### `--check_tests_up_to_date` {#check-tests-up-to-date}
+#### `--check_tests_up_to_date`
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
@@ -1483,7 +1484,7 @@ This option also implies
This option may be useful for pre-submit checks.
-#### `--test_verbose_timeout_warnings` {#test-verbose-timeout-warnings}
+#### `--test_verbose_timeout_warnings`
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
@@ -1500,14 +1501,14 @@ Note: Each test shard is allotted the timeout of the entire
`XX_test` target. Using this option does not affect a test's timeout
value, merely warns if Bazel thinks the timeout could be restricted further.
-#### `--[no]test_keep_going` {#test-keep-going}
+#### `--[no]test_keep_going`
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 `--notest_keep_going` and `--keep_going`.
-#### `--flaky_test_attempts=attempts` {#flaky-test-attempts}
+#### `--flaky_test_attempts=attempts`
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
@@ -1522,7 +1523,7 @@ default), only a single attempt is allowed for regular tests, and
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.
-#### `--runs_per_test=[regex@]number` {#runs-per-test}
+#### `--runs_per_test=[regex@]number`
This option specifies the number of times each test should be executed. All
test executions are treated as separate tests (fallback functionality
@@ -1543,7 +1544,7 @@ which match the regex (`--runs_per_test=^//pizza:.*@4` runs all tests
under `//pizza/` 4 times).
This form of `--runs_per_test` may be specified more than once.
-#### `--[no]runs_per_test_detects_flakes` {#run-per-test-detects-flakes}
+#### `--[no]runs_per_test_detects_flakes`
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
@@ -1551,7 +1552,7 @@ 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.
-#### `--test_summary=output_style` {#test-summary}
+#### `--test_summary=output_style`
Specifies how the test result summary should be displayed.
@@ -1564,7 +1565,7 @@ Specifies how the test result summary should be displayed.
only each test. The names of test output files are omitted.
* `none` does not print test summary.
-#### `--test_output=output_style` {#test-output}
+#### `--test_output=output_style`
Specifies how test output should be displayed:
@@ -1582,12 +1583,12 @@ Specifies how test output should be displayed:
* `streamed` streams stdout/stderr output from each test in
real-time.
-#### `--java_debug` {#java-debug}
+#### `--java_debug`
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`.
-#### `--[no]verbose_test_summary` {#verbose-test-summary}
+#### `--[no]verbose_test_summary`
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
@@ -1595,7 +1596,7 @@ information (such as test attempts) to be printed to the test summary. If
include only test name, test status and cached test indicator and will
be formatted to stay within 80 characters when possible.
-#### `--test_tmpdir=path` {#test-tmpdir}
+#### `--test_tmpdir=path`
Specifies temporary directory for tests executed locally. Each test will be
executed in a separate subdirectory inside this directory. The directory will
@@ -1605,7 +1606,7 @@ By default, bazel will place this directory under Bazel output base directory.
Note: This is a directory for running tests, not storing test results
(those are always stored under the `bazel-out` directory).
-#### `--test_timeout=seconds` OR `--test_timeout=seconds,seconds,seconds,seconds` {#test-timeout}
+#### `--test_timeout=seconds` OR `--test_timeout=seconds,seconds,seconds,seconds`
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
@@ -1627,7 +1628,7 @@ 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.
-#### `--test_arg=arg` {#test-arg}
+#### `--test_arg=arg`
Passes command-line options/flags/arguments to each test process. This
option can be used multiple times to pass several arguments. For example,
@@ -1645,7 +1646,7 @@ target being run is a test target. (As with any other flag, if it's passed in a
`bazel run` command after a `--` token, it's not processed by Bazel but
forwarded verbatim to the executed target.)
-#### `--test_env=variable=_value_` OR `--test_env=variable` {#test-env}
+#### `--test_env=variable=_value_` OR `--test_env=variable`
Specifies additional variables that must be injected into the test
environment for each test. If value is not specified it will be
@@ -1655,7 +1656,7 @@ command.
The environment can be accessed from within a test by using
`System.getenv("var")` (Java), `getenv("var")` (C or C++),
-#### `--run_under=command-prefix` {#test-run-under}
+#### `--run_under=command-prefix`
This specifies a prefix that the test runner will insert in front
of the test command before running it. The
@@ -1685,7 +1686,7 @@ Examples:
--run_under='/usr/bin/valgrind --quiet --num-callers=20'
-#### Test selection {#test-selection}
+#### Test selection
As documented under [Output selection options](#output-selection),
you can filter tests by [size](#test-size-filters),
@@ -1695,12 +1696,12 @@ you can filter tests by [size](#test-size-filters),
[general name filter](#test-filter) can forward particular
filter args to the test runner.
-#### Other options for `bazel test` {#bazel-test-other-options}
+#### Other options for `bazel test`
The syntax and the remaining options are exactly like
[`bazel build`](/run/build).
-## Running executables {#running-executables}
+## Running executables
The `bazel run` command is similar to `bazel build`, except
it is used to build _and run_ a single target. Here is a typical session
@@ -1755,9 +1756,9 @@ The following extra environment variables are also available to the binary:
These can be used, for example, to interpret file names on the command line in
a user-friendly way.
-### Options for `bazel run` {#bazel-run-options}
+### Options for `bazel run`
-#### `--run_under=command-prefix` {#run-run-under}
+#### `--run_under=command-prefix`
This has the same effect as the `--run_under` option for
`bazel test` ([see above](#test-run-under)),
@@ -1775,7 +1776,7 @@ suppress the outputs from Bazel itself with the `--ui_event_filters` and
For example:
`bazel run --ui_event_filters=-info,-stdout,-stderr --noshow_progress //java/myapp:myapp`
-### Executing tests {#executing-tests}
+### Executing tests
`bazel run` can also execute test binaries, which has the effect of
running the test in a close approximation of the environment described at
@@ -1783,9 +1784,9 @@ running the test in a close approximation of the environment described at
`--test_*` arguments have an effect when running a test in this manner except
`--test_arg` .
-## Cleaning build outputs {#cleaning-build-outputs}
+## Cleaning build outputs
-### The `clean` command {#clean}
+### The `clean` command
Bazel has a `clean` command, analogous to that of Make.
It deletes the output directories for all build configurations performed
@@ -1828,7 +1829,7 @@ 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 `clean`.
-## Querying the dependency graph {#querying-dependency-graph}
+## Querying the dependency graph
Bazel includes a query language for asking questions about the
dependency graph used during the build. The query language is used
@@ -1866,7 +1867,7 @@ all genrules required to build all the tests in the PEBL tree."
bazel query --output location 'kind(genrule, deps(kind(".*_test rule", foo/bar/pebl/...)))'
-## Querying the action graph {#aquery}
+## Querying the action graph
Caution: The aquery command is still experimental and its API will change.
@@ -1887,9 +1888,9 @@ It supports the same set of functions that is also available to traditional
For more details, see [Action Graph Query](/query/aquery).
-## Miscellaneous commands and options {#misc-commands-options}
+## Miscellaneous commands and options
-### `help` {#help}
+### `help`
The `help` command provides on-line help. By default, it
shows a summary of available commands and help topics, as shown in
@@ -1899,14 +1900,14 @@ topic. Most topics are Bazel commands, such as `build`
or `query`, but there are some additional help topics
that do not correspond to commands.
-#### `--[no]long` (`-l`) {#long}
+#### `--[no]long` (`-l`)
By default, `bazel help [topic]` prints only a
summary of the relevant options for a topic. If
the `--long` option is specified, the type, default value
and full description of each option is also printed.
-### `shutdown` {#shutdown}
+### `shutdown`
Bazel server processes may be stopped by using the `shutdown`
command. This command causes the Bazel server to exit as soon as it
@@ -1926,7 +1927,7 @@ 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.
-### `info` {#info}
+### `info`
The `info` command prints various values associated with
the Bazel server instance, or with a specific build configuration.
@@ -1939,7 +1940,7 @@ the value for that one key. (This is especially convenient when
scripting Bazel, as it avoids the need to pipe the result
through `sed -ne /key:/s/key://p`:
-#### Configuration-independent data {#configuration-independent-data}
+#### Configuration-independent data
* `release`: the release label for this Bazel
instance, or "development version" if this is not a released
@@ -1993,12 +1994,11 @@ through `sed -ne /key:/s/key://p`:
Example: the process ID of the Bazel server.
-
-% bazel info server_pid
+
% bazel info server_pid
1285
-#### Configuration-specific data {#configuration-specific-data}
+#### Configuration-specific data
These data may be affected by the configuration options passed
to `bazel info`, for
@@ -2038,14 +2038,13 @@ configuration. This is guaranteed to be correct even in cases where
the `bazel-bin` symlink cannot be created for some reason
(such as if you are building from a read-only directory).
-
-% bazel info --cpu=piii bazel-bin
+
% 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
-### `version` and `--version` {#version}
+### `version` and `--version`
The version command prints version details about the built Bazel
binary, including the changelist at which it was built and the date.
@@ -2064,7 +2063,7 @@ are:
a Bazel server or unpacking the server archive. `bazel --version` can be run from
anywhere - it does not require a workspace directory.
-### `mobile-install` {#mobile-install}
+### `mobile-install`
The `mobile-install` command installs apps to mobile devices.
Currently only Android devices running ART are supported.
@@ -2078,7 +2077,7 @@ transparent to the app.
The following options are supported:
-#### `--incremental` {#incremental}
+#### `--incremental`
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
@@ -2092,23 +2091,23 @@ when a full install is needed.
If you are using a device with Marshmallow or later, consider the
[`--split_apks`](#split-apks) flag.
-#### `--split_apks` {#split-apks}
+#### `--split_apks`
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
[`--incremental`](#incremental) flag
is not necessary when using `--split_apks`.
-#### `--start_app` {#start-app}
+#### `--start_app`
Starts the app in a clean state after installing. Equivalent to `--start=COLD`.
-#### `--debug_app` {#debug-app}
+#### `--debug_app`
Waits for debugger to be attached before starting the app in a clean state after installing.
Equivalent to `--start=DEBUG`.
-#### `--start=_start_type_` {#start}
+#### `--start=_start_type_`
How the app should be started after installing it. Supported _start_type_s are:
@@ -2121,21 +2120,20 @@ How the app should be started after installing it. Supported _start_type_s are:
Note: If more than one of `--start=_start_type_`, `--start_app` or
`--debug_app` is set, the last value is used.
-#### `--adb=path` {#adb}
+#### `--adb=path`
Indicates the `adb` binary to be used.
The default is to use the adb in the Android SDK specified by
[`--android_sdk`](#android-sdk).
-#### `--adb_arg=serial` {#adb-arg}
+#### `--adb_arg=serial`
Extra arguments to `adb`. 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:
-
invokes `adb` as
@@ -2144,12 +2142,12 @@ invokes `adb` as
adb -s deadbeef install ...
-#### `--incremental_install_verbosity=number` {#incremental-install-verbosity}
+#### `--incremental_install_verbosity=number`
The verbosity for incremental install. Set to 1 for debug logging to be
printed to the console.
-### `dump` {#dump}
+### `dump`
The `dump` command prints to stdout a dump of the
internal state of the Bazel server. This command is intended
@@ -2172,7 +2170,7 @@ Following options are supported:
[pprof](https://github.com/google/pprof) compatible .gz file to the specified path.
You must enable memory tracking for this to work.
-#### Memory tracking {#memory-tracking}
+#### Memory tracking
Some `dump` commands require memory tracking. To turn this on, you have to pass
startup flags to Bazel:
@@ -2206,13 +2204,13 @@ Example:
% pprof -flame $HOME/prof.gz
-### `analyze-profile` {#analyze-profile}
+### `analyze-profile`
The `analyze-profile` command analyzes a
[JSON trace profile](/advanced/performance/json-trace-profile) previously
gathered during a Bazel invocation.
-### `canonicalize-flags` {#canonicalize-flags}
+### `canonicalize-flags`
The [`canonicalize-flags`](/reference/command-line-reference#canonicalize-flags-options)
command, which takes a list of options for a Bazel command and returns a list of
@@ -2235,7 +2233,7 @@ As an example:
--test_tag_filters=-lint
-### Startup options {#startup-options}
+### Startup options
The options described in this section affect the startup of the Java
virtual machine used by Bazel server process, and they apply to all
@@ -2248,7 +2246,7 @@ All of the options described in this section must be specified using the
syntax. Also, these options must appear _before_ the name of the Bazel
command. Use `startup --key=value` to list these in a `.bazelrc` file.
-#### `--output_base=dir` {#output-base}
+#### `--output_base=dir`
This option requires a path argument, which must specify a
writable directory. Bazel will use this location to write all its
@@ -2285,7 +2283,7 @@ by an incremental build of `//bar`.
Note: 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.
-#### `--output_user_root=dir` {#output-user-root}
+#### `--output_user_root=dir`
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,
@@ -2307,7 +2305,7 @@ base) if there is a better location in your filesystem layout.
Note: 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.
-#### `--server_javabase=dir` {#server-javabase}
+#### `--server_javabase=dir`
Specifies the Java virtual machine in which _Bazel itself_ runs. The value must be a path to
the directory containing a JDK or JRE. It should not be a label.
@@ -2326,7 +2324,7 @@ This flag was previously named `--host_javabase` (sometimes referred to as the
build flag [--host_javabase](#host-javabase) (sometimes referred to as the
'right-hand side' `--host_javabase`).
-#### `--host_jvm_args=string` {#host-jvm-args}
+#### `--host_jvm_args=string`
Specifies a startup option to be passed to the Java virtual machine in which _Bazel itself_
runs. This can be used to set the stack size, for example:
@@ -2348,7 +2346,7 @@ the `--jvm_flags` argument which
all `java_binary` and `java_test` programs
support. Alternatively for tests, use `bazel test --test_arg=--jvm_flags=foo ...`.
-#### `--host_jvm_debug` {#host-java-debug}
+#### `--host_jvm_debug`
This option causes the Java virtual machine to wait for a connection
from a JDWP-compliant debugger before
@@ -2358,14 +2356,14 @@ intended for use by Bazel developers.
Note: This does _not_ affect any JVMs used by subprocesses of Bazel:
applications, tests, tools, etc.
-#### `--autodetect_server_javabase` {#autodetect-server-javabase}
+#### `--autodetect_server_javabase`
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.
`--explicit_server_javabase` can be used to pick an explicit JRE to
run Bazel with.
-#### `--batch` {#batch}
+#### `--batch`
Batch mode causes Bazel to not use the
[standard client/server mode](/run/client-server), but instead runs a bazel
@@ -2392,7 +2390,7 @@ for the purpose of build isolation, you should use the command option
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.
-#### `--max_idle_secs=n` {#max-idle-secs}
+#### `--max_idle_secs=n`
This option specifies how long, in seconds, the Bazel server process
should wait after the last client request, before it exits. The
@@ -2420,7 +2418,7 @@ 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.
-#### `--[no]shutdown_on_low_sys_mem` {#shutdown-on-low-sys-mem}
+#### `--[no]shutdown_on_low_sys_mem`
If enabled and `--max_idle_secs` is set to a positive duration,
after the build server has been idle for a while, shut down the server when the system is
@@ -2430,7 +2428,7 @@ In addition to running an idle check corresponding to max_idle_secs, the build s
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.
-#### `--[no]block_for_lock` {#block-for-lock}
+#### `--[no]block_for_lock`
If enabled, Bazel will wait for other Bazel commands holding the
server lock to complete before progressing. If disabled, Bazel will
@@ -2440,27 +2438,27 @@ proceed.
Developers might use this in presubmit checks to avoid long waits caused
by another Bazel command in the same client.
-#### `--io_nice_level=n` {#io-nice-level}
+#### `--io_nice_level=n`
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.
-#### `--batch_cpu_scheduling` {#batch-cpu-scheduling}
+#### `--batch_cpu_scheduling`
Use `batch` 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.
-### Miscellaneous options {#misc-options}
+### Miscellaneous options
-#### `--[no]announce_rc` {#announce-rc}
+#### `--[no]announce_rc`
Controls whether Bazel announces startup options and command options read from
the bazelrc files when starting up.
-#### `--color (yes|no|auto)` {#color}
+#### `--color (yes|no|auto)`
This option determines whether Bazel will use colors to highlight
its output on the screen.
@@ -2473,7 +2471,7 @@ If this option is set to `no`, color output is disabled,
regardless of whether the output is going to a terminal and regardless
of the setting of the TERM environment variable.
-#### `--config=name` {#config}
+#### `--config=name`
Selects additional config section from
[the rc files](/run/bazelrc#bazelrc-file-locations); for the current `command`,
@@ -2481,7 +2479,7 @@ it also pulls in the options from `command:name` if such a section exists. Can b
specified multiple times to add flags from several config sections. Expansions can refer to other
definitions (for example, expansions can be chained).
-#### `--curses (yes|no|auto)` {#curses}
+#### `--curses (yes|no|auto)`
This option determines whether Bazel will use cursor controls
in its screen output. This results in less scrolling data, and a more
@@ -2493,7 +2491,7 @@ If this option is set to `no`, use of cursor controls is disabled.
If this option is set to `auto`, use of cursor controls will be
enabled under the same conditions as for `--color=auto`.
-#### `--[no]show_timestamps` {#show-timestamps}
+#### `--[no]show_timestamps`
If specified, a timestamp is added to each message generated by
Bazel specifying the time at which the message was displayed.
diff --git a/extending/auto-exec-groups.mdx b/extending/auto-exec-groups.mdx
index 48100b71..9fee9783 100644
--- a/extending/auto-exec-groups.mdx
+++ b/extending/auto-exec-groups.mdx
@@ -8,7 +8,7 @@ Automatic execution groups select an [execution platform][exec_platform]
for each toolchain type. In other words, one target can have multiple
execution platforms without defining execution groups.
-## Quick summary {#quick-summary}
+## Quick summary
Automatic execution groups are closely connected to toolchains. If you are using
toolchains, you need to set them on the affected actions (actions which use an
@@ -29,9 +29,11 @@ doesn't detect that ([the error](#first-error-message) is raised), you can set
If you need to use multiple toolchains on a single execution platform (an action
uses executable or tools from two or more toolchains), you need to manually
-define [exec_groups][exec_groups](check [When should I use a custom exec_group?][multiple_toolchains_exec_groups] section).
+define [exec_groups][exec_groups] (check
+[When should I use a custom exec_group?][multiple_toolchains_exec_groups]
+section).
-## History {#history}
+## History
Before AEGs, the execution platform was selected on a rule level. For example:
@@ -42,7 +44,8 @@ my_rule = rule(
)
```
-Rule `my_rule` registers two toolchain types. This means that the [Toolchain Resolution](https://bazel.build/extending/toolchains#toolchain-resolution) used
+Rule `my_rule` registers two toolchain types. This means that the [Toolchain
+Resolution](https://bazel.build/extending/toolchains#toolchain-resolution) used
to find an execution platform which supports both toolchain types. The selected
execution platform was used for each registered action inside the rule, unless
specified differently with [exec_groups][exec_groups].
@@ -51,7 +54,7 @@ platform even if they used tools from different toolchains (execution platform
is selected for each target). This resulted in failures when there was no
execution platform supporting all toolchains.
-## Current state {#current-state}
+## Current state
With AEGs, the execution platform is selected for each toolchain type. The
implementation function of the earlier example, `my_rule`, would look like:
@@ -82,14 +85,14 @@ on different execution platforms.
The same is effective with [ctx.actions.run_shell][run_shell] where `toolchain`
parameter should be added when `tools` are from a toolchain.
-## Difference between custom exec groups and automatic exec groups {#difference-custom}
+## Difference between custom exec groups and automatic exec groups
As the name suggests, AEGs are exec groups created automatically for each
toolchain type registered on a rule. There is no need to manually specify them,
unlike the "classic" exec groups. Moreover, name of AEG is automatically set to
its toolchain type (e.g. `//tools:toolchain_type_1`).
-### When should I use a custom exec_group? {#when-should-use-exec-groups}
+### When should I use a custom exec_group?
Custom exec_groups are needed only in case where multiple toolchains need to
execute on a single execution platform. In all other cases there's no need to
@@ -116,22 +119,22 @@ my_rule = rule(
)
```
-## Migration of AEGs {#migration-aegs}
+## Migration of AEGs
Internally in google3, Blaze is already using AEGs.
Externally for Bazel, migration is in the process. Some rules are already using
this feature (e.g. Java and C++ rules).
-### Which Bazel versions support this migration? {#which-bazel}
+### Which Bazel versions support this migration?
AEGs are fully supported from Bazel 7.
-### How to enable AEGs? {#how-enable}
+### How to enable AEGs?
Set `--incompatible_auto_exec_groups` to true. More information about the flag
on [the GitHub issue][github_flag].
-### How to enable AEGs inside a particular rule? {#how-enable-particular-rule}
+### How to enable AEGs inside a particular rule?
Set the `_use_auto_exec_groups` attribute on a rule.
@@ -147,16 +150,16 @@ This enables AEGs only in `my_rule` and its actions start using the new logic
when selecting the execution platform. Incompatible flag is overridden with this
attribute.
-### How to disable AEGs in case of an error? {#how-disable}
+### How to disable AEGs in case of an error?
Set `--incompatible_auto_exec_groups` to false to completely disable AEGs in
your project ([flag's GitHub issue][github_flag]), or disable a particular rule
by setting `_use_auto_exec_groups` attribute to `False`
([more details about the attribute](#how-enable-particular-rule)).
-### Error messages while migrating to AEGs {#potential-problems}
+### Error messages while migrating to AEGs
-#### Couldn't identify if tools are from implicit dependencies or a toolchain. Please set the toolchain parameter. If you're not using a toolchain, set it to 'None'. {#first-error-message}
+#### Couldn't identify if tools are from implicit dependencies or a toolchain. Please set the toolchain parameter. If you're not using a toolchain, set it to 'None'.
* In this case you get a stack of calls before the error happened and you can
clearly see which exact action needs the toolchain parameter. Check which
toolchain is used for the action and set it with the toolchain param. If no
@@ -167,7 +170,7 @@ by setting `_use_auto_exec_groups` attribute to `False`
* This means that you've set the toolchain parameter on the action but didn't
register it on the rule. Register the toolchain or set `None` inside the action.
-## Additional material {#additional-material}
+## Additional material
For more information, check design document:
[Automatic exec groups for toolchains][aegs_design_doc].
diff --git a/extending/concepts.mdx b/extending/concepts.mdx
index 988538fa..893e9cc5 100644
--- a/extending/concepts.mdx
+++ b/extending/concepts.mdx
@@ -19,17 +19,19 @@ Before learning the more advanced concepts, first:
* Learn how you can [share variables](/build/share-variables)
between two `BUILD` files.
-## Macros and rules {#macros-and-rules}
+## Macros and rules
A macro is a function that instantiates rules. Macros come in two flavors:
-[symbolic macros](/extending/macros) (new in Bazel 8) and [legacy macros](/extending/legacy-macros). The two flavors of macros are defined
+[symbolic macros](/extending/macros) (new in Bazel 8) and [legacy
+macros](/extending/legacy-macros). The two flavors of macros are defined
differently, but behave almost the same from the point of view of a user. A
macro is useful when a `BUILD` file is getting too repetitive or too complex, as
it lets you reuse some code. The function is evaluated as soon as the `BUILD`
file is read. After the evaluation of the `BUILD` file, Bazel has little
information about macros. If your macro generates a `genrule`, Bazel will
behave *almost* as if you declared that `genrule` in the `BUILD` file. (The one
-exception is that targets declared in a symbolic macro have [special visibility semantics](/extending/macros#visibility): a symbolic macro can hide its internal
+exception is that targets declared in a symbolic macro have [special visibility
+semantics](/extending/macros#visibility): a symbolic macro can hide its internal
targets from the rest of the package.)
A [rule](/extending/rules) is more powerful than a macro. It can access Bazel
@@ -42,7 +44,7 @@ complex, it is often a good idea to make it a rule. Support for a new language
is typically done with a rule. Rules are for advanced users, and most users will
never have to write one; they will only load and call existing rules.
-## Evaluation model {#evaluation-model}
+## Evaluation model
A build consists of three phases.
@@ -76,7 +78,8 @@ they will not be executed.
## Creating extensions
* [Create your first macro](/rules/macro-tutorial) in order to reuse some code.
- Then [learn more about macros](/extending/macros) and [using them to create "custom verbs"](/rules/verbs-tutorial).
+ Then [learn more about macros](/extending/macros) and [using them to create
+ "custom verbs"](/rules/verbs-tutorial).
* [Follow the rules tutorial](/rules/rules-tutorial) to get started with rules.
Next, you can read more about the [rules concepts](/extending/rules).
@@ -91,7 +94,8 @@ them within reach:
## Going further
In addition to [macros](/extending/macros) and [rules](/extending/rules), you
-may want to write [aspects](/extending/aspects) and [repository rules](/external/repo).
+may want to write [aspects](/extending/aspects) and [repository
+rules](/external/repo).
* Use [Buildifier](https://github.com/bazelbuild/buildtools)
consistently to format and lint your code.
diff --git a/extending/config.mdx b/extending/config.mdx
index 2e1331c0..717bb72f 100644
--- a/extending/config.mdx
+++ b/extending/config.mdx
@@ -23,7 +23,7 @@ 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/configurations).
-## User-defined build settings {#user-defined-build-settings}
+## User-defined build settings
A build setting is a single piece of
[configuration](/extending/rules#configurations)
@@ -41,14 +41,11 @@ 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 {#defining-build-settings}
+### Defining build settings
[End to end example](https://github.com/bazelbuild/examples/tree/HEAD/configurations/basic_build_setting)
-Note: Before defining your own build setting, check if one of the [predefined
-settings](#predefined-settings) is suitable.
-
-#### The `build_setting` `rule()` parameter {#rule-parameter}
+#### The `build_setting` `rule()` parameter
Build settings are rules like any other rule and are differentiated using the
Starlark `rule()` function's `build_setting`
@@ -77,7 +74,7 @@ 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 {#ctx-build-setting-value}
+#### Using ctx.build_setting_value
Like all rules, build setting rules have [implementation functions](/extending/rules#implementation-function).
The basic Starlark-type value of the build settings can be accessed via the
@@ -113,7 +110,7 @@ But all other references to the value of the build setting (such as in transitio
will see its basic Starlark-typed value, not this post implementation function
value.
-#### Defining multi-set string flags {#multi-set-string-flags}
+#### 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
@@ -146,7 +143,7 @@ $ bazel build //my/target --//example:roasts=blonde \
The above is parsed to `{"//example:roasts": ["blonde", "medium,dark"]}` and
`ctx.build_setting_value` returns the list `["blonde", "medium,dark"]`.
-#### Instantiating build settings {#instantiating-build-settings}
+#### 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
@@ -174,23 +171,7 @@ flavor(
)
```
-#### Scope
-
-Build settings are by default only applied to the `target` [configuration]
-(/extending/rules#configurations), and won't be applied to the `exec`
-configuration. To have the build setting applied to both the `target` and `exec`
-configurations set the `scope` attribute to `"universal"`.
-
-```python
-# example/BUILD
-load("@bazel_skylib//rules:common_settings.bzl", "bool_flag")
-bool_flag(
- name = "use_this_for_compiler_and_sources",
- scope = "universal"
-)
-```
-
-### Predefined settings {#predefined-settings}
+### Predefined settings
[End to end example](https://github.com/bazelbuild/examples/tree/HEAD/configurations/use_skylib_build_setting)
@@ -214,9 +195,9 @@ string_flag(
For a complete list, see
[Common build setting rules](https://github.com/bazelbuild/bazel-skylib/blob/main/rules/common_settings.bzl).
-### Using build settings {#using-build-settings}
+### Using build settings
-#### Depending on build settings {#depending-on-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.
@@ -281,7 +262,7 @@ kotlin_binary = rule(
```
-#### Using build settings on the command line {#build-settings-command-line}
+#### 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](#rule-parameter). The build
@@ -299,7 +280,7 @@ $ bazel build //my/target --//example:boolean_flag
$ bazel build //my/target --no//example:boolean_flag
```
-#### Using build setting aliases {#using-build-setting-aliases}
+#### 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
@@ -331,7 +312,7 @@ $ bazel build //my/target --//experimental/user/starlark_configurations/basic_bu
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 {#label-typed-build-settings}
+### Label-typed build settings
[End to end example](https://github.com/bazelbuild/examples/tree/HEAD/configurations/label_typed_build_setting)
@@ -385,7 +366,7 @@ label_flag(
)
```
-### Build settings and select() {#build-settings-and-select}
+### Build settings and select()
[End to end example](https://github.com/bazelbuild/examples/tree/HEAD/configurations/select_on_build_setting)
@@ -403,7 +384,7 @@ config_setting(
)
```
-## User-defined transitions {#user-defined-transitions}
+## User-defined transitions
A configuration
[transition](/rules/lib/builtins/transition#transition)
@@ -412,7 +393,7 @@ build graph.
Important: Transitions have [memory and performance impact](#memory-performance-considerations).
-### Defining {#defining}
+### 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
@@ -443,7 +424,7 @@ hot_chocolate_transition = transition(
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
+`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
@@ -471,7 +452,7 @@ 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 {#defining-1-2-transitions}
+### Defining 1:2+ transitions
[End to end example](https://github.com/bazelbuild/examples/tree/HEAD/configurations/multi_arch_binary)
@@ -516,7 +497,7 @@ multi_arch_transition = transition(
)
```
-### Attaching transitions {#attaching-transitions}
+### Attaching transitions
[End to end example](https://github.com/bazelbuild/examples/tree/HEAD/configurations/attaching_transitions_to_rules)
@@ -530,7 +511,7 @@ If you need to do this, contact
bazel-discuss@googlegroups.com
for help with figuring out workarounds.
-### Incoming edge transitions {#incoming-edge-transitions}
+### Incoming edge transitions
Incoming edge transitions are activated by attaching a `transition` object
(created by `transition()`) to `rule()`'s `cfg` parameter:
@@ -546,7 +527,7 @@ drink_rule = rule(
Incoming edge transitions must be 1:1 transitions.
-### Outgoing edge transitions {#outgoing-edge-transitions}
+### Outgoing edge transitions
Outgoing edge transitions are activated by attaching a `transition` object
(created by `transition()`) to an attribute's `cfg` parameter:
@@ -564,7 +545,7 @@ Outgoing edge transitions can be 1:1 or 1:2+.
See [Accessing attributes with transitions](#accessing-attributes-with-transitions)
for how to read these keys.
-### Transitions on native options {#transitions-native-options}
+### Transitions on native options
[End to end example](https://github.com/bazelbuild/examples/tree/HEAD/configurations/transition_on_native_flag)
@@ -583,7 +564,7 @@ cpu_transition = transition(
outputs = ["//command_line_option:cpu"]
```
-#### Unsupported native options {#unsupported-native-options}
+#### Unsupported native options
Bazel doesn't support transitioning on `--define` with
`"//command_line_option:define"`. Instead, use a custom
@@ -603,7 +584,7 @@ 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 {#transitions-multiple-build-settings}
+### Transitions on allow multiple build settings
When setting build settings that
[allow multiple values](#defining-multi-set-string-flags), the value of the
@@ -636,7 +617,7 @@ coffee_transition = transition(
)
```
-### No-op transitions {#no-op-transitions}
+### 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
@@ -665,7 +646,7 @@ hot_chocolate_transition = transition(
)
```
-### Accessing attributes with transitions {#accessing-attributes-with-transitions}
+### Accessing attributes with transitions
[End to end example](https://github.com/bazelbuild/examples/tree/HEAD/configurations/read_attr_in_transition)
@@ -734,14 +715,14 @@ multi_arch_rule = rule(
See [complete example](https://github.com/bazelbuild/examples/tree/main/configurations/multi_arch_binary)
here.
-## Integration with platforms and toolchains {#integration-platforms-toolchains}
+## 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](/extending/platforms).
-## Memory and performance considerations {#memory-performance-considerations}
+## 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
@@ -749,7 +730,7 @@ 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 {#badly-behaved-builds}
+### Badly behaved builds: a case study
@@ -800,7 +781,7 @@ corresponding memory and performance consequences.
TODO: Add strategies for measurement and mitigation of these issues.
-## Further reading {#further-reading}
+## Further reading
For more details on modifying build configurations, see:
diff --git a/extending/depsets.mdx b/extending/depsets.mdx
index 8f0f31b0..4e84d3f2 100644
--- a/extending/depsets.mdx
+++ b/extending/depsets.mdx
@@ -113,7 +113,8 @@ need to ensure that if `B` depends on `A`, then `A.o` comes before `B.o` on the
linker’s command line. Other tools might have the opposite requirement.
Three traversal orders are supported: `postorder`, `preorder`, and
-`topological`. The first two work exactly like [tree traversals](https://en.wikipedia.org/wiki/Tree_traversal#Depth-first_search)
+`topological`. The first two work exactly like [tree
+traversals](https://en.wikipedia.org/wiki/Tree_traversal#Depth-first_search)
except that they operate on DAGs and skip already visited nodes. The third order
works as a topological sort from root to leaves, essentially the same as
preorder except that shared children are listed only after all of their parents.
diff --git a/extending/exec-groups.mdx b/extending/exec-groups.mdx
index 68003af0..aa70cb1e 100644
--- a/extending/exec-groups.mdx
+++ b/extending/exec-groups.mdx
@@ -8,14 +8,14 @@ Execution groups allow for multiple execution platforms within a single target.
Each execution group has its own [toolchain](/extending/toolchains) dependencies and
performs its own [toolchain resolution](/extending/toolchains#toolchain-resolution).
-## Current status {#current-status}
+## Current status
Execution groups for certain natively declared actions, like `CppLink`, can be
used inside `exec_properties` to set per-action, per-target execution
requirements. For more details, see the
[Default execution groups](#exec-groups-for-native-rules) section.
-## Background {#background}
+## Background
Execution groups allow the rule author to define sets of actions, each with a
potentially different execution platform. Multiple execution platforms can allow
@@ -28,7 +28,7 @@ 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 {#defining-exec-groups}
+## Defining execution groups
During rule definition, rule authors can
[declare](/rules/lib/globals/bzl#exec_group)
@@ -68,11 +68,12 @@ built.
As on native rules, the `test` execution group is present by default on Starlark
test rules.
-## Accessing execution groups {#accessing-exec-groups}
+## 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`](/rules/lib/builtins/actions#run) and
+param of action generating methods, specifically [`ctx.actions.run`]
+(/rules/lib/builtins/actions#run) and
[`ctx.actions.run_shell`](/rules/lib/builtins/actions#run_shell).
```python
@@ -105,7 +106,7 @@ 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.
-### Default execution groups {#exec-groups-for-native-rules}
+### Default execution groups
The following execution groups are predefined:
@@ -113,7 +114,7 @@ The following execution groups are predefined:
the [execution platform section of the Test Encyclopedia](/reference/test-encyclopedia#execution-platform)).
* `cpp_link`: C++ linking actions.
-## Using execution groups to set execution properties {#using-exec-groups-for-exec-properties}
+## Using execution groups to set execution properties
Execution groups are integrated with the
[`exec_properties`](/reference/be/common-definitions#common-attributes)
@@ -139,7 +140,7 @@ 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.
-## Using execution groups to set platform constraints {#using-exec-groups-for-platform-constraints}
+## Using execution groups to set platform constraints
Execution groups are also integrated with the
[`exec_compatible_with`](/reference/be/common-definitions#common-attributes) and
@@ -177,7 +178,7 @@ my_test(
)
```
-### Execution groups for native rules {#execution-groups-for-native-rules}
+### Execution groups for native rules
The following execution groups are available for actions defined by native
rules:
@@ -185,7 +186,7 @@ rules:
* `test`: Test runner actions.
* `cpp_link`: C++ linking actions.
-### Execution groups and platform execution properties {#platform-execution-properties}
+### 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
diff --git a/extending/legacy-macros.mdx b/extending/legacy-macros.mdx
index 564f1211..9c2b8e28 100644
--- a/extending/legacy-macros.mdx
+++ b/extending/legacy-macros.mdx
@@ -9,9 +9,9 @@ create targets. By the end of the
[loading phase](/extending/concepts#evaluation-model), legacy macros don't exist
anymore, and Bazel sees only the concrete set of instantiated rules.
-## Why you shouldn't use legacy macros (and should use Symbolic macros instead) {#no-legacy-macros}
+## Why you shouldn't use legacy macros (and should use Symbolic macros instead)
-Where possible you should use [symbolic macros](/extending/macros#macros).
+Where possible you should use [symbolic macros](macros.md#macros).
Symbolic macros
@@ -20,9 +20,9 @@ Symbolic macros
* Take typed attributes, which in turn means automatic label and select
conversion.
* Are more readable
-* Will soon have [lazy evaluation](/extending/macros#laziness)
+* Will soon have [lazy evaluation](macros.md#laziness)
-## Usage {#usage}
+## Usage
The typical use case for a macro is when you want to reuse a rule.
@@ -116,7 +116,7 @@ by other targets in the workspace.
Note: Similar to `$@` for outputs, `$<` expands to the locations of files in the
`srcs` attribute list.
-## Expanding macros {#expanding-macros}
+## Expanding macros
When you want to investigate what a macro does, use the `query` command with
`--output=build` to see the expanded form:
@@ -132,7 +132,7 @@ genrule(
)
```
-## Instantiating native rules {#instantiating-native-rules}
+## Instantiating native rules
Native rules (rules that don't need a `load()` statement) can be instantiated
from the [native](/rules/lib/toplevel/native) module:
@@ -151,10 +151,10 @@ the macro), use the function
[native.package_name()](/rules/lib/toplevel/native#package_name). Note that
`native` can only be used in `.bzl` files, and not in `BUILD` files.
-## Label resolution in macros {#label-resolution}
+## Label resolution in macros
Since legacy macros are evaluated in the
-[loading phase](/extending/concepts#evaluation-model), label strings such as
+[loading phase](concepts.md#evaluation-model), label strings such as
`"//foo:bar"` that occur in a legacy 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
@@ -190,7 +190,7 @@ relative to the package of the file that contains the `select` call. If this is
not chosen, wrap the label string with
[native.package_relative_label()](/rules/lib/toplevel/native#package_relative_label).
-## Debugging {#debugging}
+## Debugging
* `bazel query --output=build //my/path:all` will show you how the `BUILD`
file looks after evaluation. All legacy macros, globs, loops are expanded.
@@ -213,7 +213,7 @@ not chosen, wrap the label string with
`debugging` parameter that defaults to `False` before submitting the code to
the depot.
-## Errors {#errors}
+## Errors
If you want to throw an error, use the [fail](/rules/lib/globals/all#fail)
function. Explain clearly to the user what went wrong and how to fix their
@@ -226,7 +226,7 @@ def my_macro(name, deps, visibility=None):
# ...
```
-## Conventions {#conventions}
+## Conventions
* All public functions (functions that don't start with underscore) that
instantiate rules must have a `name` argument. This argument should not be
diff --git a/extending/macros.mdx b/extending/macros.mdx
index 44b7faae..136665d0 100644
--- a/extending/macros.mdx
+++ b/extending/macros.mdx
@@ -12,7 +12,7 @@ Macros are mainly used for encapsulation and code reuse of existing rules and
other macros.
Macros come in two flavors: symbolic macros, which are described on this page,
-and [legacy macros](/extending/legacy-macros). Where possible, we recommend using
+and [legacy macros](legacy-macros.md). Where possible, we recommend using
symbolic macros for code clarity.
Symbolic macros offer typed arguments (string to label conversion, relative to
@@ -25,15 +25,16 @@ referring to **symbolic macros**.
An executable example of symbolic macros can be found in the
[examples repository](https://github.com/bazelbuild/examples/tree/main/macros).
-## Usage {#usage}
+## Usage
Macros are defined in `.bzl` files by calling the
[`macro()`](https://bazel.build/rules/lib/globals/bzl.html#macro) function with
two required parameters: `attrs` and `implementation`.
-### Attributes {#attributes}
+### Attributes
-`attrs` accepts a dictionary of attribute name to [attribute types](https://bazel.build/rules/lib/toplevel/attr#members), which represents
+`attrs` accepts a dictionary of attribute name to [attribute
+types](https://bazel.build/rules/lib/toplevel/attr#members), which represents
the arguments to the macro. Two common attributes – `name` and `visibility` –
are implicitly added to all macros and are not included in the dictionary passed
to `attrs`.
@@ -57,7 +58,7 @@ Attribute type declarations accept the
as an unconfigurable `select` – `"foo"` will become
`select({"//conditions:default": "foo"})`. Learn more in [selects](#selects).
-#### Attribute inheritance {#attribute-inheritance}
+#### Attribute inheritance
Macros are often intended to wrap a rule (or another macro), and the macro's
author often wants to forward the bulk of the wrapped symbol's attributes
@@ -67,7 +68,9 @@ To support this pattern, a macro can *inherit attributes* from a rule or another
macro by passing the [rule](https://bazel.build/rules/lib/builtins/rule) or
[macro symbol](https://bazel.build/rules/lib/builtins/macro) to `macro()`'s
`inherit_attrs` argument. (You can also use the special string `"common"`
-instead of a rule or macro symbol to inherit the [common attributes defined for all Starlark build rules](https://bazel.build/reference/be/common-definitions#common-attributes).)
+instead of a rule or macro symbol to inherit the [common attributes defined for
+all Starlark build
+rules](https://bazel.build/reference/be/common-definitions#common-attributes).)
Only public attributes get inherited, and the attributes in the macro's own
`attrs` dictionary override inherited attributes with the same name. You can
also *remove* inherited attributes by using `None` as a value in the `attrs`
@@ -107,7 +110,7 @@ def _my_macro_impl(name, visibility, tags, **kwargs):
...
```
-### Implementation {#implementation}
+### Implementation
`implementation` accepts a function which contains the logic of the macro.
Implementation functions often create targets by calling one or more rules, and
@@ -141,7 +144,7 @@ invokes the inherited rule or submacro. (This helps ensure that your macro won't
be broken if the rule or macro which from which you are inheriting adds a new
attribute.)
-### Declaration {#declaration}
+### Declaration
Macros are declared by loading and calling their definition in a `BUILD` file.
@@ -177,9 +180,9 @@ my_macro(name = "abc", srcs = ["src.cc"])
This is generally not useful in `BUILD` files, but is helpful when
programmatically wrapping a macro inside another macro.
-## Details {#usage-details}
+## Details
-### Naming conventions for targets created {#naming}
+### Naming conventions for targets created
The names of any targets or submacros created by a symbolic macro must
either match the macro's `name` parameter or must be prefixed by `name` followed
@@ -196,7 +199,7 @@ exclusivity is not enforced. We are in the progress of implementing
[lazy evaluation](#laziness) as a performance improvement for Symbolic macros,
which will be impaired in packages that violate the naming schema.
-### Restrictions {#restrictions}
+### Restrictions
Symbolic macros have some additional restrictions compared to legacy macros.
@@ -216,7 +219,7 @@ Symbolic macros
* can't refer to private targets of their callers (see
[visibility and macros](#visibility) for more details).
-### Visibility and macros {#visibility}
+### Visibility and macros
The [visibility](/concepts/visibility) system helps protect the implementation
details of both (symbolic) macros and their callers.
@@ -335,7 +338,7 @@ Remember that legacy macros are entirely transparent to the visibility system,
and behave as though their location is whatever BUILD file or symbolic macro
they were called from.
-#### Finalizers and visibility {#finalizers-and-visibility}
+#### Finalizers and visibility
Targets declared in a rule finalizer, in addition to seeing targets following
the usual symbolic macro visibility rules, can *also* see all targets which are
@@ -350,7 +353,7 @@ that a finalizer's targets cannot see it under the visibility system – even
though the finalizer can *introspect* its attributes using
`native.existing_rules()`.
-### Selects {#selects}
+### Selects
If an attribute is `configurable` (the default) and its value is not `None`,
then the macro implementation function will see the attribute value as wrapped
@@ -389,7 +392,7 @@ not always possible for an attribute to take on a `None` value, but it can
happen for the `attr.label()` type, and for any inherited non-mandatory
attribute.
-## Finalizers {#finalizers}
+## Finalizers
A rule finalizer is a special symbolic macro which – regardless of its lexical
position in a BUILD file – is evaluated in the final stage of loading a package,
@@ -421,7 +424,7 @@ my_finalizer = macro(
)
```
-## Laziness {#laziness}
+## Laziness
IMPORTANT: We are in the process of implementing lazy macro expansion and
evaluation. This feature is not available yet.
@@ -432,7 +435,7 @@ unrelated macros. In the future, non-finalizer symbolic macros will only be
evaluated if they're required for the build. The prefix naming schema helps
Bazel determine which macro to expand given a requested target.
-## Migration troubleshooting {#troubleshooting}
+## Migration troubleshooting
Here are some common migration headaches and how to fix them.
diff --git a/extending/platforms.mdx b/extending/platforms.mdx
index f95f5e6a..9304d80b 100644
--- a/extending/platforms.mdx
+++ b/extending/platforms.mdx
@@ -72,7 +72,7 @@ builds target the same machine Bazel runs on. Build rules can
[@platforms/cpu](https://github.com/bazelbuild/platforms/blob/main/cpu/BUILD)
constraints.
-## Generally useful constraints and platforms {#useful-constraints-platforms}
+## 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
@@ -83,7 +83,7 @@ Bazel ships with the following special platform definition:
`@platforms//host` (aliased as `@bazel_tools//tools:host_platform`). This
auto-detects the OS and CPU properties of the machine Bazel runs on.
-## Defining constraints {#constraints}
+## Defining constraints
Constraints are modeled with the [`constraint_setting`][constraint_setting] and
[`constraint_value`][constraint_value] build rules.
@@ -113,7 +113,7 @@ the `x86` constraint as `//cpus:x86`.
If visibility allows, you can extend an existing `constraint_setting` by
defining your own value for it.
-## Defining platforms {#platforms}
+## Defining platforms
The [`platform`](/reference/be/platforms-and-toolchains#platform) build rule
defines a platform as a collection of `constraint_value`s:
@@ -135,7 +135,7 @@ Platforms may only have one `constraint_value` for a given `constraint_setting`.
This means, for example, a platform can't have two CPUs unless you create another
`constraint_setting` type to model the second value.
-## Skipping incompatible targets {#skipping-incompatible-targets}
+## 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
@@ -165,7 +165,7 @@ incompatible with all else. Incompatibility is transitive. Any targets
that transitively depend on an incompatible target are themselves considered
incompatible.
-### When are targets skipped? {#when-targets-skipped}
+### 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
@@ -200,7 +200,7 @@ FAILED: Build did NOT complete successfully
Incompatible explicit targets are silently skipped if
`--skip_incompatible_explicit_targets` is enabled.
-### More expressive constraints {#expressive-constraints}
+### More expressive constraints
For more flexibility in expressing constraints, use the
`@platforms//:incompatible`
@@ -252,11 +252,12 @@ cc_library(
)
```
-### Detecting incompatible targets using `bazel cquery` {#cquery-incompatible-target-detection}
+### Detecting incompatible targets using `bazel cquery`
You can use the
[`IncompatiblePlatformProvider`](/rules/lib/providers/IncompatiblePlatformProvider)
-in `bazel cquery`'s [Starlark output format](/query/cquery#output-format-definition) to distinguish
+in `bazel cquery`'s [Starlark output
+format](/query/cquery#output-format-definition) to distinguish
incompatible targets from compatible ones.
This can be used to filter out incompatible targets. The example below will
@@ -277,4 +278,5 @@ $ bazel cquery //... --output=starlark --starlark:file=example.cquery
### Known Issues
-Incompatible targets [ignore visibility restrictions](https://github.com/bazelbuild/bazel/issues/16044).
+Incompatible targets [ignore visibility
+restrictions](https://github.com/bazelbuild/bazel/issues/16044).
diff --git a/extending/rules.mdx b/extending/rules.mdx
index 8a4efe20..248ee328 100644
--- a/extending/rules.mdx
+++ b/extending/rules.mdx
@@ -170,7 +170,7 @@ dependency graph of targets.
-### Private attributes and implicit dependencies {#private_attributes_and_implicit_dependencies}
+### Private attributes and implicit dependencies
A dependency attribute with a default value creates an *implicit dependency*. It
is implicit because it's a part of the target graph that the user doesn't
@@ -451,7 +451,8 @@ def _example_library_impl(ctx):
If `DefaultInfo` is not returned by a rule implementation or the `files`
parameter is not specified, `DefaultInfo.files` defaults to all
-*predeclared outputs* (generally, those created by [output attributes](#output_attributes)).
+*predeclared outputs* (generally, those created by [output
+attributes](#output_attributes)).
Rules that perform actions should provide default outputs, even if those outputs
are not expected to be directly used. Actions that are not in the graph of the
@@ -542,7 +543,7 @@ provider instances satisfy certain invariants, or to give users a cleaner API fo
obtaining an instance.
This is done by passing an `init` callback to the
-[`provider`](/rules/lib/globals/bzl#provider) function. If this callback is given, the
+[`provider`](/rules/lib/globals/bzl.html#provider) function. If this callback is given, the
return type of `provider()` changes to be a tuple of two values: the provider
symbol that is the ordinary return value when `init` is not used, and a "raw
constructor".
@@ -994,7 +995,8 @@ By using `configuration_field`, the dependency on the Java LCOV merger tool can
be avoided as long as coverage is not requested.
When the test is run, it should emit coverage information in the form of one or
-more [LCOV files](https://manpages.debian.org/unstable/lcov/geninfo.1.en.html#TRACEFILE_FORMAT)
+more [LCOV files]
+(https://manpages.debian.org/unstable/lcov/geninfo.1.en.html#TRACEFILE_FORMAT)
with unique names into the directory specified by the `COVERAGE_DIR` environment
variable. Bazel will then merge these files into a single LCOV file using the
`_lcov_merger` tool. If present, it will also collect C/C++ coverage using the
diff --git a/extending/toolchains.mdx b/extending/toolchains.mdx
index 33f8bac9..249eaf06 100644
--- a/extending/toolchains.mdx
+++ b/extending/toolchains.mdx
@@ -11,7 +11,7 @@ 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 {#motivation}
+## 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`
@@ -124,7 +124,7 @@ 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 {#writing-rules-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
@@ -183,7 +183,7 @@ Bazel's procedure for resolving toolchains to targets is described
made a dependency of the `bar_binary` target, not the whole space of candidate
toolchains.
-### Mandatory and Optional Toolchains {#optional-toolchains}
+### Mandatory and Optional Toolchains
By default, when a rule expresses a toolchain type dependency using a bare label
(as shown above), the toolchain type is considered to be **mandatory**. If Bazel
@@ -232,7 +232,7 @@ You can mix and match forms in the same rule, also. However, if the same
toolchain type is listed multiple times, it will take the most strict version,
where mandatory is more strict than optional.
-### Writing aspects that use toolchains {#writing-aspects-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
@@ -251,7 +251,7 @@ def _bar_aspect_impl(target, ctx):
return []
```
-## Defining toolchains {#toolchain-definitions}
+## Defining toolchains
To define some toolchains for a given toolchain type, you need three things:
@@ -483,7 +483,7 @@ bar_toolchain(
)
```
-## Registering and building with toolchains {#registering-building-toolchains}
+## 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
@@ -539,7 +539,7 @@ has `@platforms//os:linux` and therefore resolve the
This will end up building `//bar_tools:barc_linux` but not
`//bar_tools:barc_windows`.
-## Toolchain resolution {#toolchain-resolution}
+## Toolchain resolution
Note: [Some Bazel rules](/concepts/platforms#status) do not yet support
toolchain resolution.
@@ -583,7 +583,8 @@ The set of available toolchains, in priority order, is created from
4. Toolchains registered in the "WORKSPACE suffix"; this is only used by
certain native rules bundled with the Bazel installation.
-**NOTE:** [Pseudo-targets like `:all`, `:*`, and `/...`](/run/build#specifying-build-targets) are ordered by Bazel's package
+**NOTE:** [Pseudo-targets like `:all`, `:*`, and
+`/...`](/run/build#specifying-build-targets) are ordered by Bazel's package
loading mechanism, which uses a lexicographic ordering.
The resolution steps are as follows.
@@ -631,7 +632,7 @@ additional constraints not specified by the toolchain. This lets developers
define arbitrarily precise platforms that don't lose toolchain compatibility
because of unrelated hardware variants.
-## Debugging toolchains {#debugging-toolchains}
+## Debugging toolchains
If you are adding toolchain support to an existing rule, use the
`--toolchain_resolution_debug=regex` flag. During toolchain resolution, the flag
diff --git a/external/extension.mdx b/external/extension.mdx
index 9a8dae94..15a1961d 100644
--- a/external/extension.mdx
+++ b/external/extension.mdx
@@ -6,7 +6,8 @@ title: 'Module extensions'
Module extensions allow users to extend the module system by reading input data
from modules across the dependency graph, performing necessary logic to resolve
-dependencies, and finally creating repos by calling [repo rules](/external/repo). These extensions have capabilities similar to repo
+dependencies, and finally creating repos by calling [repo
+rules](/external/repo). These extensions have capabilities similar to repo
rules, which enables them to perform file I/O, send network requests, and so on.
Among other things, they allow Bazel to interact with other package management
systems while also respecting the dependency graph built out of Bazel modules.
diff --git a/external/faq.mdx b/external/faq.mdx
index 7b1a31e8..480658fb 100644
--- a/external/faq.mdx
+++ b/external/faq.mdx
@@ -9,9 +9,9 @@ title: 'Frequently asked questions'
This page answers some frequently asked questions about external dependencies in
Bazel.
-## MODULE.bazel {#module-bazel}
+## MODULE.bazel
-### How should I version a Bazel module? {#module-versioning-best-practices}
+### How should I version a Bazel module?
Setting `version` with the [`module`] directive in the source archive
`MODULE.bazel` can have several downsides and unintended side effects if not
@@ -63,7 +63,7 @@ expected when sorting (the empty string is treated as the highest version).
[non-registry override]: module.md#non-registry_overrides
[`rules-template`]: https://github.com/bazel-contrib/rules-template
-### What is a compatibility level? {#compatibility-level}
+### What is a compatibility level?
You should stop using `compatibility_level`.
@@ -76,7 +76,7 @@ failures provide clear error messages and actionable migration paths.
**Legacy documentation:**
-The [`compatibility_level`](/external/module#compatibility_level) of a Bazel module
+The [`compatibility_level`](module.md#compatibility_level) of a Bazel module
should be incremented _in the same commit_ that introduces a backwards
incompatible ("breaking") change.
@@ -90,7 +90,7 @@ and is discouraged. To avoid this situation, the `compatibility_level` should be
incremented _only_ when the breaking change affects most use cases and isn't
easy to migrate and/or work-around.
-### Why does MODULE.bazel not support `load`s? {#why-does-module-bazel-not-support-loads}
+### Why does MODULE.bazel not support `load`s?
During dependency resolution, the MODULE.bazel file of all referenced external
dependencies are fetched from registries. At this stage, the source archives of
@@ -114,27 +114,29 @@ generally interested in, and they can be solved without `load`s:
`load`s in MODULE.bazel files, `include` cannot be used in non-root modules.
* Users of the old WORKSPACE system might remember declaring a repo, and then
immediately `load`ing from that repo to perform complex logic. This
- capability has been replaced by [module extensions](/external/extension).
+ capability has been replaced by [module extensions](extension).
-### Can I specify a SemVer range for a `bazel_dep`? {#can-i-specify-a-semver-range-for-a-bazel-dep}
+### Can I specify a SemVer range for a `bazel_dep`?
No. Some other package managers like [npm][npm-semver] and [Cargo][cargo-semver]
support version ranges (implicitly or explicitly), and this often requires a
constraint solver (making the output harder to predict for users) and makes
version resolution nonreproducible without a lockfile.
-Bazel instead uses [Minimal Version Selection](/external/module#version-selection) like
+Bazel instead uses [Minimal Version Selection](module#version-selection) like
Go, which in contrast makes the output easy to predict and guarantees
reproducibility. This is a tradeoff that matches Bazel's design goals.
-Furthermore, Bazel module versions are [a superset of SemVer](/external/module#version-format), so what makes sense in a strict SemVer
+Furthermore, Bazel module versions are [a superset of
+SemVer](module#version-format), so what makes sense in a strict SemVer
environment doesn't always carry over to Bazel module versions.
-### Can I automatically get the latest version for a `bazel_dep`? {#can-i-automatically-get-the-latest-version-for-a-bazel-dep}
+### Can I automatically get the latest version for a `bazel_dep`?
Some users occasionally ask for the ability to specify `bazel_dep(name = "foo",
version = "latest")` to automatically get the latest version of a dep. This is
-similar to [the question about SemVer ranges](#can-i-specify-a-semver-range-for-a-bazel-dep), and the answer is also
+similar to [the question about SemVer
+ranges](#can-i-specify-a-semver-range-for-a-bazel-dep), and the answer is also
no.
The recommended solution here is to have automation take care of this. For
@@ -145,7 +147,7 @@ Sometimes, users asking this question are really looking for a way to quickly
iterate during local development. This can be achieved by using a
[`local_path_override`](/rules/lib/globals/module#local_path_override).
-### Why all these `use_repo`s? {#why-all-these-use-repos}
+### Why all these `use_repo`s?
Module extension usages in MODULE.bazel files sometimes come with a big
`use_repo` directive. For example, a typical usage of the
@@ -182,9 +184,9 @@ an [`extension_metadata`](/rules/lib/builtins/module_ctx#extension_metadata)
object from its implementation function. The user can run the `bazel mod tidy`
command to update the `use_repo` directives for these module extensions.
-## Bzlmod migration {#bzlmod-migration}
+## Bzlmod migration
-### Which is evaluated first, MODULE.bazel or WORKSPACE? {#which-is-evaluated-first-module-bazel-or-workspace}
+### Which is evaluated first, MODULE.bazel or WORKSPACE?
When both `--enable_bzlmod` and `--enable_workspace` are set, it's natural to
wonder which system is consulted first. The short answer is that MODULE.bazel
@@ -192,7 +194,8 @@ wonder which system is consulted first. The short answer is that MODULE.bazel
The long answer is that "which evaluates first" is not the right question to
ask; rather, the right question to ask is: in the context of the repo with
-[canonical name](/external/overview#canonical-repo-name) `@@foo`, what does the [apparent repo name](/external/overview#apparent-repo-name) `@bar` resolve to? Alternatively, what
+[canonical name](overview#canonical-repo-name) `@@foo`, what does the [apparent
+repo name](overview#apparent-repo-name) `@bar` resolve to? Alternatively, what
is the repo mapping of `@@base`?
Labels with apparent repo names (a single leading `@`) can refer to different
@@ -201,7 +204,8 @@ things based on the context they're resolved from. When you see a label
what the context repo is: for example, if the label is in a BUILD file located
in the repo `@@foo`, then the context repo is `@@foo`.
-Then, depending on what the context repo is, the ["repository visibility" table](/external/migration#repository-visibility) in the migration guide can
+Then, depending on what the context repo is, the ["repository
+visibility" table](migration#repository-visibility) in the migration guide can
be used to find out which repo an apparent name actually resolves to.
* If the context repo is the main repo (`@@`):
@@ -247,13 +251,14 @@ Of note, labels in the Bazel command line (including Starlark flags, label-typed
flag values, and build/test target patterns) are treated as having the main repo
as the context repo.
-## Other {#other}
+## Other
-### How do I prepare and run an offline build? {#how-do-i-prepare-and-run-an-offline-build}
+### How do I prepare and run an offline build?
Use the `bazel fetch` command to prefetch repos. You can use the `--repo` flag
(like `bazel fetch --repo @foo`) to fetch only the repo `@foo` (resolved in the
-context of the main repo, see [question above](#which-is-evaluated-first-module-bazel-or-workspace)), or use a target
+context of the main repo, see [question
+above](#which-is-evaluated-first-module-bazel-or-workspace)), or use a target
pattern (like `bazel fetch @foo//:bar`) to fetch all transitive dependencies of
`@foo//:bar` (this is equivalent to `bazel build --nobuild @foo//:bar`).
@@ -261,9 +266,9 @@ To make sure no fetches happen during a build, use `--nofetch`. More precisely,
this makes any attempt to run a non-local repository rule fail.
If you want to fetch repos _and_ modify them to test locally, consider using
-the [`bazel vendor`](/external/vendor) command.
+the [`bazel vendor`](vendor) command.
-### How do I insulate my builds from the Internet? {#how-do-i-insulate-my-builds-from-the-internet}
+### How do I insulate my builds from the Internet?
Here are some websites on the publicly accessible Internet that a typical Bazel
build relies on, and what you can do to insulate yourself from potential
@@ -289,13 +294,13 @@ outages, especially as an enterprise Bazel user.
download cache as mentioned in the previous bullet point will also help
Bazel completely avoid accessing the Internet for source archives.
-### How do I use HTTP proxies? {#how-do-i-use-http-proxies}
+### How do I use HTTP proxies?
Bazel respects the `http_proxy` and `HTTPS_PROXY` environment variables commonly
accepted by other programs, such as
[curl](https://everything.curl.dev/usingcurl/proxies/env.html).
-### How do I make Bazel prefer IPv6 in dual-stack IPv4/IPv6 setups? {#ipv6}
+### How do I make Bazel prefer IPv6 in dual-stack IPv4/IPv6 setups?
On IPv6-only machines, Bazel can download dependencies with no changes. However,
on dual-stack IPv4/IPv6 machines Bazel follows the same convention as Java,
@@ -303,17 +308,21 @@ preferring IPv4 if enabled. In some situations, for example when the IPv4
network cannot resolve/reach external addresses, this can cause `Network
unreachable` exceptions and build failures. In these cases, you can override
Bazel's behavior to prefer IPv6 by using the
-[`java.net.preferIPv6Addresses=true` system property](https://docs.oracle.com/javase/8/docs/api/java/net/doc-files/net-properties.html).
+[`java.net.preferIPv6Addresses=true` system
+property](https://docs.oracle.com/javase/8/docs/api/java/net/doc-files/net-properties.html).
Specifically:
-* Use `--host_jvm_args=-Djava.net.preferIPv6Addresses=true` [startup option](/docs/user-manual#startup-options), for example by adding the
+* Use `--host_jvm_args=-Djava.net.preferIPv6Addresses=true` [startup
+ option](/docs/user-manual#startup-options), for example by adding the
following line in your [`.bazelrc` file](/run/bazelrc):
`startup --host_jvm_args=-Djava.net.preferIPv6Addresses=true`
* When running Java build targets that need to connect to the internet (such
as for integration tests), use the
- `--jvmopt=-Djava.net.preferIPv6Addresses=true` [tool flag](/docs/user-manual#jvmopt). For example, include in your [`.bazelrc` file](/run/bazelrc):
+ `--jvmopt=-Djava.net.preferIPv6Addresses=true` [tool
+ flag](/docs/user-manual#jvmopt). For example, include in your [`.bazelrc`
+ file](/run/bazelrc):
`build --jvmopt=-Djava.net.preferIPv6Addresses`
@@ -321,9 +330,10 @@ Specifically:
[`rules_jvm_external`](https://github.com/bazelbuild/rules_jvm_external) for
dependency version resolution, also add
`-Djava.net.preferIPv6Addresses=true` to the `COURSIER_OPTS` environment
- variable to [provide JVM options for Coursier](https://github.com/bazelbuild/rules_jvm_external#provide-jvm-options-for-coursier-with-coursier_opts).
+ variable to [provide JVM options for
+ Coursier](https://github.com/bazelbuild/rules_jvm_external#provide-jvm-options-for-coursier-with-coursier_opts).
-### Can repo rules be run remotely with remote execution? {#can-repo-rules-be-run-remotely-with-remote-execution}
+### Can repo rules be run remotely with remote execution?
No; or at least, not yet. Users employing remote execution services to speed up
their builds may notice that repo rules are still run locally. For example, an
@@ -346,7 +356,9 @@ build rules, which would naturally allow them to be run remotely, but conversely
raise new architectural concerns (for example, the `query` commands would
potentially need to run actions, complicating their design).
-For more previous discussion on this topic, see [A way to support repositories that need Bazel for being fetched](https://github.com/bazelbuild/bazel/discussions/20464).
+For more previous discussion on this topic, see [A way to support repositories
+that need Bazel for being
+fetched](https://github.com/bazelbuild/bazel/discussions/20464).
[npm-semver]: https://docs.npmjs.com/about-semantic-versioning
[cargo-semver]: https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#version-requirement-syntax
diff --git a/external/lockfile.mdx b/external/lockfile.mdx
index 6d66c2a6..d0eff0f8 100644
--- a/external/lockfile.mdx
+++ b/external/lockfile.mdx
@@ -14,7 +14,7 @@ in project dependencies. Furthermore, the lockfile improves stability by
preventing unexpected updates or breaking changes in external libraries, thereby
reducing the risk of introducing bugs.
-## Lockfile Generation {#lockfile-generation}
+## Lockfile Generation
The lockfile is generated under the workspace root with the name
`MODULE.bazel.lock`. It is created or updated during the build process,
@@ -28,7 +28,7 @@ remains focused on the specific set of dependencies required for the current
build, providing an accurate representation of the project's resolved
dependencies.
-## Lockfile Usage {#lockfile-usage}
+## Lockfile Usage
The lockfile can be controlled by the flag
[`--lockfile_mode`](/reference/command-line-reference#flag--lockfile_mode) to
@@ -50,7 +50,7 @@ lockfile. The available modes are:
expected to always produce the same result.
* `off`: The lockfile is neither checked nor updated.
-## Lockfile Benefits {#lockfile-benefits}
+## Lockfile Benefits
The lockfile offers several benefits and can be utilized in various ways:
@@ -69,7 +69,7 @@ The lockfile offers several benefits and can be utilized in various ways:
locking the dependencies to specific versions, the risk of introducing bugs
due to incompatible or untested updates is reduced.
-### Hidden lockfile {#hidden-lockfile}
+### Hidden lockfile
Bazel also maintains another lockfile at
`"$(bazel info output_base)"/MODULE.bazel.lock`. The format and contents of this
@@ -78,7 +78,7 @@ optimization. While it can be deleted together with the output base via
`bazel clean --expunge`, any need to do so is a bug in either Bazel itself or a
module extension.
-## Lockfile Contents {#lockfile-contents}
+## Lockfile Contents
The lockfile contains all the necessary information to determine whether the
project state has changed. It also includes the result of building the project
@@ -149,7 +149,7 @@ explanations for each section:
}
```
-### Registry File Hashes {#registry-file-hashes}
+### Registry File Hashes
The `registryFileHashes` section contains the hashes of all files from
remote registries accessed during module resolution. Since the resolution
@@ -165,7 +165,7 @@ Bazel uses the hashes from the lockfile to look up registry files in the
repository cache before downloading them, which speeds up subsequent
resolutions.
-### Selected Yanked Versions {#selected-yanked-versions}
+### Selected Yanked Versions
The `selectedYankedVersions` section contains the yanked versions of modules
that were selected by module resolution. Since this usually result in an error
@@ -177,7 +177,7 @@ This field is needed since, compared to module files, yanked version information
is inherently mutable and thus can't be referenced by a hash. This information
can be updated via `bazel mod deps --lockfile_mode=refresh`.
-### Module Extensions {#module-extensions}
+### Module Extensions
The `moduleExtensions` section is a map that includes only the extensions used
in the current invocation or previously invoked, while excluding any extensions
@@ -212,7 +212,7 @@ Module extensions can opt out of being included in the lockfile by setting the
returning metadata with `reproducible = True`. By doing so, they promise that
they will always create the same repositories when given the same inputs.
-## Best Practices {#best-practices}
+## Best Practices
To maximize the benefits of the lockfile feature, consider the following best
practices:
@@ -238,12 +238,12 @@ By following these best practices, you can effectively utilize the lockfile
feature in Bazel, leading to more efficient, reliable, and collaborative
software development workflows.
-## Merge Conflicts {#merge-conflicts}
+## Merge Conflicts
The lockfile format is designed to minimize merge conflicts, but they can still
happen.
-### Automatic Resolution {#automatic-resolution}
+### Automatic Resolution
Bazel provides a custom
[git merge driver](https://git-scm.com/docs/gitattributes#_defining_a_custom_merge_driver)
@@ -271,7 +271,7 @@ git config --global merge.bazel-lockfile-merge.name "Merge driver for the Baze
git config --global merge.bazel-lockfile-merge.driver "jq -s '${jq_script}' -- %O %A %B > %A.jq_tmp && mv %A.jq_tmp %A"
```
-### Manual Resolution {#manual-resolution}
+### Manual Resolution
Simple merge conflicts in the `registryFileHashes` and `selectedYankedVersions`
fields can be safely resolved by keeping all the entries from both sides of the
diff --git a/external/migration.mdx b/external/migration.mdx
index c3030533..b6277bf2 100644
--- a/external/migration.mdx
+++ b/external/migration.mdx
@@ -4,14 +4,15 @@ title: 'Bzlmod Migration Guide'
-Due to the [shortcomings of WORKSPACE](/external/overview#workspace-shortcomings), Bzlmod is replacing the
+Due to the [shortcomings of
+WORKSPACE](/external/overview#workspace-shortcomings), Bzlmod is replacing the
legacy WORKSPACE system. The WORKSPACE file is already disabled in Bazel 8 (late
2024) and will be removed in Bazel 9 (late 2025). This guide helps you migrate
your project to Bzlmod and drop WORKSPACE for managing external dependencies.
-## Why migrate to Bzlmod? {#why-migrate-to-bzlmod}
+## Why migrate to Bzlmod?
-* There are many [advantages](/external/overview#benefits) compared to the legacy
+* There are many [advantages](overview#benefits) compared to the legacy
WORKSPACE system, which helps to ensure a healthy growth of the Bazel
ecosystem.
@@ -22,7 +23,7 @@ your project to Bzlmod and drop WORKSPACE for managing external dependencies.
* Migration to Bzlmod is a necessary step in order to use future Bazel
versions (mandatory in Bazel 9).
-## How to migrate to Bzlmod? {#how-migrate-to-bzlmod}
+## How to migrate to Bzlmod?
Recommended migration process:
@@ -30,15 +31,16 @@ Recommended migration process:
streamline the migration process as much as possible.
2. If there are errors left after using the migration tool, resolve them
manually. For understanding the main differences between concepts inside
- `WORKSPACE` and `MODULE.bazel` files, check [WORKSPACE versus Bzlmod](#workspace-vs-bzlmod) section.
+ `WORKSPACE` and `MODULE.bazel` files, check [WORKSPACE versus
+ Bzlmod](#workspace-vs-bzlmod) section.
-## WORKSPACE vs Bzlmod {#workspace-vs-bzlmod}
+## WORKSPACE vs Bzlmod
Bazel's WORKSPACE and Bzlmod offer similar features with different syntax. This
section explains how to migrate from specific WORKSPACE functionalities to
Bzlmod.
-### Define the root of a Bazel workspace {#define-root}
+### Define the root of a Bazel workspace
The WORKSPACE file marks the source root of a Bazel project, this responsibility
is replaced by MODULE.bazel in Bazel version 6.3 and later. With Bazel versions
@@ -52,7 +54,7 @@ your workspace root, maybe with comments like:
# See MODULE.bazel for external dependencies setup.
```
-### Enable Bzlmod in your bazelrc {#enable-bzlmod}
+### Enable Bzlmod in your bazelrc
`.bazelrc` lets you set flags that apply every time your run Bazel. To enable
Bzlmod, use the `--enable_bzlmod` flag, and apply it to the `common` command so
@@ -65,7 +67,7 @@ it applies to every command:
common --enable_bzlmod
```
-### Specify repository name for your workspace {#specify-repo-name}
+### Specify repository name for your workspace
* **WORKSPACE**
@@ -99,7 +101,7 @@ it applies to every command:
)
```
-### Fetch external dependencies as Bazel modules {#fetch-bazel-modules}
+### Fetch external dependencies as Bazel modules
If your dependency is a Bazel project, you should be able to depend on it as a
Bazel module when it also adopts Bzlmod.
@@ -140,7 +142,9 @@ Bazel module when it also adopts Bzlmod.
* **Bzlmod**
- With Bzlmod, as long as your dependency is available in [Bazel Central Registry](https://registry.bazel.build) or your custom [Bazel registry](/external/registry), you can simply depend on it with a
+ With Bzlmod, as long as your dependency is available in [Bazel Central
+ Registry](https://registry.bazel.build) or your custom [Bazel
+ registry](/external/registry), you can simply depend on it with a
[`bazel_dep`](/rules/lib/globals/module#bazel_dep) directive.
```python
@@ -171,7 +175,8 @@ repository.
If your dependency is not a Bazel project or not yet available in any Bazel
registry, you can introduce it using
-[`use_repo_rule`](/external/module#use_repo_rule) or [module extensions](/external/extension).
+[`use_repo_rule`](/external/module#use_repo_rule) or [module
+extensions](/external/extension).
* **WORKSPACE**
@@ -245,7 +250,7 @@ registry, you can introduce it using
use_repo(non_module_dependencies, "data_file")
```
-### Resolve conflict external dependencies with module extension {#conflict-deps-module-extension}
+### Resolve conflict external dependencies with module extension
A project can provide a macro that introduces external repositories based on
inputs from its callers. But what if there are multiple callers in the
@@ -255,7 +260,7 @@ Assume the project `foo` provides the following macro which takes `version` as
an argument.
```python
-## repositories.bzl in foo {#repositories.bzl-foo}
+## repositories.bzl in foo
load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_file")
def data_deps(version = "1.0"):
http_file(
@@ -340,7 +345,7 @@ def data_deps(version = "1.0"):
resolve this conflict and automatically select version `3.0` for the data
dependency.
-### Integrate third party package manager {#integrate-package-manager}
+### Integrate third party package manager
Following the last section, since module extension provides a way to collect
information from the dependency graph, perform custom logic to resolve
@@ -364,7 +369,7 @@ repository.
[pkg-mgr-example]: https://github.com/bazelbuild/examples/tree/main/bzlmod/05-integrate_third_party_package_manager
-### Detect toolchains on the host machine {#detect-toolchain}
+### Detect toolchains on the host machine
When Bazel build rules need to detect what toolchains are available on your host
machine, they use repository rules to inspect the host machine and generate
@@ -437,7 +442,7 @@ toolchain info as external repositories.
use_repo(sh_config_ext, "local_config_sh")
```
-### Register toolchains & execution platforms {#register-toolchains}
+### Register toolchains & execution platforms
Following the last section, after introducing a repository hosting toolchain
information (e.g. `local_config_sh`), you probably want to register the
@@ -502,7 +507,7 @@ order of precedence during toolchain selection (from highest to lowest):
[register_execution_platforms]: /rules/lib/globals/module#register_execution_platforms
-### Introduce local repositories {#introduce-local-deps}
+### Introduce local repositories
You may need to introduce a dependency as a local repository when you need a
local version of the dependency for debugging or you want to incorporate a
@@ -551,7 +556,7 @@ directory in your workspace as external repository.
extension. It's also trivial to implement a custom version of
`local_repository` repository rule if this is a blocking issue for you.
-### Bind targets {#bind-targets}
+### Bind targets
The [`bind`](/reference/be/workspace#bind) rule in WORKSPACE is deprecated and
not supported in Bzlmod. It was introduced to give a target an alias in the
@@ -588,7 +593,7 @@ away from this by:
* Replace all usages of `//external:openssl` with `//third_party:openssl`.
-### Fetch versus Sync {#fetch-sync}
+### Fetch versus Sync
Fetch and sync commands are used to download external repos locally and keep
them updated. Sometimes also to allow building offline using the `--nofetch`
@@ -609,12 +614,13 @@ flag after fetching all repos needed for a build.
The fetch result is cached and to force a fetch you must include the
`--force` option during the fetch process.
-## Manual migration {#manual-migration}
+## Manual migration
This section provides useful information and guidance for your **manual** Bzlmod
-migration process. For more automatized migration process, check [recommended migration process](#how-migrate-to-bzlmod) section.
+migration process. For more automatized migration process, check [recommended
+migration process](#how-migrate-to-bzlmod) section.
-### Know your dependencies in WORKSPACE {#know-deps-in-workspace}
+### Know your dependencies in WORKSPACE
The first step of migration is to understand what dependencies you have. It
could be hard to figure out what exact dependencies are introduced in the
@@ -626,7 +632,8 @@ macros.
Fortunately, the flag
[`--experimental_repository_resolved_file`][resolved_file_flag]
can help. This flag essentially generates a "lock file" of all fetched external
-dependencies in your last Bazel command. You can find more details in this [blog post](https://blog.bazel.build/2018/07/09/bazel-sync-and-resolved-file.html).
+dependencies in your last Bazel command. You can find more details in this [blog
+post](https://blog.bazel.build/2018/07/09/bazel-sync-and-resolved-file.html).
[resolved_file_flag]: /reference/command-line-reference#flag--experimental_repository_resolved_file
@@ -667,11 +674,13 @@ You may also know `bazel query` can be used for inspecting repository rules with
bazel query --output=build //external:
```
-While it is more convenient and much faster, [bazel query can lie about external dependency version](https://github.com/bazelbuild/bazel/issues/12947),
+While it is more convenient and much faster, [bazel query can lie about
+external dependency version](https://github.com/bazelbuild/bazel/issues/12947),
so be careful using it! Querying and inspecting external
-dependencies with Bzlmod is going to achieved by a [new subcommand](https://github.com/bazelbuild/bazel/issues/15365).
+dependencies with Bzlmod is going to achieved by a [new
+subcommand](https://github.com/bazelbuild/bazel/issues/15365).
-#### Built-in default dependencies {#builtin-default-deps}
+#### Built-in default dependencies
If you check the file generated by `--experimental_repository_resolved_file`,
you are going to find many dependencies that are not defined in your WORKSPACE.
@@ -684,7 +693,7 @@ Bazel module.
[bazel_tools]: https://github.com/bazelbuild/bazel/blob/master/src/MODULE.tools
-### Hybrid mode for gradual migration {#hybrid-mode}
+### Hybrid mode for gradual migration
Bzlmod and WORKSPACE can work side by side, which allows migrating dependencies
from the WORKSPACE file to Bzlmod to be a gradual process.
@@ -693,7 +702,7 @@ Note: In practice, loading "*_deps" macros in WORKSPACE often causes confusions
with Bzlmod dependencies, therefore we recommend starting with a
WORKSPACE.bzlmod file and avoid loading transitive dependencies with macros.
-#### WORKSPACE.bzlmod {#workspace.bzlmod}
+#### WORKSPACE.bzlmod
During the migration, Bazel users may need to switch between builds with and
without Bzlmod enabled. WORKSPACE.bzlmod support is implemented to make the
@@ -713,10 +722,11 @@ Using the WORKSPACE.bzlmod file can make the migration easier because:
* When Bzlmod is enabled, you can better track what dependencies are left to
migrate with WORKSPACE.bzlmod.
-#### Repository visibility {#repository-visibility}
+#### Repository visibility
Bzlmod is able to control which other repositories are visible from a given
-repository, check [repository names and strict deps](/external/module#repository_names_and_strict_deps) for more details.
+repository, check [repository names and strict
+deps](/external/module#repository_names_and_strict_deps) for more details.
Here is a summary of repository visibilities from different types of
repositories when also taking WORKSPACE into consideration.
@@ -729,7 +739,8 @@ repositories when also taking WORKSPACE into consideration.
| WORKSPACE Repos | All visible | Not visible | Not visible | All visible |
Note: For the root module, if a repository `@foo` is defined in WORKSPACE and
-`@foo` is also used as an [apparent repository name](/external/overview#apparent-repo-name) in MODULE.bazel, then `@foo`
+`@foo` is also used as an [apparent repository
+name](/external/overview#apparent-repo-name) in MODULE.bazel, then `@foo`
refers to the one introduced in MODULE.bazel.
Note: For a module extension generated repository `@bar`, if `@foo` is used as
@@ -738,7 +749,7 @@ another repository generated by the same module extension and direct
dependencies of the module hosting the module extension, then for repository
`@bar`, `@foo` refers to the latter.
-### Manual migration process {#manual-migration-process}
+### Manual migration process
A typical Bzlmod migration process can look like this:
@@ -753,7 +764,7 @@ A typical Bzlmod migration process can look like this:
extension, or leave it in the WORKSPACE.bzlmod for later migration.
1. Go back to 4 and repeat until all dependencies are available.
-## Publish Bazel modules {#publish-modules}
+## Publish Bazel modules
If your Bazel project is a dependency for other projects, you can publish your
project in the [Bazel Central Registry](https://registry.bazel.build/).
@@ -774,7 +785,9 @@ the project. Take note of a few things when creating the source archive:
GitHub isn't going to guarantee the checksum of source archives generated on
demand. In short, URLs in the form of
`https://github.com///releases/download/...` is considered stable
- while `https://github.com///archive/...` is not. Check [GitHub Archive Checksum Outage](https://blog.bazel.build/2023/02/15/github-archive-checksum.html)
+ while `https://github.com///archive/...` is not. Check [GitHub
+ Archive Checksum
+ Outage](https://blog.bazel.build/2023/02/15/github-archive-checksum.html)
for more context.
* **Make sure the source tree follows the layout of the original repository.**
@@ -803,10 +816,11 @@ Pull Request.
[bcr_contrib_guide]: https://github.com/bazelbuild/bazel-central-registry/tree/main/docs#contribute-a-bazel-module
-It is **highly recommended** to set up the [Publish to BCR](https://github.com/bazel-contrib/publish-to-bcr) GitHub App for your
+It is **highly recommended** to set up the [Publish to
+BCR](https://github.com/bazel-contrib/publish-to-bcr) GitHub App for your
repository to automate the process of submitting your module to the BCR.
-## Best practices {#best-practices}
+## Best practices
This section documents a few best practices you should follow for better
managing your external dependencies.
@@ -831,14 +845,14 @@ still build without dev dependencies and overrides.
-## Community migration progress {#migration-progress}
+## Community migration progress
You can check the [Bazel Central Registry](https://registry.bazel.build) to find
out if your dependencies are already available. Otherwise feel free to join this
[GitHub discussion](https://github.com/bazelbuild/bazel/discussions/18329) to
upvote or post the dependencies that are blocking your migration.
-## Report issues {#reporting-issues}
+## Report issues
Please check the [Bazel GitHub issue list][bzlmod_github_issue] for known Bzlmod
issues. Feel free to file new issues or feature requests that can help unblock
diff --git a/external/migration_tool.mdx b/external/migration_tool.mdx
index cf59c153..fe3c591c 100644
--- a/external/migration_tool.mdx
+++ b/external/migration_tool.mdx
@@ -14,7 +14,7 @@ management system.
**Note**: If you want to try out the AI driven Bzlmod migration, check [Bzlmod Migration Agent Setup][gemini_cli_setup].
-## Core Functionality {#migration-tool-core-functionality}
+## Core Functionality
The script's primary functions are:
@@ -52,7 +52,7 @@ The migration tool supports:
recommendations for correctness.
* Use the migration tool with Bazel 7 (not supported with Bazel 8).
-## How to Use the Migration Tool {#migration-tool-how-to-use}
+## How to Use the Migration Tool
Before you begin:
@@ -65,7 +65,7 @@ Before you begin:
bazel build --nobuild --enable_workspace --noenable_bzlmod
```
-### Command for running the script {#migration-script-command}
+### Command for running the script
Once the prerequisites are met, run the following commands to use the migration
tool:
@@ -86,7 +86,7 @@ cd <your project root>
migrate2bzlmod -t <targets>
-### Files generated by this script {#migration-script-files}
+### Files generated by this script
* `MODULE.bazel` - The central manifest file for Bzlmod, which declares the
project's metadata and its direct dependencies on other Bazel modules.
@@ -102,9 +102,10 @@ migrate2bzlmod -t <targets>
script.
* `extension_for_XXX` - A file containing a module extension
definition. The migration tool generates these files for dependencies that
- are not standard Bazel modules but can be managed using Bzlmod's [module extensions](/external/extension).
+ are not standard Bazel modules but can be managed using Bzlmod's [module
+ extensions](/external/extension).
-### Flags {#migration-script-flags}
+### Flags
Flags available in this migration scripts are:
@@ -115,13 +116,13 @@ Flags available in this migration scripts are:
dependencies, introduce them in MODULE.bazel and rerun generation of
resolved dependencies.
-### Post-migration cleanup {#post-migration-cleanup}
+### Post-migration cleanup
* Delete `migration_info.md`, `resolved_deps.py` and `query_direct_deps`.
* Clean up comments from `MODULE.bazel` file which were used for the
migration, such as `# -- bazel_dep definitions -- #`.
-## Migration Example {#migration-tool-example}
+## Migration Example
To see the migration script in action, consider the following scenario when
Python, Maven and Go dependencies are declared in `WORKSPACE` file.
@@ -299,7 +300,8 @@ def my_custom_macro(name):
The end goal is to have `MODULE.bazel` file and delete the `WORKSPACE` file,
without impacting the user experience.
-The first step is to follow [How to Use the Migration Tool](#migration-tool-how-to-use), which mostly is checking the bazel version
+The first step is to follow [How to Use the Migration
+Tool](#migration-tool-how-to-use), which mostly is checking the bazel version
(it must be Bazel 7) and adding an alias to the migration script.
Then, running `migrate2bzlmod -t=//...` outputs:
@@ -341,7 +343,7 @@ which gives the following important information:
* `migration_info.md` file contains details about the migration. Check details
[at this section](#migration-tool-report-generation).
-### Transformations {#migration-tool-transformations}
+### Transformations
This section illustrates the migration of code from the `WORKSPACE` file to
`MODULE.bazel`.
@@ -595,12 +597,12 @@ extension_for_my_custom_macro = module_extension(implementation = _extension_for
-## Tips with debugging {#migration-tool-tips}
+## Tips with debugging
This section provides useful commands and information to help debug issues that
may arise during the Bzlmod migration.
-### Useful tips {#debugging-useful-tips}
+### Useful tips
* Override version - Not rarely it happens that upgrading the version of a
dependency causes troubles. Bzlmod could change the version of the
@@ -629,10 +631,11 @@ may arise during the Bzlmod migration.
`bazel vendor --enable_bzlmod --vendor_dir=vendor_src --repo=@protobuf`
-### Migration Report Generation {#migration-tool-report-generation}
+### Migration Report Generation
This file is updated with each run of the migration script or it's generated
-from scratch if it's the first run or if the [`--i` flag](#migration-script-flags) is used. The report contains:
+from scratch if it's the first run or if the [`--i`
+flag](#migration-script-flags) is used. The report contains:
* Command for local testing.
* List of direct dependencies (at least the ones which are directly used in
@@ -703,7 +706,7 @@ from scratch if it's the first run or if the [`--i` flag](#migration-script-flag
to the `MODULE.bazel` file.
* `gazelle_override` is used for adding specific directives.
-## Useful links {#useful-links}
+## Useful links
* Official pages for the external extensions
* [rules_jvm_external](https://github.com/bazelbuild/rules_jvm_external/blob/master/docs/bzlmod.md)
@@ -714,7 +717,7 @@ from scratch if it's the first run or if the [`--i` flag](#migration-script-flag
* [Moving to Bzlmod](https://www.youtube.com/watch?v=W9uXRYLVHUk).
* [How Uber Manages Go Dependencies with Bzlmod](https://www.youtube.com/watch?v=hIqzkUE_pSY).
-## Feedback {#feedback}
+## Feedback
If you would like to contribute, do so by creating an Issue or PR at
[bazel-central-registry](https://github.com/bazelbuild/bazel-central-registry).
diff --git a/external/mod-command.mdx b/external/mod-command.mdx
index 9eea1572..8ca69da8 100644
--- a/external/mod-command.mdx
+++ b/external/mod-command.mdx
@@ -9,7 +9,7 @@ why a certain module or a version of a module is present in the graph, view the
repo definitions backing modules, inspect usages of module extensions and repos
they generate, among other functions.
-## Syntax {#syntax}
+## Syntax
```sh
bazel mod [] [ [...]]
@@ -64,9 +64,11 @@ The available subcommands and their respective required arguments are:
* ``: All present versions of the module ``.
-* `@`: The repo with the given [apparent name](/external/overview#apparent-repo-name) in the context of the `--base_module`.
+* `@`: The repo with the given [apparent
+ name](overview#apparent-repo-name) in the context of the `--base_module`.
-* `@@`: The repo with the given [canonical name](/external/overview#canonical-repo-name).
+* `@@`: The repo with the given [canonical
+ name](overview#canonical-repo-name).
In a context requiring specifying modules, ``s referring to repos that
correspond to modules (as opposed to extension-generated repos) can also be
@@ -90,14 +92,15 @@ The following options only affect the subcommands that print graphs (`graph`,
information about the version resolution of each module. If the module
version changed during resolution, show either which version replaced it or
what was the original version, the reason it was replaced, and which modules
- requested the new version if the reason was [Minimal Version Selection](/external/module#version-selection).
+ requested the new version if the reason was [Minimal Version
+ Selection](module#version-selection).
* `--include_unused` *default: "false"*: Include in the output graph the
modules which were originally present in the dependency graph, but became
unused after module resolution.
-* `--extension_info mode`: Include information about the module extension
- usages as part of the output graph (see [example](#mod-example7)). `mode`
+* `--extension_info `: Include information about the module extension
+ usages as part of the output graph (see [example](#mod-example7)). ``
can be one of:
* `hidden` *(default)*: Don't show anything about extensions.
@@ -137,8 +140,8 @@ The following options only affect the subcommands that print graphs (`graph`,
Therefore, the `"ascii"` charset is present to also support the usage on
legacy platforms which cannot use Unicode.
-* `--output mode`: Include information about the module extension usages as
- part of the output graph. `mode' can be one of:
+* `--output `: Include information about the module extension usages as
+ part of the output graph. `' can be one of:
* `text` *(default)*: A human-readable representation of the output graph
(flattened as a tree).
@@ -157,8 +160,8 @@ The following options only affect the subcommands that print graphs (`graph`,
### show_repo options
`show_repo` supports a different set of output formats:
-* `--output mode`: Change how repository definitions are displayed.
- `mode` can be one of:
+* `--output `: Change how repository definitions are displayed.
+ `` can be one of:
* `text` *(default)*: Display repo definitions in Starlark.
* `streamed_proto`: Prints a
[length-delimited](https://protobuf.dev/programming-guides/encoding/#size-limit)
@@ -181,7 +184,7 @@ Other options include:
* `--extension_usages [,[,...]]`: Filters `show_extension` to only
display extension usages from the specified modules.
-## Examples {#examples}
+## Examples
Some possible usages of the `mod` command on a real Bazel project are showcased
below to give you a general idea on how you can use it to inspect your project's
@@ -210,10 +213,10 @@ use_repo(toolchains, my_jdk="remotejdk17_linux")
-
+ Graph Before Resolution
-{/* digraph mygraph {
+
-
+ Graph After Resolution
-{/* digraph mygraph {
+
diff --git a/external/module.mdx b/external/module.mdx
index f4fe31a4..b3f035da 100644
--- a/external/module.mdx
+++ b/external/module.mdx
@@ -32,7 +32,7 @@ By default, Bazel then [selects](#version-selection) one version of each module
to use. Bazel represents each module with a repo, and consults the registry
again to learn how to define each of the repos.
-## Version format {#version-format}
+## Version format
Bazel has a diverse ecosystem and projects use various versioning schemes. The
most popular by far is [SemVer](https://semver.org), but there are
@@ -56,9 +56,10 @@ Any valid SemVer version is a valid Bazel module version. Additionally, two
SemVer versions `a` and `b` compare `a < b` if and only if the same holds when
they're compared as Bazel module versions.
-Finally, to learn more about module versioning, [see the `MODULE.bazel` FAQ](/external/faq#module-versioning-best-practices).
+Finally, to learn more about module versioning, [see the `MODULE.bazel`
+FAQ](faq#module-versioning-best-practices).
-## Version selection {#version-selection}
+## Version selection
Consider the diamond dependency problem, a staple in the versioned dependency
management space. Suppose you have the dependency graph:
@@ -110,7 +111,8 @@ serves multiple purposes:
version, regardless of which versions of the dependency are requested in the
dependency graph.
* With the `registry` attribute, you can force this dependency to come from a
- specific registry, instead of following the normal [registry selection](/external/registry#selecting_registries) process.
+ specific registry, instead of following the normal [registry
+ selection](/external/registry#selecting_registries) process.
* With the `patch*` attributes, you can specify a set of patches to apply to
the downloaded module.
@@ -151,19 +153,22 @@ Bazel supports the following non-registry overrides:
Note that setting a version value in the source archive `MODULE.bazel` can have
downsides when the module is being overridden with a non-registry override. To
-learn more about this [see the `MODULE.bazel` FAQ](/external/faq#module-versioning-best-practices).
+learn more about this [see the `MODULE.bazel`
+FAQ](faq#module-versioning-best-practices).
-## Define repos that don't represent Bazel modules {#use_repo_rule}
+## Define repos that don't represent Bazel modules
With `bazel_dep`, you can define repos that represent other Bazel modules.
Sometimes there is a need to define a repo that does _not_ represent a Bazel
module; for example, one that contains a plain JSON file to be read as data.
-In this case, you could use the [`use_repo_rule` directive](/rules/lib/globals/module#use_repo_rule) to directly define a repo
+In this case, you could use the [`use_repo_rule`
+directive](/rules/lib/globals/module#use_repo_rule) to directly define a repo
by invoking a repo rule. This repo will only be visible to the module it's
defined in.
-Under the hood, this is implemented using the same mechanism as [module extensions](/external/extension), which lets you define repos with more
+Under the hood, this is implemented using the same mechanism as [module
+extensions](/external/extension), which lets you define repos with more
flexibility.
## Repository names and strict deps
diff --git a/external/overview.mdx b/external/overview.mdx
index ed819f7e..36464341 100644
--- a/external/overview.mdx
+++ b/external/overview.mdx
@@ -13,9 +13,10 @@ machine outside your current workspace.
This document gives an overview of the system before examining some of the
concepts in more detail.
-## Overview of the system {#overview}
+## Overview of the system
-Bazel's external dependency system works on the basis of [*Bazel modules*](#module), each of which is a versioned Bazel project, and
+Bazel's external dependency system works on the basis of [*Bazel
+modules*](#module), each of which is a versioned Bazel project, and
[*repositories*](#repository) (or repos), which are directory trees containing
source files.
@@ -32,7 +33,8 @@ bazel_dep(name = "platforms", version = "0.0.11")
```
From there, Bazel looks up all transitive dependency modules in a
-[*Bazel registry*](/external/registry) — by default, the [Bazel Central Registry](https://bcr.bazel.build/). The registry provides the
+[*Bazel registry*](registry) — by default, the [Bazel Central
+Registry](https://bcr.bazel.build/). The registry provides the
dependencies' `MODULE.bazel` files, which allows Bazel to discover the entire
transitive dependency graph before performing version resolution.
@@ -42,7 +44,7 @@ Bazel consults the registry again to learn how to define a repo for each module
of the time, these are just archives downloaded from the internet and extracted.
Modules can also specify customized pieces of data called *tags*, which are
-consumed by [*module extensions*](/external/extension) after module resolution
+consumed by [*module extensions*](extension) after module resolution
to define additional repos. These extensions can perform actions like file I/O
and sending network requests. Among other things, they allow Bazel to interact
with other package management systems while also respecting the dependency graph
@@ -54,23 +56,23 @@ created by module extensions -- form the [*workspace*](#workspace) together.
External repos (non-main repos) are fetched on demand, for example when they're
referred to by labels (like `@repo//pkg:target`) in BUILD files.
-## Benefits {#benefits}
+## Benefits
Bazel's external dependency system offers a wide range of benefits.
-### Automatic Dependency Resolution {#automatic-dependency-resolution}
+### Automatic Dependency Resolution
- **Deterministic Version Resolution**: Bazel adopts the deterministic
- [MVS](/external/module#version-selection) version resolution algorithm,
+ [MVS](module#version-selection) version resolution algorithm,
minimizing conflicts and addressing diamond dependency issues.
- **Simplified Dependency Management**: `MODULE.bazel` declares only direct
dependencies, while transitive dependencies are automatically resolved,
providing a clearer overview of the project's dependencies.
-- **[Strict Dependency visibility](/external/module#repository_names_and_strict_deps)**:
+- **[Strict Dependency visibility](module#repository_names_and_strict_deps)**:
Only direct dependencies are visible, ensuring correctness and
predictability.
-### Ecosystem Integration {#ecosystem-integration}
+### Ecosystem Integration
- **[Bazel Central Registry](https://registry.bazel.build/)**: A centralized
repository for discovering and managing common dependencies as Bazel
@@ -91,37 +93,38 @@ Bazel's external dependency system offers a wide range of benefits.
* [rules_rust](https://bazelbuild.github.io/rules_rust/crate_universe_bzlmod.html)
for Cargo.
-### Advanced Features {#advanced-features}
+### Advanced Features
-- **[Module Extensions](/external/extension)**: The
+- **[Module Extensions](extension)**: The
[`use_repo_rule`](/rules/lib/globals/module#use_repo_rule) and module
extension features allow flexible use of custom repository rules and
resolution logic to introduce any non-Bazel dependencies.
-- **[`bazel mod` Command](/external/mod-command)**: The sub-command offers
+- **[`bazel mod` Command](mod-command)**: The sub-command offers
powerful ways to inspect external dependencies. You know exactly how an
external dependency is defined and where it comes from.
-- **[Vendor Mode](/external/vendor)**: Pre-fetch the exact external dependencies you
+- **[Vendor Mode](vendor)**: Pre-fetch the exact external dependencies you
need to facilitate offline builds.
-- **[Lockfile](/external/lockfile)**: The lockfile improves build reproducibility and
+- **[Lockfile](lockfile)**: The lockfile improves build reproducibility and
accelerates dependency resolution.
-- **(Upcoming) [BCR Provenance Attestations](https://github.com/bazelbuild/bazel-central-registry/discussions/2721)**:
+- **(Upcoming) [BCR Provenance
+ Attestations](https://github.com/bazelbuild/bazel-central-registry/discussions/2721)**:
Strengthen supply chain security by ensuring verified provenance of
dependencies.
-## Concepts {#concepts}
+## Concepts
This section gives more detail on concepts related to external dependencies.
-### Module {#module}
+### Module
A Bazel project that can have multiple versions, each of which can have
dependencies on other modules.
In a local Bazel workspace, a module is represented by a repository.
-For more details, see [Bazel modules](/external/module).
+For more details, see [Bazel modules](module).
-### Repository {#repository}
+### Repository
A directory tree with a boundary marker file at its root, containing source
files that can be used in a Bazel build. Often shortened to just **repo**.
@@ -132,14 +135,14 @@ legacy contexts, `WORKSPACE` or `WORKSPACE.bazel`. Any repo boundary marker file
will signify the boundary of a repo; multiple such files can coexist in a
directory.
-### Main repository {#main-repository}
+### Main repository
The repository in which the current Bazel command is being run.
The root of the main repository is also known as the
**workspace root**.
-### Workspace {#workspace}
+### Workspace
The environment shared by all Bazel commands run in the same main repository. It
encompasses the main repo and the set of all defined external repos.
@@ -148,7 +151,7 @@ Note that historically the concepts of "repository" and "workspace" have been
conflated; the term "workspace" has often been used to refer to the main
repository, and sometimes even used as a synonym of "repository".
-### Canonical repository name {#canonical-repo-name}
+### Canonical repository name
The name by which a repository is always addressable. Within the context of a
workspace, each repository has a single canonical name. A target inside a repo
@@ -157,7 +160,7 @@ whose canonical name is `canonical_name` can be addressed by the label
The main repository always has the empty string as the canonical name.
-### Apparent repository name {#apparent-repo-name}
+### Apparent repository name
The name by which a repository is addressable in the context of a certain other
repo. This can be thought of as a repo's "nickname": The repo with the canonical
@@ -169,7 +172,7 @@ name `michael` might have the apparent name `mike` in the context of the repo
Conversely, this can be understood as a **repository mapping**: each repo
maintains a mapping from "apparent repo name" to a "canonical repo name".
-### Repository rule {#repo-rule}
+### Repository rule
A schema for repository definitions that tells Bazel how to materialize a
repository. For example, it could be "download a zip archive from a certain URL
@@ -177,7 +180,7 @@ and extract it", or "fetch a certain Maven artifact and make it available as a
`java_import` target", or simply "symlink a local directory". Every repo is
**defined** by calling a repo rule with an appropriate number of arguments.
-See [Repository rules](/external/repo) for more information about how to write
+See [Repository rules](repo) for more information about how to write
your own repository rules.
The most common repo rules by far are
@@ -186,7 +189,7 @@ from a URL and extracts it, and
[`local_repository`](/rules/lib/repo/local#local_repository), which symlinks a
local directory that is already a Bazel repository.
-### Fetch a repository {#fetch-repository}
+### Fetch a repository
The action of making a repo available on local disk by running its associated
repo rule. The repos defined in a workspace are not available on local disk
@@ -208,7 +211,7 @@ failure.
See [fetch options](/reference/command-line-reference#fetch-options) for more
information about controlling fetch.
-### Directory layout {#directory-layout}
+### Directory layout
After being fetched, the repo can be found in the subdirectory `external` in the
[output base](/remote/output-directories), under its canonical name.
@@ -220,7 +223,7 @@ canonical name `canonical_name`:
ls $(bazel info output_base)/external/ canonical_name
```
-### REPO.bazel file {#repo.bazel}
+### REPO.bazel file
The [`REPO.bazel`](/rules/lib/globals/repo) file is used to mark the topmost
boundary of the directory tree that constitutes a repo. It doesn't need to
@@ -228,7 +231,8 @@ contain anything to serve as a repo boundary file; however, it can also be used
to specify some common attributes for all build targets inside the repo.
The syntax of a `REPO.bazel` file is similar to `BUILD` files, except that no
-`load` statements are supported. The `repo()` function takes the same arguments as the [`package()` function](/reference/be/functions#package) in `BUILD` files; whereas `package()`
+`load` statements are supported. The `repo()` function takes the same arguments as the [`package()`
+function](/reference/be/functions#package) in `BUILD` files; whereas `package()`
specifies common attributes for all build targets inside the package, `repo()`
analogously does so for all build targets inside the repo.
@@ -241,7 +245,7 @@ repo(
)
```
-## The legacy WORKSPACE system {#workspace-system}
+## The legacy WORKSPACE system
In older Bazel versions (before 9.0), external dependencies were introduced by
defining repos in the `WORKSPACE` (or `WORKSPACE.bazel`) file. This file has a
@@ -266,7 +270,7 @@ all other repos.
See the [full list](/rules/lib/globals/workspace) of functions available in
`WORKSPACE` files.
-### Shortcomings of the `WORKSPACE` system {#workspace-shortcomings}
+### Shortcomings of the `WORKSPACE` system
In the years after the `WORKSPACE` system was introduced, users reported many
pain points, including:
@@ -289,10 +293,10 @@ pain points, including:
Due to the shortcomings of WORKSPACE, the new module-based system (codenamed
"Bzlmod") gradually replaced the legacy WORKSPACE system between Bazel 6 and 9.
-Read the [Bzlmod migration guide](/external/migration) on how to migrate
+Read the [Bzlmod migration guide](migration) on how to migrate
to Bzlmod.
-### External links on Bzlmod {#external-links}
+### External links on Bzlmod
* [Bzlmod usage examples in bazelbuild/examples](https://github.com/bazelbuild/examples/tree/main/bzlmod)
* [Bazel External Dependencies Overhaul](https://docs.google.com/document/d/1moQfNcEIttsk6vYanNKIy3ZuK53hQUFq1b1r0rmsYVg/edit)
diff --git a/external/registry.mdx b/external/registry.mdx
index 2bd0c114..45ce13b3 100644
--- a/external/registry.mdx
+++ b/external/registry.mdx
@@ -21,15 +21,17 @@ An index registry must have the following format:
* `/modules`: A directory containing a subdirectory for each module in this
registry
* `/modules/$MODULE`: A directory containing a subdirectory for each version
- of the module named `$MODULE`, as well as the [`metadata.json` file](#metadata-json) containing metadata for this module.
+ of the module named `$MODULE`, as well as the [`metadata.json`
+ file](#metadata-json) containing metadata for this module.
* `/modules/$MODULE/$VERSION`: A directory containing the following files:
* `MODULE.bazel`: The `MODULE.bazel` file of this module version. Note
that this is the `MODULE.bazel` file read during Bazel's external
dependency resolution, _not_ the one from the source archive (unless
- there's a [non-registry override](/external/module#non-registry_overrides)). Also note that it's
+ there's a [non-registry
+ override](/external/module#non-registry_overrides)). Also note that it's
best to use this file to set the version of a release and avoid doing so
in the source archive `MODULE.bazel` file. To learn more about module
- versioning, [see the FAQ](/external/faq#module-versioning-best-practices).
+ versioning, [see the FAQ](faq.md#module-versioning-best-practices).
* [`source.json`](#source-json): A JSON file containing information on how
to fetch the source of this module version
* `patches/`: An optional directory containing patch files, only used when
@@ -37,7 +39,7 @@ An index registry must have the following format:
* `overlay/`: An optional directory containing overlay files, only used
when `source.json` has "archive" type
-### `bazel_registry.json` {#bazel-registry-json}
+### `bazel_registry.json`
`bazel_registry.json` is an optional file that specifies metadata applying to
the entire registry. It can contain the following fields:
@@ -55,7 +57,7 @@ the entire registry. It can contain the following fields:
* `module_base_path`: a string, specifying the base path for modules with
`local_path` type in the `source.json` file
-### `metadata.json` {#metadata-json}
+### `metadata.json`
`metadata.json` is an optional JSON file containing information about the
module, with the following fields:
@@ -63,14 +65,15 @@ module, with the following fields:
* `versions`: An array of strings, each denoting a version of the module
available in this registry. This array should match the children of the
module directory.
-* `yanked_versions`: A JSON object specifying the [*yanked* versions](/external/module#yanked_versions) of this module. The keys
+* `yanked_versions`: A JSON object specifying the [*yanked*
+ versions](/external/module#yanked_versions) of this module. The keys
should be versions to yank, and the values should be descriptions of
why the version is yanked, ideally containing a link to more
information.
Note that the BCR requires more information in the `metadata.json` file.
-### `source.json` {#source-json}
+### `source.json`
`source.json` is a required JSON file containing information about how to fetch
a specific version of a module. The schema of this file depends on its `type`
@@ -129,12 +132,12 @@ field, which defaults to `archive`.
`--registry=file://`. Otherwise, Bazel will
throw an error
-## Bazel Central Registry {#bazel-central-registry}
+## Bazel Central Registry
-The Bazel Central Registry (BCR) at https://bcr.bazel.build/ is an index
+The Bazel Central Registry (BCR) at is an index
registry with contents backed by the GitHub repo
[`bazelbuild/bazel-central-registry`][bcr-repo]. You can browse its contents
-using the web frontend at https://registry.bazel.build/.
+using the web frontend at .
The Bazel community maintains the BCR, and contributors are welcome to submit
pull requests. See the [BCR contribution
diff --git a/external/repo.mdx b/external/repo.mdx
index 958d403e..b878f030 100644
--- a/external/repo.mdx
+++ b/external/repo.mdx
@@ -76,7 +76,8 @@ specified.
The input parameter `repository_ctx` can be used to access attribute values, and
non-hermetic functions (finding a binary, executing a binary, creating a file in
-the repository or downloading a file from the Internet). See [the API docs](/rules/lib/builtins/repository_ctx) for more context. Example:
+the repository or downloading a file from the Internet). See [the API
+docs](/rules/lib/builtins/repository_ctx) for more context. Example:
```python
def _impl(repository_ctx):
@@ -145,7 +146,8 @@ definition has the `configure` attribute set, use `bazel fetch --force
## Examples
-- [C++ auto-configured toolchain](https://cs.opensource.google/bazel/bazel/+/master:tools/cpp/cc_configure.bzl;drc=644b7d41748e09eff9e47cbab2be2263bb71f29a;l=176):
+- [C++ auto-configured
+ toolchain](https://cs.opensource.google/bazel/bazel/+/master:tools/cpp/cc_configure.bzl;drc=644b7d41748e09eff9e47cbab2be2263bb71f29a;l=176):
it uses a repo rule to automatically create the C++ configuration files for
Bazel by looking for the local C++ compiler, the environment and the flags
the C++ compiler supports.
diff --git a/external/vendor.mdx b/external/vendor.mdx
index ab82c46c..f2642ddf 100644
--- a/external/vendor.mdx
+++ b/external/vendor.mdx
@@ -8,7 +8,7 @@ Vendor mode is a feature that lets you create a local copy of
external dependencies. This is useful for offline builds, or when you want to
control the source of an external dependency.
-## Enable vendor mode {#enable-vendor-mode}
+## Enable vendor mode
You can enable vendor mode by specifying `--vendor_dir` flag.
@@ -22,10 +22,12 @@ common --vendor_dir=vendor_src
The vendor directory can be either a relative path to your workspace root or an
absolute path.
-## Vendor a specific external repository {#vendor-specific-repository}
+## Vendor a specific external repository
You can use the `vendor` command with the `--repo` flag to specify which repo
-to vendor, it accepts both [canonical repo name](/external/overview#canonical-repo-name) and [apparent repo name](/external/overview#apparent-repo-name).
+to vendor, it accepts both [canonical repo
+name](/external/overview#canonical-repo-name) and [apparent repo
+name](/external/overview#apparent-repo-name).
For example, running:
@@ -42,7 +44,7 @@ bazel vendor --vendor_dir=vendor_src --repo=@@rules_cc+
will both get rules_cc to be vendored under
`/vendor_src/rules_cc+`.
-## Vendor external dependencies for given targets {#vendor-target-dependencies}
+## Vendor external dependencies for given targets
To vendor all external dependencies required for building given target patterns,
you can run `bazel vendor `.
@@ -60,7 +62,7 @@ Under the hood, it's doing a `bazel build --nobuild` command to analyze the
target patterns, therefore build flags could be applied to this command and
affect the result.
-### Build the target offline {#build-the-target-offline}
+### Build the target offline
With the external dependencies vendored, you can build the target offline by
@@ -78,7 +80,7 @@ Note: If you make changes to the targets to build, the external dependencies,
the build configuration, or the Bazel version, you may need to re-vendor to make
sure offline build still works.
-## Vendor all external dependencies {#vendor-all-dependencies}
+## Vendor all external dependencies
To vendor all repos in your transitive external dependencies graph, you can
run:
@@ -95,7 +97,7 @@ Note that vendoring all dependencies has a few **disadvantages**:
Therefore, consider vendoring for specific targets first.
-## Configure vendor mode with VENDOR.bazel {#configure-vendor-mode}
+## Configure vendor mode with VENDOR.bazel
You can control how given repos are handled with the VENDOR.bazel file located
under the vendor directory.
@@ -130,7 +132,7 @@ Note: Repository rules with
[`configure`](/rules/lib/globals/bzl#repository_rule.configure) set to true are
always excluded from vendoring.
-## Understand how vendor mode works {#how-vendor-mode-works}
+## Understand how vendor mode works
Bazel fetches external dependencies of a project under `$(bazel info
output_base)/external`. Vendoring external dependencies means moving out
@@ -154,14 +156,14 @@ without pinning the repo, the changed vendored source will be used, but it will
be overwritten if its existing marker file is
outdated and the repo is vendored again.
-### Vendor registry files {#vendor-registry-files}
+### Vendor registry files
Bazel has to perform the Bazel module resolution in order to fetch external
dependencies, which may require accessing registry files through internet. To
achieve offline build, Bazel vendors all registry files fetched from
network under the `/_registries` directory.
-### Vendor symlinks {#vendor-symlinks}
+### Vendor symlinks
External repositories may contain symlinks pointing to other files or
directories. To make sure symlinks work correctly, Bazel uses the following
diff --git a/help.mdx b/help.mdx
index e6a1d79e..9956d928 100644
--- a/help.mdx
+++ b/help.mdx
@@ -7,7 +7,7 @@ title: 'Getting Help'
This page lists Bazel resources beyond the documentation and covers how to get
support from the Bazel team and community.
-## Search existing material {#search-material}
+## Search existing material
In addition to the documentation, you can find helpful information by searching:
@@ -17,7 +17,7 @@ In addition to the documentation, you can find helpful information by searching:
* [Stack Overflow](https://stackoverflow.com/questions/tagged/bazel)
* [`awesome-bazel` resources](https://github.com/jin/awesome-bazel)
-## Watch videos {#videos}
+## Watch videos
There are recordings of Bazel talks at various conferences, such as:
@@ -34,7 +34,7 @@ There are recordings of Bazel talks at various conferences, such as:
* Bazel day on [Google Open Source Live](https://opensourcelive.withgoogle.com/events/bazel)
-## Ask the Bazel community {#community}
+## Ask the Bazel community
If there are no existing answers, you can ask the community by:
@@ -44,11 +44,12 @@ If there are no existing answers, you can ask the community by:
* Chatting with other Bazel contributors on [Slack](https://slack.bazel.build/)
* Consulting a [Bazel community expert](/community/experts)
-## Understand Bazel's support level {#support-level}
+## Understand Bazel's support level
Please read the [release page](/release) to understand Bazel's release model and
what level of support Bazel provides.
-## File a bug {#file-bug}
+## File a bug
-If you encounter a bug or want to request a feature, file a [GitHub Issue](https://github.com/bazelbuild/bazel/issues).
+If you encounter a bug or want to request a feature, file a [GitHub
+Issue](https://github.com/bazelbuild/bazel/issues).
diff --git a/install/bazelisk.mdx b/install/bazelisk.mdx
index 3acb1147..a3189cb7 100644
--- a/install/bazelisk.mdx
+++ b/install/bazelisk.mdx
@@ -18,12 +18,13 @@ For more details, see
## Updating Bazel
Bazel has a [backward compatibility policy](/release/backward-compatibility)
-(see [guidance for rolling out incompatible changes](/contribute/breaking-changes) if you
+(see [guidance for rolling out incompatible
+changes](/contribute/breaking-changes) if you
are the author of one). That page summarizes best practices on how to test and
migrate your project with upcoming incompatible changes and how to provide
feedback to the incompatible change authors.
-### Managing Bazel versions with Bazelisk {#manage-with-bazelisk}
+### Managing Bazel versions with Bazelisk
[Bazelisk](https://github.com/bazelbuild/bazelisk) helps you manage
Bazel versions.
@@ -37,7 +38,7 @@ Bazelisk can:
* Help migrate your project for incompatible changes (see above)
* Easily try release candidates
-### Recommended migration process {#migration-process}
+### Recommended migration process
Within minor updates to any LTS release, any
project can be prepared for the next release without breaking
diff --git a/install/compile-source.mdx b/install/compile-source.mdx
index 9479e0cb..7a05ce47 100644
--- a/install/compile-source.mdx
+++ b/install/compile-source.mdx
@@ -14,9 +14,9 @@ To build Bazel from source, you can do one of the following:
* Build it [without an existing Bazel binary](#bootstrap-bazel) which is known
as _bootstrapping_.
-## Build Bazel using Bazel {#build-bazel-using-bazel}
+## Build Bazel using Bazel
-### Summary {#summary}
+### Summary
1. Get the latest Bazel release from the
[GitHub release page](https://github.com/bazelbuild/bazel/releases) or with
@@ -48,14 +48,15 @@ To build Bazel from source, you can do one of the following:
Detailed instructions follow below.
-### Step 1: Get the latest Bazel release {#build-bazel-install-bazel}
+### Step 1: Get the latest Bazel release
**Goal**: Install or download a release version of Bazel. Make sure you can run
it by typing `bazel` in a terminal.
**Reason**: To build Bazel from a GitHub source tree, you need a pre-existing
Bazel binary. You can install one from a package manager or download one from
-GitHub. See [Installing Bazel](/install). (Or you can [build from scratch (bootstrap)](#bootstrap-bazel).)
+GitHub. See [Installing Bazel](/install). (Or you can [build from
+scratch (bootstrap)](#bootstrap-bazel).)
**Troubleshooting**:
@@ -76,7 +77,7 @@ GitHub. See [Installing Bazel](/install). (Or you can [build from scratch (boots
You must make the binary executable by running `chmod +x /path/to/bazel`.
-### Step 2: Download Bazel's sources from GitHub {#build-bazel-git}
+### Step 2: Download Bazel's sources from GitHub
If you are familiar with Git, then just git clone https://github.com/bazelbuild/bazel
@@ -90,12 +91,12 @@ Otherwise:
For example create a `bazel-src` directory under your home directory and
extract there.
-### Step 3: Install prerequisites {#build-bazel-prerequisites}
+### Step 3: Install prerequisites
Install the same prerequisites as for bootstrapping (see below) -- JDK, C++
compiler, MSYS2 (if you are building on Windows), etc.
-### Step 4a: Build Bazel on Ubuntu Linux, macOS, and other Unix-like systems {#build-bazel-on-unixes}
+### Step 4a: Build Bazel on Ubuntu Linux, macOS, and other Unix-like systems
For instructions for Windows, see [Build Bazel on Windows](#build-bazel-on-windows).
@@ -123,7 +124,7 @@ For instructions for Windows, see [Build Bazel on Windows](#build-bazel-on-windo
4. The output will be at `bazel-bin/src/bazel-dev` (or `bazel-bin/src/bazel`).
-### Step 4b: Build Bazel on Windows {#build-bazel-on-windows}
+### Step 4b: Build Bazel on Windows
For instructions for Unix-like systems, see
[Ubuntu Linux, macOS, and other Unix-like systems](#build-bazel-on-unixes).
@@ -154,7 +155,7 @@ For instructions for Unix-like systems, see
4. The output will be at `bazel-bin\src\bazel-dev.exe` (or
`bazel-bin\src\bazel.exe`).
-### Step 5: Install the built binary {#build-bazel-install}
+### Step 5: Install the built binary
Actually, there's nothing to install.
@@ -164,11 +165,11 @@ your PATH so that you can run "bazel" everywhere.)
---
-## Build Bazel from scratch (bootstrapping) {#bootstrap-bazel}
+## Build Bazel from scratch (bootstrapping)
You can also build Bazel from scratch, without using an existing Bazel binary.
-### Step 1: Download Bazel's sources (distribution archive) {#download-distfile}
+### Step 1: Download Bazel's sources (distribution archive)
(This step is the same for all platforms.)
@@ -191,11 +192,11 @@ You can also build Bazel from scratch, without using an existing Bazel binary.
You should verify the signature made by Bazel's
[release key](https://bazel.build/bazel-release.pub.gpg) 3D5919B448457EE0.
-### Step 2a: Bootstrap Bazel on Ubuntu Linux, macOS, and other Unix-like systems {#bootstrap-unix-overview}
+### Step 2a: Bootstrap Bazel on Ubuntu Linux, macOS, and other Unix-like systems
For instructions for Windows, see [Bootstrap Bazel on Windows](#bootstrap-windows).
-#### 2.1. Install the prerequisites {#bootstrap-unix-prereq}
+#### 2.1. Install the prerequisites
* **Bash**
@@ -214,7 +215,7 @@ following command:
sudo apt-get install build-essential openjdk-21-jdk python3 zip unzip
```
-#### 2.2. Bootstrap Bazel on Unix {#bootstrap-unix}
+#### 2.2. Bootstrap Bazel on Unix
1. Open a shell or Terminal window.
@@ -231,12 +232,12 @@ To build the `bazel` binary in a reproducible way, also set
[`SOURCE_DATE_EPOCH`](https://reproducible-builds.org/specs/source-date-epoch/)
in the "Run the compilation script" step.
-### Step 2b: Bootstrap Bazel on Windows {#bootstrap-windows-overview}
+### Step 2b: Bootstrap Bazel on Windows
For instructions for Unix-like systems, see
[Bootstrap Bazel on Ubuntu Linux, macOS, and other Unix-like systems](#bootstrap-unix).
-#### 2.1. Install the prerequisites {#bootstrap-windows-prereq}
+#### 2.1. Install the prerequisites
* [MSYS2 shell](https://msys2.github.io/)
@@ -247,7 +248,8 @@ For instructions for Unix-like systems, see
```
* **The Visual C++ compiler.** Install the Visual C++ compiler either as part
- of Visual Studio 2015 or newer, or by installing the latest [Build Tools for Visual Studio 2017](https://aka.ms/BuildTools).
+ of Visual Studio 2015 or newer, or by installing the latest [Build Tools
+ for Visual Studio 2017](https://aka.ms/BuildTools).
* **JDK.** Version 21 is required.
@@ -256,7 +258,7 @@ For instructions for Unix-like systems, see
[https://www.python.org](https://www.python.org)). Versions installed via
pacman in MSYS2 will not work.
-#### 2.2. Bootstrap Bazel on Windows {#bootstrap-windows}
+#### 2.2. Bootstrap Bazel on Windows
1. Open the MSYS2 shell.
diff --git a/install/completion.mdx b/install/completion.mdx
index b7e1cb86..1d1d1b76 100644
--- a/install/completion.mdx
+++ b/install/completion.mdx
@@ -8,7 +8,7 @@ You can enable command-line completion (also known as tab-completion) in Bash
and Zsh. This lets you tab-complete command names, flags names and flag values,
and target names.
-## Bash {#bash}
+## Bash
Bazel comes with a Bash completion script.
@@ -64,7 +64,7 @@ If you installed Bazel:
source /path/to/bazel-complete.bash
```
-## Zsh {#zsh}
+## Zsh
Bazel comes with a Zsh completion script.
diff --git a/install/docker-container.mdx b/install/docker-container.mdx
index 928c9433..b1efb76c 100644
--- a/install/docker-container.mdx
+++ b/install/docker-container.mdx
@@ -9,7 +9,7 @@ the [abseil-cpp](https://github.com/abseil/abseil-cpp) project using Bazel
inside the Bazel container, and how to build this project directly
from the host machine using the Bazel container with directory mounting.
-## Build Abseil project from your host machine with directory mounting {#build-abseil}
+## Build Abseil project from your host machine with directory mounting
The instructions in this section allow you to build using the Bazel container
with the sources checked out in your host environment. A container is started up
@@ -59,7 +59,7 @@ docker run \
build --config={asan | tsan | msan} -- //absl/... -//absl/types:variant_test
```
-## Build Abseil project from inside the container {#build-abseil-inside-container}
+## Build Abseil project from inside the container
The instructions in this section allow you to build using the Bazel container
with the sources inside the container. By starting a container at the beginning
@@ -94,7 +94,7 @@ MemorySanitizer (msan) accordingly.
ubuntu@5a99103747c6:~/abseil-cpp$ bazel build --config={asan | tsan | msan} -- //absl/... -//absl/types:variant_test
```
-## Explore the Bazel container {#explore-bazel-container}
+## Explore the Bazel container
If you haven't already, start an interactive shell inside the Bazel container.
@@ -130,6 +130,6 @@ Build timestamp: 1685725198
Build timestamp as int: 1685725198
```
-## Explore the Bazel Dockerfile {#explore-bazel-dockerfile}
+## Explore the Bazel Dockerfile
If you want to check how the Bazel Docker image is built, you can find its Dockerfile at [bazelbuild/continuous-integration/bazel/oci](https://github.com/bazelbuild/continuous-integration/tree/master/bazel/oci).
diff --git a/install/ide.mdx b/install/ide.mdx
index d43d0696..abe1f895 100644
--- a/install/ide.mdx
+++ b/install/ide.mdx
@@ -16,15 +16,17 @@ If you are interested in developing an editor or IDE plugin for Bazel, please
join the `#ide` channel on the [Bazel Slack](https://slack.bazel.build) or start
a discussion on [GitHub](https://github.com/bazelbuild/bazel/discussions).
-## IDEs and editors {#ides-editors}
+## IDEs and editors
-### IntelliJ, Android Studio, and CLion {#intellij-android-clion}
+### IntelliJ, Android Studio, and CLion
Official Bazel plugins exist for many of the JetBrains-associated IDEs.
Full documentation is linked from the listings on the JetBrains Marketplace:
-* [IntelliJ plugin](https://plugins.jetbrains.com/plugin/22977-bazel)
-* [Android Studio plugin](https://plugins.jetbrains.com/plugin/9185-android-studio-with-bazel)
+* [IntelliJ
+ plugin](https://plugins.jetbrains.com/plugin/22977-bazel)
+* [Android Studio
+ plugin](https://plugins.jetbrains.com/plugin/9185-android-studio-with-bazel)
* [CLion plugin](https://plugins.jetbrains.com/plugin/9554-clion-with-bazel)
Features:
@@ -43,14 +45,14 @@ To manually install older versions, download the zip files from the JetBrains
Marketplace or from [GitHub Releases](https://github.com/bazelbuild/intellij/releases)
and install the zip file from the IDE's plugin browser.
-### Xcode {#xcode}
+### Xcode
[rules_xcodeproj](https://github.com/buildbuddy-io/rules_xcodeproj),
[Tulsi](https://tulsi.bazel.build), and
[XCHammer](https://github.com/pinterest/xchammer) generate Xcode
projects from Bazel `BUILD` files.
-### Visual Studio Code {#visual-studio-code}
+### Visual Studio Code
Official plugin for VS Code.
@@ -60,43 +62,45 @@ Features:
* Starlark debugger for `.bzl` files during a build (set breakpoints, step
through code, inspect variables, and so on)
-Find [the plugin on the Visual Studio marketplace](https://marketplace.visualstudio.com/items?itemName=BazelBuild.vscode-bazel)
+Find [the plugin on the Visual Studio
+marketplace](https://marketplace.visualstudio.com/items?itemName=BazelBuild.vscode-bazel)
or the [OpenVSX marketplace](https://open-vsx.org/extension/BazelBuild/vscode-bazel).
The plugin is [open source](https://github.com/bazelbuild/vscode-bazel).
See also: [Autocomplete for Source Code](#autocomplete-for-source-code)
-### Atom {#atom}
+### Atom
Find the [`language-bazel` package](https://atom.io/packages/language-bazel)
on the Atom package manager.
See also: [Autocomplete for Source Code](#autocomplete-for-source-code)
-### Vim {#vim}
+### Vim
See [`bazelbuild/vim-bazel` on GitHub](https://github.com/bazelbuild/vim-bazel)
See also: [Autocomplete for Source Code](#autocomplete-for-source-code)
-### Emacs {#emacs}
+### Emacs
-See [`bazelbuild/bazel-emacs-mode` on GitHub](https://github.com/bazelbuild/emacs-bazel-mode)
+See [`bazelbuild/bazel-emacs-mode` on
+GitHub](https://github.com/bazelbuild/emacs-bazel-mode)
See also: [Autocomplete for Source Code](#autocomplete-for-source-code)
-### Visual Studio {#visual-studio}
+### Visual Studio
[Lavender](https://github.com/tmandry/lavender) is an experimental project for
generating Visual Studio projects that use Bazel for building.
-### Eclipse {#eclipse}
+### Eclipse
[Bazel Eclipse Feature](https://github.com/salesforce/bazel-eclipse)
is a set of plugins for importing Bazel packages into an Eclipse workspace as
Eclipse projects.
-## Autocomplete for Source Code {#autocomplete-for-source-code}
+## Autocomplete for Source Code
### C Language Family (C++, C, Objective-C, Objective-C++, and CUDA)
@@ -112,12 +116,13 @@ consumes the Protobuf output of Bazel to extract the compile commands.
[`georgewfraser/java-language-server`](https://github.com/georgewfraser/java-language-server) - Java Language Server (LSP) with support for Bazel-built projects
-## Automatically run build and test on file change {#bazel-watcher}
+## Automatically run build and test on file change
[Bazel watcher](https://github.com/bazelbuild/bazel-watcher) is a
tool for building Bazel targets when source files change.
-## Building your own IDE plugin {#build-own-plugin}
+## Building your own IDE plugin
-Read the [**IDE support** blog post](https://blog.bazel.build/2016/06/10/ide-support.html) to learn more about
+Read the [**IDE support** blog
+post](https://blog.bazel.build/2016/06/10/ide-support.html) to learn more about
the Bazel APIs to use when building an IDE plugin.
diff --git a/install/index.mdx b/install/index.mdx
index 912ac212..84d9b146 100644
--- a/install/index.mdx
+++ b/install/index.mdx
@@ -11,7 +11,7 @@ to the packages for more details.
You can find available Bazel releases on our [release page](/release).
-## Community-supported packages {#community-supported-packages}
+## Community-supported packages
Bazel community members maintain these packages. The Bazel team doesn't
officially support them. Contact the package maintainers for support.
@@ -22,13 +22,13 @@ officially support them. Contact the package maintainers for support.
* [Fedora](https://copr.fedorainfracloud.org/coprs/lihaohong/bazel)
* [FreeBSD](https://www.freshports.org/devel/bazel)
* [Homebrew](https://formulae.brew.sh/formula/bazel)
-* [mise](/install/mise)
+* [mise](install/mise)
* [Nixpkgs](https://github.com/NixOS/nixpkgs/blob/master/pkgs/development/tools/build-managers/bazel)
* [openSUSE](/install/suse)
* [Scoop](https://github.com/scoopinstaller/scoop-main/blob/master/bucket/bazel.json)
* [Raspberry Pi](https://github.com/koenvervloesem/bazel-on-arm/blob/master/README.md)
-## Community-supported architectures {#community-supported-architectures}
+## Community-supported architectures
* [ppc64el](https://ftp2.osuosl.org/pub/ppc64el/bazel/)
diff --git a/install/suse.mdx b/install/suse.mdx
index 82ce1bdd..741b108f 100644
--- a/install/suse.mdx
+++ b/install/suse.mdx
@@ -14,7 +14,7 @@ available Bazel versions via openSUSE's [software search](https://software.opens
The commands below must be run either via `sudo` or while logged in as `root`.
-## Installing Bazel on openSUSE {#install-opensuse}
+## Installing Bazel on openSUSE
Run the following commands to install the package. If you need a specific
version, you can install it via the specific `bazelXXX` package, otherwise,
diff --git a/install/ubuntu.mdx b/install/ubuntu.mdx
index c1e4e32e..5e55569e 100644
--- a/install/ubuntu.mdx
+++ b/install/ubuntu.mdx
@@ -34,9 +34,9 @@ Bazel comes with two completion scripts. After installing Bazel, you can:
* Access the [bash completion script](/install/completion#bash)
* Install the [zsh completion script](/install/completion#zsh)
-## Using Bazel's apt repository {#install-on-ubuntu}
+## Using Bazel's apt repository
-### Step 1: Add Bazel distribution URI as a package source {#add-dis-uri}
+### Step 1: Add Bazel distribution URI as a package source
**Note:** This is a one-time setup step.
@@ -54,7 +54,7 @@ The component name "jdk1.8" is kept only for legacy reasons and doesn't relate
to supported or included JDK versions. Bazel releases are Java-version agnostic.
Changing the "jdk1.8" component name would break existing users of the repo.
-### Step 2: Install and update Bazel {#install-bazel}
+### Step 2: Install and update Bazel
```posix-terminal
sudo apt update && sudo apt install bazel
@@ -87,7 +87,7 @@ sudo ln -s /usr/bin/bazel-1.0.0 /usr/bin/bazel
bazel --version # 1.0.0
```
-### Step 3: Install a JDK (optional) {#install-jdk}
+### Step 3: Install a JDK (optional)
Bazel includes a private, bundled JRE as its runtime and doesn't require you to
install any specific version of Java.
@@ -98,7 +98,7 @@ However, if you want to build Java code using Bazel, you have to install a JDK.
sudo apt install default-jdk
```
-## Using the binary installer {#binary-installer}
+## Using the binary installer
Generally, you should use the apt repository, but the binary installer
can be useful if you don't have admin permissions on your machine or
@@ -109,7 +109,7 @@ The binary installers can be downloaded from Bazel's [GitHub releases page](http
The installer contains the Bazel binary and extracts it into your `$HOME/bin`
folder. Some additional libraries must be installed manually for Bazel to work.
-### Step 1: Install required packages {#install-packages}
+### Step 1: Install required packages
Bazel needs a C++ compiler and unzip / zip in order to work:
@@ -123,7 +123,7 @@ If you want to build Java code using Bazel, install a JDK:
sudo apt-get install default-jdk
```
-### Step 2: Run the installer {#run-installer}
+### Step 2: Run the installer
Next, download the Bazel binary installer named `bazel-version-installer-linux-x86_64.sh`
from the [Bazel releases page on GitHub](https://github.com/bazelbuild/bazel/releases).
@@ -140,7 +140,7 @@ The `--user` flag installs Bazel to the `$HOME/bin` directory on your system and
sets the `.bazelrc` path to `$HOME/.bazelrc`. Use the `--help` command to see
additional installation options.
-### Step 3: Set up your environment {#set-environment}
+### Step 3: Set up your environment
If you ran the Bazel installer with the `--user` flag as above, the Bazel
executable is installed in your `$HOME/bin` directory.
@@ -153,7 +153,7 @@ export PATH="$PATH:$HOME/bin"
You can also add this command to your `~/.bashrc` or `~/.zshrc` file to make it
permanent.
-## Using the Bazel Docker container {#docker-container}
+## Using the Bazel Docker container
We publish Docker container with Bazel installed for each Bazel version at `gcr.io/bazel-public/bazel`.
You can use the Docker container as follows:
diff --git a/install/windows.mdx b/install/windows.mdx
index dc2edb0a..50b387d6 100644
--- a/install/windows.mdx
+++ b/install/windows.mdx
@@ -8,12 +8,12 @@ This page describes the requirements and steps to install Bazel on Windows.
It also includes troubleshooting and other ways to install Bazel, such as
using Chocolatey or Scoop.
-## Installing Bazel {#installing-bazel}
+## Installing Bazel
This section covers the prerequisites, environment setup, and detailed
steps during installation on Windows.
-### Check your system {#check-system}
+### Check your system
Recommended: 64 bit Windows 10, version 1703 (Creators Update) or newer
@@ -23,23 +23,24 @@ To check your Windows version:
* Type `winver` in the search box and press Enter.
* You should see the About Windows box with your Windows version information.
-### Install the prerequisites {#install-prerequisites}
+### Install the prerequisites
* [Microsoft Visual C++ Redistributable](https://learn.microsoft.com/en-us/cpp/windows/latest-supported-vc-redist?view=msvc-170)
-### Download Bazel {#download-bazel}
+### Download Bazel
*Recommended*: [Use Bazelisk](/install/bazelisk)
Alternatively you can:
-* [Download the Bazel binary (`bazel-version-windows-x86_64.exe`) from GitHub](https://github.com/bazelbuild/bazel/releases).
+* [Download the Bazel binary (`bazel-version-windows-x86_64.exe`) from
+ GitHub](https://github.com/bazelbuild/bazel/releases).
* [Install Bazel from Chocolatey](#chocolately)
* [Install Bazel from Scoop](#scoop)
* [Build Bazel from source](/install/compile-source)
-### Set up your environment {#set-environment}
+### Set up your environment
To make Bazel easily accessible from command prompts or PowerShell by default, you can rename the Bazel binary to `bazel.exe` and add it to your default paths.
@@ -49,7 +50,7 @@ set PATH=%PATH%;path to the Bazel binary
You can also change your system `PATH` environment variable to make it permanent. Check out how to [set environment variables](/configure/windows#set-environment-variables).
-### Done {#done}
+### Done
"Success: You've installed Bazel."
@@ -66,7 +67,7 @@ Next, you can check out more tips and guidance here:
* [Best practices on Windows](/configure/windows#best-practices)
* [Tutorials](/start/#tutorials)
-## Installing compilers and language runtimes {#install-compilers}
+## Installing compilers and language runtimes
Depending on which languages you want to build, you will need:
@@ -115,7 +116,7 @@ Depending on which languages you want to build, you will need:
Also supported: Python 2.7 or newer for Windows x86-64
-## Troubleshooting {#troubleshooting}
+## Troubleshooting
### Bazel does not find Bash or bash.exe
@@ -194,9 +195,9 @@ If that doesn't help:
If you open a new cmd.exe or PowerShell terminal and run Bazel now, it will find Visual C++.
-## Other ways to install Bazel {#install-options}
+## Other ways to install Bazel
-### Using Chocolatey {#chocolately}
+### Using Chocolatey
1. Install the [Chocolatey](https://chocolatey.org) package manager
@@ -210,10 +211,11 @@ If that doesn't help:
its dependencies, such as the MSYS2 shell. This will not install Visual C++
though.
-See [Chocolatey installation and package maintenance guide](/contribute/windows-chocolatey-maintenance) for more
+See [Chocolatey installation and package maintenance
+guide](/contribute/windows-chocolatey-maintenance) for more
information about the Chocolatey package.
-### Using Scoop {#scoop}
+### Using Scoop
1. Install the [Scoop](https://scoop.sh/) package manager using the following PowerShell command:
@@ -227,9 +229,10 @@ information about the Chocolatey package.
scoop install bazel
```
-See [Scoop installation and package maintenance guide](/contribute/windows-scoop-maintenance) for more
+See [Scoop installation and package maintenance
+guide](/contribute/windows-scoop-maintenance) for more
information about the Scoop package.
-### Build from source {#build-from-source}
+### Build from source
To build Bazel from scratch instead of installing, see [Compiling from source](/install/compile-source).
diff --git a/migrate/maven.mdx b/migrate/maven.mdx
index 3b564450..0ca2b5c0 100644
--- a/migrate/maven.mdx
+++ b/migrate/maven.mdx
@@ -16,13 +16,14 @@ Note: While Bazel supports downloading and publishing Maven artifacts with
, it does not directly support Maven-based plugins. Maven plugins can't be
directly run by Bazel since there's no Maven compatibility layer.
-## Before you begin {#before-you-begin}
+## Before you begin
* [Install Bazel](/install) if it's not yet installed.
-* If you're new to Bazel, go through the tutorial [Introduction to Bazel: Build Java](/start/java) before you start migrating. The tutorial explains
+* If you're new to Bazel, go through the tutorial [Introduction to Bazel:
+ Build Java](/start/java) before you start migrating. The tutorial explains
Bazel's concepts, structure, and label syntax.
-## Differences between Maven and Bazel {#dif-maven-bazel}
+## Differences between Maven and Bazel
* Maven uses top-level `pom.xml` file(s). Bazel supports multiple build files
and multiple targets per `BUILD` file, allowing for builds that are more
@@ -34,7 +35,7 @@ directly run by Bazel since there's no Maven compatibility layer.
`BUILD` files. Best practice is to add a `BUILD` file to each new Java
package.
-## Migrate from Maven to Bazel {#migrate-maven-bazel}
+## Migrate from Maven to Bazel
The steps below describe how to migrate your project to Bazel:
@@ -43,7 +44,8 @@ The steps below describe how to migrate your project to Bazel:
3. [Create more BUILD files](#3-build)
4. [Build using Bazel](#4-build)
-Examples below come from a migration of the [Guava project](https://github.com/google/guava) from Maven to Bazel. The
+Examples below come from a migration of the [Guava
+project](https://github.com/google/guava) from Maven to Bazel. The
Guava project used is release `v31.1`. The examples using Guava do not walk
through each step in the migration, but they do show the files and contents that
are generated or added manually for the migration.
@@ -53,7 +55,7 @@ $ git clone https://github.com/google/guava.git && cd guava
$ git checkout v31.1
```
-### 1. Create the MODULE.bazel file {#1-build}
+### 1. Create the MODULE.bazel file
Create a file named `MODULE.bazel` at the root of your project. If your project
has no external dependencies, this file can be empty.
@@ -61,12 +63,14 @@ has no external dependencies, this file can be empty.
If your project depends on files or packages that are not in one of the
project's directories, specify these external dependencies in the MODULE.bazel
file. You can use `rules_jvm_external` to manage dependencies from Maven. For
-instructions about using this ruleset, see [the README](https://github.com/bazelbuild/rules_jvm_external/#rules_jvm_external)
+instructions about using this ruleset, see [the
+README](https://github.com/bazelbuild/rules_jvm_external/#rules_jvm_external)
.
-#### Guava project example: external dependencies {#guava-1}
+#### Guava project example: external dependencies
-You can list the external dependencies of the [Guava project](https://github.com/google/guava) with the
+You can list the external dependencies of the [Guava
+project](https://github.com/google/guava) with the
[`rules_jvm_external`](https://github.com/bazelbuild/rules_jvm_external)
ruleset.
@@ -90,7 +94,7 @@ maven.install(
use_repo(maven, "maven")
```
-### 2. Create one BUILD file {#2-build}
+### 2. Create one BUILD file
Now that you have your workspace defined and external dependencies (if
applicable) listed, you need to create `BUILD` files to describe how your
@@ -160,7 +164,8 @@ your build by adding more `BUILD` files with more granular targets.
* `resources`: Use globbing to list all resources in your project.
* `deps`: You need to determine which external dependencies your
project needs.
- * Take a look at the [example below of this top-level BUILD file](#guava-2) from the migration of the Guava project.
+ * Take a look at the [example below of this top-level BUILD
+ file](#guava-2) from the migration of the Guava project.
3. Now that you have a `BUILD` file at the root of your project, build your
project to ensure that it works. On the command line, from your workspace
@@ -169,7 +174,7 @@ your build by adding more `BUILD` files with more granular targets.
The project has now been successfully built with Bazel. You will need to add
more `BUILD` files to allow incremental builds of the project.
-#### Guava project example: start with one BUILD file {#guava-2}
+#### Guava project example: start with one BUILD file
When migrating the Guava project to Bazel, initially one `BUILD` file is used to
build the entire project. Here are the contents of this initial `BUILD` file in
@@ -193,7 +198,7 @@ java_library(
)
```
-### 3. Create more BUILD files (optional) {#3-build}
+### 3. Create more BUILD files (optional)
Bazel does work with just one `BUILD file`, as you saw after completing your
first build. You should still consider breaking the build into smaller chunks by
@@ -225,7 +230,7 @@ Tips for adding more `BUILD` files:
that the project continues to build with Bazel as you add each build file.
Run `bazel build //...` to ensure all of your targets still build.
-### 4. Build using Bazel {#4-build}
+### 4. Build using Bazel
You've been building using Bazel as you add `BUILD` files to validate the setup
of the build.
diff --git a/migrate/xcode.mdx b/migrate/xcode.mdx
index 5f6a05a2..311f5e62 100644
--- a/migrate/xcode.mdx
+++ b/migrate/xcode.mdx
@@ -7,7 +7,7 @@ describes the differences between Xcode and Bazel, and provides the steps for
converting an Xcode project to a Bazel project. It also provides troubleshooting
solutions to address common errors.
-## Differences between Xcode and Bazel {#dif-xcode-bazel}
+## Differences between Xcode and Bazel
* Bazel requires you to explicitly specify every build target and its
dependencies, plus the corresponding build settings via build rules.
@@ -26,26 +26,28 @@ solutions to address common errors.
`bazel build` and `bazel test` commands provide build and test capabilities
with certain limitations described later in this guide.
-## Before you begin {#before-you-begin}
+## Before you begin
Before you begin, do the following:
1. [Install Bazel](/install) if you have not already done so.
-2. If you're not familiar with Bazel and its concepts, complete the [iOS app tutorial](/start/ios-app)). You should understand the Bazel workspace,
+2. If you're not familiar with Bazel and its concepts, complete the [iOS app
+ tutorial](/start/ios-app)). You should understand the Bazel workspace,
including the `MODULE.bazel` and `BUILD` files, as well as the concepts of
targets, build rules, and Bazel packages.
3. Analyze and understand the project's dependencies.
-### Analyze project dependencies {#analyze-project-dependencies}
+### Analyze project dependencies
Unlike Xcode, Bazel requires you to explicitly declare all dependencies for
every target in the `BUILD` file.
-For more information on external dependencies, see [Working with external dependencies](/docs/external).
+For more information on external dependencies, see [Working with external
+dependencies](/docs/external).
-## Build or test an Xcode project with Bazel {#build-xcode-project}
+## Build or test an Xcode project with Bazel
To build or test an Xcode project with Bazel, do the following:
@@ -67,7 +69,7 @@ To build or test an Xcode project with Bazel, do the following:
6. [Generate the Xcode project with rules_xcodeproj](#generate-the-xcode-project-with-rules_xcodeproj)
-### Step 1: Create the `MODULE.bazel` file {#create-workspace}
+### Step 1: Create the `MODULE.bazel` file
Create a `MODULE.bazel` file in a new directory. This directory becomes the
Bazel workspace root. If the project uses no external dependencies, this file
@@ -78,18 +80,19 @@ the project's directories, specify these external dependencies in the
Note: Place the project source code within the directory tree containing the
`MODULE.bazel` file.
-### Step 2: (Experimental) Integrate SwiftPM dependencies {#integrate-swiftpm}
+### Step 2: (Experimental) Integrate SwiftPM dependencies
To integrate SwiftPM dependencies into the Bazel workspace with
[swift_bazel](https://github.com/cgrindel/swift_bazel), you must
-convert them into Bazel packages as described in the [following tutorial](https://chuckgrindel.com/swift-packages-in-bazel-using-swift_bazel/)
+convert them into Bazel packages as described in the [following
+tutorial](https://chuckgrindel.com/swift-packages-in-bazel-using-swift_bazel/)
.
Note: SwiftPM support is a manual process with many variables. SwiftPM
integration with Bazel has not been fully verified and is not officially
supported.
-### Step 3: Create a `BUILD` file {#create-build-file}
+### Step 3: Create a `BUILD` file
Once you have defined the workspace and external dependencies, you need to
create a `BUILD` file that tells Bazel how the project is structured. Create the
@@ -100,9 +103,10 @@ initial build of the project as follows:
* [Step 3b: (Optional) Add the test target(s)](#step-3b-optional-add-the-test-target-s)
* [Step 3c: Add the library target(s)](#step-3c-add-the-library-target-s)
-**Tip:** To learn more about packages and other Bazel concepts, see [Workspaces, packages, and targets](/concepts/build-ref).
+**Tip:** To learn more about packages and other Bazel concepts, see [Workspaces,
+packages, and targets](/concepts/build-ref).
-#### Step 3a: Add the application target {#add-app-target}
+#### Step 3a: Add the application target
Add a
[`macos_application`](https://github.com/bazelbuild/rules_apple/blob/master/doc/rules-macos.md#macos_application)
@@ -126,9 +130,10 @@ In the target, specify the following at the minimum:
application supports. This ensures Bazel builds the application with the
correct API levels.
-#### Step 3b: (Optional) Add the test target(s) {#add-test-target}
+#### Step 3b: (Optional) Add the test target(s)
-Bazel's [Apple build rules](https://github.com/bazelbuild/rules_apple) support running
+Bazel's [Apple build
+rules](https://github.com/bazelbuild/rules_apple) support running
unit and UI tests on all Apple platforms. Add test targets as follows:
* [`macos_unit_test`](https://github.com/bazelbuild/rules_apple/blob/master/doc/rules-macos.md#macos_unit_test)
@@ -153,7 +158,7 @@ with the project and adjust them as necessary. For tests that require the iOS
simulator, also specify the `ios_application` target name as the value of the
`test_host` attribute.
-#### Step 3c: Add the library target(s) {#add-library-target}
+#### Step 3c: Add the library target(s)
Add an [`objc_library`](/reference/be/objective-c#objc_library) target for each
Objective-C library and a
@@ -176,7 +181,8 @@ all sources and/or headers of a certain type. Use it carefully as it might
include files you do not want Bazel to build.
You can browse existing examples for various types of applications directly in
-the [rules_apple examples directory](https://github.com/bazelbuild/rules_apple/tree/master/examples/). For
+the [rules_apple examples
+directory](https://github.com/bazelbuild/rules_apple/tree/master/examples/). For
example:
* [macOS application targets](https://github.com/bazelbuild/rules_apple/tree/master/examples/macos)
@@ -185,13 +191,14 @@ example:
* [Multi platform applications (macOS, iOS, watchOS, tvOS)](https://github.com/bazelbuild/rules_apple/tree/master/examples/multi_platform)
-For more information on build rules, see [Apple Rules for Bazel](https://github.com/bazelbuild/rules_apple).
+For more information on build rules, see [Apple Rules for
+Bazel](https://github.com/bazelbuild/rules_apple).
At this point, it is a good idea to test the build:
`bazel build //:`
-### Step 4: (Optional) Granularize the build {#granularize-build}
+### Step 4: (Optional) Granularize the build
If the project is large, or as it grows, consider chunking it into multiple
Bazel packages. This increased granularity provides:
@@ -225,7 +232,7 @@ Tips for granularizing the project:
* Build the project after each major change to the `BUILD` files and fix build
errors as you encounter them.
-### Step 5: Run the build {#run-build}
+### Step 5: Run the build
Run the fully migrated build to ensure it completes with no errors or warnings.
Run every application and test target individually to more easily find sources
@@ -237,7 +244,7 @@ For example:
bazel build //:my-target
```
-### Step 6: Generate the Xcode project with rules_xcodeproj {#generate-the-xcode-project-with-rules_xcodeproj}
+### Step 6: Generate the Xcode project with rules_xcodeproj
When building with Bazel, the `MODULE.bazel` and `BUILD` files become the source
of truth about the build. To make Xcode aware of this, you must generate a
@@ -245,7 +252,7 @@ Bazel-compatible Xcode project using
[rules_xcodeproj](https://github.com/buildbuddy-io/rules_xcodeproj#features)
.
-### Troubleshooting {#troubleshooting}
+### Troubleshooting
Bazel errors can arise when it gets out of sync with the selected Xcode version,
like when you apply an update. Here are some things to try if you're
diff --git a/navigation.json b/navigation.json
index a3d046ca..fd3c4b14 100644
--- a/navigation.json
+++ b/navigation.json
@@ -8,14 +8,6 @@
}
]
},
- {
- "version": "9.1",
- "languages": [
- {
- "$ref": "./navigation/9.1.en.json"
- }
- ]
- },
{
"version": "9.0",
"languages": [
@@ -24,14 +16,6 @@
}
]
},
- {
- "version": "8.6",
- "languages": [
- {
- "$ref": "./navigation/8.6.en.json"
- }
- ]
- },
{
"version": "8.5",
"languages": [
diff --git a/query/aquery.mdx b/query/aquery.mdx
index be9a633f..151565b7 100644
--- a/query/aquery.mdx
+++ b/query/aquery.mdx
@@ -33,7 +33,7 @@ action 'Writing file some_file_name'
Outputs: [...]
```
-## Basic syntax {#basic-syntax}
+## Basic syntax
A simple example of the syntax for `aquery` is as follows:
@@ -60,7 +60,7 @@ $ bazel aquery 'deps(//src/target_a)'
$ bazel aquery 'inputs(".*cpp", deps(//src/target_a))'
```
-## Using aquery functions {#using-aquery-functions}
+## Using aquery functions
There are three `aquery` functions:
@@ -100,17 +100,17 @@ An example of the syntax error produced:
deps(inputs(".*cpp", //src/target_a))
```
-## Options {#options}
+## Options
-### Build options {#build-options}
+### Build options
`aquery` runs on top of a regular Bazel build and thus inherits the set of
[options](/reference/command-line-reference#build-options)
available during a build.
-### Aquery options {#aquery-options}
+### Aquery options
-#### `--output=(text|summary|commands|proto|jsonproto|textproto), default=text` {#output}
+#### `--output=(text|summary|commands|proto|jsonproto|textproto), default=text`
The default output format (`text`) is human-readable,
use `proto`, `textproto`, or `jsonproto` for machine-readable format.
@@ -122,25 +122,25 @@ one command per line.
In general, do not depend on the order of output. For more information,
see the [core query ordering contract](/query/language#graph-order).
-#### `--include_commandline, default=true` {#include-commandline}
+#### `--include_commandline, default=true`
Includes the content of the action command lines in the output (potentially large).
-#### `--include_artifacts, default=true` {#include-artifacts}
+#### `--include_artifacts, default=true`
Includes names of the action inputs and outputs in the output (potentially large).
-#### `--include_aspects, default=true` {#include-aspects}
+#### `--include_aspects, default=true`
Whether to include Aspect-generated actions in the output.
-#### `--include_param_files, default=false` {#include-param-files}
+#### `--include_param_files, default=false`
Include the content of the param files used in the command (potentially large).
Warning: Enabling this flag will automatically enable the `--include_commandline` flag.
-#### `--include_file_write_contents, default=false` {#include-file-write-contents}
+#### `--include_file_write_contents, default=false`
Include file contents for the `actions.write()` action and the contents of the
manifest file for the `SourceSymlinkManifest` action The file contents is
@@ -151,16 +151,16 @@ FileWriteContents: []
```
line
-#### `--skyframe_state, default=false` {#skyframe-state}
+#### `--skyframe_state, default=false`
Without performing extra analysis, dump the Action Graph from Skyframe.
Note: Specifying a target with `--skyframe_state` is currently not supported.
This flag is only available with `--output=proto` or `--output=textproto`.
-## Other tools and features {#other-tools-features}
+## Other tools and features
-### Querying against the state of Skyframe {#querying-against-skyframe}
+### Querying against the state of Skyframe
[Skyframe](/reference/skyframe) is the evaluation and
incrementality model of Bazel. On each instance of Bazel server, Skyframe stores the dependency graph
@@ -198,14 +198,14 @@ With `--skyframe_state` mode, `aquery` 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.
-#### Special considerations {#special-considerations}
+#### Special considerations
-##### Output format {#output-format}
+##### Output format
`--skyframe_state` is currently only available for `--output=proto`
and `--output=textproto`
-##### Non-inclusion of target labels in the query expression {#target-labels-non-inclusion}
+##### Non-inclusion of target labels in the query expression
Currently, `--skyframe_state` queries the whole action graph that exists on Skyframe,
regardless of the targets. Having the target label specified in the query together with
@@ -225,7 +225,7 @@ regardless of the targets. Having the target label specified in the query togeth
$ bazel aquery --output=proto --skyframe_state 'inputs(".*.java")'
```
-### Comparing aquery outputs {#comparing-aquery-outputs}
+### Comparing aquery outputs
You can compare the outputs of two different aquery invocations using the `aquery_differ` tool.
For instance: when you make some changes to your rule definition and want to verify that the
@@ -264,7 +264,7 @@ command line/inputs in each aquery output, ...). The result of running the above
...
```
-#### Command options {#command-options}
+#### Command options
`--before, --after`: The aquery output files to be compared
@@ -274,7 +274,7 @@ files. Support is provided for `proto` and `textproto` aquery output.
`--attrs=(cmdline|inputs), default=cmdline`: the attributes of actions
to be compared.
-### Aspect-on-aspect {#aspect-on-aspect}
+### Aspect-on-aspect
It is possible for [Aspects](/extending/aspects)
to be applied on top of each other. The aquery output of the action generated by
@@ -324,7 +324,7 @@ Each `AspectDescriptor` has the following format:
sorted in topological order of the
[dependency graph](/extending/aspects#aspect_basics).
-### Linking with the JSON profile {#linking-with-json-profile}
+### Linking with the JSON profile
While aquery provides information about the actions being run in a build (why they're being run,
their inputs/outputs), the [JSON profile](/rules/performance#performance-profiling)
@@ -339,9 +339,9 @@ is included by default by aquery.
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.
-## Known issues {#known-issues}
+## Known issues
-### Handling shared actions {#handling-shared-actions}
+### Handling shared actions
Sometimes actions are
[shared](https://source.bazel.build/bazel/+/master:src/main/java/com/google/devtools/build/lib/actions/Actions.java;l=59;drc=146d51aa1ec9dcb721a7483479ef0b1ac21d39f1)
@@ -356,9 +356,9 @@ equivalent Artifacts appear duplicated.
The list of aquery issues/planned features can be found on
[GitHub](https://github.com/bazelbuild/bazel/labels/team-Performance).
-## FAQs {#faqs}
+## FAQs
-### The ActionKey remains the same even though the content of an input file changed. {#actionkey-same}
+### The ActionKey remains the same even though the content of an input file changed.
In the context of aquery, the `ActionKey` refers to the `String` gotten from
[ActionAnalysisMetadata#getKey](https://source.bazel.build/bazel/+/master:src/main/java/com/google/devtools/build/lib/actions/ActionAnalysisMetadata.java;l=89;drc=8b856f5484f0117b2aebc302f849c2a15f273310):
@@ -386,6 +386,6 @@ In the context of aquery, the `ActionKey` refers to the `String` gotten from
This excludes the changes to the content of the input files, and is not to be confused with
[RemoteCacheClient#ActionKey](https://source.bazel.build/bazel/+/master:src/main/java/com/google/devtools/build/lib/remote/common/RemoteCacheClient.java;l=38;drc=21577f202eb90ce94a337ebd2ede824d609537b6).
-## Updates {#updates}
+## Updates
For any issues/feature requests, please file an issue [here](https://github.com/bazelbuild/bazel/issues/new).
diff --git a/query/cquery.mdx b/query/cquery.mdx
index f7195d40..d35ea829 100644
--- a/query/cquery.mdx
+++ b/query/cquery.mdx
@@ -8,7 +8,8 @@ title: 'Configurable Query (cquery)'
[`select()`](/docs/configurable-attributes) and build options' effects on the
build graph.
-It achieves this by running over the results of Bazel's [analysis phase](/extending/concepts#evaluation-model),
+It achieves this by running over the results of Bazel's [analysis
+phase](/extending/concepts#evaluation-model),
which integrates these effects. `query`, by contrast, runs over the results of
Bazel's loading phase, before options are evaluated.
@@ -66,7 +67,7 @@ Since `cquery` runs over the configured target graph. it doesn't have insight
into artifacts like build actions nor access to [`test_suite`](/reference/be/general#test_suite)
rules as they are not configured targets. For the former, see [`aquery`](/query/aquery).
-## Basic syntax {#basic-syntax}
+## Basic syntax
A simple `cquery` call looks like:
@@ -88,7 +89,7 @@ phases. Unless otherwise specified, `cquery` parses the target(s) listed in the
query expression. See [`--universe_scope`](#universe-scope)
for querying dependencies of top-level build targets.
-## Configurations {#configurations}
+## Configurations
The line:
@@ -112,7 +113,7 @@ prefix of a complete ID, similar to
[Git short hashes](https://git-scm.com/book/en/v2/Git-Tools-Revision-Selection#_revision_selection).
To see complete IDs, run `$ bazel config`.
-## Target pattern evaluation {#target-pattern-evaluation}
+## Target pattern evaluation
`//foo` has a different meaning for `cquery` than for `query`. This is because
`cquery` evaluates _configured_ targets and the build graph may have multiple
@@ -139,23 +140,23 @@ $ bazel cquery //foo --universe_scope=//foo,//genrule_with_foo_as_tool
If you want to precisely declare which instance to query over, use
the [`config`](#config) function.
-See `query`'s [target pattern documentation](/query/language#target-patterns) for more information on target
+See `query`'s [target pattern
+documentation](/query/language#target-patterns) for more information on target
patterns.
-## Functions {#functions}
+## Functions
Of the [set of functions](/query/language#functions "list of query functions")
supported by `query`, `cquery` supports all but
[`allrdeps`](/query/language#allrdeps),
[`buildfiles`](/query/language#buildfiles),
-[`loadfiles`](/query/language#loadfiles),
[`rbuildfiles`](/query/language#rbuildfiles),
[`siblings`](/query/language#siblings), [`tests`](/query/language#tests), and
[`visible`](/query/language#visible).
`cquery` also introduces the following new functions:
-### config {#config}
+### config
`expr ::= config(expr, word)`
@@ -185,17 +186,17 @@ 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.
-## Options {#options}
+## Options
-### Build options {#build-options}
+### Build options
`cquery` runs over a regular Bazel build and thus inherits the set of
[options](/reference/command-line-reference#build-options) available during a
build.
-### Using cquery options {#using-cquery-options}
+### Using cquery options
-#### `--universe_scope` (comma-separated list) {#universe-scope}
+#### `--universe_scope` (comma-separated list)
Often, the dependencies of configured targets go through
[transitions](/extending/rules#configurations),
@@ -258,13 +259,13 @@ configurations you don't care about. It could also help specify which
configuration version of a target you're looking for. You should set this flag
if your query expression is more complex than `deps(//foo)`.
-#### `--implicit_deps` (boolean, default=True) {#implicit-deps}
+#### `--implicit_deps` (boolean, default=True)
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.
-#### `--tool_deps` (boolean, default=True) {#tool-deps}
+#### `--tool_deps` (boolean, default=True)
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
@@ -276,19 +277,19 @@ non-target configuration, setting `--notool_deps` will only return targets also
in non-target configurations. This setting generally does not affect filtering
of resolved toolchains.
-#### `--include_aspects` (boolean, default=True) {#include-aspects}
+#### `--include_aspects` (boolean, default=True)
Include dependencies added by [aspects](/extending/aspects).
If this flag is disabled, `cquery somepath(X, Y)` and
`cquery deps(X) | grep 'Y'` omit Y if X only depends on it through an aspect.
-## Output formats {#output-formats}
+## Output formats
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.
-### Transitions {#transitions}
+### Transitions
```
--transitions=lite
@@ -312,7 +313,7 @@ information about rule class transitions and attribute transitions including a
detailed diff of the options before and after the transition. `LITE` mode
outputs the same information without the options diff.
-### Protocol message output {#protocol-message-output}
+### Protocol message output
```
--output=proto
@@ -327,7 +328,7 @@ has a list of `ConfiguredTarget` messages and a list of `Configuration`
messages. Each `ConfiguredTarget` has a `configuration_id` whose value is equal
to that of the `id` field from the corresponding `Configuration` message.
-#### --[no]proto:include_configurations {#proto-include-configurations}
+#### --[no]proto:include_configurations
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
@@ -340,7 +341,7 @@ Note: While selects are resolved both at the top level of returned
targets and within attributes, all possible inputs for selects are still
included as `rule_input` fields.
-### Graph output {#graph-output}
+### Graph output
```
--output=graph
@@ -351,7 +352,7 @@ This option generates output as a Graphviz-compatible .dot file. See `query`'s
also supports [`--graph:node_limit`](/query/language#graph-nodelimit) and
[`--graph:factored`](/query/language#graph-factored).
-### Files output {#files-output}
+### Files output
```
--output=files
@@ -375,7 +376,7 @@ files of `//pkg:foo` in *all* configurations that occur in the build (also see
the [section on target pattern evaluation](#target-pattern-evaluation)). If that
is not desired, wrap you query in [`config(..., target)`](#config).
-### Defining the output format using Starlark {#output-format-definition}
+### Defining the output format using Starlark
```
--output=starlark
@@ -390,7 +391,7 @@ in the query result. Alternatively, for convenience, you may specify just the
body of a function declared as `def format(target): return expr` by using the
`--starlark:expr` flag.
-#### 'cquery' Starlark dialect {#cquery-starlark}
+#### 'cquery' Starlark dialect
The cquery Starlark environment differs from a BUILD or .bzl file. It includes
all core Starlark
@@ -398,7 +399,7 @@ all core Starlark
plus a few cquery-specific ones described below, but not (for example) `glob`,
`native`, or `rule`, and it does not support load statements.
-##### build_options(target) {#build-options-function}
+##### build_options(target)
`build_options(target)` returns a map whose keys are build option identifiers
(see [Configurations](/extending/config)) and whose values are their Starlark
@@ -408,14 +409,14 @@ from this map.
If the target is an input file, `build_options(target)` returns None, as input
file targets have a null configuration.
-##### providers(target) {#providers}
+##### providers(target)
`providers(target)` returns a map whose keys are names of
[providers](/extending/rules#providers)
(for example, `"DefaultInfo"`) and whose values are their Starlark values.
Providers whose values are not legal Starlark values are omitted from this map.
-#### Examples {#output-format-definition-examples}
+#### Examples
Print a space-separated list of the base names of all files produced by `//foo`:
@@ -516,7 +517,7 @@ Extract a value from a user defined Provider.
$ bazel cquery //baz --output=starlark --starlark:file=example.cquery
```
-## cquery vs. query {#cquery-vs-query}
+## cquery vs. query
`cquery` and `query` complement each other and excel in
different niches. Consider the following to decide which is right for you:
@@ -541,7 +542,8 @@ different niches. Consider the following to decide which is right for you:
It's therefore prone to picking up results from past queries.
For example, `genrule` exerts an exec transition on its `tools` attribute -
-that is, it configures its tools in the [exec configuration](https://bazel.build/rules/rules#configurations).
+that is, it configures its tools in the [exec configuration]
+(https://bazel.build/rules/rules#configurations).
You can see the lingering effects of that transition below.
@@ -580,9 +582,9 @@ evaluate.
To disable this, run `blaze clean` before your `cquery` to ensure a fresh
analysis graph.
-## Troubleshooting {#troubleshooting}
+## Troubleshooting
-### Recursive target patterns (`/...`) {#recursive-target-patterns}
+### Recursive target patterns (`/...`)
If you encounter:
diff --git a/query/guide.mdx b/query/guide.mdx
index 705faf1d..37edd13b 100644
--- a/query/guide.mdx
+++ b/query/guide.mdx
@@ -16,7 +16,7 @@ command line.
To execute a query while ignoring errors such as missing targets, use the
`--keep_going` flag.
-## Finding the dependencies of a rule {#finding-rule-dependencies}
+## Finding the dependencies of a rule
To see the dependencies of `//foo`, use the
`deps` function in bazel query:
@@ -30,7 +30,7 @@ $ bazel query "deps(//foo)"
This is the set of all targets required to build `//foo`.
-## Tracing the dependency chain between two packages {#tracing-dependency-chain}
+## Tracing the dependency chain between two packages
The library `//third_party/zlib:zlibonly` isn't in the BUILD file for
`//foo`, but it is an indirect dependency. How can
@@ -91,7 +91,7 @@ $ bazel query "allpaths(//foo, third_party/...)"
//third_party/openssl:crypto
```
-### Aside: implicit dependencies {#implicit-dependencies}
+### Aside: implicit dependencies
The BUILD file for `//foo` never references
`//translations/tools:aggregator`. So, where's the direct dependency?
@@ -104,7 +104,7 @@ but added in by the build tool. The full set of implicit dependencies is
currently undocumented. Using `--noimplicit_deps` allows you to filter out
these deps from your query results. For cquery, this will include resolved toolchains.
-## Reverse dependencies {#reverse-dependencies}
+## Reverse dependencies
You might want to know the set of targets that depends on some target. For instance,
if you're going to change some code, you might want to know what other code
@@ -115,55 +115,41 @@ Bazel's [Sky Query](/query/language#sky-query)
supports the `allrdeps` function which allows you to query reverse dependencies
in a universe you specify.
-## Miscellaneous uses {#miscellaneous-uses}
+## Miscellaneous uses
You can use `bazel query` to analyze many dependency relationships.
-### What exists ... {#what-exists}
+### What exists ...
-#### What packages exist beneath `foo`? {#what-exists-beneath-foo}
+#### What packages exist beneath `foo`?
-```
-bazel query 'foo/...' --output package
-```
+```bazel query 'foo/...' --output package```
-#### What rules are defined in the `foo` package? {#rules-defined-in-foo}
+#### What rules are defined in the `foo` package?
-```
-bazel query 'kind(rule, foo:*)' --output label_kind
-```
+```bazel query 'kind(rule, foo:*)' --output label_kind```
-#### What files are generated by rules in the `foo` package? {#files-generated-by-rules}
+#### What files are generated by rules in the `foo` package?
-```
-bazel query 'kind("generated file", //foo:*)'
-```
+```bazel query 'kind("generated file", //foo:*)'```
-#### What targets are generated by starlark macro `foo`? {#targets-generated-by-foo}
+#### What targets are generated by starlark macro `foo`?
-```
-bazel query 'attr(generator_function, foo, //path/to/search/...)'
-```
+```bazel query 'attr(generator_function, foo, //path/to/search/...)'```
-#### What's the set of BUILD files needed to build `//foo`? {#build-files-required}
+#### What's the set of BUILD files needed to build `//foo`?
-```
-bazel query 'buildfiles(deps(//foo))' | cut -f1 -d:
-```
+```bazel query 'buildfiles(deps(//foo))' | cut -f1 -d:```
-#### What are the individual tests that a `test_suite` expands to? {#individual-tests-in-testsuite}
+#### What are the individual tests that a `test_suite` expands to?
-```
-bazel query 'tests(//foo:smoke_tests)'
-```
+```bazel query 'tests(//foo:smoke_tests)'```
-#### Which of those are C++ tests? {#cxx-tests}
+#### Which of those are C++ tests?
-```
-bazel query 'kind(cc_.*, tests(//foo:smoke_tests))'
-```
+```bazel query 'kind(cc_.*, tests(//foo:smoke_tests))'```
-#### Which of those are small? Medium? Large? {#size-of-tests}
+#### Which of those are small? Medium? Large?
```
bazel query 'attr(size, small, tests(//foo:smoke_tests))'
@@ -173,147 +159,113 @@ bazel query 'attr(size, medium, tests(//foo:smoke_tests))'
bazel query 'attr(size, large, tests(//foo:smoke_tests))'
```
-#### What are the tests beneath `foo` that match a pattern? {#tests-beneath-foo}
+#### What are the tests beneath `foo` that match a pattern?
-```
-bazel query 'filter("pa?t", kind(".*_test rule", //foo/...))'
-```
+```bazel query 'filter("pa?t", kind(".*_test rule", //foo/...))'```
The pattern is a regex and is applied to the full name of the rule. It's similar to doing
-```
-bazel query 'kind(".*_test rule", //foo/...)' | grep -E 'pa?t'
-```
+```bazel query 'kind(".*_test rule", //foo/...)' | grep -E 'pa?t'```
-#### What package contains file `path/to/file/bar.java`? {#barjava-package}
+#### What package contains file `path/to/file/bar.java`?
-```
-bazel query path/to/file/bar.java --output=package
-```
+``` bazel query path/to/file/bar.java --output=package```
-#### What is the build label for `path/to/file/bar.java?` {#barjava-build-label}
+#### What is the build label for `path/to/file/bar.java?`
-```
-bazel query path/to/file/bar.java
-```
+```bazel query path/to/file/bar.java```
-#### What rule target(s) contain file `path/to/file/bar.java` as a source? {#barjava-rule-targets}
+#### What rule target(s) contain file `path/to/file/bar.java` as a source?
```
fullname=$(bazel query path/to/file/bar.java)
bazel query "attr('srcs', $fullname, ${fullname//:*/}:*)"
```
-### What package dependencies exist ... {#package-dependencies}
+### What package dependencies exist ...
-#### What packages does `foo` depend on? (What do I need to check out to build `foo`) {#packages-foo-depends-on}
+#### What packages does `foo` depend on? (What do I need to check out to build `foo`)
-```
-bazel query 'buildfiles(deps(//foo:foo))' --output package
-```
+```bazel query 'buildfiles(deps(//foo:foo))' --output package```
Note: `buildfiles` is required in order to correctly obtain all files
referenced by `subinclude`; see the reference manual for details.
-#### What packages does the `foo` tree depend on, excluding `foo/contrib`? {#packages-foo-tree-depends-on}
+#### What packages does the `foo` tree depend on, excluding `foo/contrib`?
-```
-bazel query 'deps(foo/... except foo/contrib/...)' --output package
-```
+```bazel query 'deps(foo/... except foo/contrib/...)' --output package```
-### What rule dependencies exist ... {#rule-dependencies}
+### What rule dependencies exist ...
-#### What genproto rules does bar depend upon? {#genproto-rules}
+#### What genproto rules does bar depend upon?
-```
-bazel query 'kind(genproto, deps(bar/...))'
-```
+```bazel query 'kind(genproto, deps(bar/...))'```
-#### Find the definition of some JNI (C++) library that is transitively depended upon by a Java binary rule in the servlet tree. {#jni-library}
+#### Find the definition of some JNI (C++) library that is transitively depended upon by a Java binary rule in the servlet tree.
-```
-bazel query 'some(kind(cc_.*library, deps(kind(java_binary, //java/com/example/frontend/...))))' --output location
-```
+```bazel query 'some(kind(cc_.*library, deps(kind(java_binary, //java/com/example/frontend/...))))' --output location```
-##### ...Now find the definitions of all the Java binaries that depend on them {#java-binaries}
+##### ...Now find the definitions of all the Java binaries that depend on them
-```
-bazel query 'let jbs = kind(java_binary, //java/com/example/frontend/...) in
+```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)'
```
-### What file dependencies exist ... {#file-dependencies}
+### What file dependencies exist ...
-#### What's the complete set of Java source files required to build foo? {#java-source-files}
+#### What's the complete set of Java source files required to build foo?
Source files:
-```
-bazel query 'kind("source file", deps(//path/to/target/foo/...))' | grep java$
-```
+```bazel query 'kind("source file", deps(//path/to/target/foo/...))' | grep java$```
Generated files:
-```
-bazel query 'kind("generated file", deps(//path/to/target/foo/...))' | grep java$
-```
+```bazel query 'kind("generated file", deps(//path/to/target/foo/...))' | grep java$```
-#### What is the complete set of Java source files required to build QUX's tests? {#qux-tests}
+#### What is the complete set of Java source files required to build QUX's tests?
Source files:
-```
-bazel query 'kind("source file", deps(kind(".*_test rule", javatests/com/example/qux/...)))' | grep java$
-```
+```bazel query 'kind("source file", deps(kind(".*_test rule", javatests/com/example/qux/...)))' | grep java$```
Generated files:
-```
-bazel query 'kind("generated file", deps(kind(".*_test rule", javatests/com/example/qux/...)))' | grep java$
-```
+```bazel query 'kind("generated file", deps(kind(".*_test rule", javatests/com/example/qux/...)))' | grep java$```
-### What differences in dependencies between X and Y exist ... {#differences-in-dependencies}
+### What differences in dependencies between X and Y exist ...
-#### What targets does `//foo` depend on that `//foo:foolib` does not? {#foo-targets}
+#### What targets does `//foo` depend on that `//foo:foolib` does not?
-```
-bazel query 'deps(//foo) except deps(//foo:foolib)'
-```
+```bazel query 'deps(//foo) except deps(//foo:foolib)'```
-#### What C++ libraries do the `foo` tests depend on that the `//foo` production binary does _not_ depend on? {#foo-cxx-libraries}
+#### What C++ libraries do the `foo` tests depend on that the `//foo` production binary does _not_ depend on?
-```
-bazel query 'kind("cc_library", deps(kind(".*test rule", foo/...)) except deps(//foo))'
-```
+```bazel query 'kind("cc_library", deps(kind(".*test rule", foo/...)) except deps(//foo))'```
-### Why does this dependency exist ... {#why-dependencies}
+### Why does this dependency exist ...
-#### Why does `bar` depend on `groups2`? {#dependency-bar-groups2}
+#### Why does `bar` depend on `groups2`?
-```
-bazel query 'somepath(bar/...,groups2/...:*)'
-```
+```bazel query 'somepath(bar/...,groups2/...:*)'```
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 `bar`. The query can then be further refined to:
-#### Show me a path from `docker/updater:updater_systest` (a `py_test`) to some `cc_library` that it depends upon: {#path-docker-cclibrary}
+#### Show me a path from `docker/updater:updater_systest` (a `py_test`) to some `cc_library` that it depends upon:
-```
-bazel query 'let cc = kind(cc_library, deps(docker/updater:updater_systest)) in
- somepath(docker/updater:updater_systest, $cc)'
-```
+```bazel query 'let cc = kind(cc_library, deps(docker/updater:updater_systest)) in
+ somepath(docker/updater:updater_systest, $cc)'```
-#### Why does library `//photos/frontend:lib` depend on two variants of the same library `//third_party/jpeglib` and `//third_party/jpeg`? {#library-two-variants}
+#### Why does library `//photos/frontend:lib` depend on two variants of the same library `//third_party/jpeglib` and `//third_party/jpeg`?
This query boils down to: "show me the subgraph of `//photos/frontend:lib` that
depends on both libraries". When shown in topological order, the last element
of the result is the most likely culprit.
-```
-bazel query 'allpaths(//photos/frontend:lib, //third_party/jpeglib)
+```bazel query 'allpaths(//photos/frontend:lib, //third_party/jpeglib)
intersect
allpaths(//photos/frontend:lib, //third_party/jpeg)'
//photos/frontend:lib
@@ -325,49 +277,41 @@ bazel query 'allpaths(//photos/frontend:lib, //third_party/jpeglib)
//third_party/jpeg/img:renderer
```
-### What depends on ... {#depends-on}
+### What depends on ...
-#### What rules under bar depend on Y? {#rules-bar-y}
+#### What rules under bar depend on Y?
-```
-bazel query 'bar/... intersect allpaths(bar/..., Y)'
-```
+```bazel query 'bar/... intersect allpaths(bar/..., Y)'```
Note: `X intersect allpaths(X, Y)` 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 `let` to avoid duplication.
-#### What targets directly depend on T, in T's package? {#targets-t}
+#### What targets directly depend on T, in T's package?
-```
-bazel query 'same_pkg_direct_rdeps(T)'
-```
+```bazel query 'same_pkg_direct_rdeps(T)'```
-### How do I break a dependency ... {#break-dependency}
+### How do I break a dependency ...
{/* TODO find a convincing value of X to plug in here */}
-#### What dependency paths do I have to break to make `bar` no longer depend on X? {#break-dependency-bar-x}
+#### What dependency paths do I have to break to make `bar` no longer depend on X?
To output the graph to a `svg` file:
-```
-bazel query 'allpaths(bar/...,X)' --output graph | dot -Tsvg > /tmp/dep.svg
-```
+```bazel query 'allpaths(bar/...,X)' --output graph | dot -Tsvg > /tmp/dep.svg```
-### Misc {#misc}
+### Misc
-#### How many sequential steps are there in the `//foo-tests` build? {#steps-footests}
+#### How many sequential steps are there in the `//foo-tests` build?
Unfortunately, the query language can't currently give you the longest path
from x to y, but it can find the (or rather _a_) most distant node from the
starting point, or show you the _lengths_ of the longest path from x to every
y that it depends on. Use `maxrank`:
-```
-bazel query 'deps(//foo-tests)' --output maxrank | tail -1
-85 //third_party/zlib:zutil.c
-```
+```bazel query 'deps(//foo-tests)' --output maxrank | tail -1
+85 //third_party/zlib:zutil.c```
The result indicates that there exist paths of length 85 that must occur in
order in this build.
diff --git a/query/language.mdx b/query/language.mdx
index ee539b29..1f7de67d 100644
--- a/query/language.mdx
+++ b/query/language.mdx
@@ -13,7 +13,7 @@ For practical use cases, see the [Bazel Query How-To](/query/guide).
In addition to `query`, which runs on the post-loading phase target graph,
Bazel includes *action graph query* and *configurable query*.
-### Action graph query {#aquery}
+### Action graph query
The action graph query (`aquery`) operates on the post-analysis Configured
Target Graph and exposes information about **Actions**, **Artifacts**, and
@@ -23,7 +23,7 @@ For example, the actual commands run and their inputs, outputs, and mnemonics.
For more details, see the [aquery reference](/query/aquery).
-### Configurable query {#cquery}
+### Configurable query
Traditional Bazel query runs on the post-loading phase target graph and
therefore has no concept of configurations and their related concepts. Notably,
@@ -34,7 +34,7 @@ doesn't provide all of the functionality of this original query.
For more details, see the [cquery reference](/query/cquery).
-## Examples {#examples}
+## Examples
How do people use `bazel query`? Here are typical examples:
@@ -52,7 +52,7 @@ the `foo_bin` target does not?
kind("cc_library", deps(kind(".*test rule", foo/...)) except deps(//foo:foo_bin))
```
-## Tokens: The lexical syntax {#tokens}
+## Tokens: The lexical syntax
Expressions in the query language are composed of the following
tokens:
@@ -136,7 +136,7 @@ tokens:
Whitespace characters outside of a quoted word are ignored.
-## Bazel query language concepts {#language-concepts}
+## Bazel query language concepts
The Bazel query language is a language of expressions. Every
expression evaluates to a **partially-ordered set** of targets,
@@ -149,7 +149,7 @@ aspects of it, for example:
* **Set:** The partial order of the targets is not interesting.
* **Graph:** The partial order of targets is significant.
-### Cycles in the dependency graph {#dependency-graph-cycles}
+### Cycles in the dependency graph
Build dependency graphs should be acyclic.
@@ -161,7 +161,7 @@ operates over may contain cycles that do not exist in the configured target
graph. Cycles in the configured target graph are detected and reported as errors
by [`bazel cquery`](/query/cquery) and [`bazel aquery`](/query/aquery).
-### Implicit dependencies {#implicit-dependencies}
+### Implicit dependencies
In addition to build dependencies that are defined explicitly in `BUILD` files,
Bazel adds additional _implicit_ dependencies to rules. Implicit dependencies
@@ -179,7 +179,7 @@ Note that, as query does not consider configurations, potential toolchain
required toolchain types. See
[toolchain documentation](/extending/toolchains#writing-rules-toolchains).
-### Soundness {#soundness}
+### Soundness
Bazel query language expressions operate over the build
dependency graph, which is the graph implicitly defined by all
@@ -199,7 +199,7 @@ 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.
-### On the preservation of graph order {#graph-order}
+### On the preservation of graph order
Operations preserve any ordering
constraints inherited from their subexpressions. You can think of
@@ -235,7 +235,7 @@ Operators that introduce ordering constraints include:
`allpaths`, `deps`, `rdeps`, `somepath`, and the target pattern wildcards
`package:*`, `dir/...`, etc.
-### Sky query {#sky-query}
+### Sky query
_Sky Query_ is a mode of query that operates over a specified _universe scope_.
@@ -299,7 +299,7 @@ As well, Sky Query does its work by introspecting the
graph, which is what the default implementation does. Thus, there are some circumstances in which
it is faster and uses less memory.
-## Expressions: Syntax and semantics of the grammar {#expressions}
+## Expressions: Syntax and semantics of the grammar
This is the grammar of the Bazel query language, expressed in EBNF notation:
@@ -319,7 +319,7 @@ expr ::= word
The following sections describe each of the productions of this grammar in order.
-### Target patterns {#target-patterns}
+### Target patterns
```
expr ::= word
@@ -362,7 +362,7 @@ _graph_ over those targets. (No guarantees are made about the relative ordering
of the result nodes against other nodes.) For more details, see the
[graph order](#graph-order) section.
-### Variables {#variables}
+### Variables
```none
expr ::= let name = expr{{ '' }}1{{ '' }} in expr{{ '' }}2{{ '' }}
@@ -400,7 +400,7 @@ 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.
-### Parenthesized expressions {#parenthesized-expressions}
+### Parenthesized expressions
```none
expr ::= (expr)
@@ -409,7 +409,7 @@ expr ::= (expr)
Parentheses associate subexpressions to force an order of evaluation.
A parenthesized expression evaluates to the value of its argument.
-### Algebraic set operations: intersection, union, set difference {#algebraic-set-operations}
+### Algebraic set operations: intersection, union, set difference
```none
expr ::= expr intersect expr
@@ -453,7 +453,7 @@ x intersect (y union z)
Important: Use parentheses where there is any danger of ambiguity in reading a
query expression.
-### Read targets from an external source: set {#set}
+### Read targets from an external source: set
```none
expr ::= set(word *)
@@ -491,7 +491,7 @@ Note: `set()` introduces no graph ordering constraints, so path information may
be lost when saving and reloading sets of nodes using it. For more details,
see the [graph order](#graph-order) section below.
-## Functions {#functions}
+## Functions
```none
expr ::= word '(' int | word | expr ... ')'
@@ -521,7 +521,7 @@ functions are available:
* [`visible`](#visible)
-### Transitive closure of dependencies: deps {#deps}
+### Transitive closure of dependencies: deps
```none
expr ::= deps(expr)
@@ -551,7 +551,7 @@ correspond to the ranks shown in the [`minrank`](#output-ranked) output format.)
If the depth parameter is omitted, the search is
unbounded: it computes the reflexive transitive closure of prerequisites.
-### Transitive closure of reverse dependencies: rdeps {#rdeps}
+### Transitive closure of reverse dependencies: rdeps
```none
expr ::= rdeps(expr, expr)
@@ -575,7 +575,7 @@ numbers correspond to the ranks shown in the [`minrank`](#output-ranked) output
format.) If the depth parameter is omitted, the
search is unbounded.
-### Transitive closure of all reverse dependencies: allrdeps {#allrdeps}
+### Transitive closure of all reverse dependencies: allrdeps
```
expr ::= allrdeps(expr)
@@ -590,7 +590,7 @@ evaluated to, instead of being separately specified. Thus, if
`--universe_scope=//foo/...` was passed, then `allrdeps(//bar)` is
equivalent to `rdeps(//foo/..., //bar)`.
-### Direct reverse dependencies in the same package: same_pkg_direct_rdeps {#same_pkg_direct_rdeps}
+### Direct reverse dependencies in the same package: same_pkg_direct_rdeps
```
expr ::= same_pkg_direct_rdeps(expr)
@@ -599,7 +599,7 @@ expr ::= same_pkg_direct_rdeps(expr)
The `same_pkg_direct_rdeps(x)` operator evaluates 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.
-### Dealing with a target's package: siblings {#siblings}
+### Dealing with a target's package: siblings
```
expr ::= siblings(expr)
@@ -608,7 +608,7 @@ expr ::= siblings(expr)
The `siblings(x)` operator evaluates to the full set of targets that are in
the same package as a target in the argument set.
-### Arbitrary choice: some {#some}
+### Arbitrary choice: some
```
expr ::= some(expr)
@@ -637,7 +637,7 @@ equivalent to `//foo:main`.
It is an error if the specified argument set is empty, as in the
expression `some(//foo:main intersect //bar:baz)`.
-### Path operators: somepath, allpaths {#somepath-allpaths}
+### Path operators: somepath, allpaths
```
expr ::= somepath(expr, expr)
@@ -661,7 +661,7 @@ See the section on [graph order](#graph-order) for more details.
-
+ somepath(S1 + S2, E), one possible result.
{/* digraph somepath1 {
@@ -692,7 +692,7 @@ See the section on [graph order](#graph-order) for more details.
-
+ somepath(S1 + S2, E), another possible result.
{/* digraph somepath2 {
@@ -721,7 +721,7 @@ See the section on [graph order](#graph-order) for more details.
-
+ allpaths(S1 + S2, E)
{/* digraph allpaths {
@@ -754,7 +754,7 @@ See the section on [graph order](#graph-order) for more details.
-### Target kind filtering: kind {#kind}
+### Target kind filtering: kind
```
expr ::= kind(word, expr)
@@ -815,7 +815,7 @@ file` and `.*_test`, are not considered words by the parser.
When matching for `package group`, targets ending in
`:all` may not yield any results. Use `:all-targets` instead.
-### Target name filtering: filter {#filter}
+### Target name filtering: filter
```
expr ::= filter(word, expr)
@@ -867,7 +867,7 @@ filter("\.cc$", deps(//foo))
will provide a list of all `.cc` files used to build `//foo`.
-### Rule attribute filtering: attr {#attr}
+### Rule attribute filtering: attr
```
expr ::= attr(word, word, expr)
@@ -960,7 +960,7 @@ some_rule(
This works because the character before `key=value` will be `{` or a space and
the character after `key=value` will be a comma or `}`.
-### Rule visibility filtering: visible {#visible}
+### Rule visibility filtering: visible
```
expr ::= visible(expr, expr)
@@ -983,7 +983,7 @@ visible(//foo, //bar:*)
will select all targets in the package `//bar` that `//foo`
can depend on without violating visibility restrictions.
-### Evaluation of rule attributes of type label: labels {#labels}
+### Evaluation of rule attributes of type label: labels
```
expr ::= labels(word, expr)
@@ -1000,7 +1000,7 @@ the `//foo` rule. If there are multiple rules
with `srcs` attributes in the inputs set, the
union of their `srcs` is returned.
-### Expand and filter test_suites: tests {#tests}
+### Expand and filter test_suites: tests
```
expr ::= tests(expr)
@@ -1025,7 +1025,7 @@ foo:*`: this may include tests belonging to other packages,
that are referenced directly or indirectly
via `test_suite` rules.
-### Executable targets: executables {#executables}
+### Executable targets: executables
```
expr ::= executables(expr)
@@ -1039,7 +1039,7 @@ or any other rule that sets `executable = True` in its definition.
This doesn't include test targets, which can be added to the result with
the [`tests`](#tests) operator.
-### Package definition files: buildfiles {#buildfiles}
+### Package definition files: buildfiles
```
expr ::= buildfiles(expr)
@@ -1075,7 +1075,7 @@ target `//a:b.bzl`), but this isn't necessarily the case. Therefore,
misleading when formatted in a structured way, such as
[`--output=xml`](#xml).
-### Package definition files: rbuildfiles {#rbuildfiles}
+### Package definition files: rbuildfiles
```
expr ::= rbuildfiles(word, ...)
@@ -1107,7 +1107,7 @@ outputs of the `buildfiles` operator are targets corresponding to all packages a
files needed by a given input. However, the inputs of the `rbuildfiles` operator are
not those targets, but rather the path fragments that correspond to those targets.
-### Package definition files: loadfiles {#loadfiles}
+### Package definition files: loadfiles
```
expr ::= loadfiles(expr)
@@ -1124,7 +1124,7 @@ necessarily the case. Therefore, `loadfiles` doesn't compose well with other que
operators and its results can be misleading when formatted in a structured way, such as
[`--output=xml`](#xml).
-## Output formats {#output-formats}
+## Output formats
`bazel query` generates a graph.
You specify the content, format, and ordering by which
@@ -1143,9 +1143,10 @@ an output format other than `graph` is used. Similarly,
`--xml:line_numbers` applies only when `--output=xml`
is being used.
-### On the ordering of results {#results-ordering}
+### On the ordering of results
-Although query expressions always follow the "[law of conservation of graph order](#graph-order)", _presenting_ the results may be done
+Although query expressions always follow the "[law of
+conservation of graph order](#graph-order)", _presenting_ the results may be done
in either a dependency-ordered or unordered manner. This does **not**
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
@@ -1180,7 +1181,7 @@ in which they were visited.
Printing nodes in this order may be slower, so it should be used only when determinism is
important.
-### Print the source form of targets as they would appear in BUILD {#target-source-form}
+### Print the source form of targets as they would appear in BUILD
```
--output build
@@ -1196,7 +1197,7 @@ giving the name of the macro that was evaluated to produce the effective rule.
Although the output uses the same syntax as `BUILD` files, it is not
guaranteed to produce a valid `BUILD` file.
-### Print the label of each target {#print-label-target}
+### Print the label of each target
```
--output label
@@ -1224,7 +1225,7 @@ below) format, the distinction becomes clear: the two targets have
the same name, but one has kind `sh_binary rule` and the
other kind `source file`.
-### Print the label and kind of each target {#print-target-label}
+### Print the label and kind of each target
```
--output label_kind
@@ -1234,7 +1235,7 @@ Like `label`, this output format prints the labels of
each target in the resulting graph, in topological order, but it
additionally precedes the label by the [_kind_](#kind) of the target.
-### Print targets in protocol buffer format {#print-target-proto}
+### Print targets in protocol buffer format
```
--output proto
@@ -1244,7 +1245,7 @@ Prints the query output as a
[`QueryResult`](https://github.com/bazelbuild/bazel/blob/master/src/main/protobuf/build.proto)
protocol buffer.
-### Print targets in length-delimited protocol buffer format {#print-target-length-delimited-proto}
+### Print targets in length-delimited protocol buffer format
```
--output streamed_proto
@@ -1259,7 +1260,7 @@ protocol buffers. This is useful to _(i)_ get around
of protocol buffers when there are too many targets to fit in a single
`QueryResult` or _(ii)_ to start processing while Bazel is still outputting.
-### Print targets in text proto format {#print-target-textproto}
+### Print targets in text proto format
```
--output textproto
@@ -1270,7 +1271,7 @@ Similar to `--output proto`, prints the
protocol buffer but in
[text format](https://protobuf.dev/reference/protobuf/textformat-spec/).
-### Print targets in ndjson format {#print-target-streamed-jsonproto}
+### Print targets in ndjson format
```
--output streamed_jsonproto
@@ -1280,7 +1281,7 @@ Similar to `--output streamed_proto`, prints a stream of
[`Target`](https://github.com/bazelbuild/bazel/blob/master/src/main/protobuf/build.proto)
protocol buffers but in [ndjson](https://github.com/ndjson/ndjson-spec) format.
-### Print the label of each target, in rank order {#print-target-label-rank-order}
+### Print the label of each target, in rank order
```
--output minrank --output maxrank
@@ -1291,7 +1292,8 @@ and `maxrank` 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
-`--[no]order_results` flag (see [notes on the ordering of results](#result-order)).
+`--[no]order_results` flag (see [notes on
+the ordering of results](#result-order)).
There are two variants of this format: `minrank` ranks
each node by the length of the shortest path from a root node to it.
@@ -1328,7 +1330,7 @@ are specified, respectively.
-
+
@@ -1355,7 +1357,7 @@ are specified, respectively.
@@ -493,7 +491,7 @@ Zenly is a live map of your friends and family. It’s the most fun way to meet
***
-## Open source projects using Bazel {#open-source-projects-using-Bazel}
+## Open source projects using Bazel
### [Abseil](https://abseil.io/)
@@ -723,6 +721,10 @@ networks.
Sorbet is a fast, powerful type checker for a subset of Ruby. It scales to
codebases with millions of lines of code and can be adopted incrementally.
+### [Spotify](https://spotify.com)
+
+Spotify is using Bazel to build their iOS and Android Apps ([source](https://twitter.com/BalestraPatrick/status/1573355078995566594)).
+
### [Tink](https://github.com/google/tink)
Tink is a multi-language, cross-platform, open source library that provides
@@ -750,4 +752,4 @@ architecture.
### [ZhihuDailyPurify](https://github.com/izzyleung/ZhihuDailyPurify)
ZhihuDailyPurify is a light weight version of Zhihu Daily, a Chinese
-question-and-answer webs.
+question-and-answer webs.
\ No newline at end of file
diff --git a/concepts/build-files.mdx b/concepts/build-files.mdx
index b85f472c..66d01f8c 100644
--- a/concepts/build-files.mdx
+++ b/concepts/build-files.mdx
@@ -50,7 +50,7 @@ team. `BUILD` file authors should comment 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.
-## Loading an extension {#load}
+## Loading an extension
Bazel extensions are files ending in `.bzl`. Use the `load` statement to import
a symbol from an extension.
@@ -92,7 +92,7 @@ loaded from another file.
You can use [load visibility](/concepts/visibility#load-visibility) to restrict
who may load a `.bzl` file.
-## Types of build rules {#types-of-build-rules}
+## Types of build rules
The majority of build rules come in families, grouped together by
language. For example, `cc_binary`, `cc_library`
@@ -132,6 +132,23 @@ for anyone to create new rules.
and binaries and tests can depend on libraries, with the expected
separate-compilation behavior.
+
+ 
+ 
+ 
+ 
+ 
+