docs: Restore custom heading anchors (https://github.com/bazelbuild/bazel/pull/29092) Restores custom heading anchors to mdx files in a syntax that Mintlify supports. RELNOTES: None Closes #29092. PiperOrigin-RevId: 889420789 Change-Id: Id10c134594ea7bdec7e99809998a8a4a50ba9b4f
diff --git a/docs/about/intro.mdx b/docs/about/intro.mdx index a531ac2..242a799 100644 --- a/docs/about/intro.mdx +++ b/docs/about/intro.mdx
@@ -9,7 +9,7 @@ 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 @@ 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 @@ [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 @@ [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 @@ 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/docs/about/vision.mdx b/docs/about/vision.mdx index da0ed02..dafc64b 100644 --- a/docs/about/vision.mdx +++ b/docs/about/vision.mdx
@@ -45,7 +45,7 @@ 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 @@ possible. Bazel interfaces with de-facto standard tools for a given language/platform. -## Serving language communities +## Serving language communities {#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 @@ Bazel is committed to be extensible and open, and to support good rulesets for any language. -### Requirements of a good ruleset +### Requirements of a good ruleset {#ruleset-requirements} 1. The rules need to support efficient **building and testing** for the language, including code coverage.
diff --git a/docs/about/why.mdx b/docs/about/why.mdx index 6224abf..6ddd322 100644 --- a/docs/about/why.mdx +++ b/docs/about/why.mdx
@@ -9,7 +9,7 @@ [languages](#multi-language), [repositories](#multi-repository), and [platforms](#multi-platform) in an industry-leading [ecosystem](#ecosystem). -## Bazel is fast +## Bazel is fast {#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 @@ remote build farm, if available. At Google, we routinely achieve cache hit rates north of 99%. -## Bazel is correct +## Bazel is correct {#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 @@ 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 +## Bazel is extensible {#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 @@ 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 @@ location, thereby facilitating efficient communication of test outcomes, be it on CI or by individual developers. -## Multi-language support +## Multi-language support {#multi-language} 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 support {#multi-repository} 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 support {#multi-platform} 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 +## Wide ecosystem {#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/docs/advanced/performance/build-performance-metrics.mdx b/docs/advanced/performance/build-performance-metrics.mdx index 8391ea8..46a7732 100644 --- a/docs/advanced/performance/build-performance-metrics.mdx +++ b/docs/advanced/performance/build-performance-metrics.mdx
@@ -23,7 +23,7 @@ There are a few main ways to extract metrics from your Bazel builds, namely: -## Build Event Protocol (BEP) +## Build Event Protocol (BEP) {#build-event-protocol} 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 @@ 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’s query / cquery / aquery commands {#bazel-commands-query-cquery-aquery} Bazel provides 3 different query modes ([query](/query/quickstart), [cquery](/query/cquery) and [aquery](/query/aquery)) that allow users @@ -41,14 +41,14 @@ [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 @@ 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 @@ The data helps you predict the impact of changes to the build and action graph before you actually do them. -## Benchmarking with bazel-bench +## Benchmarking with bazel-bench {#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/docs/advanced/performance/iteration-speed.mdx b/docs/advanced/performance/iteration-speed.mdx index 2bbf839..763af9c 100644 --- a/docs/advanced/performance/iteration-speed.mdx +++ b/docs/advanced/performance/iteration-speed.mdx
@@ -7,7 +7,7 @@ This page describes how to optimize Bazel's build performance when running Bazel repeatedly. -## Bazel's Runtime State +## Bazel's Runtime State {#bazel-runtime-state} A Bazel invocation involves several interacting parts. @@ -32,7 +32,7 @@ * The result of the Bazel invocation is made available in the output tree. -## Running Bazel Iteratively +## Running Bazel Iteratively {#run-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 @@ [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 the analysis cache {#avoid-discarding-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/docs/advanced/performance/json-trace-profile.mdx b/docs/advanced/performance/json-trace-profile.mdx index 80c698c..0e93645 100644 --- a/docs/advanced/performance/json-trace-profile.mdx +++ b/docs/advanced/performance/json-trace-profile.mdx
@@ -76,7 +76,7 @@ [...] ``` -## 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 @@ * `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 @@ 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/docs/advanced/performance/memory.mdx b/docs/advanced/performance/memory.mdx index 844e691..49d6676 100644 --- a/docs/advanced/performance/memory.mdx +++ b/docs/advanced/performance/memory.mdx
@@ -6,14 +6,14 @@ This page describes how to limit and reduce the memory Bazel uses. -## Running Bazel with Limited RAM +## Running Bazel with Limited RAM {#running-bazel} 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 build speeds for memory {#trade-incremental} 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 @@ 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 build flexibility for memory with Skyfocus (Experimental) {#trade-flexibility} 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 @@ -89,7 +89,7 @@ `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/docs/basics/hermeticity.mdx b/docs/basics/hermeticity.mdx index dcee3a9..8f165a2 100644 --- a/docs/basics/hermeticity.mdx +++ b/docs/basics/hermeticity.mdx
@@ -7,7 +7,7 @@ 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 @@ 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 @@ * **Reproducibility**: Hermetic builds are good for troubleshooting because you know the exact conditions that produced the build. -## Identifying non-hermeticity +## Identifying non-hermeticity {#nonhermeticity} 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 @@ tree, fixing the source tree for target A. Then trying to build target B may fail. -## Troubleshooting non-hermetic builds +## Troubleshooting non-hermetic builds {#troubleshooting-nonhermeticity} Starting with local execution, issues that affect local cache hits reveal non-hermetic actions. @@ -94,7 +94,7 @@ 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 with Bazel {#hermeticity-bazel} For more information about how other projects have had success using hermetic builds with Bazel, see these BazelCon talks:
diff --git a/docs/brand/index.mdx b/docs/brand/index.mdx index 2a21cd4..0386d93 100644 --- a/docs/brand/index.mdx +++ b/docs/brand/index.mdx
@@ -10,7 +10,7 @@ Trademarks other than those permitted in these guidelines must be approved in advance. -## Purpose of the Brand Guidelines +## Purpose of the Brand Guidelines {#purpose-brand} 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 @@ 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 @@ * \[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 @@ materials without prior written permission from [product@bazel.build](mailto:product@bazel.build). -## Usage for Events and Community Groups +## Usage for Events and Community Groups {#usage-events} 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 @@ * 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/docs/build/style-guide.mdx b/docs/build/style-guide.mdx index cfc3cf8..3502de4 100644 --- a/docs/build/style-guide.mdx +++ b/docs/build/style-guide.mdx
@@ -4,7 +4,7 @@ -## 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 @@ code, but do need to be maintained by people and tools. That makes DAMP better for them than DRY. -## BUILD.bazel file formatting +## BUILD.bazel file formatting {#formatting} `BUILD` file formatting follows the same approach as Go, where a standardized tool takes care of most formatting issues. @@ -30,7 +30,7 @@ `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 @@ ) ``` -## File structure +## File structure {#file-structure} **Recommendation**: Use the following order (every element is optional): @@ -79,7 +79,7 @@ cc_library(name = "cc") ``` -## References to targets in the current package +## References to targets in the current package {#targets-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 @@ ) ``` -## 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 @@ * **`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 @@ 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 @@ 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 @@ 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 +## Avoid list comprehensions {#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 @@ ... ``` -## Don't use deps variables +## Don't use deps variables {#no-dep-vars} Don't use list variables to encapsulate common dependencies: @@ -289,7 +289,7 @@ maintain them. There will be repetition, but you won't have to think about how to manage the dependencies. -## Prefer literal strings +## Prefer literal strings {#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 @@ [buildozer]: https://github.com/bazelbuild/buildtools/blob/main/buildozer/README.md -## Limit the symbols exported by each `.bzl` file +## Limit the symbols exported by each `.bzl` file {#limit-symbols} 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 @@ [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 @@ "deflake this target by rerunning it once". `flaky = True` unambiguously says "this test is flaky". -## Differences with Python style guide +## Differences with Python style guide {#differences-python-style-guide} Although compatibility with [Python style guide](https://www.python.org/dev/peps/pep-0008/)
diff --git a/docs/community/recommended-rules.mdx b/docs/community/recommended-rules.mdx index 86daa05..7f5eef8 100644 --- a/docs/community/recommended-rules.mdx +++ b/docs/community/recommended-rules.mdx
@@ -11,7 +11,7 @@ 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 @@ After a review by the [Bazel core team](/contribute/policy), it will be recommended on the Bazel website. -## Requirements for the rule maintainers +## Requirements for the rule maintainers {#requirements-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 @@ should be fixed within two weeks. Migration issues should be reported to the Bazel team quickly. -## Requirements for Bazel developers +## Requirements for Bazel developers {#requirements-dev} * 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/docs/community/users.mdx b/docs/community/users.mdx index 3f027c0..65b473c 100644 --- a/docs/community/users.mdx +++ b/docs/community/users.mdx
@@ -11,7 +11,7 @@ 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) @@ -491,7 +491,7 @@ *** -## Open source projects using Bazel +## Open source projects using Bazel {#open-source-projects-using-Bazel} ### [Abseil](https://abseil.io/)
diff --git a/docs/concepts/build-files.mdx b/docs/concepts/build-files.mdx index 66d01f8..ec87f4d 100644 --- a/docs/concepts/build-files.mdx +++ b/docs/concepts/build-files.mdx
@@ -50,7 +50,7 @@ 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 +## Loading an extension {#load} Bazel extensions are files ending in `.bzl`. Use the `load` statement to import a symbol from an extension. @@ -92,7 +92,7 @@ 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`
diff --git a/docs/concepts/build-ref.mdx b/docs/concepts/build-ref.mdx index e8839d4..0af7897 100644 --- a/docs/concepts/build-ref.mdx +++ b/docs/concepts/build-ref.mdx
@@ -11,7 +11,7 @@ `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 @@ -22,7 +22,7 @@ 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 @@ -32,7 +32,7 @@ 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 @@ -56,7 +56,7 @@ 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_.
diff --git a/docs/concepts/dependencies.mdx b/docs/concepts/dependencies.mdx index bdb65f0..39fef86 100644 --- a/docs/concepts/dependencies.mdx +++ b/docs/concepts/dependencies.mdx
@@ -18,7 +18,7 @@ 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 @@ 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 +### 1. Declared dependencies match actual dependencies {#this-is-fine} 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 @@ The declared dependencies overapproximate the actual dependencies. All is well. -### 2. Adding an undeclared dependency +### 2. Adding an undeclared dependency {#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 @@ 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 +### 3. Divergence between declared and actual dependency graphs {#divergence} 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 @@ 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 @@ 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 @@ directory and the workspace-relative path, for example, `${TEST_SRCDIR}/workspace/path/to/data/file`. -## Using labels to reference directories +## Using labels to reference directories {#using-labels-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,
diff --git a/docs/concepts/labels.mdx b/docs/concepts/labels.mdx index b221e34..5b0b1c6 100644 --- a/docs/concepts/labels.mdx +++ b/docs/concepts/labels.mdx
@@ -117,7 +117,7 @@ For information about the different ways you can refer to targets, see [target patterns](/run/build#specifying-build-targets). -### Lexical specification of a label +### Lexical specification of a label {#labels-lexical-specification} 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 @@ -126,7 +126,7 @@ The precise details of allowed target names are below. -### Target names — `<var>package-name</var>:target-name` +### Target names — `<var>package-name</var>:target-name` {#target-names} `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` @@ -157,7 +157,7 @@ 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:<var>target-name</var>` +### Package names — `//package-name:<var>target-name</var>` {#package-names} 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. @@ -188,7 +188,7 @@ `//: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
diff --git a/docs/concepts/platforms.mdx b/docs/concepts/platforms.mdx index e560ea4..591ef31 100644 --- a/docs/concepts/platforms.mdx +++ b/docs/concepts/platforms.mdx
@@ -20,9 +20,9 @@ * [Toolchains][Toolchains] * [Background][Background] -## Status +## Status {#status} -### C++ +### C++ {#cxx} C++ rules use platforms to select toolchains when `--incompatible_enable_cc_toolchain_resolution` is set. @@ -45,7 +45,7 @@ [Migrating Your Project](#migrating-your-project) and [Configuring C++ toolchains]. -### Java +### Java {#java} Java rules use platforms to select toolchains. @@ -54,7 +54,7 @@ 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,7 +73,7 @@ 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. @@ -82,7 +82,7 @@ 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. @@ -90,7 +90,7 @@ 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. @@ -110,7 +110,7 @@ demands more principled support for these concepts, including a clear standard API. -### Need for migration +### Need for migration {#migration} Upgrading to the new API requires two efforts: releasing the API and upgrading rule logic to use it. @@ -125,7 +125,7 @@ This is why this is an ongoing migration. -### Goal +### Goal {#goal} This migration is complete when all projects build with the form: @@ -151,7 +151,7 @@ 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: @@ -185,7 +185,7 @@ 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 @@ -198,7 +198,7 @@ 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 @@ -235,7 +235,7 @@ `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 @@ -248,7 +248,7 @@ 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: @@ -273,7 +273,7 @@ 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). @@ -287,7 +287,7 @@ 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 @@ -327,7 +327,7 @@ 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]: @@ -379,7 +379,7 @@ 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. @@ -387,7 +387,7 @@ 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/docs/concepts/visibility.mdx b/docs/concepts/visibility.mdx index fa5cf3a..45ad798 100644 --- a/docs/concepts/visibility.mdx +++ b/docs/concepts/visibility.mdx
@@ -13,7 +13,7 @@ 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 @@ 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 @@ 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 @@ 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 @@ ) ``` -### 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 @@ 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 +#### Example {#source-file-visibility-example} File `//frobber/data/BUILD`: @@ -217,7 +217,7 @@ ) ``` -### 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 @@ 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 of implicit dependencies {#visibility-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 @@ If you want to restrict the usage of a rule to certain packages, use [load visibility](#load-visibility) instead. -### Visibility and symbolic macros +### Visibility and symbolic macros {#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 @@ 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 @@ 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 @@ `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 @@ 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 @@ 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 @@ 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 +### Example {#load-visibility-example} ```starlark # //mylib/internal_defs.bzl @@ -537,11 +537,11 @@ ... ``` -### 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 @@ 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 @@ 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 @@ 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 @@ 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/docs/configure/attributes.mdx b/docs/configure/attributes.mdx index 7bc3f41..7f4936b 100644 --- a/docs/configure/attributes.mdx +++ b/docs/configure/attributes.mdx
@@ -12,7 +12,7 @@ chooses the appropriate implementation for the architecture, or for a feature-configurable binary that can be customized at build time. -## Example +## Example {#configurable-build-example} ```python # myapp/BUILD @@ -87,7 +87,7 @@ `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 +143,7 @@ `--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 +155,7 @@ `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 +189,7 @@ 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 +225,7 @@ `values`, `flag_values`, and `define_values` evaluate independently. The `config_setting` matches if all values across all of them match. -## The default condition +## The default condition {#default-condition} The built-in condition `//conditions:default` matches when no other condition matches. @@ -261,7 +261,7 @@ 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 +363,7 @@ Platforms are still under development. See the [documentation](/concepts/platforms) for details. -## Combining `select()`s +## Combining `select()`s {#combining-selects} `select` can appear multiple times in the same attribute: @@ -412,7 +412,7 @@ 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: @@ -455,7 +455,7 @@ 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) @@ -478,7 +478,7 @@ ) ``` -### `selects.config_setting_group` +### `selects.config_setting_group` {#selects-config-setting-or-group} The @@ -521,7 +521,7 @@ 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 @@ -553,7 +553,7 @@ 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: @@ -588,7 +588,7 @@ 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: @@ -636,7 +636,7 @@ technically feasible, lack a coherent UI. Further design is necessary to change this. -## Bazel query and cquery +## Bazel query and cquery {#query-and-cquery} Bazel [`query`](/query/guide) operates over Bazel's [loading phase](/reference/glossary#loading-phase). @@ -697,9 +697,9 @@ //myapp:bar_dep ``` -## FAQ +## FAQ {#faq} -### Why doesn't select() work in macros? +### Why doesn't select() work in macros? {#faq-select-macro} select() *does* work in rules! See [Rules compatibility](#rules-compatibility) for details. @@ -811,7 +811,7 @@ 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? +### Why does select() always return true? {#faq-boolean-select} Because *macros* (but not rules) by definition [can't evaluate `select()`s](#faq-select-macro), any attempt to do so @@ -857,7 +857,7 @@ standards, all objects aside from a very small number of exceptions automatically return true. -### Can I read select() like a dict? +### Can I read select() like a dict? {#faq-inspectable-select} 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 @@ -913,7 +913,7 @@ ) ``` -### Why doesn't select() work with bind()? +### Why doesn't select() work with bind()? {#faq-select-bind} First of all, do not use `bind()`. It is deprecated in favor of `alias()`. @@ -959,7 +959,7 @@ But really, stop using `bind()`. -### Why doesn't my select() choose what I expect? +### Why doesn't my select() choose what I expect? {#faq-select-choose-condition} If `//myapp:foo` has a `select()` that doesn't choose the condition you expect, use [cquery](/query/cquery) and `bazel config` to debug: @@ -1010,7 +1010,7 @@ 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? +### Why doesn't `select()` work with platforms? {#faq-select-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/configure/best-practices.mdx b/docs/configure/best-practices.mdx index deecf9d..7f9f57f 100644 --- a/docs/configure/best-practices.mdx +++ b/docs/configure/best-practices.mdx
@@ -23,7 +23,7 @@ This page uses the requirement levels described in [this RFC](https://www.ietf.org/rfc/rfc2119.txt). -## Running builds and tests +## Running builds and tests {#running-builds-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 @@ "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 +## Depending on binaries {#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 @@ 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 @@ If you created a misleading alias to point both targets to one `guava` library, then the `BUILD` files are misleading. -## Using the `.bazelrc` file +## Using the `.bazelrc` file {#bazelrc-file} For project-specific options, use the configuration file your `<var>workspace</var>/.bazelrc` (see [bazelrc format](/run/bazelrc)). @@ -84,7 +84,7 @@ 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/docs/configure/coverage.mdx b/docs/configure/coverage.mdx index f8e3e7b..1eacadf 100644 --- a/docs/configure/coverage.mdx +++ b/docs/configure/coverage.mdx
@@ -21,7 +21,7 @@ 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 @@ 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/docs/configure/integrate-cpp.mdx b/docs/configure/integrate-cpp.mdx index 107ab81..b9ba884 100644 --- a/docs/configure/integrate-cpp.mdx +++ b/docs/configure/integrate-cpp.mdx
@@ -4,7 +4,7 @@ This page describes how to integrate with C++ rules on various levels. -## Accessing the C++ toolchain +## Accessing the C++ toolchain {#access-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) @@ -17,7 +17,7 @@ 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 +## Generating command lines and environment variables using the C++ toolchain {#generate-command-lines-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. @@ -45,7 +45,7 @@ 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 +## Implementing Starlark rules that depend on C++ rules and/or that C++ rules can depend on {#implement-starlark-rules} Most C++ rules provide [`CcInfo`](/rules/lib/providers/CcInfo), @@ -67,7 +67,7 @@ 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 +## Reusing logic and actions of C++ rules {#reuse-logic-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/docs/configure/windows.mdx b/docs/configure/windows.mdx index 67a36c8..46e6073 100644 --- a/docs/configure/windows.mdx +++ b/docs/configure/windows.mdx
@@ -7,16 +7,16 @@ 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 +### Avoid long path issues {#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 @@ startup --output_user_root=C:/tmp ``` -### Enable symlink support +### Enable symlink support {#symlink} Some features require Bazel to be able to create file symlinks on Windows, either by enabling @@ -51,7 +51,7 @@ {/* 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: MSYS2 shell vs. command prompt vs. PowerShell {#running-bazel-shells} **Recommendation:** Run Bazel from the command prompt (`cmd.exe`) or from PowerShell. @@ -66,9 +66,9 @@ [this StackOverflow answer](https://stackoverflow.com/a/49004265/7778502) for details. -### Using Bazel without Bash (MSYS2) +### Using Bazel without Bash (MSYS2) {#using-bazel-without-bash} -#### Using bazel build without Bash +#### Using bazel build without Bash {#bazel-build-without-bash} Bazel versions before 1.0 used to require Bash to build some rules. @@ -86,7 +86,7 @@ [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 +#### Using bazel test without Bash {#bazel-test-without-bash} Bazel versions before 1.0 used to require Bash to `bazel test` anything. @@ -95,7 +95,7 @@ - you use `--run_under` - the test rule itself requires Bash (because its executable is a shell script) -#### Using bazel run without Bash +#### Using bazel run without Bash {#bazel-run-without-bash} Bazel versions before 1.0 used to require Bash to `bazel run` anything. @@ -104,7 +104,7 @@ - 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 +#### Using sh\_binary and sh\_* rules, and ctx.actions.run_shell() without Bash {#sh-rules-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 @@ Linux (WSL) to build these rules, but currently it is not a priority for the Bazel-on-Windows subteam. -### Setting environment variables +### Setting environment variables {#set-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 @@ can add them to the User variables or System variables in the `Control Panel > System Properties > Advanced > Environment Variables...` dialog box. -## Build on Windows +## Build on Windows {#using} -### Build C++ with MSVC +### Build C++ with MSVC {#build_cpp} To build C++ targets with MSVC, you need: @@ -214,7 +214,7 @@ [Windows command line length limit issue](https://github.com/bazelbuild/bazel/issues/5163), enable the compiler parameter file feature via `--features=compiler_param_file`. -### Build C++ with Clang +### Build C++ with Clang {#clang} From 0.29.0, Bazel supports building with LLVM's MSVC-compatible compiler driver (`clang-cl.exe`). @@ -370,7 +370,7 @@ * Clang is not supported. -### Build Java +### Build Java {#java} To build Java targets, you need: @@ -391,7 +391,7 @@ data-terminal-prefix="C:\projects\bazel> ">bazel-bin\examples\java-native\src\main\java\com\example\<var>myproject</var>\hello-world.exe</code> ``` -### Build Python +### Build Python {#python} To build Python targets, you need:
diff --git a/docs/contribute/breaking-changes.mdx b/docs/contribute/breaking-changes.mdx index 5dda1b9..a05b4b2 100644 --- a/docs/contribute/breaking-changes.mdx +++ b/docs/contribute/breaking-changes.mdx
@@ -24,7 +24,7 @@ 1. [Flip the incompatible flag.](#flip-flag) -## GitHub issue +## GitHub issue {#github-issue} [File a GitHub issue](https://github.com/bazelbuild/bazel/issues) in the Bazel repository. @@ -56,7 +56,7 @@ It is able to apply automated fixes to `BUILD`, `WORKSPACE`, and `.bzl` files. It may also report warnings. -## Implementation +## Implementation {#implementation} Create a new flag in Bazel. The default value must be false. The help text should contain the URL of the GitHub issue. As the flag name starts with @@ -77,7 +77,7 @@ documentation is versioned, changes to the docs will not be inadvertently released prematurely. -## Labels +## Labels {#labels} Once the commit is merged and the incompatible change is ready to be adopted, add the label [`migration-ready`](https://github.com/bazelbuild/bazel/labels/migration-ready) @@ -88,7 +88,7 @@ If you plan to flip the flag in the next major release, add label `breaking-change-X.0" to the issue. -## Updating repositories +## Updating repositories {#update-repos} Bazel CI tests a list of important projects at [Bazel@HEAD + Downstream](https://buildkite.com/bazel/bazel-at-head-plus-downstream). Most of them are often @@ -109,7 +109,7 @@ 1. Reach out to the Bazel community for help on migration (e.g. [Bazel Rules Authors SIG](https://bazel-contrib.github.io/SIG-rules-authors/)). -## Flipping the flag +## Flipping the flag {#flip-flag} Before flipping the default value of the flag to true, please make sure that: @@ -136,7 +136,7 @@ * Review and update documentation if needed. * File a new issue `#abc` to track the removal of the flag. -## Removing the flag +## Removing the flag {#remove-flag} After the flag is flipped at HEAD, it should be removed from Bazel eventually. When you plan to remove the incompatible flag:
diff --git a/docs/contribute/codebase.mdx b/docs/contribute/codebase.mdx index 71ee7a7..e291f16 100644 --- a/docs/contribute/codebase.mdx +++ b/docs/contribute/codebase.mdx
@@ -7,7 +7,7 @@ This document is a description of the codebase and how Bazel is structured. It is intended for people willing to contribute to Bazel, not for end-users. -## Introduction +## Introduction {#introduction} The codebase of Bazel is large (~350KLOC production code and ~260 KLOC test code) and no one is familiar with the whole landscape: everyone knows their @@ -29,7 +29,7 @@ and manually imported by a Googler into the internal source tree, then re-exported back out to GitHub. -## Client/server architecture +## Client/server architecture {#client-architecture} The bulk of Bazel resides in a server process that stays in RAM between builds. This allows Bazel to maintain state between builds. @@ -90,7 +90,7 @@ The main entry point of the server is `BlazeRuntime.main()` and the gRPC calls from the client are handled by `CommandServer.serveAndAwaitTermination()`. -## Directory layout +## Directory layout {#directory-layout} Bazel creates a somewhat complicated set of directories during a build. A full description is available in [Output directory layout](/remote/output-directories). @@ -125,7 +125,7 @@ long term plan because it's a very incompatible change. * Files built during the build. -## The process of executing a command +## The process of executing a command {#command-process} Once the Bazel server gets control and is informed about a command it needs to execute, the following sequence of events happens: @@ -163,7 +163,7 @@ 8. The execution phase is run. This means running every action required to build the top-level targets that are requested are run. -## Command line options +## Command line options {#command-options} The command line options for a Bazel invocation are parsed into an `OptionsParsingResult` object, which holds instances of `OptionsBase` @@ -220,14 +220,14 @@ command line string to the data type falls to an implementation of `com.google.devtools.common.options.Converter`. -## The source tree, as seen by Bazel +## The source tree, as seen by Bazel {#source-tree} Bazel is in the business of building software, which happens by reading and interpreting the source code. The totality of the source code Bazel operates on is called "the workspace" and it is structured into repositories, packages and rules. -### Repositories +### Repositories {#repositories} A "repository" is a source tree on which a developer works; it usually represents a single project. Bazel's ancestor, Blaze, operated on a monorepo, @@ -250,7 +250,7 @@ to `$EXECROOT` and every external repository to either `$EXECROOT/external` or `$EXECROOT/..`. -### Packages +### Packages {#packages} Every repository is composed of packages, a collection of related files and a specification of the dependencies. These are specified by a file called @@ -298,7 +298,7 @@ needs of both. This is unfortunately difficult to do because the two are intertwined quite deeply. -### Labels, Targets, and Rules +### Labels, Targets, and Rules {#labels-targets-rules} Packages are composed of targets, which have the following types: @@ -350,7 +350,7 @@ name, there is no Java inheritance relationship between a rule class and targets of that type. -## Skyframe +## Skyframe {#skyframe} The evaluation framework underlying Bazel is called Skyframe. Its model is that everything that needs to be built during a build is organized into a directed @@ -422,7 +422,7 @@ [virtual_threads]: /contribute/statemachine-guide#epilogue_eventually_removing_callbacks -## Starlark +## Starlark {#starlark} Starlark is the domain-specific language people use to configure and extend Bazel. It's conceived as a restricted subset of Python that has far fewer types, @@ -454,7 +454,7 @@ More information about Starlark is available [here](/rules/language). -## The loading/analysis phase +## The loading/analysis phase {#loading-phase} The loading/analysis phase is where Bazel determines what actions are needed to build a particular rule. Its basic unit is a "configured target", which is, @@ -504,7 +504,7 @@ The algorithm that determines the direct dependencies of a configured target lives in `DependencyResolver.dependentNodeMap()`. -### Configurations +### Configurations {#configurations} Configurations are the "how" of building a target: for what platform, with what command line options, etc. @@ -558,7 +558,7 @@ Configuration transitions can also be implemented in Starlark (documentation [here](/extending/config)) -### Transitive info providers +### Transitive info providers {#transitive-info-providers} Transitive info providers are a way (and the _only _way) for configured targets to learn things about other configured targets that they depend on, and the only @@ -586,7 +586,7 @@ `NativeProvider` is deprecated (we haven't had time to remove it yet) and `TransitiveInfoProvider` subclasses cannot be accessed from Starlark. -### Configured targets +### Configured targets {#configured-targets} Configured targets are implemented as `RuleConfiguredTargetFactory`. There is a subclass for each rule class implemented in Java. Starlark configured targets @@ -603,7 +603,7 @@ build. They can be accessed using the output\_group attribute of the filegroup rule in BUILD and using the `OutputGroupInfo` provider in Java. -### Runfiles +### Runfiles {#runfiles} Some binaries need data files to run. A prominent example is tests that need input files. This is represented in Bazel by the concept of "runfiles". A @@ -648,7 +648,7 @@ * **Command line arguments** for running the binary whose runfiles the `RunfilesSupport` object represents. -### Aspects +### Aspects {#aspects} Aspects are a way to "propagate computation down the dependency graph". They are described for users of Bazel @@ -697,7 +697,7 @@ The complexity of aspects on aspects is captured in the class `AspectCollection`. -### Platforms and toolchains +### Platforms and toolchains {#platforms-toolchains} Bazel supports multi-platform builds, that is, builds where there may be multiple architectures where build actions run and multiple architectures for @@ -776,7 +776,7 @@ Their code is in `PlatformMappingFunction` and uses a non-Starlark "little language". -### Constraints +### Constraints {#constraints} Sometimes one wants to designate a target as being compatible with only a few platforms. Bazel has (unfortunately) multiple mechanisms to achieve this end: @@ -790,7 +790,7 @@ contain references to it. The attribute that governs this is called `constraints=` . -#### environment_group() and environment() +#### environment_group() and environment() {#environment-rule} These rules are a legacy mechanism and are not widely used. @@ -832,14 +832,14 @@ The implementation of the constraint check is in `RuleContextConstraintSemantics` and `TopLevelConstraintSemantics`. -#### Platform constraints +#### Platform constraints {#platform-constraints} The current "official" way to describe what platforms a target is compatible with is by using the same constraints used to describe toolchains and platforms. It was implemented in pull request [#10945](https://github.com/bazelbuild/bazel/pull/10945). -### Visibility +### Visibility {#visibility} If you work on a large codebase with a lot of developers (like at Google), you want to take care to prevent everyone else from arbitrarily depending on your @@ -876,7 +876,7 @@ * The actual check is done in `CommonPrerequisiteValidator.validateDirectPrerequisiteVisibility()` -### Nested sets +### Nested sets {#nested-sets} Oftentimes, a configured target aggregates a set of files from its dependencies, adds its own, and wraps the aggregate set into a transitive info provider so @@ -902,7 +902,7 @@ The same data structure is called `depset` in Starlark. -### Artifacts and Actions +### Artifacts and Actions {#artifacts} The actual build consists of a set of commands that need to be run to produce the output the user wants. The commands are represented as instances of the @@ -966,7 +966,7 @@ action that generates it * Nested sets have their own Skyframe key. -### Shared actions +### Shared actions {#shared-actions} Some actions are generated by multiple configured targets; Starlark rules are more limited since they are only allowed to put their derived actions into a @@ -988,7 +988,7 @@ and is one of the few places in Bazel that requires a "global" view of the build. -## The execution phase +## The execution phase {#execution-phase} This is when Bazel actually starts running build actions, such as commands that produce outputs. @@ -1031,7 +1031,7 @@ * The local action cache contains data about the state of the file system * Remote execution systems usually also contain their own cache -### The local action cache +### The local action cache {#cache} This cache is another layer that sits behind Skyframe; even if an action is re-executed in Skyframe, it can still be a hit in the local action cache. It @@ -1055,7 +1055,7 @@ development, which uses transitive hashes to avoid going to the cache as many times. -### Input discovery and input pruning +### Input discovery and input pruning {#input-discovery} Some actions are more complicated than just having a set of inputs. Changes to the set of inputs of an action come in two forms: @@ -1096,7 +1096,7 @@ using the `unused_inputs_list=` argument of `ctx.actions.run()`. -### Various ways to run actions: Strategies/ActionContexts +### Various ways to run actions: Strategies/ActionContexts {#options-run-actions} Some actions can be run in different ways. For example, a command line can be executed locally, locally but in various kinds of sandboxes, or remotely. The @@ -1144,7 +1144,7 @@ * Information about the intricacies of executing actions locally is available [here](https://jmmv.dev/2019/11/bazel-process-wrapper.html). -### The local resource manager +### The local resource manager {#resource-manager} Bazel _can_ run many actions in parallel. The number of local actions that _should_ be run in parallel differs from action to action: the more resources an @@ -1160,7 +1160,7 @@ A more detailed description of local resource management is available [here](https://jmmv.dev/2019/12/bazel-local-resources.html). -### The structure of the output directory +### The structure of the output directory {#output-directory} Each action requires a separate place in the output directory where it places its outputs. The location of derived artifacts is usually as follows: @@ -1198,7 +1198,7 @@ `OutputDirectories.buildMnemonic()` and relies on each configuration fragment adding its own part to the name of the output directory. -## Tests +## Tests {#tests} Bazel has rich support for running tests. It supports: @@ -1219,7 +1219,7 @@ * The number of shards the test should be split into * Some parameters about how the test should be run (such as the test timeout) -### Determining which tests to run +### Determining which tests to run {#determine-test-run} Determining which tests are run is an elaborate process. @@ -1248,7 +1248,7 @@ unfortunately a reimplementation, so it probably deviates from the above in multiple subtle ways. -### Running tests +### Running tests {#run-tests} The way the tests are run is by requesting cache status artifacts. This then results in the execution of a `TestRunnerAction`, which eventually calls the @@ -1297,7 +1297,7 @@ They are dumped to the Build Event Protocol and they are emitted to the console by `AggregatingTestListener`. -### Coverage collection +### Coverage collection {#coverage-collection} Coverage is reported by the tests in LCOV format in the files `bazel-testlogs/$PACKAGE/$TARGET/coverage.dat` . @@ -1366,7 +1366,7 @@ gets access to the tools it needs by looking at the `:coverage_report_generator` attribute of the first test that is executed. -## The query engine +## The query engine {#query-engine} Bazel has a [little language](/query/guide) @@ -1396,7 +1396,7 @@ information to the rule with that label. It's not a very satisfying workaround and it would be very nice to lift this requirement. -## The module system +## The module system {#module-system} Bazel can be extended by adding modules to it. Each module must subclass `BlazeModule` (the name is a relic of the history of Bazel when it used to be @@ -1412,7 +1412,7 @@ The set of extension points `BlazeModule` offers is somewhat haphazard. Don't use it as an example of good design principles. -## The event bus +## The event bus {#event-bus} The main way BlazeModules communicate with the rest of Bazel is by an event bus (`EventBus`): a new instance is created for every build, various parts of Bazel @@ -1436,7 +1436,7 @@ This is implemented in the `build.lib.buildeventservice` and `build.lib.buildeventstream` Java packages. -## External repositories +## External repositories {#external-repos} Note: The information in this section is out of date, as code in this area has undergone extensive change in the past couple of years. Please refer to @@ -1449,7 +1449,7 @@ bridge these two worlds: they represent code that is necessary for the build but is not in the main source tree. -### The WORKSPACE file +### The WORKSPACE file {#workspace-file} The set of external repositories is determined by parsing the WORKSPACE file. For example, a declaration like this: @@ -1469,7 +1469,7 @@ computing `WorkspaceFileFunction` until index X means evaluating it until the Xth `load()` statement. -### Fetching repositories +### Fetching repositories {#fetch-repos} Before the code of the repository is available to Bazel, it needs to be _fetched_. This results in Bazel creating a directory under @@ -1514,7 +1514,7 @@ `FileStateValue`s for an artifact in an external repository need to depend on their external repository. This is handled by `ExternalFilesHelper`. -### Repository mappings +### Repository mappings {#repo-mappings} It can happen that multiple repositories want to depend on the same repository, but in different versions (this is an instance of the "diamond dependency @@ -1543,7 +1543,7 @@ phase) * `BzlLoadFunction` for resolving labels in load() statements -## JNI bits +## JNI bits {#jni-bits} The server of Bazel is _mostly_ written in Java. The exception is the parts that Java cannot do by itself or couldn't do by itself when we implemented it. This @@ -1558,7 +1558,7 @@ * `WindowsFileOperations` and `WindowsFileProcesses` * `com.google.devtools.build.lib.platform` -## Console output +## Console output {#console-output} Emitting console output seems like a simple thing, but the confluence of running multiple processes (sometimes remotely), fine-grained caching, the desire to @@ -1611,7 +1611,7 @@ which allows direct access to these streams. It's only used when a command needs to dump large amounts of possible binary data (such as `bazel query`). -## Profiling Bazel +## Profiling Bazel {#profile-bazel} Bazel is fast. Bazel is also slow, because builds tend to grow until just the edge of what's bearable. For this reason, Bazel includes a profiler which can be @@ -1636,7 +1636,7 @@ We also do rudimentary memory profiling in `MemoryProfiler`. It's also always on and it mostly records maximum heap sizes and GC behavior. -## Testing Bazel +## Testing Bazel {#bazel-tests} Bazel has two main kinds of tests: ones that observe Bazel as a "black box" and ones that only run the analysis phase. We call the former "integration tests"
diff --git a/docs/contribute/design-documents.mdx b/docs/contribute/design-documents.mdx index 40b40bd..b757de1 100644 --- a/docs/contribute/design-documents.mdx +++ b/docs/contribute/design-documents.mdx
@@ -22,7 +22,7 @@ * Changes to widely used internal APIs * Changes to flags and command-line interface. -## Reasons for design reviews +## Reasons for design reviews {#design-reviews} When you write a design document, you can coordinate with other Bazel developers and seek guidance from Bazel's core team. For example, when a proposal adds, @@ -55,12 +55,12 @@ and *not* the ongoing changes as designs are implemented. Always go to the documentation for descriptions of current Bazel functionality. -## Contributor Workflow +## Contributor Workflow {#contributor-workflow} As a contributor, you can write a design document, send pull requests and request reviewers for your proposal. -### Write the design document +### Write the design document {#write-design-doc} All design documents must have a header that includes: @@ -79,7 +79,7 @@ Proposals that have a user-visible impact must have a section documenting the impact on backward compatibility (and a rollout plan if needed). -### Create a Pull Request +### Create a Pull Request {#pull-request} Share your design doc by creating a pull request (PR) to add the document to [the design index](https://github.com/bazelbuild/proposals). Add @@ -96,7 +96,7 @@ or will be approved; it means that the proposal contains enough information to start the discussion. -### Announce the new proposal +### Announce the new proposal {#new-proposal} Send an announcement to [bazel-dev](https://groups.google.com/forum/#!forum/bazel-dev) when @@ -106,7 +106,7 @@ [bazel-discuss](https://groups.google.com/forum/#!forum/bazel-discuss), to get feedback from Bazel end-users). -### Iterate with reviewers +### Iterate with reviewers {#reviewers} Anyone interested can comment on your proposal. Try to answer questions, clarify the proposal, and address concerns. @@ -115,7 +115,7 @@ Google Doc, comments may be used instead (Note that anonymous comments are allowed). -### Update the status +### Update the status {#update-status} Create a new PR to update the status of the proposal, when iteration is complete. Send the PR to the same lead reviewer and cc the other reviewers. @@ -131,7 +131,7 @@ proof-of-concept or an experimentation. However, you cannot submit the change before the review is complete. -### Choosing a lead reviewer +### Choosing a lead reviewer {#lead-reviewer} A lead reviewer should be a domain expert who is: @@ -142,7 +142,7 @@ Consider checking the contacts for various [team labels](/contribute/maintainers-guide#team-labels). -## Markdown vs Google Docs +## Markdown vs Google Docs {#markdown-versus-gdocs} Decide what works best for you, since both are accepted. @@ -168,7 +168,7 @@ You can choose to first iterate on a Google Doc, and then convert it to Markdown for posterity. -### Using Google Docs +### Using Google Docs {#gdocs} For consistency, use the [Bazel design doc template]( https://docs.google.com/document/d/1cE5zrjrR40RXNg64XtRFewSv6FrLV6slGkkqxBumS1w/template/preview). @@ -180,7 +180,7 @@ choose "On - Anyone with the link". If you allow comments on the document, anyone can comment anonymously, even without a Google account. -### Using Markdown +### Using Markdown {#markdown} Documents are stored on GitHub and use the [GitHub flavor of Markdown](https://guides.github.com/features/mastering-markdown/) @@ -190,16 +190,16 @@ reviewed by the document reviewers. Trivial changes (such as typos, formatting) can be approved by anyone. -## Reviewer workflow +## Reviewer workflow {#reviewer-workflow} A reviewer comments, reviews and approves design documents. -### General reviewer responsibilities +### General reviewer responsibilities {#reviewer-responsibilities} You're responsible for reviewing design documents, asking for additional information if needed, and approving a design that passes the review process. -#### When you receive a new proposal +#### When you receive a new proposal {#receive-new-proposal} 1. Take a quick look at the document. 1. Comment if critical information is missing, or if the design doesn't fit @@ -207,7 +207,7 @@ 1. Suggest additional reviewers. 1. Approve the PR when it is ready for review. -#### During the review process +#### During the review process {#during-review-process} 1. Engage in a dialogue with the design author about issues that are problematic or require clarification. @@ -222,28 +222,28 @@ affecting Bazel if they are not in the [design index](https://github.com/bazelbuild/proposals). -### Lead reviewer responsibilities +### Lead reviewer responsibilities {#lead-reviewer-responsibilities} You're responsible for making the go / no-go decision on implementation of a pending design. If you're not able to do this, you should identify a suitable delegate (reassign the PR to the delegate), or reassign the bug to a Bazel manager for further disposition. -#### During the review process +#### During the review process {#during-process} 1. Ensure that the comment and design iteration process moves forward constructively. 1. Prior to approval, ensure that concerns from other reviewers have been resolved. -#### After approval by all reviewers +#### After approval by all reviewers {#after-approval} 1. Make sure there has been at least 1 week since the announcement on the mailing list. 1. Make sure the PR updates the status. 1. Approve the PR sent by the proposal author. -#### Rejecting designs +#### Rejecting designs {#reject-designs} 1. Make sure the PR author sends a PR; or send them a PR. 1. The PR updates the status of the document.
diff --git a/docs/contribute/docs-style-guide.mdx b/docs/contribute/docs-style-guide.mdx index f50c9eb..a9867b0 100644 --- a/docs/contribute/docs-style-guide.mdx +++ b/docs/contribute/docs-style-guide.mdx
@@ -9,7 +9,7 @@ answered by this guide, follow the [Google developer documentation style guide](https://developers.google.com/style). -## Defining principles +## Defining principles {#principles} Bazel docs should uphold these principles: @@ -21,11 +21,11 @@ - **Correct.** Write in a way where the content stays correct for as long as possible by avoiding time-based information and promises for the future. -## Writing +## Writing {#writing-tips} This section contains basic writing tips. -### Headings +### Headings {#headings} - Page-level headings start at H2. (H1 headings are used as page titles.) - Make headers as short as is sensible. This way, they fit in the TOC @@ -45,7 +45,7 @@ - <span class="compare-better">Yes</span>: Preserving graph order - <span class="compare-worse">No</span>: On the preservation of graph order -### Names +### Names {#names} - Capitalize proper nouns, such as Bazel and Starlark. @@ -59,7 +59,7 @@ - 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 @@ 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 @@ - <span class="compare-worse">No</span>: 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 @@ - <span class="compare-worse">No</span>: 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 @@ - <span class="compare-worse">No</span>: 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 @@ - 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 +## Formatting {#format} -### 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 @@ [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 @@ - <span class="compare-better">Yes</span>: For more details, see [link]. - <span class="compare-worse">No</span>: 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 @@ 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: `\<example\>`. @@ -181,11 +181,11 @@ - Especially for complicated code samples, use placeholders that make sense in context. -### Table of contents +### Table of contents {#toc} 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 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 @@ - Separate commands and output into different code blocks. -### Inline code formatting +### Inline code formatting {#code-format} - 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/docs/contribute/index.mdx b/docs/contribute/index.mdx index ee66772..da2cd1b 100644 --- a/docs/contribute/index.mdx +++ b/docs/contribute/index.mdx
@@ -6,7 +6,7 @@ There are many ways to help the Bazel project and ecosystem. -## Provide feedback +## Provide feedback {#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) @@ -19,7 +19,7 @@ link at the top right corner of the page. - An error message could be improved. -## Participate in the community +## Participate in the community {#community} You can engage with the Bazel community by: @@ -30,7 +30,7 @@ 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. @@ -54,7 +54,7 @@ To learn about how to submit a change, see the [patch acceptance process](/contribute/patch-acceptance). -## Bazel's code description +## Bazel's code description {#code-description} Bazel has a large codebase with code in multiple locations. See the [codebase guide](/contribute/codebase) for more details. @@ -73,7 +73,7 @@ [compiling Bazel](/install/compile-source) section. -### Searching Bazel's source code +### Searching Bazel's source code {#search-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/docs/contribute/maintainers-guide.mdx b/docs/contribute/maintainers-guide.mdx index 30cf978..28f7c47 100644 --- a/docs/contribute/maintainers-guide.mdx +++ b/docs/contribute/maintainers-guide.mdx
@@ -24,18 +24,18 @@ * **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 +## Continuous Integration {#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 of an Issue {#lifecycle-issue} 1. A user creates an issue by choosing one of the [issue templates](https://github.com/bazelbuild/bazel/issues/new/choose) @@ -78,7 +78,7 @@ When an issue is resolved, it can be closed. -## Lifecycle of a Pull Request +## Lifecycle of a Pull Request {#lifecycle-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, @@ -98,12 +98,12 @@ 1. When the commit merges into master, GitHub automatically closes the PR. -## My team owns a label. What should I do? +## My team owns a label. What should I do? {#label-own} 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. @@ -117,7 +117,7 @@ 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 @@ -158,7 +158,7 @@ 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. @@ -187,7 +187,7 @@ 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/docs/contribute/naming.mdx b/docs/contribute/naming.mdx index 144b08a..92eb935 100644 --- a/docs/contribute/naming.mdx +++ b/docs/contribute/naming.mdx
@@ -12,12 +12,12 @@ 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 +## Naming Starlark rules {#name-starlark-rules} See [Deploying new Starlark rules](/rules/deploying) in the docs. -## Naming other Bazel related tools +## Naming other Bazel related tools {#name-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/docs/contribute/policy.mdx b/docs/contribute/policy.mdx index 1bf0029..557955f 100644 --- a/docs/contribute/policy.mdx +++ b/docs/contribute/policy.mdx
@@ -48,7 +48,7 @@ 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/docs/contribute/release-notes.mdx b/docs/contribute/release-notes.mdx index 83e1d75..61973e7 100644 --- a/docs/contribute/release-notes.mdx +++ b/docs/contribute/release-notes.mdx
@@ -10,7 +10,7 @@ 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. @@ -21,7 +21,7 @@ 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 @@ -60,7 +60,7 @@ 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),
diff --git a/docs/contribute/search.mdx b/docs/contribute/search.mdx index 43c9075..7bbea56 100644 --- a/docs/contribute/search.mdx +++ b/docs/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 @@ 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, 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 @@ 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 @@ * 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 @@ * 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 @@ 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 @@ 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 @@ 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 @@ 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 @@ 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 @@ 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 +## Searching for code {#search} 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 @@ </tbody> </table> -## 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/docs/contribute/statemachine-guide.mdx b/docs/contribute/statemachine-guide.mdx index e98a96e..69f2187 100644 --- a/docs/contribute/statemachine-guide.mdx +++ b/docs/contribute/statemachine-guide.mdx
@@ -52,7 +52,7 @@ `SkyKeyComputeState` does not fall out of cache) by exposing suspend and resume execution hooks. -### Stateful computations inside `SkyKeyComputeState` +### Stateful computations inside `SkyKeyComputeState` {#stateful-computations} 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 @@ 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 @@ -261,7 +261,7 @@ 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 @@ -386,7 +386,7 @@ } ``` -#### `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* @@ -551,7 +551,7 @@ 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. @@ -672,7 +672,7 @@ lambda-based implementations or full inner-class instances that implement the appropriate callbacks is viable. -### Propagating values between `StateMachine`s +### Propagating values between `StateMachine`s {#propagating-values} 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 @@ -779,7 +779,7 @@ 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 @@ -791,7 +791,7 @@ The next section describes a a subtle, but important interaction with Skyframe error handling. -#### Error bubbling (--nokeep\_going) +#### Error bubbling (--nokeep\_going) {#error-bubbling} Warning: Errors need to be eagerly propagated all the way back to the SkyFunction for error bubbling to function correctly. @@ -814,7 +814,7 @@ 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 @@ -823,7 +823,7 @@ `StoredEventHandler` injection is preserved because it simplifies the implementation of events emitted from error handling callbacks. -## `Driver`s and bridging to SkyFunctions +## `Driver`s and bridging to SkyFunctions {#drivers-and-bridging} A `Driver` is responsible for managing the execution of `StateMachine`s, beginning with a specified root `StateMachine`. As `StateMachine`s can @@ -938,7 +938,7 @@ } ``` -### 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. @@ -1061,7 +1061,7 @@ ## 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 @@ -1114,7 +1114,7 @@ pattern is used too densely, but this can be avoided by interspersing injections with sequential steps. -#### Example: Chained SkyValue lookups +#### Example: Chained SkyValue lookups {#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. @@ -1207,7 +1207,7 @@ `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.
diff --git a/docs/contribute/windows-chocolatey-maintenance.mdx b/docs/contribute/windows-chocolatey-maintenance.mdx index c6aee8f..d961d47 100644 --- a/docs/contribute/windows-chocolatey-maintenance.mdx +++ b/docs/contribute/windows-chocolatey-maintenance.mdx
@@ -7,7 +7,7 @@ Note: The Chocolatey package is experimental; please provide feedback (`@petemounce` in issue tracker). -## Prerequisites +## Prerequisites {#prerequisites} You need: @@ -19,7 +19,7 @@ * (to publish) to have set up that API key for the chocolatey source locally via `choco apikey -k <your key here> -s https://chocolatey.org/` -## Build +## Build {#build} Compile bazel with msys2 shell and `compile.sh`. @@ -34,7 +34,7 @@ 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 @@ 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/docs/contribute/windows-scoop-maintenance.mdx b/docs/contribute/windows-scoop-maintenance.mdx index 58e2a6c..eb607de 100644 --- a/docs/contribute/windows-scoop-maintenance.mdx +++ b/docs/contribute/windows-scoop-maintenance.mdx
@@ -7,7 +7,7 @@ Note: The Scoop package is experimental. To provide feedback, go to `@excitoon` in issue tracker. -## Prerequisites +## Prerequisites {#prerequisites} You need: @@ -19,7 +19,7 @@ [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/docs/android-build-performance.mdx b/docs/docs/android-build-performance.mdx index 0d5edc7..e94f77e 100644 --- a/docs/docs/android-build-performance.mdx +++ b/docs/docs/android-build-performance.mdx
@@ -8,7 +8,7 @@ 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/docs/android-instrumentation-test.mdx b/docs/docs/android-instrumentation-test.mdx index 14d95bd..82fb7b1 100644 --- a/docs/docs/android-instrumentation-test.mdx +++ b/docs/docs/android-instrumentation-test.mdx
@@ -26,7 +26,7 @@ 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: @@ -43,7 +43,7 @@ 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: @@ -107,7 +107,7 @@ 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`: @@ -116,7 +116,7 @@ **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: @@ -209,7 +209,7 @@ </manifest> ``` -### WORKSPACE dependencies +### WORKSPACE dependencies {#workspace-dependencies} In order to use this rule, your project needs to depend on these external repositories: @@ -242,7 +242,7 @@ 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), @@ -252,7 +252,7 @@ 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 +## Choosing an android_device target {#android-device-target} `android_instrumentation_test.target_device` specifies which Android device to run the tests on. These `android_device` targets are defined in @@ -307,7 +307,7 @@ 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 `<var>project root</var>:<var>/.bazelrc` file. @@ -342,7 +342,7 @@ 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 @@ -352,7 +352,7 @@ 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 @@ -362,7 +362,7 @@ bazel test //my/test:target --test_arg=--enable_display=true --test_env=DISPLAY ``` -### Testing with a local emulator or device +### Testing with a local emulator or device {#testing-local-emulator} Bazel also supports testing directly on a locally launched emulator or connected device. Pass the flags @@ -372,13 +372,13 @@ `--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) 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 @@ -460,9 +460,9 @@ ) ``` -## 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 @@ -530,7 +530,7 @@ 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 @@ -542,7 +542,7 @@ ls -1t /tmp/emulator_*.log | head -n 1 ``` -### Testing against multiple API levels +### Testing against multiple API levels {#testing-multiple-apis} 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: @@ -562,7 +562,7 @@ ) 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)
diff --git a/docs/docs/android-ndk.mdx b/docs/docs/android-ndk.mdx index 00b7316..363b362 100644 --- a/docs/docs/android-ndk.mdx +++ b/docs/docs/android-ndk.mdx
@@ -7,7 +7,7 @@ _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 @@ -22,11 +22,11 @@ [`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 and SDK setup {#ndk-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+.* @@ -35,7 +35,7 @@ If you are using one dependency management solution, you don't need to add the boilerplate for the other. -#### Bzlmod MODULE.bazel setup +#### Bzlmod MODULE.bazel setup {#ndk-sdk-setup-bzlmod} Add the following snippet to your MODULE.bazel: @@ -57,7 +57,7 @@ register_toolchains("@androidsdk//:sdk-toolchain", "@androidsdk//:all") ``` -#### Legacy WORKSPACE setup +#### Legacy WORKSPACE setup {#ndk-sdk-setup-workspace} Add the following snippet to your `WORKSPACE`: @@ -85,7 +85,7 @@ 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. @@ -155,7 +155,7 @@ 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). @@ -209,7 +209,7 @@ 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 the target ABI {#configuring-target-abi} To configure the target ABI, use the `--android_platforms` flag as follows: @@ -265,7 +265,7 @@ 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 a C++ standard {#selecting-c-standard} Use the following flags to build according to a C++ standard: @@ -297,7 +297,7 @@ ) ``` -## Building a `cc_library` for Android without using `android_binary` +## Building a `cc_library` for Android without using `android_binary` {#cclibrary-android} To build a standalone `cc_binary` or `cc_library` for Android without using an `android_binary`, use the `--platforms` flag.
diff --git a/docs/docs/bazel-and-android.mdx b/docs/docs/bazel-and-android.mdx index bf3625c..fcb65e5 100644 --- a/docs/docs/bazel-and-android.mdx +++ b/docs/docs/bazel-and-android.mdx
@@ -8,7 +8,7 @@ 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: @@ -18,7 +18,7 @@ * [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 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/docs/bazel-and-apple.mdx b/docs/docs/bazel-and-apple.mdx index 6e4a06f..3024f4e 100644 --- a/docs/docs/bazel-and-apple.mdx +++ b/docs/docs/bazel-and-apple.mdx
@@ -8,7 +8,7 @@ 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 @@ * [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 and new rules {#apple-apps-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 @@ * [`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/docs/bazel-and-cpp.mdx b/docs/docs/bazel-and-cpp.mdx index 73e502c..ee12316 100644 --- a/docs/docs/bazel-and-cpp.mdx +++ b/docs/docs/bazel-and-cpp.mdx
@@ -8,7 +8,7 @@ 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 @@ * [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 @@ ) ``` -### Include paths +### Include paths {#include-paths} Follow these guidelines for include paths: @@ -82,7 +82,7 @@ [`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/docs/bazel-and-java.mdx b/docs/docs/bazel-and-java.mdx index bd5af01..cc45680 100644 --- a/docs/docs/bazel-and-java.mdx +++ b/docs/docs/bazel-and-java.mdx
@@ -8,21 +8,21 @@ 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 @@ * 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 +### Configuring the version of the source code in your repository {#config-source-code} 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 @@ 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 +### Configuring the JVM used to execute and test the code {#config-jvm} Bazel uses one JDK for compilation and another JVM to execute and test the code. @@ -55,14 +55,14 @@ 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 and compilation {#hermetic-testing} 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 +### Configuring compilation and execution of build tools in Java {#config-build-tools-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 @@ `--tool_java_runtime_version`. Default values are `11` and `remotejdk_11`, respectively. -#### Compiling using locally installed JDK +#### Compiling using locally installed JDK {#compile-using-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 @@ 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 @@ * Tests should be in a matching directory under `src/test` and depend on this library. -## Creating new rules for advanced Java builds +## Creating new rules for advanced Java builds {#rules-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 @@ * [`JavaRuntimeInfo`](/rules/lib/providers/JavaRuntimeInfo) * [`JavaToolchainInfo`](/rules/lib/providers/JavaToolchainInfo) -## Configuring the Java toolchains +## Configuring the Java toolchains {#config-java-toolchains} Bazel uses two types of Java toolchains: @@ -150,7 +150,7 @@ * compilation, used to compile Java sources, controlled with the `--java_language_version` flag -### Configuring additional execution toolchains +### Configuring additional execution toolchains {#config-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 @@ register_toolchains("@openjdk_canary_linux_arm_toolchain_config_repo//:all") ``` -### Configuring additional compilation toolchains +### Configuring additional compilation toolchains {#config-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 @@ built from sources (this may be useful on operating system with different libc) -#### Configuring JVM and Java compiler flags +#### Configuring JVM and Java compiler flags {#config-jvm-flags} You may configure JVM and javac flags either with flags or with `default_java_toolchain` attributes. @@ -290,7 +290,7 @@ The relevant `default_java_toolchain` attributes are `javacopts`, `jvm_opts`, `javabuilder_jvm_opts`, and `turbine_jvm_opts`. -#### Package specific Java compiler flags configuration +#### Package specific Java compiler flags configuration {#package-java-compiler-flags} You can configure different Java compiler flags for specific source files using `package_configuration` attribute of `default_java_toolchain`. @@ -327,7 +327,7 @@ ) ``` -#### Multiple versions of Java source code in a single repository +#### Multiple versions of Java source code in a single repository {#java-source-single-repo} 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/docs/cc-toolchain-config-reference.mdx b/docs/docs/cc-toolchain-config-reference.mdx index 4a36d6d..dade7b6 100644 --- a/docs/docs/cc-toolchain-config-reference.mdx +++ b/docs/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 @@ 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 @@ 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 @@ 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 @@ -209,7 +209,7 @@ </tr> </table> -## 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,7 +230,7 @@ "assembler actions" and "compiler actions" in the table below are `CppCompileAction`, while the link actions are `CppLinkAction`. -### Assembler actions +### Assembler actions {#assembler-actions} <table> <col width="300" /> @@ -249,7 +249,7 @@ </tr> </table> -### Compiler actions +### Compiler actions {#compiler-actions} <table> <col width="300" /> @@ -280,7 +280,7 @@ </tr> </table> -### Link actions +### Link actions {#link-actions} <table> <col width="300" /> @@ -303,7 +303,7 @@ </tr> </table> -### 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. @@ -321,7 +321,7 @@ </tr> </table> -### LTO actions +### LTO actions {#lto-actions} <table> <col width="300" /> @@ -340,7 +340,7 @@ </tr> </table> -## 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 @@ -404,7 +404,7 @@ 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: @@ -439,7 +439,7 @@ 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 +531,7 @@ ), ] -### 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 @@ -602,7 +602,7 @@ ], ) -### 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 +634,12 @@ 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. @@ -922,7 +922,7 @@ </tr> </table> -### Well-known features +### Well-known features {#wellknown-features} The following is a reference of features and their activation conditions. @@ -1016,7 +1016,7 @@ </tr> </table> -#### Legacy features patching logic +#### Legacy features patching logic {#legacy-features-patching-logic} <p> Bazel applies the following changes to the toolchain's features for backwards
diff --git a/docs/docs/configurable-attributes.mdx b/docs/docs/configurable-attributes.mdx index 367317f..075431b 100644 --- a/docs/docs/configurable-attributes.mdx +++ b/docs/docs/configurable-attributes.mdx
@@ -12,7 +12,7 @@ chooses the appropriate implementation for the architecture, or for a feature-configurable binary that can be customized at build time. -## Example +## Example {#configurable-build-example} ```python # myapp/BUILD @@ -88,7 +88,7 @@ `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 @@ -144,7 +144,7 @@ `--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 @@ -156,7 +156,7 @@ `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 @@ -190,7 +190,7 @@ 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 @@ -226,7 +226,7 @@ `values`, `flag_values`, and `define_values` evaluate independently. The `config_setting` matches if all values across all of them match. -## The default condition +## The default condition {#default-condition} The built-in condition `//conditions:default` matches when no other condition matches. @@ -262,7 +262,7 @@ 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 @@ -364,7 +364,7 @@ Platforms are still under development. See the [documentation](/concepts/platforms) for details. -## Combining `select()`s +## Combining `select()`s {#combining-selects} `select` can appear multiple times in the same attribute: @@ -413,7 +413,7 @@ 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: @@ -456,7 +456,7 @@ 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) @@ -479,7 +479,7 @@ ) ``` -### `selects.config_setting_group` +### `selects.config_setting_group` {#selects-config-setting-or-group} The @@ -522,7 +522,7 @@ 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 @@ -554,7 +554,7 @@ 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: @@ -589,7 +589,7 @@ 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: @@ -637,7 +637,7 @@ technically feasible, lack a coherent UI. Further design is necessary to change this. -## Bazel query and cquery +## Bazel query and cquery {#query-and-cquery} Bazel [`query`](/query/guide) operates over Bazel's [loading phase](/reference/glossary#loading-phase). @@ -698,9 +698,9 @@ //myapp:bar_dep ``` -## FAQ +## FAQ {#faq} -### Why doesn't select() work in macros? +### Why doesn't select() work in macros? {#faq-select-macro} select() *does* work in rules! See [Rules compatibility](#rules-compatibility) for details. @@ -812,7 +812,7 @@ 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? +### Why does select() always return true? {#faq-boolean-select} Because *macros* (but not rules) by definition [can't evaluate `select()`s](#faq-select-macro), any attempt to do so @@ -858,7 +858,7 @@ standards, all objects aside from a very small number of exceptions automatically return true. -### Can I read select() like a dict? +### Can I read select() like a dict? {#faq-inspectable-select} 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 @@ -914,7 +914,7 @@ ) ``` -### Why doesn't select() work with bind()? +### Why doesn't select() work with bind()? {#faq-select-bind} First of all, do not use `bind()`. It is deprecated in favor of `alias()`. @@ -963,7 +963,7 @@ But really, stop using `bind()`. -### Why doesn't my select() choose what I expect? +### Why doesn't my select() choose what I expect? {#faq-select-choose-condition} If `//myapp:foo` has a `select()` that doesn't choose the condition you expect, use [cquery](/query/cquery) and `bazel config` to debug: @@ -1014,7 +1014,7 @@ 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? +### Why doesn't `select()` work with platforms? {#faq-select-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/docs/mobile-install.mdx b/docs/docs/mobile-install.mdx index 8bc4a67..5039aa7 100644 --- a/docs/docs/mobile-install.mdx +++ b/docs/docs/mobile-install.mdx
@@ -11,7 +11,7 @@ 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 @@ 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 @@ 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 with traditional app installation {#problems-app-install} Building an Android app has some issues, including: @@ -73,7 +73,7 @@ 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` +## The approach of `bazel mobile-install` {#approach-mobile-install} `bazel mobile-install `makes the following improvements: @@ -94,7 +94,7 @@ 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 @@ 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 @@ 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 @@ 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 @@ flags inform Bazel where the Starlark mobile-install aspect is and which rules are supported. -### A brief history of mobile-install +### A brief history of mobile-install {#mobile-install-history} 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/docs/sandboxing.mdx b/docs/docs/sandboxing.mdx index 6869795..e5d006f 100644 --- a/docs/docs/sandboxing.mdx +++ b/docs/docs/sandboxing.mdx
@@ -28,7 +28,7 @@ containers on Linux and `sandbox-exec` on macOS, to constrain the action within `execroot/`. -## Reasons for sandboxing +## Reasons for sandboxing {#sandboxing-reasons} - 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,7 +47,7 @@ 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 +## What sandbox strategy to use {#sandboxing-strategies} You can choose which kind of sandboxing to use, if any, with the [strategy flags](user-manual.html#strategy-options). Using the `sandboxed` @@ -100,7 +100,7 @@ pass the `--experimental_local_lockfree_output` flag. Dynamic execution silently sandboxes [persistent workers](/remote/persistent). -## Downsides to sandboxing +## Downsides to sandboxing {#sandboxing_downsides} - 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 @@ 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 @@ sudo sysctl kernel.unprivileged_userns_clone=1 ``` -### Rule execution failures +### Rule execution failures {#rule-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 +### Detailed debugging for build failures {#debugging-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/docs/user-manual.mdx b/docs/docs/user-manual.mdx index 3457e11..95e9595 100644 --- a/docs/docs/user-manual.mdx +++ b/docs/docs/user-manual.mdx
@@ -6,13 +6,13 @@ 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 +## Options {#build-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 @@ 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 @@ % bazel build --package_path /some/other/path //foo </pre> -#### `--deleted_packages` +#### `--deleted_packages` {#flag--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 @@ 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` +#### `--[no]check_visibility` {#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=<var>regex</var>` +#### `--output_filter=<var>regex</var>` {#output-filter} The `--output_filter` option will only show build and compilation warnings for targets that match the regular expression. If a target does not @@ -124,11 +124,11 @@ </tr> </table> -### Tool flags +### Tool flags {#tool-flags} These options control which options Bazel will pass to other tools. -#### `--copt=<var>cc-option</var>` +#### `--copt=<var>cc-option</var>` {#copt} 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 +157,35 @@ effect at link time (such as `-l`) should be specified in `--linkopt`, not in `--copt`. -#### `--host_copt=<var>cc-option</var>` +#### `--host_copt=<var>cc-option</var>` {#host-copt} 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=<var>cc-option</var>` +#### `--host_conlyopt=<var>cc-option</var>` {#host-conlyopt} 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=<var>cc-option</var>` +#### `--host_cxxopt=<var>cc-option</var>` {#host-cxxopt} 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=<var>linker-option</var>` +#### `--host_linkopt=<var>linker-option</var>` {#host-linkopt} 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=<var>cc-option</var>` +#### `--conlyopt=<var>cc-option</var>` {#cconlyopt} This option takes an argument which is to be passed to the compiler when compiling C source files. @@ -196,7 +196,7 @@ Note: copts parameters listed in specific cc_library or cc_binary build rules are placed on the compiler command line _after_ these options. -#### `--cxxopt=<var>cc-option</var>` +#### `--cxxopt=<var>cc-option</var>` {#cxxopt} This option takes an argument which is to be passed to the compiler when compiling C++ source files. @@ -214,7 +214,7 @@ Note: copts parameters listed in specific cc_library or cc_binary build rules are placed on the compiler command line _after_ these options. -#### `--linkopt=<var>linker-option</var>` +#### `--linkopt=<var>linker-option</var>` {#linkopt} This option takes an argument which is to be passed to the compiler when linking. @@ -231,7 +231,7 @@ settings always take precedence. Also see [cc_library.linkopts](/reference/be/c-cpp#cc_library.linkopts). -#### `--strip (always|never|sometimes)` +#### `--strip (always|never|sometimes)` {#strip} 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 +264,7 @@ `--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=<var>strip-option</var>` +#### `--stripopt=<var>strip-option</var>` {#stripopt} 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 +273,7 @@ Note: `--stripopt` does not apply to the stripping of the main binary with `[--strip](#flag--strip)=(always|sometimes)`. -#### `--fdo_instrument=<var>profile-output-dir</var>` +#### `--fdo_instrument=<var>profile-output-dir</var>` {#fdo-instrument} The `--fdo_instrument` option enables the generation of FDO (feedback directed optimization) profile output when the @@ -292,7 +292,7 @@ The options `--fdo_instrument` and `--fdo_optimize` cannot be used at the same time. -#### `--fdo_optimize=<var>profile-zip</var>` +#### `--fdo_optimize=<var>profile-zip</var>` {#fdo-optimize} The `--fdo_optimize` option enables the use of the per-object file profile information to perform FDO (feedback @@ -313,7 +313,7 @@ The options `--fdo_instrument` and `--fdo_optimize` cannot be used at the same time. -#### `--java_language_version=<var>version</var>` +#### `--java_language_version=<var>version</var>` {#java-language-version} This option specifies the version of Java sources. For example: @@ -326,12 +326,12 @@ 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=<var>version</var>` +#### `--tool_java_language_version=<var>version</var>` {#tool-java-language-version} The Java language version used to build tools that are executed during a build. Default value is 11. -#### `--java_runtime_version=<var>version</var>` +#### `--java_runtime_version=<var>version</var>` {#java-runtime-version} This option specifies the version of JVM to use to execute the code and run the tests. For example: @@ -348,12 +348,12 @@ You can extend the values by registering custom JVM using either `local_java_repository` or `remote_java_repository` repository rules. -#### `--tool_java_runtime_version=<var>version</var>` +#### `--tool_java_runtime_version=<var>version</var>` {#tool-java-runtime-version} The version of JVM used to execute tools that are needed during a build. Default value is `remotejdk_11`. -#### `--jvmopt=<var>jvm-option</var>` +#### `--jvmopt=<var>jvm-option</var>` {#jvmopt} 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 +365,7 @@ will use the server VM for launching all Java binaries and set the startup heap size for the VM to 256 MB. -#### `--javacopt=<var>javac-option</var>` +#### `--javacopt=<var>javac-option</var>` {#javacopt} 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 +390,7 @@ 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 (default|strict|off|warn|error)` {#strict-java-deps} This option controls whether javac checks for missing direct dependencies. Java targets must explicitly declare all directly used targets as @@ -406,11 +406,11 @@ 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 (fastbuild|opt|dbg)` (-c) {#compilation-mode} The `--compilation_mode` option (often shortened to `-c`, especially `-c opt`) takes an argument of `fastbuild`, `dbg` @@ -431,7 +431,7 @@ Debugging information will not be generated in `opt` mode unless you also pass `--copt -g`. -#### `--cpu=<var>cpu</var>` +#### `--cpu=<var>cpu</var>` {#cpu} This option specifies the target CPU architecture to be used for the compilation of binaries during the build. @@ -440,7 +440,7 @@ and target CPU is allowed only if it has been specified in the currently used CROSSTOOL file. -#### `--action_env=<var>VAR=VALUE</var>` +#### `--action_env=<var>VAR=VALUE</var>` {#action-env} 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 +450,7 @@ 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=<var>label</var>` +#### `--experimental_action_listener=<var>label</var>` {#experimental-action-listener} Warning: Extra actions are deprecated. Use [aspects](/extending/aspects) @@ -460,7 +460,7 @@ details from the [`action_listener`](/reference/be/extra-actions#action_listener) rule specified by <var>label</var> to insert [`extra_actions`](/reference/be/extra-actions#extra_action) into the build graph. -#### `--[no]experimental_extra_action_top_level_only` +#### `--[no]experimental_extra_action_top_level_only` {#experimental-extra-action-top-level-only} Warning: Extra actions are deprecated. Use [aspects](/extending/aspects) instead. @@ -469,7 +469,7 @@ [ `--experimental_action_listener`](#experimental-action-listener) command line option will only be scheduled for top level targets. -#### `--experimental_extra_action_filter=<var>regex</var>` +#### `--experimental_extra_action_filter=<var>regex</var>` {#experimental-extra-action-filter} Warning: Extra actions are deprecated. Use [aspects](/extending/aspects) instead. @@ -494,12 +494,12 @@ --experimental_extra_action_filter=.*/bar/.* </pre> -#### `--host_cpu=<var>cpu</var>` +#### `--host_cpu=<var>cpu</var>` {#host-cpu} This option specifies the name of the CPU architecture that should be used to build host tools. -#### `--android_platforms=<var>platform[,platform]*</var>` +#### `--android_platforms=<var>platform[,platform]*</var>` {#android-platforms} The platforms to build the transitive `deps` of `android_binary` rules (specifically for native dependencies like C++). For @@ -516,7 +516,7 @@ `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=<var>[+-]regex[,[+-]regex]...@option[,option]...</var>` +#### `--per_file_copt=<var>[+-]regex[,[+-]regex]...@option[,option]...</var>` {#per-file-copt} 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 +557,7 @@ 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=<var>mode</var>` +#### `--dynamic_mode=<var>mode</var>` {#dynamic-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 +573,7 @@ [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 (yes|no|[dbg][,opt][,fastbuild])` {#fission} 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 +586,13 @@ universally. When set to `no`, Fission is disabled universally. Default is <code class='flag'>no</code>. -#### `--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` +#### `--[no]force_pic` {#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 +602,38 @@ 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` +#### `--android_resource_shrinking` {#flag--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=<var>malloc-library-target</var>` +#### `--custom_malloc=<var>malloc-library-target</var>` {#custom-malloc} 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=<var>label</var>` +#### `--crosstool_top=<var>label</var>` {#crosstool-top} 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=<var>label</var>` +#### `--host_crosstool_top=<var>label</var>` {#host-crosstool-top} 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=<var>label</var>` +#### `--apple_crosstool_top=<var>label</var>` {#apple-crosstool-top} 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=<var>version</var>` +#### `--compiler=<var>version</var>` {#compiler} 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 +643,7 @@ Note: Only certain combinations of crosstool version, compiler version, and target CPU are allowed. -#### `--android_sdk=<var>label</var>` +#### `--android_sdk=<var>label</var>` {#android-sdk} Deprecated. This shouldn't be directly specified. @@ -654,30 +654,30 @@ The Android SDK will be automatically selected if an `android_sdk_repository` rule is defined in the WORKSPACE file. -#### `--java_toolchain=<var>label</var>` +#### `--java_toolchain=<var>label</var>` {#java-toolchain} No-op. Kept only for backwards compatibility. -#### `--host_java_toolchain=<var>label</var>` +#### `--host_java_toolchain=<var>label</var>` {#host-java-toolchain} No-op. Kept only for backwards compatibility. -#### `--javabase=(<var>label</var>)` +#### `--javabase=(<var>label</var>)` {#javabase} No-op. Kept only for backwards compatibility. -#### `--host_javabase=<var>label</var>` +#### `--host_javabase=<var>label</var>` {#host-javabase} 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=<var>strategy</var>` +#### `--spawn_strategy=<var>strategy</var>` {#spawn-strategy} This option controls where and how commands are executed. @@ -694,7 +694,7 @@ * `remote` causes commands to be executed remotely; this is only available if a remote executor has been configured separately. -#### `--strategy <var>mnemonic</var>=<var>strategy</var>` +#### `--strategy <var>mnemonic</var>=<var>strategy</var>` {#strategy} This option controls where and how commands are executed, overriding the [--spawn_strategy](#spawn-strategy) (and @@ -703,7 +703,7 @@ [--spawn_strategy](#spawn-strategy) for the supported strategies and their effects. -#### `--strategy_regexp=<var><filter,filter,...>=<strategy></var>` +#### `--strategy_regexp=<var><filter,filter,...>=<strategy></var>` {#strategy-regexp} This option specifies which strategy should be used to execute commands that have descriptions matching a certain `regex_filter`. See @@ -725,11 +725,11 @@ 'Compiling //foo/bar/baz' with the `local` strategy and falls back to `sandboxed` if it fails. -#### `--genrule_strategy=<var>strategy</var>` +#### `--genrule_strategy=<var>strategy</var>` {#genrule-strategy} This is a deprecated short-hand for `--strategy=Genrule=<var>strategy</var>`. -#### `--jobs=<var>n</var>` (-j) +#### `--jobs=<var>n</var>` (-j) {#jobs} This option, which takes an integer argument, specifies a limit on the number of jobs that should be executed concurrently during the @@ -743,7 +743,7 @@ of each job. The behavior of the scheduler can be controlled by the `--local_resources` option. -#### `--progress_report_interval=<var>n</var>` +#### `--progress_report_interval=<var>n</var>` {#progress-report-interval} Bazel periodically prints a progress report on jobs that are not finished yet (such as long running tests). This option sets the @@ -757,7 +757,7 @@ When bazel is using cursor control, as specified by [`--curses`](#curses), progress is reported every second. -#### `--local_resources <var>resources or resource expression</var>` +#### `--local_resources <var>resources or resource expression</var>` {#local-resources} 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 +767,7 @@ 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` +#### `--[no]build_runfile_links` {#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 +789,7 @@ contribute significantly to overall build time, particularly because each individual test (or application) requires its own runfiles tree. -#### `--[no]build_runfile_manifests` +#### `--[no]build_runfile_manifests` {#build-runfile-manifests} This option, which is enabled by default, specifies whether runfiles manifests should be written to the output tree. @@ -798,7 +798,7 @@ It can be disabled when executing tests remotely, as runfiles trees will be created remotely from in-memory manifests. -#### `--[no]discard_analysis_cache` +#### `--[no]discard_analysis_cache` {#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 +806,7 @@ The drawback is that further incremental builds will be slower. See also [memory-saving mode](/configure/memory). -#### `--[no]keep_going` (-k) +#### `--[no]keep_going` (-k) {#keep-going} 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 +823,7 @@ build will proceed to the execution phase, but only for the targets that were successfully analyzed. -#### `--[no]use_ijars` +#### `--[no]use_ijars` {#use-ijars} This option changes the way `java_library` targets are compiled by Bazel. Instead of using the output of a @@ -842,7 +842,7 @@ Changing the `--use_ijars` setting will force a recompilation of all affected classes. -#### `--[no]interface_shared_objects` +#### `--[no]interface_shared_objects` {#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 +850,11 @@ 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` +#### `--[no]build` {#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 +863,7 @@ This option can be useful for validating BUILD files and detecting errors in the inputs, without actually building anything. -#### `--[no]build_tests_only` +#### `--[no]build_tests_only` {#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 +878,7 @@ `bazel test --build_tests_only foo/...` may not detect all build breakages in the `foo` tree. -#### `--[no]check_up_to_date` +#### `--[no]check_up_to_date` {#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 +890,7 @@ See also [`--check_tests_up_to_date`](#check-tests-up-to-date). -#### `--[no]compile_one_dependency` +#### `--[no]compile_one_dependency` {#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 +905,7 @@ 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 +926,7 @@ your [`--show_result <var>n</var>`](#show-result) setting is high enough. -#### `--build_tag_filters=<var>tag[,tag]*</var>` +#### `--build_tag_filters=<var>tag[,tag]*</var>` {#build-tag-filters} 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 +938,7 @@ 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=<var>size[,size]*</var>` +#### `--test_size_filters=<var>size[,size]*</var>` {#test-size-filters} 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 +960,7 @@ By default, test size filtering is not applied. -#### `--test_timeout_filters=<var>timeout[,timeout]*</var>` +#### `--test_timeout_filters=<var>timeout[,timeout]*</var>` {#test-timeout-filters} 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 +971,7 @@ By default, test timeout filtering is not applied. -#### `--test_tag_filters=<var>tag[,tag]*</var>` +#### `--test_tag_filters=<var>tag[,tag]*</var>` {#test-tag-filters} 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 +993,7 @@ on test's `size` and `local` tags in this manner. -#### `--test_lang_filters=<var>string[,string]*</var>` +#### `--test_lang_filters=<var>string[,string]*</var>` {#test-lang-filters} 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 @@ -1027,7 +1027,7 @@ unfortunately misleading; don't make assumptions about the semantics based on the name. -#### `--test_filter=<var>filter-expression</var>` +#### `--test_filter=<var>filter-expression</var>` {#test-filter} 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 +1040,12 @@ 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=<var>logfile</var>` +#### `--explain=<var>logfile</var>` {#explain} This option, which requires a filename argument, causes the dependency checker in `bazel build`'s execution phase to @@ -1060,7 +1060,7 @@ 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 +1078,31 @@ If `--explain` is not enabled, then `--verbose_explanations` has no effect. -#### `--profile=<var>file</var>` +#### `--profile=<var>file</var>` {#profile} 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` +#### `--[no]show_loading_progress` {#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` +#### `--[no]show_progress` {#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=<var>n</var>` +#### `--show_progress_rate_limit=<var>n</var>` {#show-progress-rate} This option causes bazel to display at most one progress message per `n` seconds, where <var>n</var> 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=<var>n</var>` +#### `--show_result=<var>n</var>` {#show-result} This option controls the printing of result information at the end of a `bazel build` command. By default, if a single @@ -1136,13 +1136,13 @@ 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` (`-s`) {#subcommands} This option causes Bazel's execution phase to print the full command line for each command prior to executing it. @@ -1172,7 +1172,7 @@ 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 +1181,14 @@ 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=<var>program</var>` +#### `--workspace_status_command=<var>program</var>` {#workspace-status-command} 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 +1261,7 @@ 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` +#### `--[no]stamp` {#stamp} This option, in conjunction with the `stamp` rule attribute, controls whether to embed build information in binaries. @@ -1280,23 +1280,23 @@ 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=<var>labels</var>` +#### `--platforms=<var>labels</var>` {#platforms} The labels of the platform rules describing the target platforms for the current command. -#### `--host_platform=<var>label</var>` +#### `--host_platform=<var>label</var>` {#host-platform} The label of a platform rule that describes the host system. -#### `--extra_execution_platforms=<var>labels</var>` +#### `--extra_execution_platforms=<var>labels</var>` {#extra-execution-platforms} 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 +1305,29 @@ 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=<var>labels</var>` +#### `--extra_toolchains=<var>labels</var>` {#extra-toolchains} 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=<var>regex</var>` +#### `--toolchain_resolution_debug=<var>regex</var>` {#toolchain-resolution-debug} 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=<var>alias_name=target_path</var>` +#### `--flag_alias=<var>alias_name=target_path</var>` {#flag-alias} 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=<var>string</var>` +#### `--symlink_prefix=<var>string</var>` {#symlink-prefix} Changes the prefix of the generated convenience symlinks. The default value for the symlink prefix is `bazel-` which @@ -1355,7 +1355,7 @@ `--symlink_prefix=.bazel/` will cause Bazel to create symlinks called `bin` (etc) inside a hidden directory `.bazel`. -#### `--platform_suffix=<var>string</var>` +#### `--platform_suffix=<var>string</var>` {#platform-suffix} 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 +1363,12 @@ otherwise clobber each others output files, or to keep the output files around for comparisons. -#### `--default_visibility=<var>(private|public)</var>` +#### `--default_visibility=<var>(private|public)</var>` {#default-visibility} 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=_file_` {#starlark-cpu-profile} This flag, whose value is the name of a file, causes Bazel to gather statistics about CPU usage by all Starlark threads, @@ -1399,14 +1399,14 @@ For different views of the same data, try the `pprof` commands `svg`, `web`, and `list`. -## Using Bazel for releases +## Using Bazel for releases {#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 +1425,7 @@ 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 +1438,9 @@ interleaved with building. Doing so usually results in significant speed gains. -### Options for `bazel test` +### Options for `bazel test` {#bazel-test-options} -#### `--cache_test_results=(yes|no|auto)` (`-t`) +#### `--cache_test_results=(yes|no|auto)` (`-t`) {#cache-test-results} 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 +1468,7 @@ 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 +1483,7 @@ 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 +1500,14 @@ `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` +#### `--[no]test_keep_going` {#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=<var>attempts</var>` +#### `--flaky_test_attempts=<var>attempts</var>` {#flaky-test-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 +1522,7 @@ 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=<var>[regex@]number</var>` +#### `--runs_per_test=<var>[regex@]number</var>` {#runs-per-test} This option specifies the number of times each test should be executed. All test executions are treated as separate tests (fallback functionality @@ -1543,7 +1543,7 @@ under `//pizza/` 4 times). This form of `--runs_per_test` may be specified more than once. -#### `--[no]runs_per_test_detects_flakes` +#### `--[no]runs_per_test_detects_flakes` {#run-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 +1551,7 @@ considered flaky with the flag. If unspecified, the target will report a failing status. -#### `--test_summary=<var>output_style</var>` +#### `--test_summary=<var>output_style</var>` {#test-summary} Specifies how the test result summary should be displayed. @@ -1564,7 +1564,7 @@ only each test. The names of test output files are omitted. * `none` does not print test summary. -#### `--test_output=<var>output_style</var>` +#### `--test_output=<var>output_style</var>` {#test-output} Specifies how test output should be displayed: @@ -1582,12 +1582,12 @@ * `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` +#### `--[no]verbose_test_summary` {#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 +1595,7 @@ include only test name, test status and cached test indicator and will be formatted to stay within 80 characters when possible. -#### `--test_tmpdir=<var>path</var>` +#### `--test_tmpdir=<var>path</var>` {#test-tmpdir} Specifies temporary directory for tests executed locally. Each test will be executed in a separate subdirectory inside this directory. The directory will @@ -1605,7 +1605,7 @@ Note: This is a directory for running tests, not storing test results (those are always stored under the `bazel-out` directory). -#### `--test_timeout=<var>seconds</var>` OR `--test_timeout=<var>seconds</var>,<var>seconds</var>,<var>seconds</var>,<var>seconds</var>` +#### `--test_timeout=<var>seconds</var>` OR `--test_timeout=<var>seconds</var>,<var>seconds</var>,<var>seconds</var>,<var>seconds</var>` {#test-timeout} 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 +1627,7 @@ have the same effective timeout that a 'large' tests has with no explicit timeout. -#### `--test_arg=<var>arg</var>` +#### `--test_arg=<var>arg</var>` {#test-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 +1645,7 @@ `bazel run` command after a `--` token, it's not processed by Bazel but forwarded verbatim to the executed target.) -#### `--test_env=<var>variable</var>=_value_` OR `--test_env=<var>variable</var>` +#### `--test_env=<var>variable</var>=_value_` OR `--test_env=<var>variable</var>` {#test-env} Specifies additional variables that must be injected into the test environment for each test. If <var>value</var> is not specified it will be @@ -1655,7 +1655,7 @@ The environment can be accessed from within a test by using `System.getenv("var")` (Java), `getenv("var")` (C or C++), -#### `--run_under=<var>command-prefix</var>` +#### `--run_under=<var>command-prefix</var>` {#test-run-under} This specifies a prefix that the test runner will insert in front of the test command before running it. The @@ -1685,7 +1685,7 @@ --run_under='/usr/bin/valgrind --quiet --num-callers=20' </pre> -#### 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 +1695,12 @@ [general name filter](#test-filter) can forward particular filter args to the test runner. -#### Other options for `bazel test` +#### Other options for `bazel test` {#bazel-test-other-options} 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 +1755,9 @@ These can be used, for example, to interpret file names on the command line in a user-friendly way. -### Options for `bazel run` +### Options for `bazel run` {#bazel-run-options} -#### `--run_under=<var>command-prefix</var>` +#### `--run_under=<var>command-prefix</var>` {#run-run-under} This has the same effect as the `--run_under` option for `bazel test` ([see above](#test-run-under)), @@ -1775,7 +1775,7 @@ 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 +1783,9 @@ `--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 +### The `clean` command {#clean} Bazel has a `clean` command, analogous to that of Make. It deletes the output directories for all build configurations performed @@ -1828,7 +1828,7 @@ 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 the dependency graph {#querying-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 +1866,7 @@ bazel query --output location 'kind(genrule, deps(kind(".*_test rule", foo/bar/pebl/...)))' </pre> -## Querying the action graph +## Querying the action graph {#aquery} Caution: The aquery command is still experimental and its API will change. @@ -1887,9 +1887,9 @@ For more details, see [Action Graph Query](/query/aquery). -## Miscellaneous commands and options +## Miscellaneous commands and options {#misc-commands-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 +1899,14 @@ or `query`, but there are some additional help topics that do not correspond to commands. -#### `--[no]long` (`-l`) +#### `--[no]long` (`-l`) {#long} By default, `bazel help [<var>topic</var>]` 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 +1926,7 @@ 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 +1939,7 @@ 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 @@ -1998,7 +1998,7 @@ 1285 </pre> -#### Configuration-specific data +#### Configuration-specific data {#configuration-specific-data} These data may be affected by the configuration options passed to `bazel info`, for @@ -2045,7 +2045,7 @@ /var/tmp/_bazel_johndoe/fbd0e8a34f61ce5d491e3da69d959fe6/execroot/io_bazel/bazel-out/k8-opt/bin </pre> -### `version` and `--version` +### `version` and `--version` {#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 +2064,7 @@ 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 +2078,7 @@ 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 +2092,23 @@ 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_type_` {#start} How the app should be started after installing it. Supported _start_type_s are: @@ -2121,14 +2121,14 @@ Note: If more than one of `--start=_start_type_`, `--start_app` or `--debug_app` is set, the last value is used. -#### `--adb=<var>path</var>` +#### `--adb=<var>path</var>` {#adb} 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=<var>serial</var>` +#### `--adb_arg=<var>serial</var>` {#adb-arg} Extra arguments to `adb`. These come before the subcommand in the command line and are typically used to specify which device to install to. @@ -2144,12 +2144,12 @@ adb -s deadbeef install ... </pre> -#### `--incremental_install_verbosity=<var>number</var>` +#### `--incremental_install_verbosity=<var>number</var>` {#incremental-install-verbosity} 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 +2172,7 @@ [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 +2206,13 @@ % pprof -flame $HOME/prof.gz </pre> -### `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 +2235,7 @@ --test_tag_filters=-lint </pre> -### 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 +2248,7 @@ 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=<var>dir</var>` +#### `--output_base=<var>dir</var>` {#output-base} This option requires a path argument, which must specify a writable directory. Bazel will use this location to write all its @@ -2285,7 +2285,7 @@ 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=<var>dir</var>` +#### `--output_user_root=<var>dir</var>` {#output-user-root} 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 +2307,7 @@ 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=<var>dir</var>` +#### `--server_javabase=<var>dir</var>` {#server-javabase} 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 +2326,7 @@ build flag [--host_javabase](#host-javabase) (sometimes referred to as the 'right-hand side' `--host_javabase`). -#### `--host_jvm_args=<var>string</var>` +#### `--host_jvm_args=<var>string</var>` {#host-jvm-args} 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 +2348,7 @@ all `java_binary` and `java_test` programs support. Alternatively for tests, use `bazel test --test_arg=--jvm_flags=foo ...`. -#### `--host_jvm_debug` +#### `--host_jvm_debug` {#host-java-debug} This option causes the Java virtual machine to wait for a connection from a JDWP-compliant debugger before @@ -2358,14 +2358,14 @@ 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 +2392,7 @@ 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=<var>n</var>` +#### `--max_idle_secs=<var>n</var>` {#max-idle-secs} This option specifies how long, in seconds, the Bazel server process should wait after the last client request, before it exits. The @@ -2420,7 +2420,7 @@ 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` +#### `--[no]shutdown_on_low_sys_mem` {#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 +2430,7 @@ 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` +#### `--[no]block_for_lock` {#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 +2440,27 @@ Developers might use this in presubmit checks to avoid long waits caused by another Bazel command in the same client. -#### `--io_nice_level=<var>n</var>` +#### `--io_nice_level=<var>n</var>` {#io-nice-level} 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 +### Miscellaneous options {#misc-options} -#### `--[no]announce_rc` +#### `--[no]announce_rc` {#announce-rc} Controls whether Bazel announces startup options and command options read from the bazelrc files when starting up. -#### `--color (yes|no|auto)` +#### `--color (yes|no|auto)` {#color} This option determines whether Bazel will use colors to highlight its output on the screen. @@ -2473,7 +2473,7 @@ regardless of whether the output is going to a terminal and regardless of the setting of the TERM environment variable. -#### `--config=<var>name</var>` +#### `--config=<var>name</var>` {#config} Selects additional config section from [the rc files](/run/bazelrc#bazelrc-file-locations); for the current `command`, @@ -2481,7 +2481,7 @@ 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 (yes|no|auto)` {#curses} This option determines whether Bazel will use cursor controls in its screen output. This results in less scrolling data, and a more @@ -2493,7 +2493,7 @@ 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` +#### `--[no]show_timestamps` {#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/docs/extending/auto-exec-groups.mdx b/docs/extending/auto-exec-groups.mdx index 9fee978..36bcab4 100644 --- a/docs/extending/auto-exec-groups.mdx +++ b/docs/extending/auto-exec-groups.mdx
@@ -8,7 +8,7 @@ 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 @@ -33,7 +33,7 @@ [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: @@ -54,7 +54,7 @@ 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: @@ -85,14 +85,14 @@ 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 between custom exec groups and automatic exec groups {#difference-custom} 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 I use a custom exec_group? {#when-should-use-exec-groups} 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 @@ -119,22 +119,22 @@ ) ``` -## Migration of AEGs +## Migration of AEGs {#migration-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 versions support this migration? {#which-bazel} AEGs are fully supported from Bazel 7. -### How to enable AEGs? +### How to enable AEGs? {#how-enable} 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 to enable AEGs inside a particular rule? {#how-enable-particular-rule} Set the `_use_auto_exec_groups` attribute on a rule. @@ -150,16 +150,16 @@ when selecting the execution platform. Incompatible flag is overridden with this attribute. -### How to disable AEGs in case of an error? +### How to disable AEGs in case of an error? {#how-disable} 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 +### Error messages while migrating to AEGs {#potential-problems} -#### 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'. +#### 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} * 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 @@ -170,7 +170,7 @@ * 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/docs/extending/concepts.mdx b/docs/extending/concepts.mdx index 893e9cc..3864fc8 100644 --- a/docs/extending/concepts.mdx +++ b/docs/extending/concepts.mdx
@@ -19,7 +19,7 @@ * 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 @@ -44,7 +44,7 @@ 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.
diff --git a/docs/extending/config.mdx b/docs/extending/config.mdx index 0e8b4b9..436397a 100644 --- a/docs/extending/config.mdx +++ b/docs/extending/config.mdx
@@ -23,7 +23,7 @@ `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,11 +41,11 @@ (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) -#### The `build_setting` `rule()` parameter +#### The `build_setting` `rule()` parameter {#rule-parameter} Build settings are rules like any other rule and are differentiated using the Starlark `rule()` function's `build_setting` @@ -74,7 +74,7 @@ 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 +#### Using ctx.build_setting_value {#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 @@ -110,7 +110,7 @@ will see its basic Starlark-typed value, not this post implementation function value. -#### Defining multi-set string flags +#### Defining multi-set string flags {#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 @@ -143,7 +143,7 @@ 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 @@ -171,7 +171,7 @@ ) ``` -### Predefined settings +### Predefined settings {#predefined-settings} [End to end example](https://github.com/bazelbuild/examples/tree/HEAD/configurations/use_skylib_build_setting) @@ -195,9 +195,9 @@ 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. @@ -262,7 +262,7 @@ ``` -#### Using build settings on the command line +#### Using build settings on the command line {#build-settings-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 @@ -280,7 +280,7 @@ $ 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 @@ -312,7 +312,7 @@ 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) @@ -366,7 +366,7 @@ ) ``` -### 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) @@ -384,7 +384,7 @@ ) ``` -## User-defined transitions +## User-defined transitions {#user-defined-transitions} A configuration [transition](/rules/lib/builtins/transition#transition) @@ -393,7 +393,7 @@ 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 @@ -452,7 +452,7 @@ 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) @@ -497,7 +497,7 @@ ) ``` -### Attaching transitions +### Attaching transitions {#attaching-transitions} [End to end example](https://github.com/bazelbuild/examples/tree/HEAD/configurations/attaching_transitions_to_rules) @@ -511,7 +511,7 @@ 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: @@ -527,7 +527,7 @@ 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: @@ -545,7 +545,7 @@ See [Accessing attributes with transitions](#accessing-attributes-with-transitions) for how to read these keys. -### Transitions on native options +### Transitions on native options {#transitions-native-options} [End to end example](https://github.com/bazelbuild/examples/tree/HEAD/configurations/transition_on_native_flag) @@ -564,7 +564,7 @@ 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 @@ -584,7 +584,7 @@ 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 on allow multiple build settings {#transitions-multiple-build-settings} When setting build settings that [allow multiple values](#defining-multi-set-string-flags), the value of the @@ -617,7 +617,7 @@ ) ``` -### 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 @@ -646,7 +646,7 @@ ) ``` -### 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) @@ -715,14 +715,14 @@ See [complete example](https://github.com/bazelbuild/examples/tree/main/configurations/multi_arch_binary) here. -## Integration with platforms and toolchains +## Integration with platforms and toolchains {#integration-platforms-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 and performance considerations {#memory-performance-considerations} Adding transitions, and therefore new configurations, to your build comes at a cost: larger build graphs, less comprehensible build graphs, and slower @@ -730,7 +730,7 @@ 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: a case study {#badly-behaved-builds}  @@ -781,7 +781,7 @@ 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/docs/extending/exec-groups.mdx b/docs/extending/exec-groups.mdx index aa70cb1..bd2e6db 100644 --- a/docs/extending/exec-groups.mdx +++ b/docs/extending/exec-groups.mdx
@@ -8,14 +8,14 @@ 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 @@ 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 execution groups {#defining-exec-groups} During rule definition, rule authors can [declare](/rules/lib/globals/bzl#exec_group) @@ -68,7 +68,7 @@ As on native rules, the `test` execution group is present by default on Starlark test rules. -## Accessing execution groups +## Accessing execution groups {#accessing-exec-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` @@ -106,7 +106,7 @@ issues. A mismatch like this may not immediately cause failures, but is a latent problem. -### Default execution groups +### Default execution groups {#exec-groups-for-native-rules} The following execution groups are predefined: @@ -114,7 +114,7 @@ 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 execution groups to set execution properties {#using-exec-groups-for-exec-properties} Execution groups are integrated with the [`exec_properties`](/reference/be/common-definitions#common-attributes) @@ -140,7 +140,7 @@ dictionary as `{"mem": "16g"}`. As you see here, execution-group-level settings override target-level settings. -## Using execution groups to set platform constraints +## Using execution groups to set platform constraints {#using-exec-groups-for-platform-constraints} Execution groups are also integrated with the [`exec_compatible_with`](/reference/be/common-definitions#common-attributes) and @@ -178,7 +178,7 @@ ) ``` -### 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: @@ -186,7 +186,7 @@ * `test`: Test runner actions. * `cpp_link`: C++ linking actions. -### Execution groups and platform execution properties +### Execution groups and platform execution properties {#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/docs/extending/legacy-macros.mdx b/docs/extending/legacy-macros.mdx index 9c2b8e2..6827a07 100644 --- a/docs/extending/legacy-macros.mdx +++ b/docs/extending/legacy-macros.mdx
@@ -9,7 +9,7 @@ [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) +## Why you shouldn't use legacy macros (and should use Symbolic macros instead) {#no-legacy-macros} Where possible you should use [symbolic macros](macros.md#macros). @@ -22,7 +22,7 @@ * Are more readable * 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 @@ 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 @@ ) ``` -## 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,7 +151,7 @@ [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 in macros {#label-resolution} Since legacy macros are evaluated in the [loading phase](concepts.md#evaluation-model), label strings such as @@ -190,7 +190,7 @@ 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 @@ `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 @@ # ... ``` -## 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/docs/extending/macros.mdx b/docs/extending/macros.mdx index 136665d..7920d7c 100644 --- a/docs/extending/macros.mdx +++ b/docs/extending/macros.mdx
@@ -25,13 +25,13 @@ 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 @@ -58,7 +58,7 @@ 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 @@ -110,7 +110,7 @@ ... ``` -### 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 @@ -144,7 +144,7 @@ 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. @@ -180,9 +180,9 @@ This is generally not useful in `BUILD` files, but is helpful when programmatically wrapping a macro inside another macro. -## Details +## Details {#usage-details} -### Naming conventions for targets created +### Naming conventions for targets created {#naming} 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 @@ -199,7 +199,7 @@ [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. @@ -219,7 +219,7 @@ * can't refer to private targets of their callers (see [visibility and macros](#visibility) for more details). -### Visibility and macros +### Visibility and macros {#visibility} The [visibility](/concepts/visibility) system helps protect the implementation details of both (symbolic) macros and their callers. @@ -338,7 +338,7 @@ 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 @@ -353,7 +353,7 @@ 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 @@ -392,7 +392,7 @@ 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, @@ -424,7 +424,7 @@ ) ``` -## Laziness +## Laziness {#laziness} IMPORTANT: We are in the process of implementing lazy macro expansion and evaluation. This feature is not available yet. @@ -435,7 +435,7 @@ 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 +## Migration troubleshooting {#troubleshooting} Here are some common migration headaches and how to fix them.
diff --git a/docs/extending/platforms.mdx b/docs/extending/platforms.mdx index 9304d80..7009de1 100644 --- a/docs/extending/platforms.mdx +++ b/docs/extending/platforms.mdx
@@ -72,7 +72,7 @@ [@platforms/cpu](https://github.com/bazelbuild/platforms/blob/main/cpu/BUILD) constraints. -## Generally useful constraints and platforms +## Generally useful constraints and platforms {#useful-constraints-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 @@ `@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 +## Defining constraints {#constraints} Constraints are modeled with the [`constraint_setting`][constraint_setting] and [`constraint_value`][constraint_value] build rules. @@ -113,7 +113,7 @@ If visibility allows, you can extend an existing `constraint_setting` by defining your own value for it. -## Defining platforms +## Defining platforms {#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 @@ 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 @@ that transitively depend on an incompatible target are themselves considered incompatible. -### When are targets skipped? +### When are targets skipped? {#when-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 @@ Incompatible explicit targets are silently skipped if `--skip_incompatible_explicit_targets` is enabled. -### More expressive constraints +### More expressive constraints {#expressive-constraints} For more flexibility in expressing constraints, use the `@platforms//:incompatible` @@ -252,7 +252,7 @@ ) ``` -### Detecting incompatible targets using `bazel cquery` +### Detecting incompatible targets using `bazel cquery` {#cquery-incompatible-target-detection} You can use the [`IncompatiblePlatformProvider`](/rules/lib/providers/IncompatiblePlatformProvider)
diff --git a/docs/extending/rules.mdx b/docs/extending/rules.mdx index 248ee32..07515c9 100644 --- a/docs/extending/rules.mdx +++ b/docs/extending/rules.mdx
@@ -170,7 +170,7 @@ <a name="private-attributes"></a> -### 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
diff --git a/docs/extending/toolchains.mdx b/docs/extending/toolchains.mdx index 249eaf0..9534774 100644 --- a/docs/extending/toolchains.mdx +++ b/docs/extending/toolchains.mdx
@@ -11,7 +11,7 @@ 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 @@ 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 that use toolchains {#writing-rules-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 @@ made a dependency of the `bar_binary` target, not the whole space of candidate toolchains. -### Mandatory and Optional Toolchains +### Mandatory and Optional Toolchains {#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 @@ 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 that use toolchains {#writing-aspects-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 @@ return [] ``` -## Defining toolchains +## Defining toolchains {#toolchain-definitions} To define some toolchains for a given toolchain type, you need three things: @@ -483,7 +483,7 @@ ) ``` -## Registering and building with toolchains +## Registering and building with toolchains {#registering-building-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 @@ 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. @@ -632,7 +632,7 @@ 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/docs/external/faq.mdx b/docs/external/faq.mdx index 480658f..817040a 100644 --- a/docs/external/faq.mdx +++ b/docs/external/faq.mdx
@@ -9,9 +9,9 @@ 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? +### How should I version a Bazel module? {#module-versioning-best-practices} 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 @@ [non-registry override]: module.md#non-registry_overrides [`rules-template`]: https://github.com/bazel-contrib/rules-template -### What is a compatibility level? +### What is a compatibility level? {#compatibility-level} You should stop using `compatibility_level`. @@ -90,7 +90,7 @@ 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 `load`s? {#why-does-module-bazel-not-support-loads} During dependency resolution, the MODULE.bazel file of all referenced external dependencies are fetched from registries. At this stage, the source archives of @@ -116,7 +116,7 @@ immediately `load`ing from that repo to perform complex logic. This 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 @@ -131,7 +131,7 @@ 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 @@ -147,7 +147,7 @@ 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_repo`s? {#why-all-these-use-repos} Module extension usages in MODULE.bazel files sometimes come with a big `use_repo` directive. For example, a typical usage of the @@ -184,9 +184,9 @@ 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 @@ -251,9 +251,9 @@ 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 @@ -268,7 +268,7 @@ If you want to fetch repos _and_ modify them to test locally, consider using 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 @@ -294,13 +294,13 @@ 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? +### How do I make Bazel prefer IPv6 in dual-stack IPv4/IPv6 setups? {#ipv6} 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, @@ -333,7 +333,7 @@ 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
diff --git a/docs/external/lockfile.mdx b/docs/external/lockfile.mdx index d0eff0f..6d66c2a 100644 --- a/docs/external/lockfile.mdx +++ b/docs/external/lockfile.mdx
@@ -14,7 +14,7 @@ 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 @@ 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 @@ 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 @@ 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 @@ `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 @@ } ``` -### 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 @@ 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 @@ 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 @@ 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 @@ 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.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/docs/external/migration.mdx b/docs/external/migration.mdx index b6277bf..38e049f 100644 --- a/docs/external/migration.mdx +++ b/docs/external/migration.mdx
@@ -10,7 +10,7 @@ 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](overview#benefits) compared to the legacy WORKSPACE system, which helps to ensure a healthy growth of the Bazel @@ -23,7 +23,7 @@ * Migration to Bzlmod is a necessary step in order to use future Bazel versions (mandatory in Bazel 9). -## How to migrate to Bzlmod? +## How to migrate to Bzlmod? {#how-migrate-to-bzlmod} Recommended migration process: @@ -34,13 +34,13 @@ `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 the root of a Bazel workspace {#define-root} 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 @@ -54,7 +54,7 @@ # See MODULE.bazel for external dependencies setup. ``` -### Enable Bzlmod in your bazelrc +### Enable Bzlmod in your bazelrc {#enable-bzlmod} `.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 @@ -67,7 +67,7 @@ common --enable_bzlmod ``` -### Specify repository name for your workspace +### Specify repository name for your workspace {#specify-repo-name} * **WORKSPACE** @@ -101,7 +101,7 @@ ) ``` -### Fetch external dependencies as Bazel modules +### Fetch external dependencies as Bazel modules {#fetch-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. @@ -250,7 +250,7 @@ use_repo(non_module_dependencies, "data_file") ``` -### Resolve conflict external dependencies with module extension +### Resolve conflict external dependencies with module extension {#conflict-deps-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 @@ -260,7 +260,7 @@ an argument. ```python -## repositories.bzl in foo +## repositories.bzl in foo {#repositories.bzl-foo} load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_file") def data_deps(version = "1.0"): http_file( @@ -345,7 +345,7 @@ resolve this conflict and automatically select version `3.0` for the data dependency. -### Integrate third party package manager +### Integrate third party package manager {#integrate-package-manager} Following the last section, since module extension provides a way to collect information from the dependency graph, perform custom logic to resolve @@ -369,7 +369,7 @@ [pkg-mgr-example]: https://github.com/bazelbuild/examples/tree/main/bzlmod/05-integrate_third_party_package_manager -### Detect toolchains on the host machine +### Detect toolchains on the host machine {#detect-toolchain} 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 @@ -442,7 +442,7 @@ use_repo(sh_config_ext, "local_config_sh") ``` -### Register toolchains & execution platforms +### Register toolchains & execution platforms {#register-toolchains} Following the last section, after introducing a repository hosting toolchain information (e.g. `local_config_sh`), you probably want to register the @@ -507,7 +507,7 @@ [register_execution_platforms]: /rules/lib/globals/module#register_execution_platforms -### Introduce local repositories +### Introduce local repositories {#introduce-local-deps} 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 @@ -556,7 +556,7 @@ 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 @@ -593,7 +593,7 @@ * Replace all usages of `//external:openssl` with `//third_party:openssl`. -### Fetch versus Sync +### Fetch versus Sync {#fetch-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` @@ -614,13 +614,13 @@ 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. -### Know your dependencies in WORKSPACE +### Know your dependencies in WORKSPACE {#know-deps-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 @@ -680,7 +680,7 @@ dependencies with Bzlmod is going to achieved by a [new subcommand](https://github.com/bazelbuild/bazel/issues/15365). -#### Built-in default dependencies +#### Built-in default dependencies {#builtin-default-deps} 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. @@ -693,7 +693,7 @@ [bazel_tools]: https://github.com/bazelbuild/bazel/blob/master/src/MODULE.tools -### Hybrid mode for gradual migration +### Hybrid mode for gradual migration {#hybrid-mode} Bzlmod and WORKSPACE can work side by side, which allows migrating dependencies from the WORKSPACE file to Bzlmod to be a gradual process. @@ -702,7 +702,7 @@ 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 @@ -722,7 +722,7 @@ * 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 @@ -749,7 +749,7 @@ 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: @@ -764,7 +764,7 @@ 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 Bazel modules {#publish-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/). @@ -820,7 +820,7 @@ 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. @@ -845,14 +845,14 @@ -## Community migration progress +## Community migration progress {#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 +## Report issues {#reporting-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/docs/external/migration_tool.mdx b/docs/external/migration_tool.mdx index fe3c591..e9435ce 100644 --- a/docs/external/migration_tool.mdx +++ b/docs/external/migration_tool.mdx
@@ -14,7 +14,7 @@ **Note**: If you want to try out the AI driven Bzlmod migration, check [Bzlmod Migration Agent Setup][gemini_cli_setup]. -## Core Functionality +## Core Functionality {#migration-tool-core-functionality} The script's primary functions are: @@ -52,7 +52,7 @@ recommendations for correctness. * Use the migration tool with Bazel 7 (not supported with Bazel 8). -## How to Use the Migration Tool +## How to Use the Migration Tool {#migration-tool-how-to-use} Before you begin: @@ -65,7 +65,7 @@ bazel build --nobuild --enable_workspace --noenable_bzlmod <targets> ``` -### Command for running the script +### Command for running the script {#migration-script-command} Once the prerequisites are met, run the following commands to use the migration tool: @@ -86,7 +86,7 @@ migrate2bzlmod -t <targets> </pre> -### Files generated by this script +### Files generated by this script {#migration-script-files} * `MODULE.bazel` - The central manifest file for Bzlmod, which declares the project's metadata and its direct dependencies on other Bazel modules. @@ -105,7 +105,7 @@ are not standard Bazel modules but can be managed using Bzlmod's [module extensions](/external/extension). -### Flags +### Flags {#migration-script-flags} Flags available in this migration scripts are: @@ -116,13 +116,13 @@ 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 Example {#migration-tool-example} To see the migration script in action, consider the following scenario when Python, Maven and Go dependencies are declared in `WORKSPACE` file. @@ -343,7 +343,7 @@ * `migration_info.md` file contains details about the migration. Check details [at this section](#migration-tool-report-generation). -### Transformations +### Transformations {#migration-tool-transformations} This section illustrates the migration of code from the `WORKSPACE` file to `MODULE.bazel`. @@ -597,12 +597,12 @@ <hr style="height: 1px; background-color: black; border: none;"/> -## Tips with debugging +## Tips with debugging {#migration-tool-tips} This section provides useful commands and information to help debug issues that may arise during the Bzlmod migration. -### Useful tips +### Useful tips {#debugging-useful-tips} * Override version - Not rarely it happens that upgrading the version of a dependency causes troubles. Bzlmod could change the version of the @@ -631,7 +631,7 @@ `bazel vendor --enable_bzlmod --vendor_dir=vendor_src --repo=@protobuf` -### Migration Report Generation +### Migration Report Generation {#migration-tool-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` @@ -706,7 +706,7 @@ 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) @@ -717,7 +717,7 @@ * [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/docs/external/mod-command.mdx b/docs/external/mod-command.mdx index c8804be..69a3cd8 100644 --- a/docs/external/mod-command.mdx +++ b/docs/external/mod-command.mdx
@@ -9,7 +9,7 @@ repo definitions backing modules, inspect usages of module extensions and repos they generate, among other functions. -## Syntax +## Syntax {#syntax} ```sh bazel mod <subcommand> [<options>] [<arg> [<arg>...]] @@ -184,7 +184,7 @@ * `--extension_usages <arg>[,<arg>[,...]]`: 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
diff --git a/docs/external/module.mdx b/docs/external/module.mdx index b3f035d..e3fe913 100644 --- a/docs/external/module.mdx +++ b/docs/external/module.mdx
@@ -32,7 +32,7 @@ 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 @@ -59,7 +59,7 @@ 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: @@ -156,7 +156,7 @@ learn more about this [see the `MODULE.bazel` FAQ](faq#module-versioning-best-practices). -## Define repos that don't represent Bazel modules +## Define repos that don't represent Bazel modules {#use_repo_rule} 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
diff --git a/docs/external/overview.mdx b/docs/external/overview.mdx index 3646434..c6a24ec 100644 --- a/docs/external/overview.mdx +++ b/docs/external/overview.mdx
@@ -13,7 +13,7 @@ This document gives an overview of the system before examining some of the concepts in more detail. -## Overview of the system +## Overview of the system {#overview} Bazel's external dependency system works on the basis of [*Bazel modules*](#module), each of which is a versioned Bazel project, and @@ -56,11 +56,11 @@ 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](module#version-selection) version resolution algorithm, @@ -72,7 +72,7 @@ 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 @@ -93,7 +93,7 @@ * [rules_rust](https://bazelbuild.github.io/rules_rust/crate_universe_bzlmod.html) for Cargo. -### Advanced Features +### Advanced Features {#advanced-features} - **[Module Extensions](extension)**: The [`use_repo_rule`](/rules/lib/globals/module#use_repo_rule) and module @@ -111,11 +111,11 @@ 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. @@ -124,7 +124,7 @@ 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**. @@ -135,14 +135,14 @@ 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 <span id="#workspace-root">**workspace root**</span>. -### 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. @@ -151,7 +151,7 @@ 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 repository name {#canonical-repo-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 @@ -160,7 +160,7 @@ The main repository always has the empty string as the canonical name. -### Apparent repository name +### Apparent repository name {#apparent-repo-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 @@ -172,7 +172,7 @@ 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 +### Repository rule {#repo-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 @@ -189,7 +189,7 @@ [`local_repository`](/rules/lib/repo/local#local_repository), which symlinks a local directory that is already a Bazel repository. -### Fetch a repository +### Fetch a repository {#fetch-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 @@ -211,7 +211,7 @@ 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. @@ -223,7 +223,7 @@ ls $(bazel info output_base)/external/<var> canonical_name </var> ``` -### REPO.bazel file +### REPO.bazel file {#repo.bazel} 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 @@ -245,7 +245,7 @@ ) ``` -## The legacy WORKSPACE system +## The legacy WORKSPACE system {#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 @@ -270,7 +270,7 @@ See the [full list](/rules/lib/globals/workspace) of functions available in `WORKSPACE` files. -### Shortcomings of the `WORKSPACE` system +### Shortcomings of the `WORKSPACE` system {#workspace-shortcomings} In the years after the `WORKSPACE` system was introduced, users reported many pain points, including: @@ -296,7 +296,7 @@ Read the [Bzlmod migration guide](migration) on how to migrate to Bzlmod. -### External links on Bzlmod +### External links on Bzlmod {#external-links} * [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/docs/external/registry.mdx b/docs/external/registry.mdx index 32bd085..1d44158 100644 --- a/docs/external/registry.mdx +++ b/docs/external/registry.mdx
@@ -39,7 +39,7 @@ * `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: @@ -57,7 +57,7 @@ * `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: @@ -73,7 +73,7 @@ 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` @@ -132,7 +132,7 @@ `--registry=file://<registry_path>`. 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 registry with contents backed by the GitHub repo
diff --git a/docs/external/vendor.mdx b/docs/external/vendor.mdx index f2642dd..2c850de 100644 --- a/docs/external/vendor.mdx +++ b/docs/external/vendor.mdx
@@ -8,7 +8,7 @@ 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,7 +22,7 @@ The vendor directory can be either a relative path to your workspace root or an absolute path. -## Vendor a specific external repository +## Vendor a specific external repository {#vendor-specific-repository} You can use the `vendor` command with the `--repo` flag to specify which repo to vendor, it accepts both [canonical repo @@ -44,7 +44,7 @@ will both get rules_cc to be vendored under `<workspace root>/vendor_src/rules_cc+`. -## Vendor external dependencies for given targets +## Vendor external dependencies for given targets {#vendor-target-dependencies} To vendor all external dependencies required for building given target patterns, you can run `bazel vendor <target patterns>`. @@ -62,7 +62,7 @@ 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 @@ -80,7 +80,7 @@ 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 external dependencies {#vendor-all-dependencies} To vendor all repos in your transitive external dependencies graph, you can run: @@ -97,7 +97,7 @@ Therefore, consider vendoring for specific targets first. -## Configure vendor mode with VENDOR.bazel +## Configure vendor mode with VENDOR.bazel {#configure-vendor-mode} You can control how given repos are handled with the VENDOR.bazel file located under the vendor directory. @@ -132,7 +132,7 @@ [`configure`](/rules/lib/globals/bzl#repository_rule.configure) set to true are always excluded from vendoring. -## Understand how vendor mode works +## Understand how vendor mode works {#how-vendor-mode-works} Bazel fetches external dependencies of a project under `$(bazel info output_base)/external`. Vendoring external dependencies means moving out @@ -156,14 +156,14 @@ 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 `<vendor_dir>/_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/docs/help.mdx b/docs/help.mdx index 9956d92..6226c6e 100644 --- a/docs/help.mdx +++ b/docs/help.mdx
@@ -7,7 +7,7 @@ This page lists Bazel resources beyond the documentation and covers how to get support from the Bazel team and community. -## Search existing material +## Search existing material {#search-material} In addition to the documentation, you can find helpful information by searching: @@ -17,7 +17,7 @@ * [Stack Overflow](https://stackoverflow.com/questions/tagged/bazel) * [`awesome-bazel` resources](https://github.com/jin/awesome-bazel) -## Watch videos +## Watch videos {#videos} There are recordings of Bazel talks at various conferences, such as: @@ -34,7 +34,7 @@ * Bazel day on [Google Open Source Live](https://opensourcelive.withgoogle.com/events/bazel) -## Ask the Bazel community +## Ask the Bazel community {#community} If there are no existing answers, you can ask the community by: @@ -44,12 +44,12 @@ * Chatting with other Bazel contributors on [Slack](https://slack.bazel.build/) * Consulting a [Bazel community expert](/community/experts) -## Understand Bazel's support level +## Understand Bazel's support level {#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 a bug {#file-bug} If you encounter a bug or want to request a feature, file a [GitHub Issue](https://github.com/bazelbuild/bazel/issues).
diff --git a/docs/install/bazelisk.mdx b/docs/install/bazelisk.mdx index a3189cb..6c0d5cc 100644 --- a/docs/install/bazelisk.mdx +++ b/docs/install/bazelisk.mdx
@@ -24,7 +24,7 @@ migrate your project with upcoming incompatible changes and how to provide feedback to the incompatible change authors. -### Managing Bazel versions with Bazelisk +### Managing Bazel versions with Bazelisk {#manage-with-bazelisk} [Bazelisk](https://github.com/bazelbuild/bazelisk) helps you manage Bazel versions. @@ -38,7 +38,7 @@ * Help migrate your project for incompatible changes (see above) * Easily try release candidates -### Recommended migration process +### Recommended migration process {#migration-process} Within minor updates to any LTS release, any project can be prepared for the next release without breaking
diff --git a/docs/install/compile-source.mdx b/docs/install/compile-source.mdx index 7a05ce4..c2fb5af 100644 --- a/docs/install/compile-source.mdx +++ b/docs/install/compile-source.mdx
@@ -14,9 +14,9 @@ * 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,7 +48,7 @@ Detailed instructions follow below. -### Step 1: Get the latest Bazel release +### Step 1: Get the latest Bazel release {#build-bazel-install-bazel} **Goal**: Install or download a release version of Bazel. Make sure you can run it by typing `bazel` in a terminal. @@ -77,7 +77,7 @@ You must make the binary executable by running `chmod +x /path/to/bazel`. -### Step 2: Download Bazel's sources from GitHub +### Step 2: Download Bazel's sources from GitHub {#build-bazel-git} If you are familiar with Git, then just git clone https://github.com/bazelbuild/bazel @@ -91,12 +91,12 @@ For example create a `bazel-src` directory under your home directory and extract there. -### Step 3: Install prerequisites +### Step 3: Install prerequisites {#build-bazel-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 +### Step 4a: Build Bazel on Ubuntu Linux, macOS, and other Unix-like systems {#build-bazel-on-unixes} For instructions for Windows, see [Build Bazel on Windows](#build-bazel-on-windows). @@ -124,7 +124,7 @@ 4. The output will be at `bazel-bin/src/bazel-dev` (or `bazel-bin/src/bazel`). -### Step 4b: Build Bazel on Windows +### Step 4b: Build Bazel on Windows {#build-bazel-on-windows} For instructions for Unix-like systems, see [Ubuntu Linux, macOS, and other Unix-like systems](#build-bazel-on-unixes). @@ -155,7 +155,7 @@ 4. The output will be at `bazel-bin\src\bazel-dev.exe` (or `bazel-bin\src\bazel.exe`). -### Step 5: Install the built binary +### Step 5: Install the built binary {#build-bazel-install} Actually, there's nothing to install. @@ -165,11 +165,11 @@ --- -## Build Bazel from scratch (bootstrapping) +## Build Bazel from scratch (bootstrapping) {#bootstrap-bazel} You can also build Bazel from scratch, without using an existing Bazel binary. -### Step 1: Download Bazel's sources (distribution archive) +### Step 1: Download Bazel's sources (distribution archive) {#download-distfile} (This step is the same for all platforms.) @@ -192,11 +192,11 @@ 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 +### Step 2a: Bootstrap Bazel on Ubuntu Linux, macOS, and other Unix-like systems {#bootstrap-unix-overview} For instructions for Windows, see [Bootstrap Bazel on Windows](#bootstrap-windows). -#### 2.1. Install the prerequisites +#### 2.1. Install the prerequisites {#bootstrap-unix-prereq} * **Bash** @@ -215,7 +215,7 @@ sudo apt-get install build-essential openjdk-21-jdk python3 zip unzip ``` -#### 2.2. Bootstrap Bazel on Unix +#### 2.2. Bootstrap Bazel on Unix {#bootstrap-unix} 1. Open a shell or Terminal window. @@ -232,12 +232,12 @@ [`SOURCE_DATE_EPOCH`](https://reproducible-builds.org/specs/source-date-epoch/) in the "Run the compilation script" step. -### Step 2b: Bootstrap Bazel on Windows +### Step 2b: Bootstrap Bazel on Windows {#bootstrap-windows-overview} 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 +#### 2.1. Install the prerequisites {#bootstrap-windows-prereq} * [MSYS2 shell](https://msys2.github.io/) @@ -258,7 +258,7 @@ [https://www.python.org](https://www.python.org)). Versions installed via pacman in MSYS2 will not work. -#### 2.2. Bootstrap Bazel on Windows +#### 2.2. Bootstrap Bazel on Windows {#bootstrap-windows} 1. Open the MSYS2 shell.
diff --git a/docs/install/completion.mdx b/docs/install/completion.mdx index 1d1d1b7..b7e1cb8 100644 --- a/docs/install/completion.mdx +++ b/docs/install/completion.mdx
@@ -8,7 +8,7 @@ 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 @@ source /path/to/bazel-complete.bash ``` -## Zsh +## Zsh {#zsh} Bazel comes with a Zsh completion script.
diff --git a/docs/install/docker-container.mdx b/docs/install/docker-container.mdx index b1efb76..928c943 100644 --- a/docs/install/docker-container.mdx +++ b/docs/install/docker-container.mdx
@@ -9,7 +9,7 @@ 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 project from your host machine with directory mounting {#build-abseil} 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 @@ build --config={asan | tsan | msan} -- //absl/... -//absl/types:variant_test ``` -## Build Abseil project from inside the container +## Build Abseil project from inside the container {#build-abseil-inside-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 @@ ubuntu@5a99103747c6:~/abseil-cpp$ bazel build --config={asan | tsan | msan} -- //absl/... -//absl/types:variant_test ``` -## Explore the Bazel container +## Explore the Bazel container {#explore-bazel-container} If you haven't already, start an interactive shell inside the Bazel container. @@ -130,6 +130,6 @@ Build timestamp as int: 1685725198 ``` -## Explore the Bazel Dockerfile +## Explore the Bazel Dockerfile {#explore-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/docs/install/ide.mdx b/docs/install/ide.mdx index abe1f89..22ee969 100644 --- a/docs/install/ide.mdx +++ b/docs/install/ide.mdx
@@ -16,9 +16,9 @@ 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 and editors {#ides-editors} -### IntelliJ, Android Studio, and CLion +### IntelliJ, Android Studio, and CLion {#intellij-android-clion} Official Bazel plugins exist for many of the JetBrains-associated IDEs. Full documentation is linked from the listings on the JetBrains Marketplace: @@ -45,14 +45,14 @@ 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. @@ -69,38 +69,38 @@ 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 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) @@ -116,12 +116,12 @@ [`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 +## Automatically run build and test on file change {#bazel-watcher} [Bazel watcher](https://github.com/bazelbuild/bazel-watcher) is a tool for building Bazel targets when source files change. -## Building your own IDE plugin +## Building your own IDE plugin {#build-own-plugin} Read the [**IDE support** blog post](https://blog.bazel.build/2016/06/10/ide-support.html) to learn more about
diff --git a/docs/install/index.mdx b/docs/install/index.mdx index 84d9b14..dc1e6d2 100644 --- a/docs/install/index.mdx +++ b/docs/install/index.mdx
@@ -11,7 +11,7 @@ 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. @@ -28,7 +28,7 @@ * [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/docs/install/suse.mdx b/docs/install/suse.mdx index 741b108..82ce1bd 100644 --- a/docs/install/suse.mdx +++ b/docs/install/suse.mdx
@@ -14,7 +14,7 @@ The commands below must be run either via `sudo` or while logged in as `root`. -## Installing Bazel on openSUSE +## Installing Bazel on openSUSE {#install-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/docs/install/ubuntu.mdx b/docs/install/ubuntu.mdx index 5e55569..c1e4e32 100644 --- a/docs/install/ubuntu.mdx +++ b/docs/install/ubuntu.mdx
@@ -34,9 +34,9 @@ * Access the [bash completion script](/install/completion#bash) * Install the [zsh completion script](/install/completion#zsh) -## Using Bazel's apt repository +## Using Bazel's apt repository {#install-on-ubuntu} -### Step 1: Add Bazel distribution URI as a package source +### Step 1: Add Bazel distribution URI as a package source {#add-dis-uri} **Note:** This is a one-time setup step. @@ -54,7 +54,7 @@ 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 +### Step 2: Install and update Bazel {#install-bazel} ```posix-terminal sudo apt update && sudo apt install bazel @@ -87,7 +87,7 @@ bazel --version # 1.0.0 ``` -### Step 3: Install a JDK (optional) +### Step 3: Install a JDK (optional) {#install-jdk} 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 @@ sudo apt install default-jdk ``` -## Using the binary installer +## Using the binary installer {#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 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 +### Step 1: Install required packages {#install-packages} Bazel needs a C++ compiler and unzip / zip in order to work: @@ -123,7 +123,7 @@ sudo apt-get install default-jdk ``` -### Step 2: Run the installer +### Step 2: Run the installer {#run-installer} Next, download the Bazel binary installer named `bazel-<var>version</var>-installer-linux-x86_64.sh` from the [Bazel releases page on GitHub](https://github.com/bazelbuild/bazel/releases). @@ -140,7 +140,7 @@ sets the `.bazelrc` path to `$HOME/.bazelrc`. Use the `--help` command to see additional installation options. -### Step 3: Set up your environment +### Step 3: Set up your environment {#set-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 @@ You can also add this command to your `~/.bashrc` or `~/.zshrc` file to make it permanent. -## Using the Bazel Docker container +## Using the Bazel Docker container {#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/docs/install/windows.mdx b/docs/install/windows.mdx index 50b387d..9b0b07d 100644 --- a/docs/install/windows.mdx +++ b/docs/install/windows.mdx
@@ -8,12 +8,12 @@ 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 your system {#check-system} Recommended: 64 bit Windows 10, version 1703 (Creators Update) or newer @@ -23,11 +23,11 @@ * 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 the prerequisites {#install-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) @@ -40,7 +40,7 @@ * [Install Bazel from Scoop](#scoop) * [Build Bazel from source](/install/compile-source) -### Set up your environment +### Set up your environment {#set-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. @@ -50,7 +50,7 @@ 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." @@ -67,7 +67,7 @@ * [Best practices on Windows](/configure/windows#best-practices) * [Tutorials](/start/#tutorials) -## Installing compilers and language runtimes +## Installing compilers and language runtimes {#install-compilers} Depending on which languages you want to build, you will need: @@ -116,7 +116,7 @@ Also supported: Python 2.7 or newer for Windows x86-64 -## Troubleshooting +## Troubleshooting {#troubleshooting} ### Bazel does not find Bash or bash.exe @@ -195,9 +195,9 @@ If you open a new cmd.exe or PowerShell terminal and run Bazel now, it will find Visual C++. -## Other ways to install Bazel +## Other ways to install Bazel {#install-options} -### Using Chocolatey +### Using Chocolatey {#chocolately} 1. Install the [Chocolatey](https://chocolatey.org) package manager @@ -215,7 +215,7 @@ guide](/contribute/windows-chocolatey-maintenance) for more information about the Chocolatey package. -### Using Scoop +### Using Scoop {#scoop} 1. Install the [Scoop](https://scoop.sh/) package manager using the following PowerShell command: @@ -233,6 +233,6 @@ 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/docs/migrate/maven.mdx b/docs/migrate/maven.mdx index 0ca2b5c..ac8a042 100644 --- a/docs/migrate/maven.mdx +++ b/docs/migrate/maven.mdx
@@ -16,14 +16,14 @@ , 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 Bazel's concepts, structure, and label syntax. -## Differences between Maven and Bazel +## Differences between Maven and Bazel {#dif-maven-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 @@ -35,7 +35,7 @@ `BUILD` files. Best practice is to add a `BUILD` file to each new Java package. -## Migrate from Maven to Bazel +## Migrate from Maven to Bazel {#migrate-maven-bazel} The steps below describe how to migrate your project to Bazel: @@ -55,7 +55,7 @@ $ git checkout v31.1 ``` -### 1. Create the MODULE.bazel file +### 1. Create the MODULE.bazel file {#1-build} Create a file named `MODULE.bazel` at the root of your project. If your project has no external dependencies, this file can be empty. @@ -67,7 +67,7 @@ README](https://github.com/bazelbuild/rules_jvm_external/#rules_jvm_external) . -#### Guava project example: external dependencies +#### Guava project example: external dependencies {#guava-1} You can list the external dependencies of the [Guava project](https://github.com/google/guava) with the @@ -94,7 +94,7 @@ use_repo(maven, "maven") ``` -### 2. Create one BUILD file +### 2. Create one BUILD file {#2-build} Now that you have your workspace defined and external dependencies (if applicable) listed, you need to create `BUILD` files to describe how your @@ -174,7 +174,7 @@ 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 project example: start with one BUILD file {#guava-2} 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 @@ -198,7 +198,7 @@ ) ``` -### 3. Create more BUILD files (optional) +### 3. Create more BUILD files (optional) {#3-build} 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 @@ -230,7 +230,7 @@ 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 using Bazel {#4-build} You've been building using Bazel as you add `BUILD` files to validate the setup of the build.
diff --git a/docs/migrate/xcode.mdx b/docs/migrate/xcode.mdx index 311f5e6..84e52f8 100644 --- a/docs/migrate/xcode.mdx +++ b/docs/migrate/xcode.mdx
@@ -7,7 +7,7 @@ converting an Xcode project to a Bazel project. It also provides troubleshooting solutions to address common errors. -## Differences between Xcode and Bazel +## Differences between Xcode and Bazel {#dif-xcode-bazel} * Bazel requires you to explicitly specify every build target and its dependencies, plus the corresponding build settings via build rules. @@ -26,7 +26,7 @@ `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: @@ -39,7 +39,7 @@ 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. @@ -47,7 +47,7 @@ For more information on external dependencies, see [Working with external dependencies](/docs/external). -## Build or test an Xcode project with Bazel +## Build or test an Xcode project with Bazel {#build-xcode-project} To build or test an Xcode project with Bazel, do the following: @@ -69,7 +69,7 @@ 6. [Generate the Xcode project with rules_xcodeproj](#generate-the-xcode-project-with-rules_xcodeproj) -### Step 1: Create the `MODULE.bazel` file +### Step 1: Create the `MODULE.bazel` file {#create-workspace} 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 @@ -80,7 +80,7 @@ Note: Place the project source code within the directory tree containing the `MODULE.bazel` file. -### Step 2: (Experimental) Integrate SwiftPM dependencies +### Step 2: (Experimental) Integrate SwiftPM dependencies {#integrate-swiftpm} To integrate SwiftPM dependencies into the Bazel workspace with [swift_bazel](https://github.com/cgrindel/swift_bazel), you must @@ -92,7 +92,7 @@ integration with Bazel has not been fully verified and is not officially supported. -### Step 3: Create a `BUILD` file +### Step 3: Create a `BUILD` file {#create-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 @@ -106,7 +106,7 @@ **Tip:** To learn more about packages and other Bazel concepts, see [Workspaces, packages, and targets](/concepts/build-ref). -#### Step 3a: Add the application target +#### Step 3a: Add the application target {#add-app-target} Add a [`macos_application`](https://github.com/bazelbuild/rules_apple/blob/master/doc/rules-macos.md#macos_application) @@ -130,7 +130,7 @@ application supports. This ensures Bazel builds the application with the correct API levels. -#### Step 3b: (Optional) Add the test target(s) +#### Step 3b: (Optional) Add the test target(s) {#add-test-target} Bazel's [Apple build rules](https://github.com/bazelbuild/rules_apple) support running @@ -158,7 +158,7 @@ simulator, also specify the `ios_application` target name as the value of the `test_host` attribute. -#### Step 3c: Add the library target(s) +#### Step 3c: Add the library target(s) {#add-library-target} Add an [`objc_library`](/reference/be/objective-c#objc_library) target for each Objective-C library and a @@ -198,7 +198,7 @@ `bazel build //:<application_target>` -### Step 4: (Optional) Granularize the build +### Step 4: (Optional) Granularize the build {#granularize-build} If the project is large, or as it grows, consider chunking it into multiple Bazel packages. This increased granularity provides: @@ -232,7 +232,7 @@ * Build the project after each major change to the `BUILD` files and fix build errors as you encounter them. -### Step 5: Run the build +### Step 5: Run the build {#run-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 @@ -244,7 +244,7 @@ bazel build //:my-target ``` -### Step 6: Generate the Xcode project with rules_xcodeproj +### Step 6: Generate the Xcode project with rules_xcodeproj {#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 @@ -252,7 +252,7 @@ [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/docs/query/aquery.mdx b/docs/query/aquery.mdx index 151565b..be9a633 100644 --- a/docs/query/aquery.mdx +++ b/docs/query/aquery.mdx
@@ -33,7 +33,7 @@ Outputs: [...] ``` -## Basic syntax +## Basic syntax {#basic-syntax} A simple example of the syntax for `aquery` is as follows: @@ -60,7 +60,7 @@ $ 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 @@ 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=(text|summary|commands|proto|jsonproto|textproto), default=text` {#output} The default output format (`text`) is human-readable, use `proto`, `textproto`, or `jsonproto` for machine-readable format. @@ -122,25 +122,25 @@ 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, default=true` {#include-commandline} Includes the content of the action command lines in the output (potentially large). -#### `--include_artifacts, default=true` +#### `--include_artifacts, default=true` {#include-artifacts} Includes names of the action inputs and outputs in the output (potentially large). -#### `--include_aspects, default=true` +#### `--include_aspects, default=true` {#include-aspects} Whether to include Aspect-generated actions in the output. -#### `--include_param_files, default=false` +#### `--include_param_files, default=false` {#include-param-files} 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, default=false` {#include-file-write-contents} 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 @@ ``` line -#### `--skyframe_state, default=false` +#### `--skyframe_state, default=false` {#skyframe-state} 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 and features {#other-tools-features} -### Querying against the state of Skyframe +### Querying against the state of Skyframe {#querying-against-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 @@ 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 +##### Non-inclusion of target labels in the query expression {#target-labels-non-inclusion} 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 @@ $ 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 options +#### Command options {#command-options} `--before, --after`: The aquery output files to be compared @@ -274,7 +274,7 @@ `--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 @@ sorted in topological order of the [dependency graph](/extending/aspects#aspect_basics). -### Linking with the JSON profile +### Linking with the JSON profile {#linking-with-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 @@ 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 @@ 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. +### The ActionKey remains the same even though the content of an input file changed. {#actionkey-same} 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 @@ 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/docs/query/cquery.mdx b/docs/query/cquery.mdx index d35ea82..9d01b98 100644 --- a/docs/query/cquery.mdx +++ b/docs/query/cquery.mdx
@@ -67,7 +67,7 @@ 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: @@ -89,7 +89,7 @@ query expression. See [`--universe_scope`](#universe-scope) for querying dependencies of top-level build targets. -## Configurations +## Configurations {#configurations} The line: @@ -113,7 +113,7 @@ [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 @@ -144,7 +144,7 @@ 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 @@ -156,7 +156,7 @@ `cquery` also introduces the following new functions: -### config +### config {#config} `expr ::= config(expr, word)` @@ -186,17 +186,17 @@ 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` (comma-separated list) {#universe-scope} Often, the dependencies of configured targets go through [transitions](/extending/rules#configurations), @@ -259,13 +259,13 @@ 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` (boolean, default=True) {#implicit-deps} 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` (boolean, default=True) {#tool-deps} 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 @@ -277,19 +277,19 @@ in non-target configurations. This setting generally does not affect filtering of resolved toolchains. -#### `--include_aspects` (boolean, default=True) +#### `--include_aspects` (boolean, default=True) {#include-aspects} 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 @@ -313,7 +313,7 @@ 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 @@ -328,7 +328,7 @@ 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 +#### --[no]proto:include_configurations {#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 @@ -341,7 +341,7 @@ targets and within attributes, all possible inputs for selects are still included as `rule_input` fields. -### Graph output +### Graph output {#graph-output} ``` --output=graph @@ -352,7 +352,7 @@ also supports [`--graph:node_limit`](/query/language#graph-nodelimit) and [`--graph:factored`](/query/language#graph-factored). -### Files output +### Files output {#files-output} ``` --output=files @@ -376,7 +376,7 @@ 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 +### Defining the output format using Starlark {#output-format-definition} ``` --output=starlark @@ -391,7 +391,7 @@ body of a function declared as `def format(target): return expr` by using the `--starlark:expr` flag. -#### 'cquery' Starlark dialect +#### 'cquery' Starlark dialect {#cquery-starlark} The cquery Starlark environment differs from a BUILD or .bzl file. It includes all core Starlark @@ -399,7 +399,7 @@ 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(target) {#build-options-function} `build_options(target)` returns a map whose keys are build option identifiers (see [Configurations](/extending/config)) and whose values are their Starlark @@ -409,14 +409,14 @@ If the target is an input file, `build_options(target)` returns None, as input file targets have a null configuration. -##### providers(target) +##### providers(target) {#providers} `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 +#### Examples {#output-format-definition-examples} Print a space-separated list of the base names of all files produced by `//foo`: @@ -517,7 +517,7 @@ $ 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: @@ -582,9 +582,9 @@ 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/docs/query/guide.mdx b/docs/query/guide.mdx index 37edd13..32ad6ed 100644 --- a/docs/query/guide.mdx +++ b/docs/query/guide.mdx
@@ -16,7 +16,7 @@ To execute a query while ignoring errors such as missing targets, use the `--keep_going` flag. -## Finding the dependencies of a rule +## Finding the dependencies of a rule {#finding-rule-dependencies} To see the dependencies of `//foo`, use the `deps` function in bazel query: @@ -30,7 +30,7 @@ This is the set of all targets required to build `//foo`. -## Tracing the dependency chain between two packages +## Tracing the dependency chain between two packages {#tracing-dependency-chain} 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 @@ //third_party/openssl:crypto ``` -### Aside: implicit dependencies +### Aside: implicit dependencies {#implicit-dependencies} The BUILD file for `//foo` never references `//translations/tools:aggregator`. So, where's the direct dependency? @@ -104,7 +104,7 @@ 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,41 +115,41 @@ 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 packages exist beneath `foo`? {#what-exists-beneath-foo} ```bazel query 'foo/...' --output package``` -#### What rules are defined in the `foo` package? +#### What rules are defined in the `foo` package? {#rules-defined-in-foo} ```bazel query 'kind(rule, foo:*)' --output label_kind``` -#### What files are generated by rules in the `foo` package? +#### What files are generated by rules in the `foo` package? {#files-generated-by-rules} ```bazel query 'kind("generated file", //foo:*)'``` -#### What targets are generated by starlark macro `foo`? +#### What targets are generated by starlark macro `foo`? {#targets-generated-by-foo} ```bazel query 'attr(generator_function, foo, //path/to/search/...)'``` -#### What's the set of BUILD files needed to build `//foo`? +#### What's the set of BUILD files needed to build `//foo`? {#build-files-required} ```bazel query 'buildfiles(deps(//foo))' | cut -f1 -d:``` -#### What are the individual tests that a `test_suite` expands to? +#### What are the individual tests that a `test_suite` expands to? {#individual-tests-in-testsuite} ```bazel query 'tests(//foo:smoke_tests)'``` -#### Which of those are C++ tests? +#### Which of those are C++ tests? {#cxx-tests} ```bazel query 'kind(cc_.*, tests(//foo:smoke_tests))'``` -#### Which of those are small? Medium? Large? +#### Which of those are small? Medium? Large? {#size-of-tests} ``` bazel query 'attr(size, small, tests(//foo:smoke_tests))' @@ -159,7 +159,7 @@ bazel query 'attr(size, large, tests(//foo:smoke_tests))' ``` -#### What are the tests beneath `foo` that match a pattern? +#### What are the tests beneath `foo` that match a pattern? {#tests-beneath-foo} ```bazel query 'filter("pa?t", kind(".*_test rule", //foo/...))'``` @@ -167,54 +167,54 @@ ```bazel query 'kind(".*_test rule", //foo/...)' | grep -E 'pa?t'``` -#### What package contains file `path/to/file/bar.java`? +#### What package contains file `path/to/file/bar.java`? {#barjava-package} ``` bazel query path/to/file/bar.java --output=package``` -#### What is the build label for `path/to/file/bar.java?` +#### What is the build label for `path/to/file/bar.java?` {#barjava-build-label} ```bazel query path/to/file/bar.java``` -#### What rule target(s) contain file `path/to/file/bar.java` as a source? +#### What rule target(s) contain file `path/to/file/bar.java` as a source? {#barjava-rule-targets} ``` fullname=$(bazel query path/to/file/bar.java) bazel query "attr('srcs', $fullname, ${fullname//:*/}:*)" ``` -### What package dependencies exist ... +### What package dependencies exist ... {#package-dependencies} -#### What packages does `foo` depend on? (What do I need to check out to build `foo`) +#### What packages does `foo` depend on? (What do I need to check out to build `foo`) {#packages-foo-depends-on} ```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`? +#### What packages does the `foo` tree depend on, excluding `foo/contrib`? {#packages-foo-tree-depends-on} ```bazel query 'deps(foo/... except foo/contrib/...)' --output package``` -### What rule dependencies exist ... +### What rule dependencies exist ... {#rule-dependencies} -#### What genproto rules does bar depend upon? +#### What genproto rules does bar depend upon? {#genproto-rules} ```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. +#### Find the definition of some JNI (C++) library that is transitively depended upon by a Java binary rule in the servlet tree. {#jni-library} ```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 +##### ...Now find the definitions of all the Java binaries that depend on them {#java-binaries} ```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 ... +### What file dependencies exist ... {#file-dependencies} -#### What's the complete set of Java source files required to build foo? +#### What's the complete set of Java source files required to build foo? {#java-source-files} Source files: @@ -224,7 +224,7 @@ ```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? +#### What is the complete set of Java source files required to build QUX's tests? {#qux-tests} Source files: @@ -234,19 +234,19 @@ ```bazel query 'kind("generated file", deps(kind(".*_test rule", javatests/com/example/qux/...)))' | grep java$``` -### What differences in dependencies between X and Y exist ... +### What differences in dependencies between X and Y exist ... {#differences-in-dependencies} -#### What targets does `//foo` depend on that `//foo:foolib` does not? +#### What targets does `//foo` depend on that `//foo:foolib` does not? {#foo-targets} ```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? +#### What C++ libraries do the `foo` tests depend on that the `//foo` production binary does _not_ depend on? {#foo-cxx-libraries} ```bazel query 'kind("cc_library", deps(kind(".*test rule", foo/...)) except deps(//foo))'``` -### Why does this dependency exist ... +### Why does this dependency exist ... {#why-dependencies} -#### Why does `bar` depend on `groups2`? +#### Why does `bar` depend on `groups2`? {#dependency-bar-groups2} ```bazel query 'somepath(bar/...,groups2/...:*)'``` @@ -254,12 +254,12 @@ 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: +#### Show me a path from `docker/updater:updater_systest` (a `py_test`) to some `cc_library` that it depends upon: {#path-docker-cclibrary} ```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`? +#### Why does library `//photos/frontend:lib` depend on two variants of the same library `//third_party/jpeglib` and `//third_party/jpeg`? {#library-two-variants} 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 @@ -277,9 +277,9 @@ //third_party/jpeg/img:renderer ``` -### What depends on ... +### What depends on ... {#depends-on} -#### What rules under bar depend on Y? +#### What rules under bar depend on Y? {#rules-bar-y} ```bazel query 'bar/... intersect allpaths(bar/..., Y)'``` @@ -287,23 +287,23 @@ 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? +#### What targets directly depend on T, in T's package? {#targets-t} ```bazel query 'same_pkg_direct_rdeps(T)'``` -### How do I break a dependency ... +### How do I break a dependency ... {#break-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? +#### What dependency paths do I have to break to make `bar` no longer depend on X? {#break-dependency-bar-x} To output the graph to a `svg` file: ```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? +#### How many sequential steps are there in the `//foo-tests` build? {#steps-footests} 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
diff --git a/docs/query/language.mdx b/docs/query/language.mdx index 6f8e0a7..767e455 100644 --- a/docs/query/language.mdx +++ b/docs/query/language.mdx
@@ -13,7 +13,7 @@ In addition to `query`, which runs on the post-loading phase target graph, Bazel includes *action graph query* and *configurable query*. -### Action graph query +### Action graph query {#aquery} 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 more details, see the [aquery reference](/query/aquery). -### Configurable query +### Configurable query {#cquery} 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 @@ 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 @@ kind("cc_library", deps(kind(".*test rule", foo/...)) except deps(//foo:foo_bin)) ``` -## Tokens: The lexical syntax +## Tokens: The lexical syntax {#tokens} Expressions in the query language are composed of the following tokens: @@ -136,7 +136,7 @@ Whitespace characters outside of a quoted word are ignored. -## Bazel query language concepts +## Bazel query language concepts {#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 @@ * **Set:** The partial order of the targets is not interesting. * **Graph:** The partial order of targets is significant. -### Cycles in the dependency graph +### Cycles in the dependency graph {#dependency-graph-cycles} Build dependency graphs should be acyclic. @@ -161,7 +161,7 @@ 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 @@ 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 @@ needed to support message translation, even though you don't intend to use that feature in your build. -### On the preservation of graph order +### On the preservation of graph order {#graph-order} Operations preserve any ordering constraints inherited from their subexpressions. You can think of @@ -235,7 +235,7 @@ `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 @@ 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: Syntax and semantics of the grammar {#expressions} This is the grammar of the Bazel query language, expressed in EBNF notation: @@ -319,7 +319,7 @@ The following sections describe each of the productions of this grammar in order. -### Target patterns +### Target patterns {#target-patterns} ``` expr ::= <var>word</var> @@ -362,7 +362,7 @@ of the result nodes against other nodes.) For more details, see the [graph order](#graph-order) section. -### Variables +### Variables {#variables} ```none expr ::= let <var>name</var> = <var>expr</var>{{ '<sub>' }}1{{ '</sub>' }} in <var>expr</var>{{ '<sub>' }}2{{ '</sub>' }} @@ -400,7 +400,7 @@ improve the conciseness of many queries, and may also lead to more efficient query evaluation. -### Parenthesized expressions +### Parenthesized expressions {#parenthesized-expressions} ```none expr ::= (<var>expr</var>) @@ -409,7 +409,7 @@ 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: intersection, union, set difference {#algebraic-set-operations} ```none expr ::= <var>expr</var> intersect <var>expr</var> @@ -453,7 +453,7 @@ Important: Use parentheses where there is any danger of ambiguity in reading a query expression. -### Read targets from an external source: set +### Read targets from an external source: set {#set} ```none expr ::= set(<var>word</var> *) @@ -491,7 +491,7 @@ 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 ::= <var>word</var> '(' <var>int</var> | <var>word</var> | <var>expr</var> ... ')' @@ -521,7 +521,7 @@ * [`visible`](#visible) -### Transitive closure of dependencies: deps +### Transitive closure of dependencies: deps {#deps} ```none expr ::= deps(<var>expr</var>) @@ -551,7 +551,7 @@ If the <var>depth</var> parameter is omitted, the search is unbounded: it computes the reflexive transitive closure of prerequisites. -### Transitive closure of reverse dependencies: rdeps +### Transitive closure of reverse dependencies: rdeps {#rdeps} ```none expr ::= rdeps(<var>expr</var>, <var>expr</var>) @@ -575,7 +575,7 @@ format.) If the <var>depth</var> parameter is omitted, the search is unbounded. -### Transitive closure of all reverse dependencies: allrdeps +### Transitive closure of all reverse dependencies: allrdeps {#allrdeps} ``` expr ::= allrdeps(<var>expr</var>) @@ -590,7 +590,7 @@ `--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 +### Direct reverse dependencies in the same package: same_pkg_direct_rdeps {#same_pkg_direct_rdeps} ``` expr ::= same_pkg_direct_rdeps(<var>expr</var>) @@ -599,7 +599,7 @@ The `same_pkg_direct_rdeps(<var>x</var>)` 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 +### Dealing with a target's package: siblings {#siblings} ``` expr ::= siblings(<var>expr</var>) @@ -608,7 +608,7 @@ The `siblings(<var>x</var>)` operator evaluates to the full set of targets that are in the same package as a target in the argument set. -### Arbitrary choice: some +### Arbitrary choice: some {#some} ``` expr ::= some(<var>expr</var>) @@ -637,7 +637,7 @@ 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 +### Path operators: somepath, allpaths {#somepath-allpaths} ``` expr ::= somepath(<var>expr</var>, <var>expr</var>) @@ -754,7 +754,7 @@ </tr> </table> -### Target kind filtering: kind +### Target kind filtering: kind {#kind} ``` expr ::= kind(<var>word</var>, <var>expr</var>) @@ -815,7 +815,7 @@ When matching for `package group`, targets ending in `:all` may not yield any results. Use `:all-targets` instead. -### Target name filtering: filter +### Target name filtering: filter {#filter} ``` expr ::= filter(<var>word</var>, <var>expr</var>) @@ -867,7 +867,7 @@ will provide a list of all `.cc` files used to build `//foo`. -### Rule attribute filtering: attr +### Rule attribute filtering: attr {#attr} ``` expr ::= attr(<var>word</var>, <var>word</var>, <var>expr</var>) @@ -960,7 +960,7 @@ 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 +### Rule visibility filtering: visible {#visible} ``` expr ::= visible(<var>expr</var>, <var>expr</var>) @@ -983,7 +983,7 @@ 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 +### Evaluation of rule attributes of type label: labels {#labels} ``` expr ::= labels(<var>word</var>, <var>expr</var>) @@ -1000,7 +1000,7 @@ with `srcs` attributes in the <var>inputs</var> set, the union of their `srcs` is returned. -### Expand and filter test_suites: tests +### Expand and filter test_suites: tests {#tests} ``` expr ::= tests(<var>expr</var>) @@ -1025,7 +1025,7 @@ that are referenced directly or indirectly via `test_suite` rules. -### Executable targets: executables +### Executable targets: executables {#executables} ``` expr ::= executables(<var>expr</var>) @@ -1039,7 +1039,7 @@ This doesn't include test targets, which can be added to the result with the [`tests`](#tests) operator. -### Package definition files: buildfiles +### Package definition files: buildfiles {#buildfiles} ``` expr ::= buildfiles(<var>expr</var>) @@ -1075,7 +1075,7 @@ misleading when formatted in a structured way, such as [`--output=xml`](#xml). -### Package definition files: rbuildfiles +### Package definition files: rbuildfiles {#rbuildfiles} ``` expr ::= rbuildfiles(<var>word</var>, ...) @@ -1107,7 +1107,7 @@ 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 +### Package definition files: loadfiles {#loadfiles} ``` expr ::= loadfiles(<var>expr</var>) @@ -1124,7 +1124,7 @@ 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,7 +1143,7 @@ `--xml:line_numbers` applies only when `--output=xml` is being used. -### On the ordering of results +### On the ordering of results {#results-ordering} Although query expressions always follow the "[law of conservation of graph order](#graph-order)", _presenting_ the results may be done @@ -1181,7 +1181,7 @@ 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 +### Print the source form of targets as they would appear in BUILD {#target-source-form} ``` --output build @@ -1197,7 +1197,7 @@ 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 the label of each target {#print-label-target} ``` --output label @@ -1225,7 +1225,7 @@ 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 the label and kind of each target {#print-target-label} ``` --output label_kind @@ -1235,7 +1235,7 @@ 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 targets in protocol buffer format {#print-target-proto} ``` --output proto @@ -1245,7 +1245,7 @@ [`QueryResult`](https://github.com/bazelbuild/bazel/blob/master/src/main/protobuf/build.proto) protocol buffer. -### Print targets in length-delimited protocol buffer format +### Print targets in length-delimited protocol buffer format {#print-target-length-delimited-proto} ``` --output streamed_proto @@ -1260,7 +1260,7 @@ 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 targets in text proto format {#print-target-textproto} ``` --output textproto @@ -1271,7 +1271,7 @@ protocol buffer but in [text format](https://protobuf.dev/reference/protobuf/textformat-spec/). -### Print targets in ndjson format +### Print targets in ndjson format {#print-target-streamed-jsonproto} ``` --output streamed_jsonproto @@ -1281,7 +1281,7 @@ [`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 the label of each target, in rank order {#print-target-label-rank-order} ``` --output minrank --output maxrank @@ -1357,7 +1357,7 @@ </tr> </table> -### Print the location of each target +### Print the location of each target {#print-target-location} ``` --output location @@ -1380,7 +1380,7 @@ information to find the actual location of the generated file, and in any case, it might not exist if a build has not yet been performed.) -### Print the set of packages +### Print the set of packages {#print-package-set} ```--output package``` @@ -1398,7 +1398,7 @@ option can be used to find the set of packages that must be checked out in order to build a given set of targets. -### Display a graph of the result +### Display a graph of the result {#display-result-graph} ```--output graph``` @@ -1424,7 +1424,7 @@ are represented by a single node. This behavior may be disabled with the `--nograph:factored` option. -#### `--graph:node_limit <var>n</var>` +#### `--graph:node_limit <var>n</var>` {#graph-nodelimit} The option specifies the maximum length of the label string for a graph node in the output. Longer labels will be truncated; -1 @@ -1434,7 +1434,7 @@ of this option. This option has no effect unless `--output=graph` is being used. -#### `--[no]graph:factored` +#### `--[no]graph:factored` {#graph-factored} By default, graphs are displayed in factored form, as explained [above](#output-graph). @@ -1444,7 +1444,7 @@ tools (such as grep). This option has no effect unless `--output=graph` is being used. -### XML +### XML {#xml} ```--output xml``` @@ -1523,12 +1523,12 @@ a `location` attribute, whose value is the target's location as printed by the [`--output location`](#print-target-location). -#### `--[no]xml:line_numbers` +#### `--[no]xml:line_numbers` {#xml-linenumbers} By default, the locations displayed in the XML output contain line numbers. When `--noxml:line_numbers` is specified, line numbers are not printed. -#### `--[no]xml:default_values` +#### `--[no]xml:default_values` {#xml-defaultvalues} By default, XML output does not include rule attribute whose value is the default value for that kind of attribute (for example, if it @@ -1536,13 +1536,13 @@ provided explicitly). This option causes such attribute values to be included in the XML output. -### Regular expressions +### Regular expressions {#regular-expressions} Regular expressions in the query language use the Java regex library, so you can use the full syntax for [`java.util.regex.Pattern`](https://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html). -### Querying with external repositories +### Querying with external repositories {#querying-external-repositories} If the build depends on rules from [external repositories](/external/overview) then query results will include these dependencies. For
diff --git a/docs/reference/flag-cheatsheet.mdx b/docs/reference/flag-cheatsheet.mdx index 275dee9..2c6be2c 100644 --- a/docs/reference/flag-cheatsheet.mdx +++ b/docs/reference/flag-cheatsheet.mdx
@@ -12,7 +12,7 @@ command line reference. </aside> -## Useful general options +## Useful general options {#useful-command} The following flags are meant to be set explicitly on the command line. @@ -86,7 +86,7 @@ </tr> </table> -## Uncover Build & Test Issues +## Uncover Build & Test Issues {#uncover-build} The following flags can help you better understand Bazel build or test errors. @@ -160,7 +160,7 @@ </tr> </table> -## Startup +## Startup {#startup} Caution: Startup flags need to be passed before the command and cause a server restart. Toggle these flags with caution. @@ -249,7 +249,7 @@ </tr> </table> -## Bazel tests +## Bazel tests {#bazel-tests} The following flags are related to Bazel test @@ -318,7 +318,7 @@ </tr> </table> -## Bazel run +## Bazel run {#bazel-run} The following flags are related to Bazel run. @@ -343,7 +343,7 @@ </table> -## User-specific bazelrc options +## User-specific bazelrc options {#user-specific-bazelrc} The following flags are related to user-specific **.bazelrc** options. @@ -423,7 +423,7 @@ </tr> </table> -## Project-specific bazelrc options +## Project-specific bazelrc options {#project-specific-bazelrc} The following flags are related to project-specific <strong>.bazelrc</strong> options.
diff --git a/docs/reference/glossary.mdx b/docs/reference/glossary.mdx index 4959f6b..c34dd9d 100644 --- a/docs/reference/glossary.mdx +++ b/docs/reference/glossary.mdx
@@ -2,7 +2,7 @@ title: 'Bazel Glossary' --- -### Action +### Action {#action} A command to run during the build, for example, a call to a compiler that takes [artifacts](#artifact) as inputs and produces other artifacts as outputs. @@ -11,14 +11,14 @@ **See also:** [Rules documentation](/extending/rules#actions) -### Action cache +### Action cache {#action-cache} An on-disk cache that stores a mapping of executed [actions](#action) to the outputs they created. The cache key is known as the [action key](#action-key). A core component for Bazel's incrementality model. The cache is stored in the output base directory and thus survives Bazel server restarts. -### Action graph +### Action graph {#action-graph} An in-memory graph of [actions](#action) and the [artifacts](#artifact) that these actions read and generate. The graph might include artifacts that exist as @@ -27,20 +27,20 @@ during the [analysis phase](#analysis-phase) and used during the [execution phase](#execution-phase). -### Action graph query (aquery) +### Action graph query (aquery) {#action-graph-query} A [query](#query-concept) tool that can query over build [actions](#action). This provides the ability to analyze how [build rules](#rule) translate into the actual work builds do. -### Action key +### Action key {#action-key} The cache key of an [action](#action). Computed based on action metadata, which might include the command to be executed in the action, compiler flags, library locations, or system headers, depending on the action. Enables Bazel to cache or invalidate individual actions deterministically. -### Analysis phase +### Analysis phase {#analysis-phase} The second phase of a build. Processes the [target graph](#target-graph) specified in [`BUILD` files](#build-file) to produce an in-memory [action @@ -48,7 +48,7 @@ [execution phase](#execution-phase). This is the phase in which rule implementations are evaluated. -### Artifact +### Artifact {#artifact} A source file or a generated file. Can also be a directory of files, known as [tree artifacts](#tree-artifact). @@ -59,7 +59,7 @@ An artifact that corresponds to a [file target](#target) can be addressed by a label. -### Aspect +### Aspect {#aspect} A mechanism for rules to create additional [actions](#action) in their dependencies. For example, if target A depends on B, one can apply an aspect on @@ -71,7 +71,7 @@ **See also:** [Aspects documentation](/extending/aspects) -### Aspect-on-aspect +### Aspect-on-aspect {#aspect-on-aspect} A composition mechanism whereby aspects can be applied to the results of other aspects. For example, an aspect that generates information for use by @@ -83,14 +83,14 @@ must match what `A` declares it wants in its [`required_aspect_providers`](/rules/lib/globals#aspect.required_aspect_providers) attribute. -### Attribute +### Attribute {#attribute} A parameter to a [rule](#rule), used to express per-target build information. Examples include `srcs`, `deps`, and `copts`, which respectively declare a target's source files, dependencies, and custom compiler options. The particular attributes available for a given target depend on its rule type. -### .bazelrc +### .bazelrc {#bazelrc} Bazel’s configuration file used to change the default values for [startup flags](#startup-flags) and [command flags](#command-flags), and to define common @@ -99,12 +99,12 @@ (systemwide, per-workspace, per-user, or from a custom location), and a `bazelrc` file may also import settings from other `bazelrc` files. -### Blaze +### Blaze {#blaze} The Google-internal version of Bazel. Google’s main build system for its mono-repository. -### BUILD File +### BUILD File {#build-file} A `BUILD` file is the main configuration file that tells Bazel what software outputs to build, what their dependencies are, and how to build them. Bazel @@ -115,12 +115,12 @@ [targets](#target) created by [rules](#rule). The file can also be named `BUILD.bazel`. -### BUILD.bazel File +### BUILD.bazel File {#build-bazel-file} See [`BUILD` File](#build-file). Takes precedence over a `BUILD` file in the same directory. -### .bzl File +### .bzl File {#bzl-file} A file that defines rules, [macros](#macro), and constants written in [Starlark](#starlark). These can then be imported into [`BUILD` @@ -130,7 +130,7 @@ {/* TODO: ### Build flag */} -### Build graph +### Build graph {#build-graph} The dependency graph that Bazel constructs and traverses to perform a build. Includes nodes like [targets](#target), [configured @@ -138,21 +138,21 @@ build is considered complete when all [artifacts](#artifact) on which a set of requested targets depend are verified as up-to-date. -### Build setting +### Build setting {#build-setting} A Starlark-defined piece of [configuration](#configuration). [Transitions](#transition) can set build settings to change a subgraph's configuration. If exposed to the user as a [command-line flag](#command-flags), also known as a build flag. -### Clean build +### Clean build {#clean-build} A build that doesn't use the results of earlier builds. This is generally slower than an [incremental build](#incremental-build) but commonly considered to be more [correct](#correctness). Bazel guarantees both clean and incremental builds are always correct. -### Client-server model +### Client-server model {#client-server-model} The `bazel` command-line client automatically starts a background server on the local machine to execute Bazel [commands](#command). The server persists across @@ -161,12 +161,12 @@ startup time and supports faster [incremental builds](#incremental-build) because the [action graph](#action-graph) remains in memory across commands. -### Command +### Command {#command} Used on the command line to invoke different Bazel functions, like `bazel build`, `bazel test`, `bazel run`, and `bazel query`. -### Command flags +### Command flags {#command-flags} A set of flags specific to a [command](#command). Command flags are specified *after* the command (`bazel build <command flags>`). Flags can be applicable to @@ -176,7 +176,7 @@ purposes, so changes in flag values can cause Bazel to invalidate in-memory graphs and restart the [analysis phase](#analysis-phase). -### Configuration +### Configuration {#configuration} Information outside of [rule](#rule) definitions that impacts how rules generate [actions](#action). Every build has at least one configuration specifying the @@ -188,7 +188,7 @@ {/* TODO: ### Configuration fragment */} -### Configuration trimming +### Configuration trimming {#config-trimming} The process of only including the pieces of [configuration](#configuration) a target actually needs. For example, if you build Java binary `//:j` with C++ @@ -196,7 +196,7 @@ configuration of `//:c` because changing `--javacopt` unnecessarily breaks C++ build cacheability. -### Configured query (cquery) +### Configured query (cquery) {#configured-query} A [query](#query-concept) tool that queries over [configured targets](#configured-target) (after the [analysis phase](#analysis-phase) @@ -205,7 +205,7 @@ **See also:** [cquery documentation](/query/cquery) -### Configured target +### Configured target {#configured-target} The result of evaluating a [target](#target) with a [configuration](#configuration). The [analysis phase](#analysis-phase) produces @@ -213,7 +213,7 @@ For example, if `//:foo` builds for two different architectures in the same build, it has two configured targets: `<//:foo, x86>` and `<//:foo, arm>`. -### Correctness +### Correctness {#correctness} A build is correct when its output faithfully reflects the state of its transitive inputs. To achieve correct builds, Bazel strives to be @@ -221,7 +221,7 @@ analysis](#analysis-phase) and [action execution](#execution-phase) deterministic. -### Dependency +### Dependency {#dependency} A directed edge between two [targets](#target). A target `//:foo` has a *target dependency* on target `//:bar` if `//:foo`'s attribute values contain a @@ -232,7 +232,7 @@ In certain contexts, it could also refer to an _external dependency_; see [modules](#module). -### Depset +### Depset {#depset} A data structure for collecting data on transitive dependencies. Optimized so that merging depsets is time and space efficient, because it’s common to have @@ -245,17 +245,17 @@ **See also:** [Depset documentation](/extending/depsets) -### Disk cache +### Disk cache {#disk-cache} A local on-disk blob store for the remote caching feature. Can be used in conjunction with an actual remote blob store. -### Distdir +### Distdir {#distdir} A read-only directory containing files that Bazel would otherwise fetch from the internet using repository rules. Enables builds to run fully offline. -### Dynamic execution +### Dynamic execution {#dynamic-execution} An execution strategy that selects between local and remote execution based on various heuristics, and uses the execution results of the faster successful @@ -264,7 +264,7 @@ compilation). A dynamic execution strategy can provide the best possible incremental and clean build times. -### Execution phase +### Execution phase {#execution-phase} The third phase of a build. Executes the [actions](#action) in the [action graph](#action-graph) created during the [analysis phase](#analysis-phase). @@ -272,7 +272,7 @@ [artifacts](#artifact). *Spawn strategies* control how these actions are executed: locally, remotely, dynamically, sandboxed, docker, and so on. -### Execution root +### Execution root {#execution-root} A directory in the [workspace](#workspace)’s [output base](#output-base) directory where local [actions](#action) are executed in @@ -284,11 +284,11 @@ closure of packages on which a build depends. Accessible with `bazel info execution_root` on the command line. -### File +### File {#file} See [Artifact](#artifact). -### Hermeticity +### Hermeticity {#hermeticity} A build is hermetic if there are no external influences on its build and test operations, which helps to make sure that results are deterministic and @@ -297,7 +297,7 @@ timezones, restrict access to environment variables, and use fixed seeds for random number generators -### Incremental build +### Incremental build {#incremental-build} An incremental build reuses the results of earlier builds to reduce build time and resource usage. Dependency checking and caching aim to produce correct @@ -306,7 +306,7 @@ {/* TODO: ### Install base */} -### Label +### Label {#label} An identifier for a [target](#target). Generally has the form `@repo//path/to/package:target`, where `repo` is the (apparent) name of the @@ -318,7 +318,7 @@ **See also**: [Labels](/concepts/labels) -### Loading phase +### Loading phase {#loading-phase} The first phase of a build where Bazel executes [`BUILD` files](#build-file) to create [packages](#package). [Macros](#macro) and certain functions like @@ -326,7 +326,7 @@ build, the [analysis phase](#analysis-phase), to build up a [target graph](#target-graph). -### Legacy macro +### Legacy macro {#legacy-macro} A flavor of [macro](#macro) which is declared as an ordinary [Starlark](#starlark) function, and which runs as a side effect of executing a @@ -341,7 +341,7 @@ **See also:** [Legacy macro documentation](/extending/legacy-macros) -### Macro +### Macro {#macro} A mechanism to compose multiple [rule](#rule) target declarations together under a single [Starlark](#starlark) callable. Enables reusing common rule declaration @@ -351,7 +351,7 @@ Comes in two flavors: [symbolic macros](#symbolic-macro) (since Bazel 8) and [legacy macros](#legacy-macro). -### Mnemonic +### Mnemonic {#mnemonic} A short, human-readable string selected by a rule author to quickly understand what an [action](#action) in the rule is doing. Mnemonics can be used as @@ -359,7 +359,7 @@ are `Javac` from Java rules, `CppCompile` from C++ rules, and `AndroidManifestMerger` from Android rules. -### Module +### Module {#module} A Bazel project that can have multiple versions, each of which can have dependencies on other modules. This is analogous to familiar concepts in other @@ -376,7 +376,7 @@ **See also:** [Bazel modules](/external/module) -### Module Extension +### Module Extension {#module-extension} A piece of logic that can be run to generate [repos](#repository) by reading inputs from across the [module](#module) dependency graph and invoking [repo @@ -385,20 +385,20 @@ **See also:** [Module extensions](/external/extension) -### Native rules +### Native rules {#native-rules} [Rules](#rule) that are built into Bazel and implemented in Java. Such rules appear in [`.bzl` files](#bzl-file) as functions in the native module (for example, `native.cc_library` or `native.java_library`). User-defined rules (non-native) are created using [Starlark](#starlark). -### Output base +### Output base {#output-base} A [workspace](#workspace)-specific directory to store Bazel output files. Used to separate outputs from the *workspace*'s source tree (the [main repo](#repository)). Located in the [output user root](#output-user-root). -### Output groups +### Output groups {#output-groups} A group of files that is expected to be built when Bazel finishes building a target. [Rules](#rule) put their usual outputs in the "default output group" @@ -409,7 +409,7 @@ [`BUILD` files](#build-file) (`filegroup` rule) or the command line (`--output_groups` flag). -### Output user root +### Output user root {#output-user-root} A user-specific directory to store Bazel's outputs. The directory name is derived from the user's system username. Prevents output file collisions if @@ -417,25 +417,25 @@ Contains subdirectories corresponding to build outputs of individual workspaces, also known as [output bases](#output-base). -### Package +### Package {#package} The set of [targets](#target) defined by a [`BUILD` file](#build-file). A package's name is the `BUILD` file's path relative to the [repo](#repository) root. A package can contain subpackages, or subdirectories containing `BUILD` files, thus forming a package hierarchy. -### Package group +### Package group {#package-group} A [target](#target) representing a set of packages. Often used in `visibility` attribute values. -### Platform +### Platform {#platform} A "machine type" involved in a build. This includes the machine Bazel runs on (the "host" platform), the machines build tools execute on ("exec" platforms), and the machines targets are built for ("target platforms"). -### Provider +### Provider {#provider} A schema describing a unit of information to pass between [rule targets](#rule-target) along dependency relationships. Typically this @@ -450,14 +450,14 @@ **See also:** [Provider documentation](/extending/rules#providers) -### Query (concept) +### Query (concept) {#query-concept} The process of analyzing a [build graph](#build-graph) to understand [target](#target) properties and dependency structures. Bazel supports three query variants: [query](#query-command), [cquery](#configured-query), and [aquery](#action-graph-query). -### query (command) +### query (command) {#query-command} A [query](#query-concept) tool that operates over the build's post-[loading phase](#loading-phase) [target graph](#target-graph). This is relatively fast, @@ -466,7 +466,7 @@ **See also:** [Query how-to](/query/guide), [Query reference](/query/language) -### 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**. @@ -488,7 +488,7 @@ **See also**: [External dependencies overview](/external/overview) -### Repository cache +### Repository cache {#repo-cache} A shared content-addressable cache of files downloaded by Bazel for builds, shareable across [workspaces](#workspace). Enables offline builds after the @@ -497,7 +497,7 @@ `repository_ctx.download`. Files are cached only if their SHA-256 checksums are specified for the download. -### Repository rule +### Repository rule {#repository-rule} A schema for repository definitions that tells Bazel how to materialize (or "fetch") a [repository](#repository). Often shortened to just **repo rule**. @@ -509,14 +509,14 @@ **See also:** [Repo rule documentation](/external/repo) -### Reproducibility +### Reproducibility {#reproducibility} The property of a build or test that a set of inputs to the build or test will always produce the same set of outputs every time, regardless of time, method, or environment. Note that this does not necessarily imply that the outputs are [correct](#correctness) or the desired outputs. -### Rule +### Rule {#rule} A schema for defining [rule targets](#rule-target) in a `BUILD` file, such as `cc_library`. From the perspective of a `BUILD` file author, a rule consists of @@ -539,12 +539,12 @@ **See also:** [Rules documentation](/extending/rules) -### Rule target +### Rule target {#rule-target} A [target](#target) that is an instance of a rule. Contrasts with file targets and package groups. Not to be confused with [rule](#rule). -### Runfiles +### Runfiles {#runfiles} The runtime dependencies of an executable [target](#target). Most commonly, the executable is the executable output of a test rule, and the runfiles are runtime @@ -554,7 +554,7 @@ **See also:** [Runfiles documentation](/extending/rules#runfiles) -### Sandboxing +### Sandboxing {#sandboxing} A technique to isolate a running [action](#action) inside a restricted and temporary [execution root](#execution-root), helping to ensure that it doesn’t @@ -563,13 +563,13 @@ support from the operating system. The performance cost depends on the platform. On Linux, it's not significant, but on macOS it can make sandboxing unusable. -### Skyframe +### Skyframe {#skyframe} [Skyframe](/reference/skyframe) is the core parallel, functional, and incremental evaluation framework of Bazel. {/* TODO: ### Spawn strategy */} -### Stamping +### Stamping {#stamping} A feature to embed additional information into Bazel-built [artifacts](#artifact). For example, this can be used for source control, build @@ -577,7 +577,7 @@ Enable through the `--workspace_status_command` flag and [rules](/extending/rules) that support the stamp attribute. -### Starlark +### Starlark {#starlark} The extension language for writing [rules](/extending/rules) and [macros](#macro). A restricted subset of Python (syntactically and grammatically) aimed for the @@ -592,7 +592,7 @@ {/* TODO: ### Starlark rule sandwich */} -### Startup flags +### Startup flags {#startup-flags} The set of flags specified between `bazel` and the [command](#query-command), for example, bazel `--host_jvm_debug` build. These flags modify the @@ -600,7 +600,7 @@ startup flags causes a server restart. Startup flags are not specific to any command. -### Symbolic macro +### Symbolic macro {#symbolic-macro} A flavor of [macro](#macro) which is declared with a [rule](#rule)-like [attribute](#attribute) schema, allows hiding internal declared @@ -610,7 +610,7 @@ **See also:** [Symbolic macro documentation](/extending/macros) -### Target +### Target {#target} An object that is defined in a [`BUILD` file](#build-file) and identified by a [label](#label). Targets represent the buildable units of a workspace from @@ -632,13 +632,13 @@ configurations](#configuration) to form [configured targets](#configured-target). -### Target graph +### Target graph {#target-graph} An in-memory graph of [targets](#target) and their dependencies. Produced during the [loading phase](#loading-phase) and used as an input to the [analysis phase](#analysis-phase). -### Target pattern +### Target pattern {#target-pattern} A way to specify a group of [targets](#target) on the command line. Commonly used patterns are `:all` (all rule targets), `:*` (all rule + file targets), @@ -646,7 +646,7 @@ in combination, for example, `//...:*` means all rule and file targets in all packages recursively from the root of the [workspace](#workspace). -### Tests +### Tests {#tests} Rule [targets](#target) instantiated from test rules, and therefore contains a test executable. A return code of zero from the completion of the executable @@ -654,7 +654,7 @@ environment variables, test result collection methods) is specified in the [Test Encyclopedia](/reference/test-encyclopedia). -### Toolchain +### Toolchain {#toolchain} A set of tools to build outputs for a language. Typically, a toolchain includes compilers, linkers, interpreters or/and linters. A toolchain can also vary by @@ -662,7 +662,7 @@ Windows variant, even though the toolchain is for the same language. Selecting the right toolchain for the platform is known as toolchain resolution. -### Top-level target +### Top-level target {#top-level-target} A build [target](#target) is top-level if it’s requested on the Bazel command line. For example, if `//:foo` depends on `//:bar`, and `bazel build //:foo` is @@ -674,7 +674,7 @@ targets, but might be modified by a [transition](#transition) for non-top-level targets. -### Transition +### Transition {#transition} A mapping of [configuration](#configuration) state from one value to another. Enables [targets](#target) in the [build graph](#build-graph) to have different @@ -686,13 +686,13 @@ **See also:** [User-defined transitions](/extending/config#user-defined-transitions) -### Tree artifact +### Tree artifact {#tree-artifact} An [artifact](#artifact) that represents a collection of files. Since these files are not themselves artifacts, an [action](#action) operating on them must instead register the tree artifact as its input or output. -### Visibility +### Visibility {#visibility} One of two mechanisms for preventing unwanted dependencies in the build system: *target visibility* for controlling whether a [target](#target) can be depended @@ -702,7 +702,7 @@ **See also:** [Visibility documentation](/concepts/visibility) -### Workspace +### Workspace {#workspace} The environment shared by all Bazel commands run from the same [main repository](#repository).
diff --git a/docs/reference/test-encyclopedia.mdx b/docs/reference/test-encyclopedia.mdx index f2a3cbf..b613577 100644 --- a/docs/reference/test-encyclopedia.mdx +++ b/docs/reference/test-encyclopedia.mdx
@@ -4,7 +4,7 @@ An exhaustive specification of the test execution environment. -## Background +## Background {#background} The Bazel BUILD language includes rules which can be used to define automated test programs in many languages. @@ -22,7 +22,7 @@ testing frameworks ought not DDOS a server because some tests happen to talk to it). -## Objective +## Objective {#objective} The goal of this page is to formally establish the runtime environment for and expected behavior of Bazel tests. It will also impose requirements on the test @@ -38,13 +38,13 @@ specification and the implemented behavior of test runner disagree, the specification takes precedence. -## Proposed Specification +## Proposed Specification {#proposed-specification} The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" are to be interpreted as described in IETF RFC 2119. -## Purpose of tests +## Purpose of tests {#purpose-of-tests} The purpose of Bazel tests is to confirm some property of the source files checked into the repository. (On this page, "source files" includes test data, @@ -64,7 +64,7 @@ Currently, such behavior is not enforced. However, test runners reserve the right to add such enforcement in the future. -## Role of the build system +## Role of the build system {#role-build-system} Test rules are analogous to binary rules in that each must yield an executable program. For some languages, this is a stub program which combines a @@ -81,7 +81,7 @@ image provided by the test runner, rather than hardcoded references to absolute locations in the source or output tree. -## Role of the test runner +## Role of the test runner {#role-test-runner} From the point of view of the test runner, each test is a program which can be invoked with `execve()`. There may be other ways to execute tests; for example, @@ -210,7 +210,7 @@ failure based on the exit code observed from the main process. The test runner may kill any stray processes. Tests should not leak processes in this fashion. -## Test sharding +## Test sharding {#test-sharding} Tests can be parallelized via test sharding. See [`--test_sharding_strategy`](/reference/command-line-reference#flag--test_sharding_strategy) @@ -225,7 +225,7 @@ [`TEST_SHARD_STATUS_FILE`](#initial-conditions), otherwise Bazel will fail the test if it is sharded. -## Initial conditions +## Initial conditions {#initial-conditions} When executing a test, the test runner must establish certain initial conditions. @@ -565,13 +565,13 @@ The initial scheduling policy and priority are unspecified. -## Role of the host system +## Role of the host system {#role-host-system} In addition to the aspects of user context under direct control of the test runner, the operating system on which tests execute must satisfy certain properties for a test run to be valid. -#### Filesystem +#### Filesystem {#filesystem} The root directory observed by a test may or may not be the real root directory. @@ -590,7 +590,7 @@ Tests must not assume that atimes are enabled for any mounted filesystem. -#### Users and groups +#### Users and groups {#users-groups} The users root, nobody, and unittest must exist. The groups root, nobody, and eng must exist. @@ -607,13 +607,13 @@ The current user must have a home directory. It may not be writable. Tests must not attempt to write to it. -#### Networking +#### Networking {#networking} The hostname is unspecified. It may or may not contain a dot. Resolving the hostname must give an IP address of the current host. Resolving the hostname cut after the first dot must also work. The hostname localhost must resolve. -#### Other resources +#### Other resources {#other-resources} Tests are granted at least one CPU core. Others may be available but this is not guaranteed. Other performance aspects of this core are not specified. You can @@ -628,14 +628,14 @@ There is a limit on the number of input files a test may consume. This limit is subject to change, but is currently in the range of tens of thousands of inputs. -#### Time and date +#### Time and date {#time-and-date} The current time and date are unspecified. The system timezone is unspecified. X Windows may or may not be available. Tests that need an X server should start Xvfb. -## Test interaction with the filesystem +## Test interaction with the filesystem {#test-interaction-filesystem} All file paths specified in test environment variables point to somewhere on the local filesystem, unless otherwise specified. @@ -696,7 +696,7 @@ file when the test finishes, it will assume that the test exited prematurely and mark it as having failed. -## Execution platform +## Execution platform {#execution-platform} The [execution platform](/extending/platforms) for a test action is determined via [toolchain resolution](/extending/toolchains#toolchain-resolution), just @@ -738,7 +738,7 @@ Test rule authors can define their own test toolchain type and also register a default toolchain for it. -## Tag conventions +## Tag conventions {#tag-conventions} Some tags in the test rules have a special meaning. See also the @@ -784,19 +784,19 @@ Note: bazel `query` does not respect the manual tag. -## Runfiles +## Runfiles {#runfiles} In the following, assume there is a *_binary() rule labeled `//foo/bar:unittest`, with a run-time dependency on the rule labeled `//deps/server:server`. -#### Location +#### Location {#runfiles-location} The runfiles directory for a target `//foo/bar:unittest` is the directory `$(WORKSPACE)/$(BINDIR)/foo/bar/unittest.runfiles`. This path is referred to as the `runfiles_dir`. -#### Dependencies +#### Dependencies {#runfiles-dependencies} The runfiles directory is declared as a compile-time dependency of the `*_binary()` rule. The runfiles directory itself depends on the set of BUILD @@ -804,7 +804,7 @@ dependencies. Modifying source files does not affect the structure of the runfiles directory, and thus does not trigger any rebuilding. -#### Contents +#### Contents {#runfiles-contents} The runfiles directory contains the following:
diff --git a/docs/release/backward-compatibility.mdx b/docs/release/backward-compatibility.mdx index af653cc..780e9f7 100644 --- a/docs/release/backward-compatibility.mdx +++ b/docs/release/backward-compatibility.mdx
@@ -14,7 +14,7 @@ For more information about Bazel's release model, please check out the [Release Model](/release) page. -## Summary +## Summary {#summary} 1. It is recommended to use `--incompatible_*` flags for breaking changes. 1. For every `--incompatible_*` flag, a GitHub issue explains the change in @@ -26,13 +26,13 @@ 1. Never run production builds with `--experimental_*` or `--incompatible_*` flags. -## How to follow this policy +## How to follow this policy {#policy} * [For Bazel users - how to update Bazel](/install/bazelisk) * [For contributors - best practices for incompatible changes](/contribute/breaking-changes) * [For release managers - how to update issue labels and release](https://github.com/bazelbuild/continuous-integration/tree/master/docs/release-playbook.%6D%64) -## What is stable functionality? +## What is stable functionality? {#stable-functionality} In general, APIs or behaviors without `--experimental_...` flags are considered stable, supported features in Bazel. @@ -44,7 +44,7 @@ * Bazel APIs such as Remote Execution APIs or Build Event Protocol * Flags and their semantics -## Incompatible changes and migration recipes +## Incompatible changes and migration recipes {#incompatible-changes} For every incompatible change in a new release, the Bazel team aims to provide a _migration recipe_ that helps you update your code (`BUILD` and `.bzl` files, as @@ -58,7 +58,7 @@ to migrate for the incompatible changes before the next LTS release is available. -## Communicating incompatible changes +## Communicating incompatible changes {#communicating-incompatible-changes} The primary source of information about incompatible changes are GitHub issues marked with an ["incompatible-change"
diff --git a/docs/release/index.mdx b/docs/release/index.mdx index 84e6e4d..48d9eb1 100644 --- a/docs/release/index.mdx +++ b/docs/release/index.mdx
@@ -10,7 +10,7 @@ releases and long term support (LTS) releases. This page covers the latest information about Bazel's release model. -## Support matrix +## Support matrix {#support-matrix} | LTS release | Support stage | Latest version | End of support | | ----------- | ------------- | -------------- | -------------- | @@ -25,7 +25,7 @@ All Bazel LTS releases can be found on the [release page](https://github.com/bazelbuild/bazel/releases) on GitHub. -## Release versioning +## Release versioning {#bazel-versioning} Bazel uses a _major.minor.patch_ [Semantic Versioning](https://semver.org/) scheme. @@ -46,7 +46,7 @@ * Patch: 6.1.2 * Pre-release: 7.0.0-pre.20230502.1 -## Support stages +## Support stages {#support-stages} For each major Bazel version, there are four support stages: @@ -60,11 +60,11 @@ * **Deprecated**: The Bazel team no longer provides support for this major version, all users should migrate to newer Bazel LTS releases. -## Release cadence +## Release cadence {#release-cadence} Bazel regularly publish releases for two release tracks. -### Rolling releases +### Rolling releases {#rolling-releases} * Rolling releases are coordinated with Google Blaze release and are released from HEAD around every two weeks. It is a preview of the next Bazel LTS @@ -74,7 +74,7 @@ should follow our [backward compatibility policy](/release/backward-compatibility). -### LTS releases +### LTS releases {#lts-releases} * _Major release_: A new LTS release is expected to be cut from HEAD roughly every @@ -92,7 +92,7 @@ issues](https://github.com/bazelbuild/bazel/issues?q=is%3Aopen+is%3Aissue+label%3Arelease) on Github. -## Release procedure & policies +## Release procedure & policies {#release-procedure-policies} For rolling releases, the process is straightforward: about every two weeks, a new release is created, aligning with the same baseline as the Google internal @@ -183,7 +183,7 @@ the Bazel team monitors and addresses community bug reports for the new release. -## Report regressions +## Report regressions {#report-regressions} If a user finds a regression in a new Bazel release, release candidate or even Bazel at HEAD, please file a bug on @@ -206,7 +206,7 @@ Remember to upgrade Bazelisk to the latest version to use the bisect feature. -## Rule compatibility +## Rule compatibility {#rule-compatibility} If you are a rule authors and want to maintain compatibility with different Bazel versions, please check out the [Rule
diff --git a/docs/release/rolling.mdx b/docs/release/rolling.mdx index ba7ba91..e4a87b3 100644 --- a/docs/release/rolling.mdx +++ b/docs/release/rolling.mdx
@@ -9,6 +9,6 @@ [Bazelisk](https://github.com/bazelbuild/bazelisk) is the best way to use these releases. -## Index +## Index {#index} <iframe src="https://releases.bazel.build/rolling.html" style="height: 3000px; width: 100%" ></iframe>
diff --git a/docs/release/rule-compatibility.mdx b/docs/release/rule-compatibility.mdx index 05a8a95..2a00588 100644 --- a/docs/release/rule-compatibility.mdx +++ b/docs/release/rule-compatibility.mdx
@@ -18,7 +18,7 @@ page covers how rules authors should maintain rule compatibility with Bazel to make it easier for users to upgrade Bazel and rules. -## Manageable migration process +## Manageable migration process {#manageable-migration-process} While it's obviously not feasible to guarantee compatibility between every version of Bazel and every version of the rule, our aim is to ensure that the @@ -50,7 +50,7 @@ ✅: At least one version of the rule is compatible with the latest version of the Bazel LTS release. -## Best practices +## Best practices {#best-practices} As Bazel rules authors, you can ensure a manageable migration process for users by following these best practices:
diff --git a/docs/remote/bep-examples.mdx b/docs/remote/bep-examples.mdx index faf11bf..7b3f406 100644 --- a/docs/remote/bep-examples.mdx +++ b/docs/remote/bep-examples.mdx
@@ -100,7 +100,7 @@ } ``` -## Aspect Results in BEP +## Aspect Results in BEP {#aspect-results} Ordinary builds evaluate actions associated with `(target, configuration)` pairs. When building with [aspects](/extending/aspects) enabled, Bazel @@ -142,7 +142,7 @@ field. A tool that does not check the `aspect` ID field and accumulates output files by target may conflate target outputs with aspect outputs. -## Consuming `NamedSetOfFiles` +## Consuming `NamedSetOfFiles` {#consuming-namedsetoffiles} Determining the artifacts produced by a given target (or aspect) is a common BEP use-case that can be done efficiently with some preparation. This section
diff --git a/docs/remote/bep-glossary.mdx b/docs/remote/bep-glossary.mdx index 3bd11ee..d40d13f 100644 --- a/docs/remote/bep-glossary.mdx +++ b/docs/remote/bep-glossary.mdx
@@ -8,7 +8,7 @@ [build\_event\_stream.proto](https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/buildeventstream/proto/build_event_stream.proto). The following glossary describes each event type. -## Aborted +## Aborted {#aborted} Unlike other events, `Aborted` does not have a corresponding ID type, because the `Aborted` event *replaces* events of other types. This event indicates that @@ -35,7 +35,7 @@ } ``` -## ActionExecuted +## ActionExecuted {#actionexecuted} Provides details about the execution of a specific [Action](/rules/lib/actions) in a build. By default, this event is @@ -43,19 +43,19 @@ of build failures. Users may set the `--build_event_publish_all_actions` flag to include all `ActionExecuted` events. -## BuildFinished +## BuildFinished {#buildfinished} A single `BuildFinished` event is sent after the command is complete and includes the exit code for the command. This event provides authoritative success/failure information. -## BuildMetadata +## BuildMetadata {#buildmetadata} Contains the parsed contents of the `--build_metadata` flag. This event exists to support Bazel integration with other tooling by plumbing external data (such as identifiers). -## BuildMetrics +## BuildMetrics {#buildmetrics} A single `BuildMetrics` event is sent at the end of every command and includes counters/gauges useful for quantifying the build tool's behavior during the @@ -92,12 +92,12 @@ } ``` -## BuildStarted +## BuildStarted {#buildstarted} The first event in a BEP stream, `BuildStarted` includes metadata describing the command before any meaningful work begins. -## BuildToolLogs +## BuildToolLogs {#buildtoollogs} A single `BuildToolLogs` event is sent at the end of a command, including URIs of files generated by the build tool that may aid in understanding or debugging @@ -128,7 +128,7 @@ } ``` -## CommandLine +## CommandLine {#commandline} The BEP contains multiple `CommandLine` events containing representations of all command-line arguments (including options and uninterpreted arguments). @@ -145,7 +145,7 @@ which is used directly, or a string which is parsed but not interpreted (as the tool's options may differ from Bazel's). -## Configuration +## Configuration {#configuration} A `Configuration` event is sent for every [`configuration`](/extending/config) used in the top-level targets in a build. At least one configuration event is @@ -174,7 +174,7 @@ } ``` -## ConvenienceSymlinksIdentified +## ConvenienceSymlinksIdentified {#conveniencesymlinksidentified} **Experimental.** If the `--experimental_convenience_symlinks_bep_event` option is set, a single `ConvenienceSymlinksIdentified` event is produced by @@ -209,13 +209,13 @@ } ``` -## Fetch +## Fetch {#fetch} Indicates that a Fetch operation occurred as a part of the command execution. Unlike other events, if a cached fetch result is re-used, this event does not appear in the BEP stream. -## NamedSetOfFiles +## NamedSetOfFiles {#namedsetoffiles} `NamedSetOfFiles` events report a structure matching a [`depset`](/extending/depsets) of files produced during command evaluation. @@ -224,7 +224,7 @@ For more information on interpreting a stream's `NamedSetOfFiles` events, see the [BEP examples page](/remote/bep-examples#consuming-namedsetoffiles). -## OptionsParsed +## OptionsParsed {#optionsparsed} A single `OptionsParsed` event lists all options applied to the command, separating startup options from command options. It also includes the @@ -262,7 +262,7 @@ } ``` -## PatternExpanded +## PatternExpanded {#patternexpanded} `PatternExpanded` events indicate the set of all targets that match the patterns supplied on the commandline. For successful commands, a single event is present @@ -292,14 +292,14 @@ } ``` -## Progress +## Progress {#progress} Progress events contain the standard output and standard error produced by Bazel during command execution. These events are also auto-generated as needed to announce events that have not been announced by a logical "parent" event (in particular, [NamedSetOfFiles](#namedsetoffiles).) -## TargetComplete +## TargetComplete {#targetcomplete} For each `(target, configuration, aspect)` combination that completes the execution phase, a `TargetComplete` event is included in BEP. The event contains @@ -331,7 +331,7 @@ } ``` -## TargetConfigured +## TargetConfigured {#targetconfigured} For each Target that completes the analysis phase, a `TargetConfigured` event is included in BEP. This is the authoritative source for a target's "rule kind" @@ -373,20 +373,20 @@ } ``` -## TargetSummary +## TargetSummary {#targetsummary} For each `(target, configuration)` pair that is executed, a `TargetSummary` event is included with an aggregate success result encompassing the configured target's execution and all aspects applied to that configured target. -## TestResult +## TestResult {#testresult} If testing is requested, a `TestResult` event is sent for each test attempt, shard, and run per test. This allows BEP consumers to identify precisely which test actions failed their tests and identify the test outputs (such as logs, test.xml files) for each test action. -## TestSummary +## TestSummary {#testsummary} If testing is requested, a `TestSummary` event is sent for each test `(target, configuration)`, containing information necessary to interpret the test's @@ -395,7 +395,7 @@ and runs per test are considered while producing the aggregate `TestStatus` to differentiate `FLAKY` tests from `FAILED` tests. -## UnstructuredCommandLine +## UnstructuredCommandLine {#unstructuredcommandline} Unlike [CommandLine](#commandline), this event carries the unparsed commandline flags in string form as encountered by the build tool after expanding all @@ -405,12 +405,12 @@ The `UnstructuredCommandLine` event may be relied upon to precisely reproduce a given command execution. -## WorkspaceConfig +## WorkspaceConfig {#workspaceconfig} A single `WorkspaceConfig` event contains configuration information regarding the workspace, such as the execution root. -## WorkspaceStatus +## WorkspaceStatus {#workspacestatus} A single `WorkspaceStatus` event contains the result of the [workspace status command](/docs/user-manual#workspace-status).
diff --git a/docs/remote/bep.mdx b/docs/remote/bep.mdx index bafdaa9..2cfa555 100644 --- a/docs/remote/bep.mdx +++ b/docs/remote/bep.mdx
@@ -41,7 +41,7 @@ payload might not be the expected type, but could be an `Aborted` message if the build aborted prematurely. -### Build event graph +### Build event graph {#build-event-graph} All build events form a directed acyclic graph through their parent and child relationship. Every build event except for the initial build event has one or @@ -64,9 +64,9 @@ by events containing summary information about the build (for example, metric or profiling data). -## Consuming Build Event Protocol +## Consuming Build Event Protocol {#consuming-bep} -### Consume in binary format +### Consume in binary format {#consuming-bep-binary} To consume the BEP in a binary format: @@ -81,7 +81,7 @@ 2. Then, write a program that extracts the relevant information from the serialized protocol buffer message. -### Consume in text or JSON formats +### Consume in text or JSON formats {#consuming-bep-text-json} The following Bazel command line flags will output the BEP in human-readable formats, such as text and JSON: @@ -91,7 +91,7 @@ --build_event_json_file ``` -## Build Event Service +## Build Event Service {#build-event-service} The [Build Event Service](https://github.com/googleapis/googleapis/blob/master/google/devtools/build/v1/publish_build_event.proto) @@ -103,7 +103,7 @@ you must prefix the address with the appropriate scheme: `grpc://` for plaintext gRPC and `grpcs://` for gRPC with TLS enabled. -### Build Event Service flags +### Build Event Service flags {#bes-flags} Bazel has several flags related to the Build Event Service protocol, including: @@ -116,7 +116,7 @@ For a description of each of these flags, see the [Command-Line Reference](/reference/command-line-reference). -### Authentication and security +### Authentication and security {#authentication-security} Bazel’s Build Event Service implementation also supports authentication and TLS. These settings can be controlled using the below flags. Please note that these @@ -133,7 +133,7 @@ For a description of each of these flags, see the [Command-Line Reference](/reference/command-line-reference). -### Build Event Service and remote caching +### Build Event Service and remote caching {#bes-remote-caching} The BEP typically contains many references to log files (test.log, test.xml, etc. ) stored on the machine where Bazel is running. A remote BES server
diff --git a/docs/remote/cache-local.mdx b/docs/remote/cache-local.mdx index 2d5fa81..7cb59a6 100644 --- a/docs/remote/cache-local.mdx +++ b/docs/remote/cache-local.mdx
@@ -17,7 +17,7 @@ Everything presented in that guide also applies to remote caching with local execution. However, local execution presents some additional challenges. -## Checking your cache hit rate +## Checking your cache hit rate {#cache-hits} Successful remote cache hits will show up in the status line, similar to [Cache Hits rate with Remote @@ -36,11 +36,11 @@ 0 processes (or a number lower than expected), run `bazel clean` followed by your build/test command. -## Troubleshooting cache hits +## Troubleshooting cache hits {#troubleshooting-cache-hits} If you are not getting the cache hit rate you are expecting, do the following: -### Ensure successful communication with the remote endpoint +### Ensure successful communication with the remote endpoint {#remote-endpoint-success} To ensure your build is successfully communicating with the remote cache, follow the steps in this section.
diff --git a/docs/remote/cache-remote.mdx b/docs/remote/cache-remote.mdx index 1480c03..21eb25f 100644 --- a/docs/remote/cache-remote.mdx +++ b/docs/remote/cache-remote.mdx
@@ -11,7 +11,7 @@ utilizes remote execution, and you want to ensure that you are effectively utilizing remote cache. -## Checking your cache hit rate +## Checking your cache hit rate {#check-cache-hits} In the standard output of your Bazel run, look at the `INFO` line that lists processes, which roughly correspond to Bazel actions. That line details @@ -33,11 +33,11 @@ (or a number lower than expected), run `bazel clean` followed by your build/test command. -## Troubleshooting cache hits +## Troubleshooting cache hits {#troubleshooting-cache-hits} If you are not getting the cache hit rate you are expecting, do the following: -### Ensure re-running the same build/test command produces cache hits +### Ensure re-running the same build/test command produces cache hits {#rerun-cache-hits} 1. Run the build(s) and/or test(s) that you expect to populate the cache. The first time a new build is run on a particular stack, you can expect no remote @@ -108,7 +108,7 @@ set to `false`: either at the command line or in a [bazelrc](/run/bazelrc#bazelrc-file-locations) file. -### Ensure caching across machines +### Ensure caching across machines {#caching-across-machines} After cache hits are happening as expected on the same machine, run the same build(s)/test(s) on a different machine. If you suspect that caching is @@ -138,7 +138,7 @@ for discrepancies as well as properties from the host environment leaking into either of the builds. -## Comparing the execution logs +## Comparing the execution logs {#compare-logs} The execution log contains records of actions executed during the build. Each record describes both the inputs (not only files, but also command line
diff --git a/docs/remote/caching.mdx b/docs/remote/caching.mdx index 415925d..a11953b2 100644 --- a/docs/remote/caching.mdx +++ b/docs/remote/caching.mdx
@@ -12,7 +12,7 @@ outputs from one machine can be safely reused on another machine, which can make builds significantly faster. -## Overview +## Overview {#overview} Bazel breaks a build into discrete steps, which are called actions. Each action has inputs, output names, a command line, and environment variables. Required @@ -38,7 +38,7 @@ action. Inspecting the stdout/stderr of Bazel thus is not a good signal for [estimating cache hits](/remote/cache-local). -### How a build uses remote caching +### How a build uses remote caching {#remote-caching} Once a server is set up as the remote cache, you use the cache in multiple ways: @@ -62,7 +62,7 @@ actions locally and creates the required build outputs. 5. New build outputs are uploaded to the remote cache. -## Setting up a server as the cache's backend +## Setting up a server as the cache's backend {#cache-backend} You need to set up a server to act as the cache's backend. A HTTP/1.1 server can treat Bazel's data as opaque bytes and so many existing servers @@ -85,7 +85,7 @@ * [bazel-remote](#bazel-remote) * [Google Cloud Storage](#cloud-storage) -### nginx +### nginx {#nginx} nginx is an open source web server. With its [WebDAV module], it can be used as a remote cache for Bazel. On Debian and Ubuntu you can install the @@ -120,7 +120,7 @@ } ``` -### bazel-remote +### bazel-remote {#bazel-remote} bazel-remote is an open source remote build cache that you can use on your infrastructure. It has been successfully used in production at @@ -136,7 +136,7 @@ Refer to the [GitHub](https://github.com/buchgr/bazel-remote/) page for instructions on how to use it. -### Google Cloud Storage +### Google Cloud Storage {#cloud-storage} [Google Cloud Storage] is a fully managed object store which provides an HTTP API that is compatible with Bazel's remote caching protocol. It requires @@ -164,13 +164,13 @@ 5. You can configure Cloud Storage to automatically delete old files. To do so, see [Managing Object Lifecycles](https://cloud.google.com/storage/docs/managing-lifecycles). -### Other servers +### Other servers {#other-servers} You can set up any HTTP/1.1 server that supports PUT and GET as the cache's backend. Users have reported success with caching backends such as [Hazelcast](https://hazelcast.com), [Apache httpd](http://httpd.apache.org), and [AWS S3](https://aws.amazon.com/s3). -## Authentication +## Authentication {#authentication} As of version 0.11.0 support for HTTP Basic Authentication was added to Bazel. You can pass a username and password to Bazel via the remote cache URL. The @@ -178,7 +178,7 @@ HTTP Basic Authentication transmits username and password in plaintext over the network and it's thus critical to always use it with HTTPS. -## HTTP caching protocol +## HTTP caching protocol {#http-caching} Bazel supports remote caching via HTTP/1.1. The protocol is conceptually simple: Binary data (BLOB) is uploaded via PUT requests and downloaded via GET requests. @@ -209,7 +209,7 @@ 0x310x320x330x340x350x360x370x380x39 ``` -## Run Bazel using the remote cache +## Run Bazel using the remote cache {#run-remote-cache} Once a server is set up as the remote cache, to use the remote cache you need to add flags to your Bazel command. See list of configurations and @@ -226,7 +226,7 @@ * In your project's workspace, shared with the team * On the CI system -### Read from and write to the remote cache +### Read from and write to the remote cache {#read-write-remote-cache} Take care in who has the ability to write to the remote cache. You may want only your CI system to be able to write to the remote cache. @@ -246,7 +246,7 @@ build --remote_upload_local_results=false ``` -### Exclude specific targets from using the remote cache +### Exclude specific targets from using the remote cache {#targets-remote-cache} To exclude specific targets from using the remote cache, tag the target with `no-remote-cache`. For example: @@ -258,7 +258,7 @@ ) ``` -### Delete content from the remote cache +### Delete content from the remote cache {#delete-remote-cache} Deleting content from the remote cache is part of managing your server. How you delete content from the remote cache depends on the server you have @@ -274,7 +274,7 @@ * Create a clean cache after a cache was poisoned * Reduce the amount of storage used by deleting old outputs -### Unix sockets +### Unix sockets {#unix-sockets} The remote HTTP cache supports connecting over unix domain sockets. The behavior is similar to curl's `--unix-socket` flag. Use the following to configure unix @@ -287,7 +287,7 @@ This feature is unsupported on Windows. -## Disk cache +## Disk cache {#disk-cache} Bazel can use a directory on the file system as a remote cache. This is useful for sharing build artifacts when switching branches and/or working @@ -303,7 +303,7 @@ when enabling the disk cache for all developers of a project via the project's checked in `.bazelrc` file. -### Garbage collection +### Garbage collection {#disk-cache-gc} Starting with Bazel 7.4, you can use `--experimental_disk_cache_gc_max_size` and `--experimental_disk_cache_gc_max_age` to set a maximum size for the disk cache @@ -315,7 +315,7 @@ https://github.com/bazelbuild/bazel/tree/master/src/tools/diskcache) to run a garbage collection on demand. -## Known issues +## Known issues {#known-issues} **Input file modification during a build** @@ -351,7 +351,7 @@ When running builds inside docker containers such as in CI, the in-memory state is lost and Bazel must rebuild it before using the remote cache. -## External links +## External links {#external-links} * **Your Build in a Datacenter:** The Bazel team gave a [talk](https://fosdem.org/2018/schedule/event/datacenter_build/) about remote caching and execution at FOSDEM 2018.
diff --git a/docs/remote/ci.mdx b/docs/remote/ci.mdx index 325393d..d5de9c5 100644 --- a/docs/remote/ci.mdx +++ b/docs/remote/ci.mdx
@@ -10,7 +10,7 @@ scenario. The instructions on this page apply to projects stored in GitHub repositories. -## Prerequisites +## Prerequisites {#prerequisites} Before completing the steps on this page, ensure the following: @@ -19,7 +19,7 @@ * You have configured Buildkite for your repository as described in [Bazel Continuous Integration](https://github.com/bazelbuild/continuous-integration/tree/master/buildkite). -## Setting up the Bazel CI for testing +## Setting up the Bazel CI for testing {#bazel-ci-testing} 1. In your `.bazelci/presubmit.yml` file, do the following: @@ -58,7 +58,7 @@  -## Troubleshooting failed builds and tests +## Troubleshooting failed builds and tests {#troubleshooting-failed-builds} If your build or tests fail, it's likely due to the following: @@ -76,7 +76,7 @@ [Adapting Bazel Rules for Remote Execution](/remote/rules) for details about compatibility with remote execution. -## Using a custom container in the rbe_ubuntu1604 CI config +## Using a custom container in the rbe_ubuntu1604 CI config {#custom-container} The `rbe-ubuntu16-04` container is publicly available at the following URL: @@ -91,7 +91,7 @@ If you are building the container from source, you must also install the latest version of Bazel. -### Pulling the rbe-ubuntu16-04 from Container Registry +### Pulling the rbe-ubuntu16-04 from Container Registry {#container-registry} To pull the `rbe-ubuntu16-04` container from Container Registry, run the following command: @@ -103,7 +103,7 @@ Replace <var>sha256-checksum</var> with the SHA256 checksum value for [the latest container](https://console.cloud.google.com/gcr/images/cloud-marketplace/GLOBAL/google/rbe-ubuntu16-04). -### Building the rbe-ubuntu16-04 container from source +### Building the rbe-ubuntu16-04 container from source {#container-source} To build the `rbe-ubuntu16-04` container from source, do the following: @@ -122,7 +122,7 @@ gcloud docker -- pull gcr.io/<var>project-id</var>/<var>custom-container-name</var><var>sha256-checksum</var> ``` -### Running the custom container +### Running the custom container {#run-custom-container} To run the custom container, do one of the following: @@ -142,7 +142,7 @@ docker run -it gcr.io/<var>project-id</var>/<var>custom-container-name</var>@sha256:<var>sha256sum</var> /bin/bash ``` -### Adding resources to the custom container +### Adding resources to the custom container {#add-resources-container} Use a [`Dockerfile`](https://docs.docker.com/engine/reference/builder/) or [`rules_docker`](https://github.com/bazelbuild/rules_docker) to add resources or @@ -159,7 +159,7 @@ RUN apt-get update && yes | apt-get install -y <var>my_tool_package</var> ``` -### Pushing the custom container to Container Registry +### Pushing the custom container to Container Registry {#push-container-registry} Once you have customized the container, build the container image and push it to Container Registry as follows: @@ -193,7 +193,7 @@ [Pushing and Pulling Images](https://cloud.google.com/container-registry/docs/pushing-and-pulling). -### Specifying the build platform definition +### Specifying the build platform definition {#platform-definition} You must include a [Bazel platform](/extending/platforms) configuration in your custom toolchain configuration, which allows Bazel to select a toolchain
diff --git a/docs/remote/creating.mdx b/docs/remote/creating.mdx index 0e46a07..b2ea83f 100644 --- a/docs/remote/creating.mdx +++ b/docs/remote/creating.mdx
@@ -17,7 +17,7 @@ * The [worker](#making-worker). * The [rule that uses the worker](#rule-uses-worker). -## Making the worker +## Making the worker {#making-worker} A persistent worker upholds a few requirements: @@ -34,7 +34,7 @@ If your program upholds these requirements, it can be used as a persistent worker! -### Work requests +### Work requests {#work-requests} A `WorkRequest` contains a list of arguments to the worker, a list of path-digest pairs representing the inputs the worker can access (this isn’t @@ -66,7 +66,7 @@ The optional `sandbox_dir` field is used only by workers that support [multiplex sandboxing](/remote/multiplex). -### Work responses +### Work responses {#work-responses} A `WorkResponse` contains a request id, a zero or nonzero exit code, and an output message describing any errors encountered in processing or executing @@ -116,7 +116,7 @@ * Bazel stores requests as protobufs and converts them to JSON using [protobuf's JSON format](https://cs.opensource.google/protobuf/protobuf/+/master:java/util/src/main/java/com/google/protobuf/util/JsonFormat.java) -### Cancellation +### Cancellation {#cancellation} Workers can optionally allow work requests to be cancelled before they finish. This is particularly useful in connection with dynamic execution, where local @@ -144,7 +144,7 @@ files in its working directory. The server is free to clean up the files, including temporary files. -## Making the rule that uses the worker +## Making the rule that uses the worker {#rule-uses-worker} You'll also need to create a rule that generates actions to be performed by the worker. Making a Starlark rule that uses a worker is just like @@ -186,7 +186,7 @@ execution platform rather than on the target platform (i.e., the worker is used as tool during the build). -### Work action requirements +### Work action requirements {#work-action-requirements} The rule that uses the worker creates actions for the worker to perform. These actions have a couple of requirements. @@ -239,7 +239,7 @@ For another example, see [Implementing persistent workers](/remote/persistent#implementation). -## Examples +## Examples {#examples} The Bazel code base uses [Java compiler workers](https://github.com/bazelbuild/bazel/blob/a4251eab6988d6cf4f5e35681fbe2c1b0abe48ef/src/java_tools/buildjar/java/com/google/devtools/build/buildjar/BazelJavaBuilder.java),
diff --git a/docs/remote/dynamic.mdx b/docs/remote/dynamic.mdx index 59cfee8..e954e0d 100644 --- a/docs/remote/dynamic.mdx +++ b/docs/remote/dynamic.mdx
@@ -15,7 +15,7 @@ remote execution set up, go to the Bazel [Remote Execution Overview](/remote/rbe) first. -## Enabling dynamic execution? +## Enabling dynamic execution? {#enabling-dynamic-execution} The dynamic execution module is part of Bazel, but to make use of dynamic execution, you must already be able to compile both locally and remotely from @@ -70,7 +70,7 @@ Merino's excellent [blog posts](https://jmmv.dev/series/bazel-dynamic-execution/) -## When should I use dynamic execution? +## When should I use dynamic execution? {#when-to-use} Dynamic execution requires some form of [remote execution system](/remote/rbe). It is not currently possible to use a cache-only remote system, as a cache miss @@ -115,7 +115,7 @@ It turns on dynamic execution and sets `dynamic` as the default strategy for all mnemonics, which would often lead to these kinds of problems. -## Performance +## Performance {#performance} The dynamic execution approach assumes there are enough resources available locally and remotely that it's worth spending some extra resources to improve @@ -163,7 +163,7 @@ number of performance-related graphs that can help identify ways to improve the trade-off of performance and resource usage. -## Troubleshooting +## Troubleshooting {#troubleshooting} Problems with dynamic execution can be subtle and hard to debug, as they can manifest only under some specific combinations of local and remote execution.
diff --git a/docs/remote/multiplex.mdx b/docs/remote/multiplex.mdx index b4b0a0d..fd5b472 100644 --- a/docs/remote/multiplex.mdx +++ b/docs/remote/multiplex.mdx
@@ -18,7 +18,7 @@ time, and in general it allows using one shared cache between all workers of the same type. -## Overview +## Overview {#overview} There are two layers between the Bazel server and the worker process. For certain mnemonics that can run processes in parallel, Bazel gets a `WorkerProxy` from @@ -39,7 +39,7 @@ worker process. The total number of workers, including regular workers and `WorkerProxy`s, is still limited by `--worker_max_instances`. -## Writing multiplex-compatible rules +## Writing multiplex-compatible rules {#multiplex-rules} The rule's worker process should be multi-threaded to take advantage of multiplex workers. Protobuf allows a ruleset to parse a single request even @@ -50,7 +50,7 @@ atomically (messages don't overlap). Responses must contain the `request_id` of the request they're handling. -### Handling multiplex output +### Handling multiplex output {#output} Multiplex workers need to be more careful about handling their output than singleplex workers. Anything sent to `stderr` will go into a single log file @@ -61,7 +61,7 @@ If your tool only sends user-oriented output to `stdout` or `stderr`, you will need to change that behaviour before you can enable multiplex workers. -## Enabling multiplex workers +## Enabling multiplex workers {#multiplex-workers} Multiplex workers are not enabled by default. A ruleset can turn on multiplex workers by using the `supports-multiplex-workers` tag in the
diff --git a/docs/remote/output-directories.mdx b/docs/remote/output-directories.mdx index f3af3a7..69abcb6 100644 --- a/docs/remote/output-directories.mdx +++ b/docs/remote/output-directories.mdx
@@ -6,7 +6,7 @@ This page covers requirements and layout for output directories. -## Requirements +## Requirements {#requirements} Requirements for an output directory layout: @@ -21,7 +21,7 @@ * All the build state per user should be underneath one directory ("I'd like to clean all the .o files from all my clients.") -## Current layout +## Current layout {#layout} The solution that's currently implemented: @@ -64,7 +64,7 @@ These symlinks are only for the user's convenience, as Bazel itself does not use them. Also, this is done only if the workspace root is writable. -## Layout diagram +## Layout diagram {#layout-diagram} The directories are laid out as follows:
diff --git a/docs/remote/persistent.mdx b/docs/remote/persistent.mdx index 8820950..3a7dbee 100644 --- a/docs/remote/persistent.mdx +++ b/docs/remote/persistent.mdx
@@ -33,7 +33,7 @@ [@bazel/worker](https://www.npmjs.com/package/@bazel/worker) helper library to implement the worker protocol. -## Using persistent workers +## Using persistent workers {#usage} [Bazel 0.27 and higher](https://blog.bazel.build/2019/06/19/list-strategy.html) uses persistent workers by default when executing builds, though remote @@ -64,7 +64,7 @@ specify the `worker` strategy, but you can still use `local` or `sandboxed` as fallbacks. -## Choosing number of workers +## Choosing number of workers {#number-of-workers} The default number of worker instances per mnemonic is 4, but can be adjusted with the @@ -112,7 +112,7 @@ The speed-up depends on the change being made. A speed-up of a factor 6 is measured in the above situation when a commonly used constant is changed. -## Modifying persistent workers +## Modifying persistent workers {#options} You can pass the [`--worker_extra_flag`](/reference/command-line-reference#flag--worker_extra_flag) @@ -150,7 +150,7 @@ For Android builds, see details at the [Android Build Performance page](/docs/android-build-performance). -## Implementing persistent workers +## Implementing persistent workers {#implementation} See the [creating persistent workers](/remote/creating) page for more information on how to make a worker. @@ -232,7 +232,7 @@ [nodejs worker example](https://github.com/bazelbuild/rules_nodejs/tree/stable/examples/worker) might be helpful. -## How do workers affect sandboxing? +## How do workers affect sandboxing? {#sandboxing} Using the `worker` strategy by default does not run the action in a [sandbox](/docs/sandboxing), similar to the `local` strategy. You can set the @@ -255,7 +255,7 @@ `--experimental_worker_multiplex_sandboxing` flag. See more details in [the design doc](https://docs.google.com/document/d/1ncLW0hz6uDhNvci1dpzfEoifwTiNTqiBEm1vi-bIIRM/edit)). -## Further reading +## Further reading {#further-reading} For more information on persistent workers, see:
diff --git a/docs/remote/rbe.mdx b/docs/remote/rbe.mdx index 75d4a15..8daffa5 100644 --- a/docs/remote/rbe.mdx +++ b/docs/remote/rbe.mdx
@@ -26,7 +26,7 @@ self-service tools, see [Remote Execution Services](https://www.bazel.build/remote-execution-services.html) -## Requirements +## Requirements {#requirements} Remote execution of Bazel builds imposes a set of mandatory configuration constraints on the build. For more information, see
diff --git a/docs/remote/rules.mdx b/docs/remote/rules.mdx index 340ab02..adc445a 100644 --- a/docs/remote/rules.mdx +++ b/docs/remote/rules.mdx
@@ -23,7 +23,7 @@ * **Execution platform** - where Bazel actions run. * **Target platform** - where the build outputs (and some actions) run. -## Overview +## Overview {#overview} When configuring a Bazel build for remote execution, you must follow the guidelines described in this page to ensure the build executes remotely @@ -44,7 +44,7 @@ * [Managing platform-dependent binaries](#manage-binaries) * [Managing configure-style WORKSPACE rules](#manage-workspace-rules) -## Invoking build tools through toolchain rules +## Invoking build tools through toolchain rules {#toolchain-rules} A Bazel toolchain rule is a configuration provider that tells a build rule what build tools, such as compilers and linkers, to use and how to configure them @@ -65,7 +65,7 @@ If a toolchain rule does not exist for the tool your rule uses, consider [creating a toolchain rule](/extending/toolchains#creating-a-toolchain-rule). -## Managing implicit dependencies +## Managing implicit dependencies {#manage-dependencies} If a build tool can access dependencies across build actions, those actions will fail when remotely executed because each remote build action is executed @@ -89,7 +89,7 @@ identifying and resolving dependency-related build errors. See [Troubleshooting Bazel Remote Execution with Docker Sandbox](/remote/sandbox) for more information. -## Managing platform-dependent binaries +## Managing platform-dependent binaries {#manage-binaries} Typically, a binary built on the host platform cannot safely execute on an arbitrary remote execution platform due to potentially mismatched dependencies. @@ -109,7 +109,7 @@ toolchain container) if it's stable enough and use toolchain rules to run it in your build. -## Managing configure-style WORKSPACE rules +## Managing configure-style WORKSPACE rules {#manage-workspace-rules} Bazel's `WORKSPACE` rules can be used for probing the host platform for tools and libraries required by the build, which, for local builds, is also Bazel's
diff --git a/docs/remote/sandbox.mdx b/docs/remote/sandbox.mdx index d230d69..de66ba6 100644 --- a/docs/remote/sandbox.mdx +++ b/docs/remote/sandbox.mdx
@@ -46,7 +46,7 @@ build even if portions of the build are failing. This method is experimental and not officially supported. -## Prerequisites +## Prerequisites {#prerequisites} Before you begin troubleshooting, do the following if you have not already done so: @@ -88,7 +88,7 @@ name of your custom container image. -## Troubleshooting natively +## Troubleshooting natively {#troubleshooting-natively} This method executes Bazel and all of its build actions directly on the local machine and is a reliable way to confirm whether your build will succeed when @@ -99,7 +99,7 @@ Such leaks will cause problems with remote execution; to detect them, [troubleshoot in a Docker container](#troubleshooting-docker-container) in addition to troubleshooting natively. -### Step 1: Run the build +### Step 1: Run the build {#run-build} 1. Add the `--config=docker-sandbox` flag to the Bazel command that executes your build. For example: @@ -123,7 +123,7 @@ current user account. See the [Docker documentation](https://docs.docker.com/install/linux/linux-postinstall/) for more information. If problems persist, skip ahead to [Troubleshooting in a Docker container](#troubleshooting-docker-container). -### Step 2: Resolve detected issues +### Step 2: Resolve detected issues {#resolve-common-issues} The following are the most commonly encountered issues and their workarounds. @@ -153,7 +153,7 @@ * **Other errors.** Contact [bazel-discuss@google.com](mailto:bazel-discuss@google.com) for help. -## Troubleshooting in a Docker container +## Troubleshooting in a Docker container {#troubleshooting-docker-container} With this method, Bazel runs inside a host Docker container, and Bazel's build actions execute inside individual toolchain containers spawned by the Docker @@ -165,7 +165,7 @@ build actions and keeping the installed tooling to a minimum, you can verify whether your build has any dependencies on the local execution environment. -### Step 1: Build the container +### Step 1: Build the container {#build-container} Note: The commands below are tailored specifically for a `debian:stretch` base. For other bases, modify them as necessary. @@ -195,7 +195,7 @@ docker build -t bazel_container - < Dockerfile ``` -### Step 2: Start the container +### Step 2: Start the container {#start-container} Start the Docker container using the command shown below. In the command, substitute the path to the source code on your host that you want to build. @@ -220,7 +220,7 @@ toolchain container. If binaries from the local environment are leaking into the toolchain container, they will cause build errors. -### Step 3: Test the container +### Step 3: Test the container {#test-container} Run the following commands from inside the Docker container to test it: @@ -230,7 +230,7 @@ bazel version ``` -### Step 4: Run the build +### Step 4: Run the build {#run-build-step} Run the build as shown below. The output user is root so that it corresponds to a directory that is accessible with the same absolute path from inside the host @@ -242,7 +242,7 @@ bazel --output_user_root=/tmp/bazel_docker_root --bazelrc=.bazelrc \ build --config=docker-sandbox <var>target</var> ``` -### Step 5: Resolve detected issues +### Step 5: Resolve detected issues {#resolve-build-failures} You can resolve build failures as follows:
diff --git a/docs/remote/workspace.mdx b/docs/remote/workspace.mdx index 3793fcc..c2581b2 100644 --- a/docs/remote/workspace.mdx +++ b/docs/remote/workspace.mdx
@@ -19,7 +19,7 @@ rules using the workspace log. -## Finding non-hermetic rules +## Finding non-hermetic rules {#nonhermetic-rules} [Repository rules](/external/repo) allow the developer to add dependencies to external workspaces, but they are rich enough to allow arbitrary processing to
diff --git a/docs/rules/bzl-style.mdx b/docs/rules/bzl-style.mdx index 65f589f..240c9f2 100644 --- a/docs/rules/bzl-style.mdx +++ b/docs/rules/bzl-style.mdx
@@ -39,15 +39,15 @@ [DRY](https://en.wikipedia.org/wiki/Don%27t_repeat_yourself) principle doesn't really apply here. -## General advice +## General advice {#general-advice} * Use [Buildifier](https://github.com/bazelbuild/buildtools/tree/master/buildifier#linter) as a formatter and linter. * Follow [testing guidelines](/rules/testing). -## Style +## Style {#style} -### Python style +### Python style {#python-style} When in doubt, follow the [PEP 8 style guide](https://www.python.org/dev/peps/pep-0008/) where possible. @@ -61,18 +61,18 @@ Starlark. -### Docstring +### Docstring {#docstring} Document files and functions using [docstrings](https://github.com/bazelbuild/buildtools/blob/master/WARNINGS.md#function-docstring). Use a docstring at the top of each `.bzl` file, and a docstring for each public function. -### Document rules and aspects +### Document rules and aspects {#doc-rules-aspects} Rules and aspects, along with their attributes, as well as providers and their fields, should be documented using the `doc` argument. -### Naming convention +### Naming convention {#naming-convention} * Variables and function names use lowercase with words separated by underscores (`[a-z][a-z0-9_]*`), such as `cc_library`. @@ -80,7 +80,7 @@ private values cannot be used from other files. Local variables should not use the underscore prefix. -### Line length +### Line length {#line-length} As in `BUILD` files, there is no strict line length limit as labels can be long. When possible, try to use at most 79 characters per line (following Python's @@ -89,7 +89,7 @@ automated changes will frequently introduce longer lines, and humans shouldn't spend time splitting lines that are already readable. -### Keyword arguments +### Keyword arguments {#keyword-arguments} In keyword arguments, spaces around the equal sign are preferred: @@ -103,12 +103,12 @@ ) ``` -### Boolean values +### Boolean values {#boolean-values} Prefer values `True` and `False` (rather than of `1` and `0`) for boolean values (such as when using a boolean attribute in a rule). -### Use print only for debugging +### Use print only for debugging {#print-for-debugging} Do not use the `print()` function in production code; it is only intended for debugging, and will spam all direct and indirect users of your `.bzl` file. The @@ -118,7 +118,7 @@ `False`. Be mindful of whether these statements are useful enough to justify their impact on readability. -## Macros +## Macros {#macros} A macro is a function which instantiates one or more rules during the loading phase. In general, use rules whenever possible instead of macros. The build @@ -171,7 +171,7 @@ See also [macros](/extending/macros#conventions). -## Rules +## Rules {#rules} * Rules, aspects, and their attributes should use lower_case names ("snake case").
diff --git a/docs/rules/challenges.mdx b/docs/rules/challenges.mdx index 10ff737..06727dd 100644 --- a/docs/rules/challenges.mdx +++ b/docs/rules/challenges.mdx
@@ -7,7 +7,7 @@ This page gives a high-level overview of the specific issues and challenges of writing efficient Bazel rules. -## Summary Requirements +## Summary Requirements {#summary-requirements} * Assumption: Aim for Correctness, Throughput, Ease of Use & Latency * Assumption: Large Scale Repositories @@ -19,14 +19,14 @@ requires Unusual Coding Patterns * Intrinsic: Avoiding Quadratic Time and Memory Consumption is Hard -## Assumptions +## Assumptions {#assumptions} Here are some assumptions made about the build system, such as need for correctness, ease of use, throughput, and large scale repositories. The following sections address these assumptions and offer guidelines to ensure rules are written in an effective manner. -### Aim for correctness, throughput, ease of use & latency +### Aim for correctness, throughput, ease of use & latency {#aim} We assume that the build system needs to be first and foremost correct with respect to incremental builds. For a given source tree, the output of the @@ -57,7 +57,7 @@ Note that these goals often overlap; latency is as much a function of throughput of the remote execution service as is correctness relevant for ease of use. -### Large scale repositories +### Large scale repositories {#large-repos} The build system needs to operate at the scale of large repositories where large scale means that it does not fit on a single hard drive, so it is impossible to @@ -68,7 +68,7 @@ reasonable amount of time and memory. As such, it is critical that `BUILD` files can be loaded and parsed independently. -### BUILD-like description language +### BUILD-like description language {#language} In this context, we assume a configuration language that is roughly similar to `BUILD` files in declaration of library and binary rules @@ -76,12 +76,12 @@ and we avoid even looking at source files whenever we can (except for existence). -## Historic +## Historic {#historic} There are differences between Bazel versions that cause challenges and some of these are outlined in the following sections. -### Hard separation between loading, analysis, and execution is outdated but still affects the API +### Hard separation between loading, analysis, and execution is outdated but still affects the API {#loading-outdated} Technically, it is sufficient for a rule to know the input and output files of an action just before the action is sent to remote execution. However, the @@ -102,12 +102,12 @@ graph of build steps and output file names that is only determined from the rule itself and its dependencies. -## Intrinsic +## Intrinsic {#intrinsic} There are some intrinsic properties that make writing rules challenging and some of the most common ones are described in the following sections. -### Remote execution and caching are hard +### Remote execution and caching are hard {#remote-execution} Remote execution and caching improve build times in large repositories by roughly two orders of magnitude compared to running the build on a single @@ -123,7 +123,7 @@ addressed by digest later on. However, this imposes restrictions on the Bazel rules, which need to declare all input files ahead of time. -### Using change information for correct and fast incremental builds requires unusual coding patterns +### Using change information for correct and fast incremental builds requires unusual coding patterns {#coding-patterns} Above, we argued that in order to be correct, Bazel needs to know all the input files that go into a build step in order to detect whether that build step is @@ -176,7 +176,7 @@ several Bazel bugs in the past were caused by rules using unsafe APIs, even though the rules were written by the Bazel team or other domain experts. -### Avoiding quadratic time and memory consumption is hard +### Avoiding quadratic time and memory consumption is hard {#avoid} To make matters worse, apart from the requirements imposed by Skyframe, the historical constraints of using Java, and the outdatedness of the rules API, @@ -204,7 +204,7 @@ could expand the command line string representation of the C++ link action. N/2 copies of N/2 elements is O(N^2) memory. -#### Custom collections classes to avoid quadratic complexity +#### Custom collections classes to avoid quadratic complexity {#custom-classes} Bazel is heavily affected by both of these scenarios, so we introduced a set of custom collection classes that effectively compress the information in memory by
diff --git a/docs/rules/index.mdx b/docs/rules/index.mdx index 2a6c3eb..a8d32ee 100644 --- a/docs/rules/index.mdx +++ b/docs/rules/index.mdx
@@ -10,7 +10,7 @@ This page describes the recommended, native, and non-native Bazel rules. -## Recommended rules +## Recommended rules {#recommended-rules} Here is a selection of recommended rules: @@ -72,7 +72,7 @@ - [`xcode_config`](/reference/be/objective-c#xcode_config) - [`xcode_version`](/reference/be/objective-c#xcode_version) -## Embedded non-native rules +## Embedded non-native rules {#embedded-rules} Bazel also embeds additional rules written in [Starlark](/rules/language). Those can be loaded from the `@bazel_tools` built-in external repository.
diff --git a/docs/rules/language.mdx b/docs/rules/language.mdx index e6066cf..a95dd7b 100644 --- a/docs/rules/language.mdx +++ b/docs/rules/language.mdx
@@ -45,7 +45,7 @@ * [list](lib/list) * [string](lib/string) -## Type annotations +## Type annotations {#StarlarkTypes} **Experimental**. Type annotations are an experimental feature and may change at any time. Don't depend on it. It may be enabled in Bazel at HEAD @@ -104,7 +104,7 @@ `bzl` file that defined them. Just like the above example using `bzl` files, values returned by rules are immutable. -## Differences between BUILD and .bzl files +## Differences between BUILD and .bzl files {#differences-between-build-and-bzl-files} `BUILD` files register targets via making calls to rules. `.bzl` files provide definitions for constants, rules, macros, and functions.
diff --git a/docs/rules/performance.mdx b/docs/rules/performance.mdx index c415cf1..e518273 100644 --- a/docs/rules/performance.mdx +++ b/docs/rules/performance.mdx
@@ -14,7 +14,7 @@ The cost of writing an inefficient rule may not be evident until it is in widespread use. -## Use depsets +## Use depsets {#use-depsets} Whenever you are rolling up information from rule dependencies you should use [depsets](lib/depset). Only use plain lists or dicts to publish information @@ -72,7 +72,7 @@ See the [depset overview](/extending/depsets) page for more information. -### Avoid calling `depset.to_list()` +### Avoid calling `depset.to_list()` {#avoid-depset-to-list} You can coerce a depset to a flat list using [`to_list()`](lib/depset#to_list), but doing so usually results in O(N^2) @@ -85,7 +85,7 @@ you build a set of targets with overlapping dependencies. This happens when building your tests `//foo/tests/...`, or when importing an IDE project. -### Reduce the number of calls to `depset` +### Reduce the number of calls to `depset` {#reduce-calls-depset} Calling `depset` inside a loop is often a mistake. It can lead to depsets with very deep nesting, which perform poorly. For example: @@ -115,7 +115,7 @@ x = depset(transitive = [i.deps for i in inputs]) ``` -## Use ctx.actions.args() for command lines +## Use ctx.actions.args() for command lines {#ctx-actions-args} When building command lines you should use [ctx.actions.args()](lib/Args). This defers expansion of any depsets to the execution phase. @@ -176,7 +176,7 @@ return f.short_path ``` -## Transitive action inputs should be depsets +## Transitive action inputs should be depsets {#transitive-action-inputs} When building an action using [ctx.actions.run](lib/actions?#run), do not forget that the `inputs` field accepts a depset. Use this whenever inputs are @@ -190,7 +190,7 @@ ) ``` -## Hanging +## Hanging {#hanging} If Bazel appears to be hung, you can hit <kbd>Ctrl-\</kbd> or send Bazel a `SIGQUIT` signal (`kill -3 $(bazel info server_pid)`) to get a thread @@ -200,7 +200,7 @@ `output_base` directory is usually the parent of the `bazel-<workspace>` symlink in your workspace directory. -## Performance profiling +## Performance profiling {#performance-profiling} The [JSON trace profile](/advanced/performance/json-trace-profile) can be very useful to quickly understand what Bazel spent time on during the invocation. @@ -212,13 +212,13 @@ The [`--starlark_cpu_profile`](https://bazel.build/reference/command-line-reference#flag--starlark_cpu_profile) flag may be used to write a pprof profile of CPU usage by all Starlark threads. -## Memory profiling +## Memory profiling {#memory-profiling} Bazel comes with a built-in memory profiler that can help you check your rule’s memory use. If there is a problem you can dump the heap to find the exact line of code that is causing the problem. -### Enabling memory tracking +### Enabling memory tracking {#enabling-memory-tracking} You must pass these two startup flags to *every* Bazel invocation: @@ -235,7 +235,7 @@ These start the server in memory tracking mode. If you forget these for even one Bazel invocation the server will restart and you will have to start over. -### Using the Memory Tracker +### Using the Memory Tracker {#memory-tracker} As an example, look at the target `foo` and see what it does. To only run the analysis and not run the build execution phase, add the
diff --git a/docs/rules/testing.mdx b/docs/rules/testing.mdx index 2996e08..17120dd 100644 --- a/docs/rules/testing.mdx +++ b/docs/rules/testing.mdx
@@ -7,7 +7,7 @@ There are several different approaches to testing Starlark code in Bazel. This page gathers the current best practices and frameworks by use case. -## Testing rules +## Testing rules {#testing-rules} [Skylib](https://github.com/bazelbuild/bazel-skylib) has a test framework called [`unittest.bzl`](https://github.com/bazelbuild/bazel-skylib/blob/main/lib/unittest.bzl) @@ -46,7 +46,7 @@ See below for a minimal toy example, followed by an example that checks actions. -### Minimal example +### Minimal example {#testing-rules-example} `//mypkg/myrules.bzl`: @@ -176,7 +176,7 @@ Note that the labels of all targets can conflict with other labels in the same BUILD package, so it's helpful to use a unique name for the test. -### Failure testing +### Failure testing {#failure-testing} It may be useful to verify that a rule fails given certain inputs or in certain state. This can be done using the analysis test framework: @@ -217,7 +217,7 @@ # ":failure_testing_test" to the suite's test targets. ``` -### Verifying registered actions +### Verifying registered actions {#verifying-registered-actions} You may want to write tests which make assertions about the actions that your rule registers, for example, using `ctx.actions.run()`. This can be done in your @@ -240,7 +240,7 @@ [`Action`](lib/Action) objects which represent actions registered by the target under test. -### Verifying rule behavior under different flags +### Verifying rule behavior under different flags {#verifying-rule-behavior} You may want to verify your real rule behaves a certain way given certain build flags. For example, your rule may behave differently if a user specifies: @@ -289,7 +289,7 @@ above. -## Validating artifacts +## Validating artifacts {#validating-artifacts} The main ways to check that your generated files are correct are: @@ -298,7 +298,7 @@ * You can use a specialized rule for the kind of test you want to perform. -### Using a test target +### Using a test target {#using-test-target} The most straightforward way to validate an artifact is to write a script and add a `*_test` target to your BUILD file. The specific artifacts you want to @@ -339,7 +339,7 @@ ) ``` -### Using a custom rule +### Using a custom rule {#using-custom-rule} A more complicated alternative is to write the shell script as a template that gets instantiated by a new rule. This involves more indirection and Starlark @@ -421,7 +421,7 @@ inlined the template into the .bzl file as a string and expanded it during the analysis phase using the `str.format` method or `%`-formatting. -## Testing Starlark utilities +## Testing Starlark utilities {#testing-starlark-utilities} [Skylib](https://github.com/bazelbuild/bazel-skylib)'s [`unittest.bzl`](https://github.com/bazelbuild/bazel-skylib/blob/main/lib/unittest.bzl)
diff --git a/docs/run/bazelrc.mdx b/docs/run/bazelrc.mdx index f71aabb..82e723c 100644 --- a/docs/run/bazelrc.mdx +++ b/docs/run/bazelrc.mdx
@@ -10,7 +10,7 @@ (and other commands), you can specify options in a configuration file, called `.bazelrc`. -### Where are the `.bazelrc` files? +### Where are the `.bazelrc` files? {#bazelrc-file-locations} Bazel looks for optional configuration files in the following locations, in the order shown below. The options are interpreted in this order, so @@ -77,14 +77,14 @@ file. For more details, see the [global bazelrc section](#global-bazelrc). -### `.bazelrc` syntax and semantics +### `.bazelrc` syntax and semantics {#bazelrc-syntax-semantics} Like all UNIX "rc" files, the `.bazelrc` file is a text file with a line-based grammar. Empty lines and lines starting with `#` (comments) are ignored. Each line contains a sequence of words, which are tokenized according to the same rules as the Bourne shell. -#### Imports +#### Imports {#imports} Lines that start with `import`, `try-import` or `try-import-if-bazel-version` are special: use these to load other "rc" files. To specify a path that is @@ -149,7 +149,7 @@ options in the imported file. - Options in files imported later take precedence over files imported earlier. -#### Option defaults +#### Option defaults {#option-defaults} Most lines of a bazelrc define default option values. The first word on each line specifies when these defaults are applied: @@ -234,7 +234,7 @@ on the command line, and are always prepended to the explicit list of non- option arguments. -#### `--config` +#### `--config` {#config} In addition to setting option defaults, the rc file can be used to group options and provide a shorthand for common groupings. This is done by adding a `:name` @@ -259,7 +259,7 @@ [startup options](#option-defaults). Setting `startup:config-name --some_startup_option` in the .bazelrc will be ignored. -#### `--enable_platform_specific_config` +#### `--enable_platform_specific_config` {#enable_platform_specific_config} Platform specific configs in the `.bazelrc` can be automatically enabled using `--enable_platform_specific_config`. For example, if the host OS is Linux and @@ -270,7 +270,7 @@ See [--enable_platform_specific_config](/reference/command-line-reference#flag--enable_platform_specific_config). -#### Example +#### Example {#bazelrc-example} Here's an example `~/.bazelrc` file: @@ -287,9 +287,9 @@ build:memcheck --strip=never --test_timeout=3600 ``` -### Other files governing Bazel's behavior +### Other files governing Bazel's behavior {#bazel-behavior-files} -#### `.bazelignore` +#### `.bazelignore` {#bazelignore} You can specify directories within the workspace that you want Bazel to ignore, such as related projects @@ -303,7 +303,7 @@ It takes a list of directories to ignore just like .bazelignore does, but with glob semantics. See [#24203](https://github.com/bazelbuild/bazel/pull/24203). -### The global bazelrc file +### The global bazelrc file {#global-bazelrc} Bazel reads optional bazelrc files in this order:
diff --git a/docs/run/build.mdx b/docs/run/build.mdx index b99830e..c572d2d 100644 --- a/docs/run/build.mdx +++ b/docs/run/build.mdx
@@ -5,7 +5,7 @@ This page covers how to build a program with Bazel, build command syntax, and target pattern syntax. -## Quickstart +## Quickstart {#quickstart} To run Bazel, go to your base [workspace](/concepts/build-ref#workspace) directory or any of its subdirectories and type `bazel`. See [build](#bazel-build) if you @@ -17,7 +17,7 @@ Usage: bazel <var>command</var> <var>options</var> ... ``` -### Available commands +### Available commands {#available-commands} * [`analyze-profile`](/docs/user-manual#analyze-profile): Analyzes build profile data. * [`aquery`](/docs/user-manual#aquery): Executes a query on the [post-analysis](#analysis) action graph. @@ -36,7 +36,7 @@ * [`test`](/docs/user-manual#running-tests): Builds and runs the specified test targets. * [`version`](/docs/user-manual#version): Prints version information for Bazel. -### Getting help +### Getting help {#getting-help} * `bazel help <var>command</var>`: Prints help and options for `<var>command</var>`. @@ -48,7 +48,7 @@ used ones are `bazel build` and `bazel test`. You can browse the online help messages using `bazel help`. -### Building one target +### Building one target {#bazel-build} Before you can start a build, you need a _workspace_. A workspace is a directory tree that contains all the source files needed to build your @@ -108,7 +108,7 @@ dependencies, Bazel would re-execute some build actions, or complete an _incremental build_. -### Building multiple targets +### Building multiple targets {#specifying-build-targets} Bazel allows a number of ways to specify the targets to be built. Collectively, these are known as _target patterns_. This syntax is used in commands like @@ -271,7 +271,7 @@ any such filtering automatically (that would defeat the purpose of `bazel query`). -### Fetching external dependencies +### Fetching external dependencies {#fetching-external-dependencies} By default, Bazel will download and symlink external dependencies during the build. However, this can be undesirable, either because you'd like to know @@ -323,7 +323,7 @@ will automatically run `bazel fetch` before running `bazel build`. -#### The repository cache +#### The repository cache {#repository-cache} Bazel tries to avoid fetching the same file several times, even if the same file is needed in different workspaces, or if the definition of an external @@ -345,7 +345,7 @@ cleaned up automatically, as it might contain a copy of a file that is no longer available upstream. -#### [Deprecated] Distribution files directories +#### [Deprecated] Distribution files directories {#distribution-directory} **Deprecated**: *Using repository cache is preferred to achieve offline build.* @@ -367,7 +367,7 @@ way, specifying distribution files directories remains efficient, even if the number of files in such a directory grows large. -#### Running Bazel in an airgapped environment +#### Running Bazel in an airgapped environment {#running-bazel-airgapped} To keep Bazel's binary size small, Bazel's implicit dependencies are fetched over the network while running for the first time. These implicit dependencies @@ -470,7 +470,7 @@ build --distdir=<var>path</var>/to/<var>directory</var> ``` -### Build configurations and cross-compilation +### Build configurations and cross-compilation {#build-config-cross-compilation} All the inputs that specify the behavior and result of a given build can be divided into two distinct categories. The first kind is the intrinsic @@ -537,7 +537,7 @@ request configuration (such as changing a linker options does), as described earlier. -### Correct incremental rebuilds +### Correct incremental rebuilds {#correct-incremental-rebuilds} One of the primary goals of the Bazel project is to ensure correct incremental rebuilds. Previous build tools, especially those based on Make, make several @@ -572,7 +572,7 @@ confusion. (Also, less time spent waiting for rebuilds caused by use of `make clean`, whether necessary or pre-emptive.) -#### Build consistency and incremental builds +#### Build consistency and incremental builds {#build-consistency} Formally, we define the state of a build as _consistent_ when all the expected output files exist, and their contents are correct, as specified by the steps or @@ -614,7 +614,7 @@ If you ever detect a stable inconsistent state with Bazel, please report a bug. -#### Sandboxed execution +#### Sandboxed execution {#sandboxed-execution} Note: Sandboxing is enabled by default for local execution. @@ -650,13 +650,13 @@ issue tracker and mention which Linux distribution you're using so that we can investigate and provide a fix in a subsequent release. -### Phases of a build +### Phases of a build {#build-phases} In Bazel, a build occurs in three distinct phases; as a user, understanding the difference between them provides insight into the options which control a build (see below). -#### Loading phase +#### Loading phase {#loading} The first is **loading** during which all the necessary BUILD files for the initial targets, and their transitive closure of dependencies, are loaded, @@ -670,7 +670,7 @@ Errors reported during this phase include: package not found, target not found, lexical and grammatical errors in a BUILD file, and evaluation errors. -#### Analysis phase +#### Analysis phase {#analysis} The second phase, **analysis**, involves the semantic analysis and validation of each build rule, the construction of a build dependency graph, and the @@ -690,7 +690,7 @@ such as Bazel's [query](/query/guide) command, which is implemented atop the loading phase. -#### Execution phase +#### Execution phase {#execution} The third and final phase of the build is **execution**. This phase ensures that the outputs of each step in the build are consistent with its inputs, re-running
diff --git a/docs/run/scripts.mdx b/docs/run/scripts.mdx index f267c90..fcf0ef8 100644 --- a/docs/run/scripts.mdx +++ b/docs/run/scripts.mdx
@@ -9,7 +9,7 @@ this section lists some details to bear in mind to make your scripts more robust. -### Choosing the output base +### Choosing the output base {#output-base-option} The `--output_base` option controls where the Bazel process should write the outputs of a build to, as well as various working files used internally by @@ -32,14 +32,14 @@ long-running commands such as builds, your script will have to wait for those commands to complete before it can continue. -### Notes about server mode +### Notes about server mode {#server-mode} By default, Bazel uses a long-running [server process](/run/client-server) as an optimization. When running Bazel in a script, don't forget to call `shutdown` when you're finished with the server, or, specify `--max_idle_secs=5` so that idle servers shut themselves down promptly. -### What exit code will I get? +### What exit code will I get? {#exit-codes} Bazel attempts to differentiate failures due to the source code under consideration from external errors that prevent Bazel from executing properly. @@ -92,7 +92,7 @@ However, all non-zero exit values will always constitute an error. -### Reading the .bazelrc file +### Reading the .bazelrc file {#reading-bazelrc} By default, Bazel reads the [`.bazelrc` file](/run/bazelrc) from the base workspace directory or the user's home directory. Whether or not this is @@ -101,7 +101,7 @@ .bazelrc file by using the option `--bazelrc=/dev/null`. If you want to perform a build using the user's preferred settings, the default behavior is better. -### Command log +### Command log {#command-log} The Bazel output is also available in a command log file which you can find with the following command: @@ -116,7 +116,7 @@ However, the location of the command log file will not change unless you change the setting of the `--output_base` or `--output_user_root` options. -### Parsing output +### Parsing output {#parsing-output} The Bazel output is quite easy to parse for many purposes. Two options that may be helpful for your script are `--noshow_progress` which suppresses progress @@ -126,6 +126,6 @@ files they created. Be sure to specify a very large value of _n_ if you rely on these messages. -## Troubleshooting performance by profiling +## Troubleshooting performance by profiling {#performance-profiling} See the [Performance Profiling](/rules/performance#performance-profiling) section.
diff --git a/docs/start/cpp.mdx b/docs/start/cpp.mdx index 927bde0..15cda32 100644 --- a/docs/start/cpp.mdx +++ b/docs/start/cpp.mdx
@@ -4,7 +4,7 @@ -## Introduction +## Introduction {#introduction} New to Bazel? You're in the right place. Follow this First Build tutorial for a simplified introduction to using Bazel. This tutorial defines key terms as they @@ -18,7 +18,7 @@ Estimated completion time: 30 minutes. -### Prerequisites +### Prerequisites {#prerequisites} Start by [installing Bazel](https://bazel.build/install), if you haven't already. This tutorial uses Git for source control, so for best results [install @@ -72,14 +72,14 @@ stage, you will build a project with multiple packages and build it with multiple targets. -### Summary: Introduction +### Summary: Introduction {#summary-introduction} By installing Bazel (and Git) and cloning the repository for this tutorial, you have laid the foundation for your first build with Bazel. Continue to the next section to define some terms and set up your [workspace](https://bazel.build/reference/glossary#workspace). -## Getting started +## Getting started {#getting-started} Before you can build a project, you need to set up its workspace. A workspace is a directory that holds your project's source files and Bazel's build outputs. @@ -99,7 +99,7 @@ empty file named `MODULE.bazel` in that directory. For the purposes of this tutorial, a `MODULE.bazel` file is already present in each stage. -### Understand the BUILD file +### Understand the BUILD file {#understand-build} A `BUILD` file contains several different types of instructions for Bazel. Each `BUILD` file requires at least one @@ -125,13 +125,13 @@ tells Bazel to build a self-contained executable binary from the `hello-world.cc` source file with no dependencies. -### Summary: getting started +### Summary: getting started {#summary-getting-started} Now you are familiar with some key terms, and what they mean in the context of this project and Bazel in general. In the next section, you will build and test Stage 1 of the project. -## Stage 1: single target, single package +## Stage 1: single target, single package {#stage-1} It's time to build the first part of the project. For a visual reference, the structure of the Stage 1 section of the project is: @@ -188,13 +188,13 @@ file.](/docs/images/cpp-tutorial-stage1.png "Dependency graph for hello-world displays a single target with a single source file.") -### Summary: stage 1 +### Summary: stage 1 {#summary-stage-1} Now that you have completed your first build, you have a basic idea of how a build is structured. In the next stage, you will add complexity by adding another target. -## Stage 2: multiple build targets +## Stage 2: multiple build targets {#stage-2} While a single target is sufficient for small projects, you may want to split larger projects into multiple targets and packages. This allows for fast @@ -279,14 +279,14 @@ graph for `hello-world` displays dependency changes after modification to the file.") -### Summary: stage 2 +### Summary: stage 2 {#summary-stage-2} You've now built the project with two targets. The `hello-world` target builds one source file and depends on one other target (`//main:hello-greet`), which builds two additional source files. In the next section, take it a step further and add another package. -## Stage 3: multiple packages +## Stage 3: multiple packages {#stage-3} This next stage adds another layer of complication and builds a project with multiple packages. Take a look at the structure and contents of the @@ -385,14 +385,14 @@ bazel-bin/main/hello-world ``` -### Summary: stage 3 +### Summary: stage 3 {#summary-stage-3} You've now built the project as two packages with three targets and understood the dependencies between them, which equips you to go forth and build future projects with Bazel. In the next section, take a look at how to continue your Bazel journey. -## Next steps +## Next steps {#next-steps} You've now completed your first basic build with Bazel, but this is just the start. Here are some more resources to continue learning with Bazel:
diff --git a/docs/start/go.mdx b/docs/start/go.mdx index f47399d..5fb604c 100644 --- a/docs/start/go.mdx +++ b/docs/start/go.mdx
@@ -11,16 +11,16 @@ Estimated completion time: 30 minutes -## Before you begin +## Before you begin {#you-begin} -### Install Bazel +### Install Bazel {#install-bazel} Before you get started, first [install bazel](/install) if you haven't done so already. You can check if Bazel is installed by running `bazel version` in any directory. -### Install Go (optional) +### Install Go (optional) {#install-go} You don't need to [install Go](https://go.dev/doc/install) to build Go projects with Bazel. The Bazel Go rule set automatically downloads and uses a Go @@ -32,7 +32,7 @@ You can check if Go is installed by running `go version` in any directory. -### Get the sample project +### Get the sample project {#get-sample} The Bazel examples are stored in a Git repository, so you'll need to [install Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) if you @@ -55,7 +55,7 @@ There are three subdirectories (`stage1`, `stage2`, and `stage3`), each for a different section of this tutorial. Each stage builds on the previous one. -## Build with Bazel +## Build with Bazel {#build-bazel} Start in the `stage1` directory, where we'll find a program. We can build it with `bazel build`, then run it: @@ -91,7 +91,7 @@ Hello, Bazel! 💚 ``` -### Understanding project structure +### Understanding project structure {#understanding-project} Take a look at the project we just built. @@ -146,7 +146,7 @@ ensure everyone on your project gets the same version of each dependency. You shouldn't need to edit `MODULE.bazel.lock` manually. -### Understand the BUILD file +### Understand the BUILD file {#understand-build} Most of your interaction with Bazel will be through `BUILD` files (or equivalently, `BUILD.bazel` files), so it's important to understand what they @@ -178,7 +178,7 @@ rule sets for many other languages and tools on the [Bazel Central Registry (BCR)](https://registry.bazel.build/). -## Add a library +## Add a library {#add-library} Move onto the `stage2` directory, where we'll build a new program that prints your fortune. This program uses a separate Go package as a library that @@ -299,7 +299,7 @@ actions for [remote execution](https://bazel.build/remote/rbe) without built-in language-specific logic. -### Understanding labels +### Understanding labels {#understanding-labels} A [label](https://bazel.build/reference/glossary#label) is a string Bazel uses to identify a target or a file. Labels are used in command line arguments and in @@ -343,7 +343,7 @@ $ bazel build //... ``` -## Test your project +## Test your project {#test-project} Next, move to the `stage3` directory, where we'll add a test. @@ -437,7 +437,7 @@ $ bazel test //... ``` -## Conclusion and further reading +## Conclusion and further reading {#conclusion-and} In this tutorial, we built and tested a small Go project with Bazel, and we learned some core Bazel concepts along the way.
diff --git a/docs/tutorials/ccp-toolchain-config.mdx b/docs/tutorials/ccp-toolchain-config.mdx index f5b6f04..205f27f 100644 --- a/docs/tutorials/ccp-toolchain-config.mdx +++ b/docs/tutorials/ccp-toolchain-config.mdx
@@ -7,7 +7,7 @@ This tutorial uses an example scenario to describe how to configure C++ toolchains for a project. -## What you'll learn +## What you'll learn {#what-you-learn} In this tutorial you learn how to: @@ -21,13 +21,13 @@ * Cross-compile the binary for android by running `bazel build //main:hello-world --platforms=//:android_x86_64` -## Before you begin +## Before you begin {#before-you-begin} This tutorial assumes you are on Linux and have successfully built C++ applications and installed the appropriate tooling and libraries. The tutorial uses `clang version 19`, which you can install on your system. -### Set up the build environment +### Set up the build environment {#setup-build-environment} Set up your build environment as follows: @@ -71,7 +71,7 @@ `@platforms//host` using `@bazel_tools+cc_configure_extension+local_config_cc//:cc-compiler-k8`. -## Configure the C++ toolchain +## Configure the C++ toolchain {#configure-cc-toolchain} To configure the C++ toolchain, repeatedly build the application and eliminate each error one by one as described as following. @@ -447,7 +447,7 @@ create a separate rules (i.e. `CcToolchainConfigInfo` provider) for separate platforms. -## Review your work +## Review your work {#review-your-work} In this tutorial you learned how to configure a basic C++ toolchain, but toolchains are more powerful than this example. @@ -468,7 +468,7 @@ - You can create features to customize which flags should be passed to different actions, be it linking or any other type of action. -## Further reading +## Further reading {#further-reading} For more details, see [C++ toolchain configuration](/docs/cc-toolchain-config-reference)
diff --git a/docs/tutorials/cpp-use-cases.mdx b/docs/tutorials/cpp-use-cases.mdx index f25f80b..1a57f54 100644 --- a/docs/tutorials/cpp-use-cases.mdx +++ b/docs/tutorials/cpp-use-cases.mdx
@@ -12,7 +12,7 @@ For information on cc_library and hdrs header files, see <a href="/reference/be/c-cpp#cc_library">cc_library</a>. -## Including multiple files in a target +## Including multiple files in a target {#multiple-files-target} You can include multiple files in a single target with <a href="/reference/be/functions#glob">glob</a>. @@ -30,7 +30,7 @@ same directory as the `BUILD` file that contains this target (excluding subdirectories). -## Using transitive includes +## Using transitive includes {#transitive-includes} If a file includes a header, then any rule with that file as a source (that is, having that file in the `srcs`, `hdrs`, or `textual_hdrs` attribute) should @@ -65,7 +65,7 @@ Here, the `sandwich` library depends on the `bread` library, which depends on the `flour` library. -## Adding include paths +## Adding include paths {#add-include-paths} Sometimes you cannot (or do not want to) root include paths at the workspace root. Existing libraries might already have an include directory that doesn't @@ -101,7 +101,7 @@ This is especially useful for external dependencies, as their header files must otherwise be included with a `/` prefix. -## Include external libraries +## Include external libraries {#include-external-libraries} Suppose you are using [Google Test](https://github.com/google/googletest) . @@ -112,7 +112,7 @@ bazel_dep(name = "googletest", version = "1.15.2") ``` -## Writing and running C++ tests +## Writing and running C++ tests {#run-c-tests} For example, you could create a test `./test/hello-test.cc`, such as: @@ -164,7 +164,7 @@ ``` -## Adding dependencies on precompiled libraries +## Adding dependencies on precompiled libraries {#precompiled-libraries} If you want to use a library of which you only have a compiled version (for example, headers and a `.so` file) wrap it in a `cc_library` rule: