From c1941eb82e86299757da2e95f522a7f6cc78d936 Mon Sep 17 00:00:00 2001 From: "promptless[bot]" <179508745+promptless[bot]@users.noreply.github.com> Date: Mon, 13 Oct 2025 21:58:33 +0000 Subject: [PATCH 1/2] Documentation updates from Promptless --- docs.json | 12 ++ reference/flag-cheatsheet.mdx | 342 ++++++++++++++++++++++++++++++++ reference/skyframe.mdx | 2 +- reference/test-encyclopedia.mdx | 308 ++++++++++++++++++++++++++++ 4 files changed, 663 insertions(+), 1 deletion(-) create mode 100644 reference/flag-cheatsheet.mdx create mode 100644 reference/test-encyclopedia.mdx diff --git a/docs.json b/docs.json index 89ac54c..c504cc6 100644 --- a/docs.json +++ b/docs.json @@ -185,6 +185,18 @@ "reference/glossary" ] }, + { + "group": "Test Encyclopedia", + "pages": [ + "reference/test-encyclopedia" + ] + }, + { + "group": "Flag Cheat Sheet", + "pages": [ + "reference/flag-cheatsheet" + ] + }, { "group": "Skyframe", "pages": [ diff --git a/reference/flag-cheatsheet.mdx b/reference/flag-cheatsheet.mdx new file mode 100644 index 0000000..51194be --- /dev/null +++ b/reference/flag-cheatsheet.mdx @@ -0,0 +1,342 @@ +--- +title: 'Bazel Flag Cheat Sheet' +--- + +Navigating Bazel's extensive list of command line flags can be a challenge. This page focuses on the most crucial flags you'll need to know. + + +Select the flag name in table to navigate to its entry in the command line reference. + + +## Useful general options + +The following flags are meant to be set explicitly on the command line. + +### --config + +You can organize flags in a `.bazelrc` file into configurations, like ones for debugging or release builds. Additional configuration groups can be selected with `--config=`. + +[See command line reference](/reference/command-line-reference#flag--config) + +### --keep_going + +Bazel should try as much as possible to continue with build and test execution. By default, Bazel fails eagerly. + +[See command line reference](/reference/command-line-reference#flag--keep_going) + +### --remote_download_outputs + +When using remote execution or caching (both disk and remote), you can signal to Bazel that you want to download **all** (intermediate) build artifacts as follows: + +```bash +--remote_download_outputs=all +``` + +By default, Bazel only downloads top-level artifacts, such as the final binary, and intermediate artifacts that are necessary for local actions. + +[See command line reference](/reference/command-line-reference#flag--remote_download_outputs) + +### --stamp + +Adds build info (user, timestamp) to binaries. + + +Because this increases build time, it's only intended for release builds. + + +[See command line reference](/reference/command-line-reference#flag--stamp) + +## Uncover Build & Test Issues + +The following flags can help you better understand Bazel build or test errors. + +### --announce_rc + +Shows which flags are implicitly set through user-defined, machine-defined, or project-defined `.bazelrc` files. + +[See command line reference](/reference/command-line-reference#flag--announce_rc) + +### --auto_output_filter + +By default, Bazel tries to prevent log spam and does only print compiler warnings and Starlark debug output for packages and subpackages requested on the command line. To disable all filtering, set `--auto_output_filter=none`. + +[See command line reference](/reference/command-line-reference#flag--auto_output_filter) + +### --sandbox_debug + +Lets you drill into sandboxing errors. For details on why Bazel sandboxes builds by default and what gets sandboxed, see our [sandboxing documentation](/docs/sandboxing). + + +If you think the error might be caused by sandboxing, try turning sandboxing off temporarily. + +To do this, add `--spawn_strategy=local` to your command. + + +[See command line reference](/reference/command-line-reference#flag--sandbox_debug) + +### --subcommands (-s) + +Displays a comprehensive list of every command that Bazel runs during a build, regardless of whether it succeeds or fails. + +[See command line reference](/reference/command-line-reference#flag--subcommands) + +## Startup + + +Startup flags need to be passed before the command and cause a server restart. Toggle these flags with caution. + + +### --bazelrc + +You can specify default Bazel options in `.bazelrc` files. If multiple `.bazelrc` files exist, you can select which one to use with `--bazelrc=/path/to/.bazelrc`. + +To ignore all `.bazelrc` files, use `--bazelrc=/dev/null`. + +[See command line reference](/reference/command-line-reference#flag--bazelrc) + +### --output_base + +Bazel stores all data at `~/.cache/bazel/_bazel_$USER` by default. If this directory is on a network drive, you may want to relocate it to local storage using `--output_base=/path/to/base`. + +[See command line reference](/reference/command-line-reference#flag--output_base) + +## Set Bazelrc files + +You can control which `.bazelrc` files Bazel reads and in what order. + +### --bazelrc + +Specifies the path to a `.bazelrc` file to use. Can be passed multiple times. + +[See command line reference](/reference/command-line-reference#flag--bazelrc) + +### --nosystem_rc + +Prevents reading system-wide `.bazelrc` files. + +[See command line reference](/reference/command-line-reference#flag--nosystem_rc) + +### --noworkspace_rc + +Prevents reading workspace `.bazelrc` files. + +[See command line reference](/reference/command-line-reference#flag--noworkspace_rc) + +### --nohome_rc + +Prevents reading home directory `.bazelrc` files. + +[See command line reference](/reference/command-line-reference#flag--nohome_rc) + +## Building and Testing + +Flags for optimizing your build and test workflows. + +### --jobs (-j) + +Controls how many parallel jobs Bazel runs. The default is based on your host's capacity. Setting it too high may cause thrashing, while setting it too low underutilizes resources. + +```bash +bazel build --jobs=50 //my:target +``` + +[See command line reference](/reference/command-line-reference#flag--jobs) + +### --local_resources + +Explicitly sets the amount of local resources (RAM, CPU) that Bazel can use. Useful when running builds on machines with limited resources. + +```bash +--local_resources=12000,8,1.0 +``` + +[See command line reference](/reference/command-line-reference#flag--local_resources) + +### --test_output + +Controls how test output is displayed: +- `summary` - shows only final summary (default) +- `errors` - shows output from failed tests +- `all` - shows all test output +- `streamed` - streams test output in real-time + +```bash +bazel test --test_output=errors //my:test +``` + +[See command line reference](/reference/command-line-reference#flag--test_output) + +### --test_filter + +Runs only tests whose names match the specified pattern. Useful for running a subset of tests. + +```bash +bazel test --test_filter=MyTestCase.testMethod //my:test +``` + +[See command line reference](/reference/command-line-reference#flag--test_filter) + +### --cache_test_results + +Controls whether test results are cached. Set to `no` or `false` to force tests to re-run even if nothing has changed. + +```bash +bazel test --cache_test_results=no //my:test +``` + +[See command line reference](/reference/command-line-reference#flag--cache_test_results) + +## Remote Execution and Caching + +Flags for configuring remote build execution and caching. + +### --remote_executor + +Specifies the remote execution endpoint. + +```bash +--remote_executor=grpc://remote.build.example.com:8080 +``` + +[See command line reference](/reference/command-line-reference#flag--remote_executor) + +### --remote_cache + +Specifies the remote cache endpoint. + +```bash +--remote_cache=grpc://cache.build.example.com:8080 +``` + +[See command line reference](/reference/command-line-reference#flag--remote_cache) + +### --remote_timeout + +Sets the timeout for remote execution and cache operations. + +```bash +--remote_timeout=60s +``` + +[See command line reference](/reference/command-line-reference#flag--remote_timeout) + +## Debugging + +Flags to help debug build issues. + +### --explain + +Generates a detailed explanation of why each action was executed, writing it to the specified file. + +```bash +bazel build --explain=explain.log //my:target +``` + +[See command line reference](/reference/command-line-reference#flag--explain) + +### --verbose_explanations + +Provides more detailed explanations when used with `--explain`. + +[See command line reference](/reference/command-line-reference#flag--verbose_explanations) + +### --profile + +Generates a JSON profile of the build, useful for performance analysis. + +```bash +bazel build --profile=profile.json //my:target +``` + +You can analyze the profile with `bazel analyze-profile profile.json`. + +[See command line reference](/reference/command-line-reference#flag--profile) + +## Output Control + +### --output_filter + +Filters build output to show only messages from targets matching the specified pattern. + +```bash +--output_filter=^//my/package +``` + +[See command line reference](/reference/command-line-reference#flag--output_filter) + +### --show_progress + +Controls whether to show progress messages during build. + +[See command line reference](/reference/command-line-reference#flag--show_progress) + +### --show_progress_rate_limit + +Sets the minimum time between progress updates (in seconds). + +```bash +--show_progress_rate_limit=1.0 +``` + +[See command line reference](/reference/command-line-reference#flag--show_progress_rate_limit) + +## Sandboxing + +### --spawn_strategy + +Controls the execution strategy for actions. Common values: +- `sandboxed` - run in sandbox (default on Linux/macOS) +- `local` - run without sandboxing +- `worker` - use persistent worker processes +- `remote` - execute remotely + +```bash +--spawn_strategy=local +``` + +[See command line reference](/reference/command-line-reference#flag--spawn_strategy) + +### --sandbox_tmpfs_path + +Mounts a temporary filesystem at the specified path within the sandbox. Can improve performance for heavy I/O operations. + +```bash +--sandbox_tmpfs_path=/tmp +``` + +[See command line reference](/reference/command-line-reference#flag--sandbox_tmpfs_path) + +## Configuration + +### --compilation_mode (-c) + +Sets the compilation mode: +- `fastbuild` - fast compilation with minimal optimizations (default) +- `opt` - optimized build for release +- `dbg` - debug build with symbols + +```bash +bazel build -c opt //my:target +``` + +[See command line reference](/reference/command-line-reference#flag--compilation_mode) + +### --platforms + +Specifies the target platform for the build. + +```bash +--platforms=@platforms//os:linux +``` + +[See command line reference](/reference/command-line-reference#flag--platforms) + +### --cpu + +Specifies the target CPU architecture. Being replaced by `--platforms`. + +```bash +--cpu=k8 +``` + +[See command line reference](/reference/command-line-reference#flag--cpu) diff --git a/reference/skyframe.mdx b/reference/skyframe.mdx index ba9149f..8047056 100644 --- a/reference/skyframe.mdx +++ b/reference/skyframe.mdx @@ -195,4 +195,4 @@ implementations Bazel uses to perform a build: As a visual aid, this diagram shows the relationships between SkyFunction implementations after a build of Bazel itself: -![A graph of SkyFunction implementation relationships](/reference/skyframe.png) +![A graph of SkyFunction implementation relationships](https://promptless-customer-doc-assets.s3.amazonaws.com/docs-images/org_33oBWv0plYpZ78RGDScbYDj8Ise/skyframe-graph-1760392307.png) diff --git a/reference/test-encyclopedia.mdx b/reference/test-encyclopedia.mdx new file mode 100644 index 0000000..7b88baf --- /dev/null +++ b/reference/test-encyclopedia.mdx @@ -0,0 +1,308 @@ +--- +title: 'Test Encyclopedia' +--- + +An exhaustive specification of the test execution environment. + +## Background + +The Bazel BUILD language includes rules which can be used to define automated test programs in many languages. + +Tests are run using `bazel test`. + +Users may also execute test binaries directly. This is allowed but not endorsed, as such an invocation will not adhere to the mandates described below. + +Tests should be *hermetic*: that is, they ought to access only those resources on which they have a declared dependency. If tests are not properly hermetic then they do not give historically reproducible results. This could be a significant problem for culprit finding (determining which change broke a test), release engineering auditability, and resource isolation of tests (automated testing frameworks ought not DDOS a server because some tests happen to talk to it). + +## 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 runner and the build system. + +The test environment specification helps test authors avoid relying on unspecified behavior, and thus gives the testing infrastructure more freedom to make implementation changes. The specification tightens up some holes that currently allow many tests to pass despite not being properly hermetic, deterministic, and reentrant. + +This page is intended to be both normative and authoritative. If this specification and the implemented behavior of test runner disagree, the specification takes precedence. + +## 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 + +The purpose of Bazel tests is to confirm some property of the source files checked into the repository. (On this page, "source files" includes test data, golden outputs, and anything else kept under version control.) One user writes a test to assert an invariant which they expect to be maintained. Other users execute the test later to check whether the invariant has been broken. If the test depends on any variables other than source files (non-hermetic), its value is diminished, because the later users cannot be sure their changes are at fault when the test stops passing. + +Therefore the outcome of a test must depend only on: + +* source files on which the test has a declared dependency +* products of the build system on which the test has a declared dependency +* resources whose behavior is guaranteed by the test runner to remain constant + +Currently, such behavior is not enforced. However, test runners reserve the right to add such enforcement in the future. + +## Role of the 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 language-specific harness with the test code. Test rules must produce other outputs as well. In addition to the primary test executable, the test runner will need a manifest of **runfiles**, input files which should be made available to the test at runtime, and it may need information about the type, size, and tags of a test. + +The build system may use the runfiles to deliver code as well as data. (This might be used as an optimization to make each test binary smaller by sharing files across tests, such as through the use of dynamic linking.) The build system should ensure that the generated executable loads these files via the runfiles image provided by the test runner, rather than hardcoded references to absolute locations in the source or output tree. + +## Role of the 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, an IDE might allow the execution of Java tests in-process. However, the result of running the test as a standalone process must be considered authoritative. If a test process runs to completion and terminates normally with an exit code of zero, the test has passed. Any other result is considered a test failure. In particular, writing any of the strings `PASS` or `FAIL` to stdout has no significance to the test runner. + +If a test takes too long to execute, exceeds some resource limit, or the test runner otherwise detects prohibited behavior, it may choose to kill the test and treat the run as a failure. The runner must not report the test as passing after sending a signal to the test process or any children thereof. + +The whole test target (not individual methods or tests) is given a limited amount of time to run to completion. The time limit for a test is based on its [`timeout`](/reference/be/common-definitions#test.timeout) attribute according to the following table: + +| timeout | Time Limit (sec.) | +|---------|-------------------| +| short | 60 | +| moderate | 300 | +| long | 900 | +| eternal | 3600 | + +Tests which do not explicitly specify a timeout have one implied based on the test's [`size`](/reference/be/common-definitions#test.size) as follows: + +| size | Implied timeout label | +|------|----------------------| +| small | short | +| medium | moderate | +| large | long | +| enormous | eternal | + +A "large" test with no explicit timeout setting will be allotted 900 seconds to run. A "medium" test with a timeout of "short" will be allotted 60 seconds. + +Unlike `timeout`, the `size` additionally determines the assumed peak usage of other resources (like RAM) when running the test locally, as described in [Common definitions](/reference/be/common-definitions#common-attributes-tests). + +All combinations of `size` and `timeout` labels are legal, so an "enormous" test may be declared to have a timeout of "short". Presumably it would do some really horrible things very quickly. + +Tests may return arbitrarily fast regardless of timeout. A test is not penalized for an overgenerous timeout, although a warning may be issued: you should generally set your timeout as tight as you can without incurring any flakiness. + +The test timeout can be overridden with the `--test_timeout` bazel flag when manually running under conditions that are known to be slow. The `--test_timeout` values are in seconds. For example, `--test_timeout=120` sets the test timeout to two minutes. + +There is also a recommended lower bound for test timeouts as follows: + +| timeout | Time minimum (sec.) | +|---------|---------------------| +| short | 0 | +| moderate | 30 | +| long | 300 | +| eternal | 900 | + +For example, if a "moderate" test completes in 5.5s, consider setting `timeout = "short"` or `size = "small"`. Using the bazel `--test_verbose_timeout_warnings` command line option will show the tests whose specified size is too big. + +Test sizes and timeouts are specified in the BUILD file according to the specification [here](/reference/be/common-definitions#common-attributes-tests). If unspecified, a test's size will default to "medium". + +If the main process of a test exits, but some of its children are still running, the test runner should consider the run complete and count it as a success or failure based on the exit code observed from the main process. The test runner may kill any stray processes. Tests should not leak processes in this fashion. + +## Test sharding + +Tests can be parallelized via test sharding. See [`--test_sharding_strategy`](/reference/command-line-reference#flag--test_sharding_strategy) and [`shard_count`](/reference/be/common-definitions#common-attributes-tests) to enable test sharding. When sharding is enabled, the test runner is launched once per shard. The environment variable [`TEST_TOTAL_SHARDS`](#initial-conditions) is the number of shards, and [`TEST_SHARD_INDEX`](#initial-conditions) is the shard index, beginning at 0. Runners use this information to select which tests to run - for example, using a round-robin strategy. Not all test runners support sharding. If a runner supports sharding, it must create or update the last modified date of the file specified by [`TEST_SHARD_STATUS_FILE`](#initial-conditions). Otherwise, if [`--incompatible_check_sharding_support`](/reference/command-line-reference#flag--incompatible_check_sharding_support) is enabled, Bazel will fail the test if it is sharded. + +## Initial conditions + +When executing a test, the test runner must establish certain initial conditions. + +The test runner must invoke each test with the path to the test executable in `argv[0]`. This path must be relative and beneath the test's current directory (which is in the runfiles tree, see below). The test runner should not pass any other arguments to a test unless the user explicitly requests it. + +The initial environment block shall be composed as follows: + +| Variable | Value | Status | +|----------|-------|--------| +| `HOME` | value of `$TEST_TMPDIR` | recommended | +| `LANG` | *unset* | required | +| `LANGUAGE` | *unset* | required | +| `LC_ALL` | *unset* | required | +| `LC_COLLATE` | *unset* | required | +| `LC_CTYPE` | *unset* | required | +| `LC_MESSAGES` | *unset* | required | +| `LC_MONETARY` | *unset* | required | +| `LC_NUMERIC` | *unset* | required | +| `LC_TIME` | *unset* | required | +| `LD_LIBRARY_PATH` | colon-separated list of directories containing shared libraries | optional | +| `JAVA_RUNFILES` | value of `$TEST_SRCDIR` | deprecated | +| `LOGNAME` | value of `$USER` | required | +| `PATH` | `/usr/local/bin:/usr/local/sbin:/usr/bin:/usr/sbin:/bin:/sbin:.` | recommended | +| `PWD` | `$TEST_SRCDIR/` | recommended | +| `SHLVL` | `2` | recommended | +| `TEST_INFRASTRUCTURE_FAILURE_FILE` | absolute path to a private file in a writable directory (This file should only be used to report failures originating from the testing infrastructure, not as a general mechanism for reporting flaky failures of tests. In this context, testing infrastructure is defined as systems or libraries that are not test-specific, but can cause test failures by malfunctioning. The first line is the name of the testing infrastructure component that caused the failure, the second one a human-readable description of the failure. Additional lines are ignored.) | optional | +| `TEST_LOGSPLITTER_OUTPUT_FILE` | absolute path to a private file in a writable directory (used to write Logsplitter protobuffer log) | optional | +| `TEST_PREMATURE_EXIT_FILE` | absolute path to a private file in a writable directory (used for catching calls to `exit()`) | optional | +| `TEST_RANDOM_SEED` | If the `--runs_per_test` option is used, `TEST_RANDOM_SEED` is set to the run number (starting with 1) for each individual test run. | optional | +| `TEST_RUN_NUMBER` | If the `--runs_per_test` option is used, `TEST_RUN_NUMBER` is set to the run number (starting with 1) for each individual test run. | optional | +| `TEST_TARGET` | The name of the target being tested | optional | +| `TEST_SIZE` | The test `size` | optional | +| `TEST_TIMEOUT` | The test `timeout` in seconds | optional | +| `TEST_SHARD_INDEX` | shard index, if sharding is used | optional | +| `TEST_SHARD_STATUS_FILE` | path to file to touch to indicate support for sharding | optional | +| `TEST_SRCDIR` | absolute path to the base of the runfiles tree | required | +| `TEST_TOTAL_SHARDS` | total [shard count](/reference/be/common-definitions#test.shard_count), if sharding is used | optional | +| `TEST_TMPDIR` | absolute path to a private writable directory | required | +| `TEST_WORKSPACE` | the local repository's workspace name | optional | +| `TEST_UNDECLARED_OUTPUTS_DIR` | absolute path to a private writable directory (used to write undeclared test outputs). Any files written to the `TEST_UNDECLARED_OUTPUTS_DIR` directory will be zipped up and added to an `outputs.zip` file under `bazel-testlogs`. | optional | +| `TEST_UNDECLARED_OUTPUTS_ANNOTATIONS_DIR` | absolute path to a private writable directory (used to write undeclared test output annotation `.part` and `.pb` files). | optional | +| `TEST_WARNINGS_OUTPUT_FILE` | absolute path to a private file in a writable directory (used to write test target warnings) | optional | +| `TESTBRIDGE_TEST_ONLY` | value of `--test_filter`, if specified | optional | +| `TZ` | `UTC` | required | +| `USER` | value of `getpwuid(getuid())->pw_name` | required | +| `XML_OUTPUT_FILE` | Location to which test actions should write a test result XML output file. Otherwise, Bazel generates a default XML output file wrapping the test log as part of the test action. The XML schema is based on the [JUnit test result schema](https://windyroad.com.au/dl/Open%20Source/JUnit.xsd). | optional | +| `BAZEL_TEST` | Signifies test executable is being driven by `bazel test` | required | + +The environment may contain additional entries. Tests should not depend on the presence, absence, or value of any environment variable not listed above. + +The initial working directory shall be `$TEST_SRCDIR/$TEST_WORKSPACE`. + +The current process id, process group id, session id, and parent process id are unspecified. The process may or may not be a process group leader or a session leader. The process may or may not have a controlling terminal. The process may have zero or more running or unreaped child processes. The process should not have multiple threads when the test code gains control. + +File descriptor 0 (`stdin`) shall be open for reading, but what it is attached to is unspecified. Tests must not read from it. File descriptors 1 (`stdout`) and 2 (`stderr`) shall be open for writing, but what they are attached to is unspecified. It could be a terminal, a pipe, a regular file, or anything else to which characters can be written. They may share an entry in the open file table (meaning that they cannot seek independently). Tests should not inherit any other open file descriptors. + +The initial umask shall be `022` or `027`. + +No alarm or interval timer shall be pending. + +The initial mask of blocked signals shall be empty. All signals shall be set to their default action. + +The initial resource limits, both soft and hard, should be set as follows: + +| Resource | Limit | +|----------|-------| +| `RLIMIT_AS` | unlimited | +| `RLIMIT_CORE` | unspecified | +| `RLIMIT_CPU` | unlimited | +| `RLIMIT_DATA` | unlimited | +| `RLIMIT_FSIZE` | unlimited | +| `RLIMIT_LOCKS` | unlimited | +| `RLIMIT_MEMLOCK` | unlimited | +| `RLIMIT_MSGQUEUE` | unspecified | +| `RLIMIT_NICE` | unspecified | +| `RLIMIT_NOFILE` | at least 1024 | +| `RLIMIT_NPROC` | unspecified | +| `RLIMIT_RSS` | unlimited | +| `RLIMIT_RTPRIO` | unspecified | +| `RLIMIT_SIGPENDING` | unspecified | +| `RLIMIT_STACK` | unlimited, or 2044KB <= rlim <= 8192KB | + +The initial process times (as returned by `times()`) and resource utilization (as returned by `getrusage()`) are unspecified. + +The initial scheduling policy and priority are unspecified. + +## Role of the 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 + +The root directory observed by a test may or may not be the real root directory. + +`/proc` shall be mounted. + +All build tools shall be present at the absolute paths under `/usr` used by a local installation. + +Paths starting with `/home` may not be available. Tests should not access any such paths. + +`/tmp` shall be writable, but tests should avoid using these paths. + +Tests must not assume that any constant path is available for their exclusive use. + +Tests must not assume that atimes are enabled for any mounted filesystem. + +### Users and groups + +The users root, nobody, and unittest must exist. The groups root, nobody, and eng must exist. + +Tests must be executed as a non-root user. The real and effective user ids must be equal; likewise for group ids. Beyond this, the current user id, group id, user name, and group name are unspecified. The set of supplementary group ids is unspecified. + +The current user id and group id must have corresponding names which can be retrieved with `getpwuid()` and `getgrgid()`. The same may not be true for supplementary group ids. + +The current user must have a home directory. It may not be writable. Tests must not attempt to write to it. + +### 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 + +Tests are granted at least one CPU core. Others may be available but this is not guaranteed. Other performance aspects of this core are not specified. You can increase the reservation to a higher number of CPU cores by adding the tag "cpu:n" (where n is a positive number) to a test rule. If a machine has less total CPU cores than requested, Bazel will still run the test. If a test uses [sharding](#test-sharding), each individual shard will reserve the number of CPU cores specified here. + +Tests may create subprocesses, but not process groups or sessions. + +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 + +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 + +All file paths specified in test environment variables point to somewhere on the local filesystem, unless otherwise specified. + +Tests should create files only within the directories specified by `$TEST_TMPDIR` and `$TEST_UNDECLARED_OUTPUTS_DIR` (if set). + +These directories will be initially empty. + +Tests must not attempt to remove, chmod, or otherwise alter these directories. + +These directories may be a symbolic links. + +The filesystem type of `$TEST_TMPDIR/.` remains unspecified. + +Tests may also write .part files to the `$TEST_UNDECLARED_OUTPUTS_ANNOTATIONS_DIR` to annotate undeclared output files. + +In rare cases, a test may be forced to create files in `/tmp`. For example, [path length limits for Unix domain sockets](https://serverfault.com/questions/641347) typically require creating the socket under `/tmp`. Bazel will be unable to track such files; the test itself must take care to be hermetic, to use unique paths to avoid colliding with other, simultaneously running tests and non-test processes, and to clean up the files it creates in `/tmp`. + +Some popular testing frameworks, such as [JUnit4 `TemporaryFolder`](https://junit.org/junit4/javadoc/latest/org/junit/rules/TemporaryFolder.html) or [Go `TempDir`](https://golang.org/pkg/testing/#T.TempDir), have their own ways to create a temporary directory under `/tmp`. These testing frameworks include functionality that cleans up files in `/tmp`, so you may use them even though they create files outside of `TEST_TMPDIR`. + +Tests must access inputs through the **runfiles** mechanism, or other parts of the execution environment which are specifically intended to make input files available. + +Tests must not access other outputs of the build system at paths inferred from the location of their own executable. + +It is unspecified whether the runfiles tree contains regular files, symbolic links, or a mixture. The runfiles tree may contain symlinks to directories. Tests should avoid using paths containing `..` components within the runfiles tree. + +No directory, file, or symlink within the runfiles tree (including paths which traverse symlinks) should be writable. (It follows that the initial working directory should not be writable.) Tests must not assume that any part of the runfiles is writable, or owned by the current user (for example, `chmod` and `chgrp` may fail). + +The runfiles tree (including paths which traverse symlinks) must not change during test execution. Parent directories and filesystem mounts must not change in any way which affects the result of resolving a path within the runfiles tree. + +In order to catch early exit, a test may create a file at the path specified by `TEST_PREMATURE_EXIT_FILE` upon start and remove it upon exit. If Bazel sees the file when the test finishes, it will assume that the test exited prematurely and mark it as having failed. + +## Execution platform + +The [execution platform](/extending/platforms) for a test action is determined via [toolchain resolution](/extending/toolchains#toolchain-resolution), just like for any other action. Each test rule has an implicitly defined [`test` exec group](/extending/exec-groups#exec-groups-for-native-rules) that, unless overridden, has a mandatory toolchain requirement on `@bazel_tools//tools/test:default_test_toolchain_type`. Toolchains of this type do not carry any data in the form of providers, but can be used to influence the execution platform of the test action. By default, Bazel registers two such toolchains: + +* If `--@bazel_tools//tools/test:incompatible_use_default_test_toolchain` is disabled (the current default), the active test toolchain is `@bazel_tools//tools/test:legacy_test_toolchain`. This toolchain does not impose any constraints and thus test actions without manually specified exec constraints are configured for the first registered execution platform. This is often not the intended behavior in multi-platform builds as it can result in e.g. a test binary built for Linux on a Windows machine to be executed on Windows. +* If `--@bazel_tools//tools/test:incompatible_use_default_test_toolchain` is enabled, the active test toolchain is `@bazel_tools//tools/test:default_test_toolchain`. This toolchain requires an execution platform to match all the constraints of the test rule's target platform. In particular, the target platform is compatible with this toolchain if it is also registered as an execution platform. If no such platform is found, the test rule fails with a toolchain resolution error. + +Users can register additional toolchains for this type to influence this behavior and their toolchains will take precedence over the default ones. Test rule authors can define their own test toolchain type and also register a default toolchain for it. + +## Tag conventions + +Some tags in the test rules have a special meaning. See also the [Bazel Build Encyclopedia on the `tags` attribute](/reference/be/common-definitions#common.tags). + +| Tag | Meaning | +|-----|---------| +| `exclusive` | run no other test at the same time | +| `external` | test has an external dependency; disable test caching | +| `large` | `test_suite` convention; suite of large tests | +| `manual` | don't include test target in wildcard target patterns like `:...`, `:*`, or `:all` | +| `medium` | `test_suite` convention; suite of medium tests | +| `small` | `test_suite` convention; suite of small tests | +| `smoke` | `test_suite` convention; means it should be run before committing code changes into the version control system | + +Note: bazel `query` does not respect the manual tag. + +## 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 + +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 + +The runfiles directory is declared as a compile-time dependency of the `*_binary()` rule. The runfiles directory itself depends on the set of BUILD files that affect the `*_binary()` rule or any of its compile-time or run-time dependencies. Modifying source files does not affect the structure of the runfiles directory, and thus does not trigger any rebuilding. + +### Contents + +The runfiles directory contains the following: + +* **Symlinks to run-time dependencies**: each OutputFile and CommandRule that is a run-time dependency of the `*_binary()` rule is represented by one symlink in the runfiles directory. The name of the symlink is `$(WORKSPACE)/package_name/rule_name`. For example, the symlink for server would be named `$(WORKSPACE)/deps/server/server`, and the full path would be `$(WORKSPACE)/foo/bar/unittest.runfiles/$(WORKSPACE)/deps/server/server`. The destination of the symlink is the OutputFileName() of the OutputFile or CommandRule, expressed as an absolute path. Thus, the destination of the symlink might be `$(WORKSPACE)/linux-dbg/deps/server/42/server`. From 2c6ccb42e85459092e2d49520901858339910a84 Mon Sep 17 00:00:00 2001 From: "promptless[bot]" <179508745+promptless[bot]@users.noreply.github.com> Date: Mon, 13 Oct 2025 22:59:47 +0000 Subject: [PATCH 2/2] Sync documentation updates from Promptless agent --- docs.json | 14 + query/language.mdx | 1538 ++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 1552 insertions(+) create mode 100644 query/language.mdx diff --git a/docs.json b/docs.json index c504cc6..b96b544 100644 --- a/docs.json +++ b/docs.json @@ -179,6 +179,20 @@ "reference/be/shell" ] }, + { + "group": "Command line reference", + "pages": [ + "reference/command-line-reference" + ] + }, + { + "group": "Query reference", + "pages": [ + "query/language", + "query/aquery", + "query/cquery" + ] + }, { "group": "Glossary", "pages": [ diff --git a/query/language.mdx b/query/language.mdx new file mode 100644 index 0000000..5087162 --- /dev/null +++ b/query/language.mdx @@ -0,0 +1,1538 @@ +--- +title: 'Query Language Reference' +--- + +This page is the reference manual for the _Bazel Query Language_ used +when you use `bazel query` to analyze build dependencies. It also +describes the output formats `bazel query` supports. + +For practical use cases, see the [Bazel Query How-To](/query/guide). +## Additional query reference + +In addition to `query`, which runs on the post-loading phase target graph, +Bazel includes *action graph query* and *configurable query*. + +### Action graph query {#aquery} + +The action graph query (`aquery`) operates on the post-analysis Configured +Target Graph and exposes information about **Actions**, **Artifacts**, and +their relationships. `aquery` is useful when you are interested in the +properties of the Actions/Artifacts generated from the Configured Target Graph. +For example, the actual commands run and their inputs, outputs, and mnemonics. + +For more details, see the [aquery reference](/query/aquery). + +### 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, +it doesn't correctly resolve [select statements](/reference/be/functions#select) +and instead returns all possible resolutions of selects. However, the +configurable query environment, `cquery`, properly handles configurations but +doesn't provide all of the functionality of this original query. + +For more details, see the [cquery reference](/query/cquery). + + +## Examples {#examples} + +How do people use `bazel query`? Here are typical examples: + +Why does the `//foo` tree depend on `//bar/baz`? +Show a path: + +``` +somepath(foo/..., //bar/baz:all) +``` + +What C++ libraries do all the `foo` tests depend on that +the `foo_bin` target does not? + +``` +kind("cc_library", deps(kind(".*test rule", foo/...)) except deps(//foo:foo_bin)) +``` + +## Tokens: The lexical syntax {#tokens} + +Expressions in the query language are composed of the following +tokens: + +* **Keywords**, such as `let`. Keywords are the reserved words of the + language, and each of them is described below. The complete set + of keywords is: + + * [`except`](#set-operations) + + * [`in`](#variables) + + * [`intersect`](#set-operations) + + * [`let`](#variables) + + * [`set`](#set) + + * [`union`](#set-operations) + +* **Words**, such as "`foo/...`" or "`.*test rule`" or "`//bar/baz:all`". If a + character sequence is "quoted" (begins and ends with a single-quote ' or + begins and ends with a double-quote "), it is a word. If a character sequence + is not quoted, it may still be parsed as a word. Unquoted words are sequences + of characters drawn from the alphabet characters A-Za-z, the numerals 0-9, + and the special characters `*/@.-_:$~[]` (asterisk, forward slash, at, period, + hyphen, underscore, colon, dollar sign, tilde, left square brace, right square + brace). However, unquoted words may not start with a hyphen `-` or asterisk `*` + even though relative [target names](/concepts/labels#target-names) may start + with those characters. As a special rule meant to simplify the handling of + labels referring to external repositories, unquoted words that start with + `@@` may contain `+` characters. + + Unquoted words also may not include the characters plus sign `+` or equals + sign `=`, even though those characters are permitted in target names. When + writing code that generates query expressions, target names should be quoted. + + Quoting _is_ necessary when writing scripts that construct Bazel query + expressions from user-supplied values. + + ``` + //foo:bar+wiz # WRONG: scanned as //foo:bar + wiz. + //foo:bar=wiz # WRONG: scanned as //foo:bar = wiz. + "//foo:bar+wiz" # OK. + "//foo:bar=wiz" # OK. + ``` + + Note that this quoting is in addition to any quoting that may be required by + your shell, such as: + + ```bash + bazel query ' "//foo:bar=wiz" ' # single-quotes for shell, double-quotes for Bazel. + ``` + + Keywords and operators, when quoted, are treated as ordinary words. For example, `some` is a + keyword but "some" is a word. Both `foo` and "foo" are words. + + However, be careful when using single or double quotes in target names. When + quoting one or more target names, use only one type of quotes (either all + single or all double quotes). + + The following are examples of what the Java query string will be: + + + ``` + 'a"'a' # WRONG: Error message: unclosed quotation. + "a'"a" # WRONG: Error message: unclosed quotation. + '"a" + 'a'' # WRONG: Error message: unexpected token 'a' after query expression '"a" + ' + "'a' + "a"" # WRONG: Error message: unexpected token 'a' after query expression ''a' + ' + "a'a" # OK. + 'a"a' # OK. + '"a" + "a"' # OK + "'a' + 'a'" # OK + ``` + + We chose this syntax so that quote marks aren't needed in most cases. The + (unusual) `".*test rule"` example needs quotes: it starts with a period and + contains a space. Quoting `"cc_library"` is unnecessary but harmless. + +* **Punctuation**, such as parens `()`, period `.` and comma `,`. Words + containing punctuation (other than the exceptions listed above) must be quoted. + +Whitespace characters outside of a quoted word are ignored. + +## 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, +or equivalently, a **graph** (DAG) of targets. This is the only +datatype. + +Set and graph refer to the same datatype, but emphasize different +aspects of it, for example: + +* **Set:** The partial order of the targets is not interesting. +* **Graph:** The partial order of targets is significant. + +### Cycles in the dependency graph {#dependency-graph-cycles} + +Build dependency graphs should be acyclic. + +The algorithms used by the query language are robust against cycles, and will +not report cycles as errors. + +Note that the post-loading phase unconfigured target graph that `bazel query` +operates over may contain cycles that do not exist in the configured target +graph. Cycles in the configured target graph are detected and reported as errors +by [`bazel cquery`](/query/cquery) and [`bazel aquery`](/query/aquery). + +### Implicit dependencies {#implicit-dependencies} + +In addition to build dependencies that are defined explicitly in `BUILD` files, +Bazel adds additional _implicit_ dependencies to rules. Implicit dependencies +may be defined by: + +- [Private attributes](/extending/rules#private_attributes_and_implicit_dependencies) +- [Toolchain requirements](/extending/toolchains#writing-rules-toolchains) + +By default, `bazel query` takes implicit dependencies into account +when computing the query result. This behavior can be changed with +the `--[no]implicit_deps` option. + +Note that, as query does not consider configurations, potential toolchain +**implementations** are not considered dependencies, only the +required toolchain types. See +[toolchain documentation](/extending/toolchains#writing-rules-toolchains). + +### Soundness {#soundness} + +Bazel query language expressions operate over the build +dependency graph, which is the graph implicitly defined by all +rule declarations in all `BUILD` files. It is important to understand +that this graph is somewhat abstract, and does not constitute a +complete description of how to perform all the steps of a build. In +order to perform a build, a _configuration_ is required too; +see the [configurations](/run/bazelrc#configurations) +section of the User's Guide for more detail. + +The result of evaluating an expression in the Bazel query language +is true _for all configurations_, which means that it may be +a conservative over-approximation, and not exactly precise. If you +use the query tool to compute the set of all source files needed +during a build, it may report more than are actually necessary +because, for example, the query tool will include all the files +needed to support message translation, even though you don't intend +to use that feature in your build. + +### On the preservation of graph order {#graph-order} + +Operations preserve any ordering +constraints inherited from their subexpressions. You can think of +this as "the law of conservation of partial order". Consider an +example: if you issue a query to determine the transitive closure of +dependencies of a particular target, the resulting set is ordered +according to the dependency graph. If you filter that set to +include only the targets of `file` kind, the same +_transitive_ partial ordering relation holds between every +pair of targets in the resulting subset - even though none of +these pairs is actually directly connected in the original graph. +(There are no file-file edges in the build dependency graph). + +However, while all operators _preserve_ order, some +operations, such as the [set operations](#set-operations) +don't _introduce_ any ordering constraints of their own. +Consider this expression: + +``` +deps(x) union y +``` + +The order of the final result set is guaranteed to preserve all the +ordering constraints of its subexpressions, namely, that all the +transitive dependencies of `x` are correctly ordered with +respect to each other. However, the query guarantees nothing about +the ordering of the targets in `y`, nor about the +ordering of the targets in `deps(x)` relative to those in +`y` (except for those targets in +`y` that also happen to be in `deps(x)`). + +Operators that introduce ordering constraints include: +`allpaths`, `deps`, `rdeps`, `somepath`, and the target pattern wildcards +`package:*`, `dir/...`, etc. + +### Sky query {#sky-query} + +_Sky Query_ is a mode of query that operates over a specified _universe scope_. + +#### Special functions available only in SkyQuery + +Sky Query mode has the additional query functions `allrdeps` and +`rbuildfiles`. These functions operate over the entire +universe scope (which is why they don't make sense for normal Query). + +#### Specifying a universe scope + +Sky Query mode is activated by passing the following two flags: +(`--universe_scope` or `--infer_universe_scope`) and +`--order_output=no`. +`--universe_scope=,...,` tells query to +preload the transitive closure of the target pattern specified by the target patterns, which can +be both additive and subtractive. All queries are then evaluated in this "scope". In particular, +the [`allrdeps`](#allrdeps) and +[`rbuildfiles`](#rbuildfiles) operators only return results from this scope. +`--infer_universe_scope` tells Bazel to infer a value for `--universe_scope` +from the query expression. This inferred value is the list of unique target patterns in the +query expression, but this might not be what you want. For example: + +```bash +bazel query --infer_universe_scope --order_output=no "allrdeps(//my:target)" +``` + +The list of unique target patterns in this query expression is `["//my:target"]`, so +Bazel treats this the same as the invocation: + +```bash +bazel query --universe_scope=//my:target --order_output=no "allrdeps(//my:target)" +``` + +But the result of that query with `--universe_scope` is only `//my:target`; +none of the reverse dependencies of `//my:target` are in the universe, by +construction! On the other hand, consider: + +```bash +bazel query --infer_universe_scope --order_output=no "tests(//a/... + b/...) intersect allrdeps(siblings(rbuildfiles(my/starlark/file.bzl)))" +``` + +This is a meaningful query invocation that is trying to compute the test targets in the +[`tests`](#tests) expansion of the targets under some directories that +transitively depend on targets whose definition uses a certain `.bzl` file. Here, +`--infer_universe_scope` is a convenience, especially in the case where the choice of +`--universe_scope` would otherwise require you to parse the query expression yourself. + +So, for query expressions that use universe-scoped operators like +[`allrdeps`](#allrdeps) and +[`rbuildfiles`](#rbuildfiles) be sure to use +`--infer_universe_scope` only if its behavior is what you want. + +Sky Query has some advantages and disadvantages compared to the default query. The main +disadvantage is that it cannot order its output according to graph order, and thus certain +[output formats](#output-formats) are forbidden. Its advantages are that it provides +two operators ([`allrdeps`](#allrdeps) and +[`rbuildfiles`](#rbuildfiles)) that are not available in the default query. +As well, Sky Query does its work by introspecting the +[Skyframe](/reference/skyframe) graph, rather than creating a new +graph, which is what the default implementation does. Thus, there are some circumstances in which +it is faster and uses less memory. + +## Expressions: Syntax and semantics of the grammar {#expressions} + +This is the grammar of the Bazel query language, expressed in EBNF notation: + +```none {:.devsite-disable-click-to-copy} +expr ::= {{ '' }}word{{ '' }} + | let {{ '' }}name{{ '' }} = {{ '' }}expr{{ '' }} in {{ '' }}expr{{ '' }} + | ({{ '' }}expr{{ '' }}) + | {{ '' }}expr{{ '' }} intersect {{ '' }}expr{{ '' }} + | {{ '' }}expr{{ '' }} ^ {{ '' }}expr{{ '' }} + | {{ '' }}expr{{ '' }} union {{ '' }}expr{{ '' }} + | {{ '' }}expr{{ '' }} + {{ '' }}expr{{ '' }} + | {{ '' }}expr{{ '' }} except {{ '' }}expr{{ '' }} + | {{ '' }}expr{{ '' }} - {{ '' }}expr{{ '' }} + | set({{ '' }}word{{ '' }} *) + | {{ '' }}word{{ '' }} '(' {{ '' }}int{{ '' }} | {{ '' }}word{{ '' }} | {{ '' }}expr{{ '' }} ... ')' +``` + +The following sections describe each of the productions of this grammar in order. + +### Target patterns {#target-patterns} + +``` +expr ::= {{ '' }}word{{ '' }} +``` + +Syntactically, a _target pattern_ is just a word. It's interpreted as an +(unordered) set of targets. The simplest target pattern is a label, which +identifies a single target (file or rule). For example, the target pattern +`//foo:bar` evaluates to a set containing one element, the target, the `bar` +rule. + +Target patterns generalize labels to include wildcards over packages and +targets. For example, `foo/...:all` (or just `foo/...`) is a target pattern +that evaluates to a set containing all _rules_ in every package recursively +beneath the `foo` directory; `bar/baz:all` is a target pattern that evaluates +to a set containing all the rules in the `bar/baz` package, but not its +subpackages. + +Similarly, `foo/...:*` is a target pattern that evaluates to a set containing +all _targets_ (rules _and_ files) in every package recursively beneath the +`foo` directory; `bar/baz:*` evaluates to a set containing all the targets in +the `bar/baz` package, but not its subpackages. + +Because the `:*` wildcard matches files as well as rules, it's often more +useful than `:all` for queries. Conversely, the `:all` wildcard (implicit in +target patterns like `foo/...`) is typically more useful for builds. + +`bazel query` target patterns work the same as `bazel build` build targets do. +For more details, see [Target Patterns](/run/bazelrc#target-patterns), or +type `bazel help target-syntax`. + +Target patterns may evaluate to a singleton set (in the case of a label), to a +set containing many elements (as in the case of `foo/...`, which has thousands +of elements) or to the empty set, if the target pattern matches no targets. + +All nodes in the result of a target pattern expression are correctly ordered +relative to each other according to the dependency relation. So, the result of +`foo:*` is not just the set of targets in package `foo`, it is also the +_graph_ over those targets. (No guarantees are made about the relative ordering +of the result nodes against other nodes.) For more details, see the +[graph order](#graph-order) section. + +### Variables {#variables} + +```none {:.devsite-disable-click-to-copy} +expr ::= let {{ '' }}name{{ '' }} = {{ '' }}expr{{ '' }}{{ '' }}1{{ '' }} in {{ '' }}expr{{ '' }}{{ '' }}2{{ '' }} + | {{ '' }}$name{{ '' }} +``` + +The Bazel query language allows definitions of and references to +variables. The result of evaluation of a `let` expression is the same as +that of {{ '' }}expr{{ '' }}2, with all free occurrences +of variable {{ '' }}name{{ '' }} replaced by the value of +{{ '' }}expr{{ '' }}1. + +For example, `let v = foo/... in allpaths($v, //common) intersect $v` is +equivalent to the `allpaths(foo/...,//common) intersect foo/...`. + +An occurrence of a variable reference `name` other than in +an enclosing `let {{ '' }}name{{ '' }} = ...` expression is an +error. In other words, top-level query expressions cannot have free +variables. + +In the above grammar productions, `name` is like _word_, but with the +additional constraint that it be a legal identifier in the C programming +language. References to the variable must be prepended with the "$" character. + +Each `let` expression defines only a single variable, but you can nest them. + +Both [target patterns](#target-patterns) and variable references consist of +just a single token, a word, creating a syntactic ambiguity. However, there is +no semantic ambiguity, because the subset of words that are legal variable +names is disjoint from the subset of words that are legal target patterns. + +Technically speaking, `let` expressions do not increase +the expressiveness of the query language: any query expressible in +the language can also be expressed without them. However, they +improve the conciseness of many queries, and may also lead to more +efficient query evaluation. + +### Parenthesized expressions {#parenthesized-expressions} + +```none {:.devsite-disable-click-to-copy} +expr ::= ({{ '' }}expr{{ '' }}) +``` + +Parentheses associate subexpressions to force an order of evaluation. +A parenthesized expression evaluates to the value of its argument. + +### Algebraic set operations: intersection, union, set difference {#algebraic-set-operations} + +```none {:.devsite-disable-click-to-copy} +expr ::= {{ '' }}expr{{ '' }} intersect {{ '' }}expr{{ '' }} + | {{ '' }}expr{{ '' }} ^ {{ '' }}expr{{ '' }} + | {{ '' }}expr{{ '' }} union {{ '' }}expr{{ '' }} + | {{ '' }}expr{{ '' }} + {{ '' }}expr{{ '' }} + | {{ '' }}expr{{ '' }} except {{ '' }}expr{{ '' }} + | {{ '' }}expr{{ '' }} - {{ '' }}expr{{ '' }} +``` + +These three operators compute the usual set operations over their arguments. +Each operator has two forms, a nominal form, such as `intersect`, and a +symbolic form, such as `^`. Both forms are equivalent; the symbolic forms are +quicker to type. (For clarity, the rest of this page uses the nominal forms.) + +For example, + +``` +foo/... except foo/bar/... +``` + +evaluates to the set of targets that match `foo/...` but not `foo/bar/...`. + +You can write the same query as: + +``` +foo/... - foo/bar/... +``` + +The `intersect` (`^`) and `union` (`+`) operations are commutative (symmetric); +`except` (`-`) is asymmetric. The parser treats all three operators as +left-associative and of equal precedence, so you might want parentheses. For +example, the first two of these expressions are equivalent, but the third is not: + +``` +x intersect y union z +(x intersect y) union z +x intersect (y union z) +``` + +Important: Use parentheses where there is any danger of ambiguity in reading a +query expression. + +### Read targets from an external source: set {#set} + +```none {:.devsite-disable-click-to-copy} +expr ::= set({{ '' }}word{{ '' }} *) +``` + +The `set({{ '' }}a{{ '' }} {{ '' }}b{{ '' }} {{ '' }}c{{ '' }} ...)` +operator computes the union of a set of zero or more +[target patterns](#target-patterns), separated by whitespace (no commas). + +In conjunction with the Bourne shell's `$(...)` feature, `set()` provides a +means of saving the results of one query in a regular text file, manipulating +that text file using other programs (such as standard UNIX shell tools), and then +introducing the result back into the query tool as a value for further +processing. For example: + +```bash +bazel query deps(//my:target) --output=label | grep ... | sed ... | awk ... > foo + +bazel query "kind(cc_binary, set($( foo + +bazel query "kind(cc_library, set($(' }}word{{ '' }} '(' {{ '' }}int{{ '' }} | {{ '' }}word{{ '' }} | {{ '' }}expr{{ '' }} ... ')' +``` + +The query language defines several functions. The name of the function +determines the number and type of arguments it requires. The following +functions are available: + +* [`allpaths`](#somepath-allpaths) +* [`attr`](#attr) +* [`buildfiles`](#buildfiles) +* [`rbuildfiles`](#rbuildfiles) +* [`deps`](#deps) +* [`filter`](#filter) +* [`kind`](#kind) +* [`labels`](#labels) +* [`loadfiles`](#loadfiles) +* [`rdeps`](#rdeps) +* [`allrdeps`](#allrdeps) +* [`same_pkg_direct_rdeps`](#same_pkg_direct_rdeps) +* [`siblings`](#siblings) +* [`some`](#some) +* [`somepath`](#somepath-allpaths) +* [`tests`](#tests) +* [`visible`](#visible) + + + +### Transitive closure of dependencies: deps {#deps} + +```none {:.devsite-disable-click-to-copy} +expr ::= deps({{ '' }}expr{{ '' }}) + | deps({{ '' }}expr{{ '' }}, {{ '' }}depth{{ '' }}) +``` + +The `deps({{ '' }}x{{ '' }})` operator evaluates to the graph formed +by the transitive closure of dependencies of its argument set +{{ '' }}x{{ '' }}. For example, the value of `deps(//foo)` is the +dependency graph rooted at the single node `foo`, including all its +dependencies. The value of `deps(foo/...)` is the dependency graphs whose roots +are all rules in every package beneath the `foo` directory. In this context, +'dependencies' means only rule and file targets, therefore the `BUILD` and +Starlark files needed to create these targets are not included here. For that +you should use the [`buildfiles`](#buildfiles) operator. + +The resulting graph is ordered according to the dependency relation. For more +details, see the section on [graph order](#graph-order). + +The `deps` operator accepts an optional second argument, which is an integer +literal specifying an upper bound on the depth of the search. So +`deps(foo:*, 0)` returns all targets in the `foo` package, while +`deps(foo:*, 1)` further includes the direct prerequisites of any target in the +`foo` package, and `deps(foo:*, 2)` further includes the nodes directly +reachable from the nodes in `deps(foo:*, 1)`, and so on. (These numbers +correspond to the ranks shown in the [`minrank`](#output-ranked) output format.) +If the {{ '' }}depth{{ '' }} parameter is omitted, the search is +unbounded: it computes the reflexive transitive closure of prerequisites. + +### Transitive closure of reverse dependencies: rdeps {#rdeps} + +```none {:.devsite-disable-click-to-copy} +expr ::= rdeps({{ '' }}expr{{ '' }}, {{ '' }}expr{{ '' }}) + | rdeps({{ '' }}expr{{ '' }}, {{ '' }}expr{{ '' }}, {{ '' }}depth{{ '' }}) +``` + +The `rdeps({{ '' }}u{{ '' }}, {{ '' }}x{{ '' }})` +operator evaluates to the reverse dependencies of the argument set +{{ '' }}x{{ '' }} within the transitive closure of the universe set +{{ '' }}u{{ '' }}. + +The resulting graph is ordered according to the dependency relation. See the +section on [graph order](#graph-order) for more details. + +The `rdeps` operator accepts an optional third argument, which is an integer +literal specifying an upper bound on the depth of the search. The resulting +graph only includes nodes within a distance of the specified depth from any +node in the argument set. So `rdeps(//foo, //common, 1)` evaluates to all nodes +in the transitive closure of `//foo` that directly depend on `//common`. (These +numbers correspond to the ranks shown in the [`minrank`](#output-ranked) output +format.) If the {{ '' }}depth{{ '' }} parameter is omitted, the +search is unbounded. + +### Transitive closure of all reverse dependencies: allrdeps {#allrdeps} + +``` +expr ::= allrdeps({{ '' }}expr{{ '' }}) + | allrdeps({{ '' }}expr{{ '' }}, {{ '' }}depth{{ '' }}) +``` + +Note: Only available with [Sky Query](#sky-query) + +The `allrdeps` operator behaves just like the [`rdeps`](#rdeps) +operator, except that the "universe set" is whatever the `--universe_scope` flag +evaluated to, instead of being separately specified. Thus, if +`--universe_scope=//foo/...` was passed, then `allrdeps(//bar)` is +equivalent to `rdeps(//foo/..., //bar)`. + +### Direct reverse dependencies in the same package: same_pkg_direct_rdeps {#same_pkg_direct_rdeps} + +``` +expr ::= same_pkg_direct_rdeps({{ '' }}expr{{ '' }}) +``` + +The `same_pkg_direct_rdeps({{ '' }}x{{ '' }})` operator evaluates to the full set of targets +that are in the same package as a target in the argument set, and which directly depend on it. + +### Dealing with a target's package: siblings {#siblings} + +``` +expr ::= siblings({{ '' }}expr{{ '' }}) +``` + +The `siblings({{ '' }}x{{ '' }})` operator evaluates to the full set of targets that are in +the same package as a target in the argument set. + +### Arbitrary choice: some {#some} + +``` +expr ::= some({{ '' }}expr{{ '' }}) + | some({{ '' }}expr{{ '' }}, {{ '' }}count{{ ' '}}) +``` + +The `some({{ '' }}x{{ '' }}, {{ '' }}k{{ '' }})` operator +selects at most {{ '' }}k{{ '' }} targets arbitrarily from its +argument set {{ '' }}x{{ '' }}, and evaluates to a set containing +only those targets. Parameter {{ '' }}k{{ '' }} is optional; if +missing, the result will be a singleton set containing only one target +arbitrarily selected. If the size of argument set {{ '' }}x{{ '' }} is +smaller than {{ '' }}k{{ '' }}, the whole argument set +{{ '' }}x{{ '' }} will be returned. + +For example, the expression `some(//foo:main union //bar:baz)` evaluates to a +singleton set containing either `//foo:main` or `//bar:baz`—though which +one is not defined. The expression `some(//foo:main union //bar:baz, 2)` or +`some(//foo:main union //bar:baz, 3)` returns both `//foo:main` and +`//bar:baz`. + +If the argument is a singleton, then `some` +computes the identity function: `some(//foo:main)` is +equivalent to `//foo:main`. + +It is an error if the specified argument set is empty, as in the +expression `some(//foo:main intersect //bar:baz)`. + +### Path operators: somepath, allpaths {#somepath-allpaths} + +``` +expr ::= somepath({{ '' }}expr{{ '' }}, {{ '' }}expr{{ '' }}) + | allpaths({{ '' }}expr{{ '' }}, {{ '' }}expr{{ '' }}) +``` + +The `somepath({{ '' }}S{{ '' }}, {{ '' }}E{{ '' }})` and +`allpaths({{ '' }}S{{ '' }}, {{ '' }}E{{ '' }})` operators compute +paths between two sets of targets. Both queries accept two +arguments, a set {{ '' }}S{{ '' }} of starting points and a set +{{ '' }}E{{ '' }} of ending points. `somepath` returns the +graph of nodes on _some_ arbitrary path from a target in +{{ '' }}S{{ '' }} to a target in {{ '' }}E{{ '' }}; `allpaths` +returns the graph of nodes on _all_ paths from any target in +{{ '' }}S{{ '' }} to any target in {{ '' }}E{{ '' }}. + +The resulting graphs are ordered according to the dependency relation. +See the section on [graph order](#graph-order) for more details. + + + + + + + +
+
+ Somepath +
somepath(S1 + S2, E), one possible result.
+
+ + 		+
+ Somepath +
somepath(S1 + S2, E), another possible result.
+
+ + 		+
+ Allpaths +
allpaths(S1 + S2, E)
+
+ +
+ +### Target kind filtering: kind {#kind} + +``` +expr ::= kind({{ '' }}word{{ '' }}, {{ '' }}expr{{ '' }}) +``` + +The `kind({{ '' }}pattern{{ '' }}, {{ '' }}input{{ '' }})` +operator applies a filter to a set of targets, and discards those targets +that are not of the expected kind. The {{ '' }}pattern{{ '' }} +parameter specifies what kind of target to match. + +For example, the kinds for the four targets defined by the `BUILD` file +(for package `p`) shown below are illustrated in the table: + + + + + + + + + + + + + + + + + + + + + + + + +
CodeTargetKind
+ 
+        genrule(
+            name = "a",
+            srcs = ["a.in"],
+            outs = ["a.out"],
+            cmd = "...",
+        )
+
+ 		//p:agenrule rule
//p:a.insource file
//p:a.outgenerated file
//p:BUILDsource file
+ +Thus, `kind("cc_.* rule", foo/...)` evaluates to the set +of all `cc_library`, `cc_binary`, etc, +rule targets beneath `foo`, and `kind("source file", deps(//foo))` +evaluates to the set of all source files in the transitive closure +of dependencies of the `//foo` target. + +Quotation of the {{ '' }}pattern{{ '' }} argument is often required +because without it, many [regular expressions](#regex), such as `source +file` and `.*_test`, are not considered words by the parser. + +When matching for `package group`, targets ending in +`:all` may not yield any results. Use `:all-targets` instead. + +### Target name filtering: filter {#filter} + +``` +expr ::= filter({{ '' }}word{{ '' }}, {{ '' }}expr{{ '' }}) +``` + +The `filter({{ '' }}pattern{{ '' }}, {{ '' }}input{{ '' }})` +operator applies a filter to a set of targets, and discards targets whose +labels (in absolute form) do not match the pattern; it +evaluates to a subset of its input. + +The first argument, {{ '' }}pattern{{ '' }} is a word containing a +[regular expression](#regex) over target names. A `filter` expression +evaluates to the set containing all targets {{ '' }}x{{ '' }} such that +{{ '' }}x{{ '' }} is a member of the set {{ '' }}input{{ '' }} and the +label (in absolute form, such as `//foo:bar`) +of {{ '' }}x{{ '' }} contains an (unanchored) match +for the regular expression {{ '' }}pattern{{ '' }}. Since all +target names start with `//`, it may be used as an alternative +to the `^` regular expression anchor. + +This operator often provides a much faster and more robust alternative to the +`intersect` operator. For example, in order to see all +`bar` dependencies of the `//foo:foo` target, one could +evaluate + +``` +deps(//foo) intersect //bar/... +``` + +This statement, however, will require parsing of all `BUILD` files in the +`bar` tree, which will be slow and prone to errors in +irrelevant `BUILD` files. An alternative would be: + +``` +filter(//bar, deps(//foo)) +``` + +which would first calculate the set of `//foo` dependencies and +then would filter only targets matching the provided pattern—in other +words, targets with names containing `//bar` as a substring. + +Another common use of the `filter({{ '' }}pattern{{ '' }}, +{{ '' }}expr{{ '' }})` operator is to filter specific files by their +name or extension. For example, + +``` +filter("\.cc$", deps(//foo)) +``` + +will provide a list of all `.cc` files used to build `//foo`. + +### Rule attribute filtering: attr {#attr} + +``` +expr ::= attr({{ '' }}word{{ '' }}, {{ '' }}word{{ '' }}, {{ '' }}expr{{ '' }}) +``` + +The +`attr({{ '' }}name{{ '' }}, {{ '' }}pattern{{ '' }}, {{ '' }}input{{ '' }})` +operator applies a filter to a set of targets, and discards targets that aren't +rules, rule targets that do not have attribute {{ '' }}name{{ '' }} +defined or rule targets where the attribute value does not match the provided +[regular expression](#regex) {{ '' }}pattern{{ '' }}; it evaluates +to a subset of its input. + +The first argument, {{ '' }}name{{ '' }} is the name of the rule +attribute that should be matched against the provided +[regular expression](#regex) pattern. The second argument, +{{ '' }}pattern{{ '' }} is a regular expression over the attribute +values. An `attr` expression evaluates to the set containing all targets +{{ '' }}x{{ '' }} such that {{ '' }}x{{ '' }} is a +member of the set {{ '' }}input{{ '' }}, is a rule with the defined +attribute {{ '' }}name{{ '' }} and the attribute value contains an +(unanchored) match for the regular expression +{{ '' }}pattern{{ '' }}. If {{ '' }}name{{ '' }} is an +optional attribute and rule does not specify it explicitly then default +attribute value will be used for comparison. For example, + +``` +attr(linkshared, 0, deps(//foo)) +``` + +will select all `//foo` dependencies that are allowed to have a +linkshared attribute (such as, `cc_binary` rule) and have it either +explicitly set to 0 or do not set it at all but default value is 0 (such as for +`cc_binary` rules). + +List-type attributes (such as `srcs`, `data`, etc) are +converted to strings of the form `[value1, ..., valuen]`, +starting with a `[` bracket, ending with a `]` bracket +and using "`, `" (comma, space) to delimit multiple values. +Labels are converted to strings by using the absolute form of the +label. For example, an attribute `deps=[":foo", +"//otherpkg:bar", "wiz"]` would be converted to the +string `[//thispkg:foo, //otherpkg:bar, //thispkg:wiz]`. +Brackets are always present, so the empty list would use string value `[]` +for matching purposes. For example, + +``` +attr("srcs", "\[\]", deps(//foo)) +``` + +will select all rules among `//foo` dependencies that have an +empty `srcs` attribute, while + +``` +attr("data", ".{3,}", deps(//foo)) +``` + +will select all rules among `//foo` dependencies that specify at +least one value in the `data` attribute (every label is at least +3 characters long due to the `//` and `:`). + +To select all rules among `//foo` dependencies with a particular `value` in a +list-type attribute, use + +``` +attr("tags", "[\[ ]value[,\]]", deps(//foo)) +``` + +This works because the character before `value` will be `[` or a space and the +character after `value` will be a comma or `]`. + +To select all rules among `//foo` dependencies with a particular `key` and +`value` in a dict-type attribute, use + +``` +attr("some_dict_attribute", "[\{ ]key=value[,\}]", deps(//foo)) +``` + +This would select `//foo` if `//foo` is defined as + +``` +some_rule( + name = "foo", + some_dict_attribute = { + "key": "value", + }, +) +``` + +This works because the character before `key=value` will be `{` or a space and +the character after `key=value` will be a comma or `}`. + +### Rule visibility filtering: visible {#visible} + +``` +expr ::= visible({{ '' }}expr{{ '' }}, {{ '' }}expr{{ '' }}) +``` + +The `visible({{ '' }}predicate{{ '' }}, {{ '' }}input{{ '' }})` operator +applies a filter to a set of targets, and discards targets without the +required visibility. + +The first argument, {{ '' }}predicate{{ '' }}, is a set of targets that all targets +in the output must be visible to. A {{ '' }}visible{{ '' }} expression +evaluates to the set containing all targets {{ '' }}x{{ '' }} such that {{ '' }}x{{ '' }} +is a member of the set {{ '' }}input{{ '' }}, and for all targets {{ '' }}y{{ '' }} in +{{ '' }}predicate{{ '' }} {{ '' }}x{{ '' }} is visible to {{ '' }}y{{ '' }}. For example: + +``` +visible(//foo, //bar:*) +``` + +will select all targets in the package `//bar` that `//foo` +can depend on without violating visibility restrictions. + +### Evaluation of rule attributes of type label: labels {#labels} + +``` +expr ::= labels({{ '' }}word{{ '' }}, {{ '' }}expr{{ '' }}) +``` + +The `labels({{ '' }}attr_name{{ '' }}, {{ '' }}inputs{{ '' }})` +operator returns the set of targets specified in the +attribute {{ '' }}attr_name{{ '' }} of type "label" or "list of label" in +some rule in set {{ '' }}inputs{{ '' }}. + +For example, `labels(srcs, //foo)` returns the set of +targets appearing in the `srcs` attribute of +the `//foo` rule. If there are multiple rules +with `srcs` attributes in the {{ '' }}inputs{{ '' }} set, the +union of their `srcs` is returned. + +### Expand and filter test_suites: tests {#tests} + +``` +expr ::= tests({{ '' }}expr{{ '' }}) +``` + +The `tests({{ '' }}x{{ '' }})` operator returns the set of all test +rules in set {{ '' }}x{{ '' }}, expanding any `test_suite` rules into +the set of individual tests that they refer to, and applying filtering by +`tag` and `size`. + +By default, query evaluation +ignores any non-test targets in all `test_suite` rules. This can be +changed to errors with the `--strict_test_suite` option. + +For example, the query `kind(test, foo:*)` lists all +the `*_test` and `test_suite` rules +in the `foo` package. All the results are (by +definition) members of the `foo` package. In contrast, +the query `tests(foo:*)` will return all of the +individual tests that would be executed by `bazel test +foo:*`: this may include tests belonging to other packages, +that are referenced directly or indirectly +via `test_suite` rules. + +### Package definition files: buildfiles {#buildfiles} + +``` +expr ::= buildfiles({{ '' }}expr{{ '' }}) +``` + +The `buildfiles({{ '' }}x{{ '' }})` operator returns the set +of files that define the packages of each target in +set {{ '' }}x{{ '' }}; in other words, for each package, its `BUILD` file, +plus any .bzl files it references via `load`. Note that this +also returns the `BUILD` files of the packages containing these +`load`ed files. + +This operator is typically used when determining what files or +packages are required to build a specified target, often in conjunction with +the [`--output package`](#output-package) option, below). For example, + +```bash +bazel query 'buildfiles(deps(//foo))' --output package +``` + +returns the set of all packages on which `//foo` transitively depends. + +Note: A naive attempt at the above query would omit +the `buildfiles` operator and use only `deps`, +but this yields an incorrect result: while the result contains the +majority of needed packages, those packages that contain only files +that are `load()`'ed will be missing. + +Warning: Bazel pretends each `.bzl` file produced by +`buildfiles` has a corresponding target (for example, file `a/b.bzl` => +target `//a:b.bzl`), but this isn't necessarily the case. Therefore, +`buildfiles` doesn't compose well with other query operators and its results can be +misleading when formatted in a structured way, such as +[`--output=xml`](#xml). + +### Package definition files: rbuildfiles {#rbuildfiles} + +``` +expr ::= rbuildfiles({{ '' }}word{{ '' }}, ...) +``` + +Note: Only available with [Sky Query](#sky-query). + +The `rbuildfiles` operator takes a comma-separated list of path fragments and returns +the set of `BUILD` files that transitively depend on these path fragments. For instance, if +`//foo` is a package, then `rbuildfiles(foo/BUILD)` will return the +`//foo:BUILD` target. If the `foo/BUILD` file has +`load('//bar:file.bzl'...` in it, then `rbuildfiles(bar/file.bzl)` will +return the `//foo:BUILD` target, as well as the targets for any other `BUILD` files that +load `//bar:file.bzl` + +The scope of the rbuildfiles operator is the universe specified by the +`--universe_scope` flag. Files that do not correspond directly to `BUILD` files and `.bzl` +files do not affect the results. For instance, source files (like `foo.cc`) are ignored, +even if they are explicitly mentioned in the `BUILD` file. Symlinks, however, are respected, so that +if `foo/BUILD` is a symlink to `bar/BUILD`, then +`rbuildfiles(bar/BUILD)` will include `//foo:BUILD` in its results. + +The `rbuildfiles` operator is almost morally the inverse of the +[`buildfiles`](#buildfiles) operator. However, this moral inversion +holds more strongly in one direction: the outputs of `rbuildfiles` are just like the +inputs of `buildfiles`; the former will only contain `BUILD` file targets in packages, +and the latter may contain such targets. In the other direction, the correspondence is weaker. The +outputs of the `buildfiles` operator are targets corresponding to all packages and .`bzl` +files needed by a given input. However, the inputs of the `rbuildfiles` operator are +not those targets, but rather the path fragments that correspond to those targets. + +### Package definition files: loadfiles {#loadfiles} + +``` +expr ::= loadfiles({{ '' }}expr{{ '' }}) +``` + +The `loadfiles({{ '' }}x{{ '' }})` operator returns the set of +Starlark files that are needed to load the packages of each target in +set {{ '' }}x{{ '' }}. In other words, for each package, it returns the +.bzl files that are referenced from its `BUILD` files. + +Warning: Bazel pretends each of these .bzl files has a corresponding target +(for example, file `a/b.bzl` => target `//a:b.bzl`), but this isn't +necessarily the case. Therefore, `loadfiles` doesn't compose well with other query +operators and its results can be misleading when formatted in a structured way, such as +[`--output=xml`](#xml). + +## Output formats {#output-formats} + +`bazel query` generates a graph. +You specify the content, format, and ordering by which +`bazel query` presents this graph +by means of the `--output` command-line option. + +When running with [Sky Query](#sky-query), only output formats that are compatible with +unordered output are allowed. Specifically, `graph`, `minrank`, and +`maxrank` output formats are forbidden. + +Some of the output formats accept additional options. The name of +each output option is prefixed with the output format to which it +applies, so `--graph:factored` applies only +when `--output=graph` is being used; it has no effect if +an output format other than `graph` is used. Similarly, +`--xml:line_numbers` applies only when `--output=xml` +is being used. + +### On the ordering of results {#results-ordering} + +Although query expressions always follow the "[law of +conservation of graph order](#graph-order)", _presenting_ the results may be done +in either a dependency-ordered or unordered manner. This does **not** +influence the targets in the result set or how the query is computed. It only +affects how the results are printed to stdout. Moreover, nodes that are +equivalent in the dependency order may or may not be ordered alphabetically. +The `--order_output` flag can be used to control this behavior. +(The `--[no]order_results` flag has a subset of the functionality +of the `--order_output` flag and is deprecated.) + +The default value of this flag is `auto`, which prints results in **lexicographical +order**. However, when `somepath(a,b)` is used, the results will be printed in +`deps` order instead. + +When this flag is `no` and `--output` is one of +`build`, `label`, `label_kind`, `location`, `package`, `proto`, or +`xml`, the outputs will be printed in arbitrary order. **This is +generally the fastest option**. It is not supported though when +`--output` is one of `graph`, `minrank` or +`maxrank`: with these formats, Bazel always prints results +ordered by the dependency order or rank. + +When this flag is `deps`, Bazel prints results in some topological order—that is, +dependents first and dependencies after. However, nodes that are unordered by the +dependency order (because there is no path from either one to the other) may be +printed in any order. + +When this flag is `full`, Bazel prints nodes in a fully deterministic (total) order. +First, all nodes are sorted alphabetically. Then, each node in the list is used as the start of a +post-order depth-first search in which outgoing edges to unvisited nodes are traversed in +alphabetical order of the successor nodes. Finally, nodes are printed in the reverse of the order +in which they were visited. + +Printing nodes in this order may be slower, so it should be used only when determinism is +important. + +### Print the source form of targets as they would appear in BUILD {#target-source-form} + +``` +--output build +``` + +With this option, the representation of each target is as if it were +hand-written in the BUILD language. All variables and function calls +(such as glob, macros) are expanded, which is useful for seeing the effect +of Starlark macros. Additionally, each effective rule reports a +`generator_name` and/or `generator_function`) value, +giving the name of the macro that was evaluated to produce the effective rule. + +Although the output uses the same syntax as `BUILD` files, it is not +guaranteed to produce a valid `BUILD` file. + +### Print the label of each target {#print-label-target} + +``` +--output label +``` + +With this option, the set of names (or _labels_) of each target +in the resulting graph is printed, one label per line, in +topological order (unless `--noorder_results` is specified, see +[notes on the ordering of results](#result-order)). +(A topological ordering is one in which a graph +node appears earlier than all of its successors.) Of course there +are many possible topological orderings of a graph (_reverse +postorder_ is just one); which one is chosen is not specified. + +When printing the output of a `somepath` query, the order +in which the nodes are printed is the order of the path. + +Caveat: in some corner cases, there may be two distinct targets with +the same label; for example, a `sh_binary` rule and its +sole (implicit) `srcs` file may both be called +`foo.sh`. If the result of a query contains both of +these targets, the output (in `label` format) will appear +to contain a duplicate. When using the `label_kind` (see +below) format, the distinction becomes clear: the two targets have +the same name, but one has kind `sh_binary rule` and the +other kind `source file`. + +### Print the label and kind of each target {#print-target-label} + +``` +--output label_kind +``` + +Like `label`, this output format prints the labels of +each target in the resulting graph, in topological order, but it +additionally precedes the label by the [_kind_](#kind) of the target. + +### Print targets in protocol buffer format {#print-target-proto} + +``` +--output proto +``` + +Prints the query output as a +[`QueryResult`](https://github.com/bazelbuild/bazel/blob/master/src/main/protobuf/build.proto) +protocol buffer. + +### Print targets in length-delimited protocol buffer format {#print-target-length-delimited-proto} + +``` +--output streamed_proto +``` + +Prints a +[length-delimited](https://protobuf.dev/programming-guides/encoding/#size-limit) +stream of +[`Target`](https://github.com/bazelbuild/bazel/blob/master/src/main/protobuf/build.proto) +protocol buffers. This is useful to _(i)_ get around +[size limitations](https://protobuf.dev/programming-guides/encoding/#size-limit) +of protocol buffers when there are too many targets to fit in a single +`QueryResult` or _(ii)_ to start processing while Bazel is still outputting. + +### Print targets in text proto format {#print-target-textproto} + +``` +--output textproto +``` + +Similar to `--output proto`, prints the +[`QueryResult`](https://github.com/bazelbuild/bazel/blob/master/src/main/protobuf/build.proto) +protocol buffer but in +[text format](https://protobuf.dev/reference/protobuf/textformat-spec/). + +### Print targets in ndjson format {#print-target-streamed-jsonproto} + +``` +--output streamed_jsonproto +``` + +Similar to `--output streamed_proto`, prints a stream of +[`Target`](https://github.com/bazelbuild/bazel/blob/master/src/main/protobuf/build.proto) +protocol buffers but in [ndjson](https://github.com/ndjson/ndjson-spec) format. + +### Print the label of each target, in rank order {#print-target-label-rank-order} + +``` +--output minrank --output maxrank +``` + +Like `label`, the `minrank` +and `maxrank` output formats print the labels of each +target in the resulting graph, but instead of appearing in +topological order, they appear in rank order, preceded by their +rank number. These are unaffected by the result ordering +`--[no]order_results` flag (see [notes on +the ordering of results](#result-order)). + +There are two variants of this format: `minrank` ranks +each node by the length of the shortest path from a root node to it. +"Root" nodes (those which have no incoming edges) are of rank 0, +their successors are of rank 1, etc. (As always, edges point from a +target to its prerequisites: the targets it depends upon.) + +`maxrank` ranks each node by the length of the longest +path from a root node to it. Again, "roots" have rank 0, all other +nodes have a rank which is one greater than the maximum rank of all +their predecessors. + +All nodes in a cycle are considered of equal rank. (Most graphs are +acyclic, but cycles do occur +simply because `BUILD` files contain erroneous cycles.) + +These output formats are useful for discovering how deep a graph is. +If used for the result of a `deps(x)`, `rdeps(x)`, +or `allpaths` query, then the rank number is equal to the +length of the shortest (with `minrank`) or longest +(with `maxrank`) path from `x` to a node in +that rank. `maxrank` can be used to determine the +longest sequence of build steps required to build a target. + +Note: The ranked output of a `somepath` query is +basically meaningless because `somepath` doesn't +guarantee to return either a shortest or a longest path, and it may +include "transitive" edges from one path node to another that are +not direct edges in original graph. + +For example, the graph on the left yields the outputs on the right +when `--output minrank` and `--output maxrank` +are specified, respectively. + + + + + + + +
Out ranked + + 
+      minrank
+
+      0 //c:c
+      1 //b:b
+      1 //a:a
+      2 //b:b.cc
+      2 //a:a.cc
+
+ 		+ 
+      maxrank
+
+      0 //c:c
+      1 //b:b
+      2 //a:a
+      2 //b:b.cc
+      3 //a:a.cc
+
+
+ +### Print the location of each target {#print-target-location} + +``` +--output location +``` + +Like `label_kind`, this option prints out, for each +target in the result, the target's kind and label, but it is +prefixed by a string describing the location of that target, as a +filename and line number. The format resembles the output of +`grep`. Thus, tools that can parse the latter (such as Emacs +or vi) can also use the query output to step through a series of +matches, allowing the Bazel query tool to be used as a +dependency-graph-aware "grep for BUILD files". + +The location information varies by target kind (see the [kind](#kind) operator). For rules, the +location of the rule's declaration within the `BUILD` file is printed. +For source files, the location of line 1 of the actual file is +printed. For a generated file, the location of the rule that +generates it is printed. (The query tool does not have sufficient +information to find the actual location of the generated file, and +in any case, it might not exist if a build has not yet been performed.) + +### Print the set of packages {#print-package-set} + +```--output package``` + +This option prints the name of all packages to which +some target in the result set belongs. The names are printed in +lexicographical order; duplicates are excluded. Formally, this +is a _projection_ from the set of labels (package, target) onto +packages. + +Packages in external repositories are formatted as +`@repo//foo/bar` while packages in the main repository are +formatted as `foo/bar`. + +In conjunction with the `deps(...)` query, this output +option can be used to find the set of packages that must be checked +out in order to build a given set of targets. + +### Display a graph of the result {#display-result-graph} + +```--output graph``` + +This option causes the query result to be printed as a directed +graph in the popular AT&T GraphViz format. Typically the +result is saved to a file, such as `.png` or `.svg`. +(If the `dot` program is not installed on your workstation, you +can install it using the command `sudo apt-get install graphviz`.) +See the example section below for a sample invocation. + +This output format is particularly useful for `allpaths`, +`deps`, or `rdeps` queries, where the result +includes a _set of paths_ that cannot be easily visualized when +rendered in a linear form, such as with `--output label`. + +By default, the graph is rendered in a _factored_ form. That is, +topologically-equivalent nodes are merged together into a single +node with multiple labels. This makes the graph more compact +and readable, because typical result graphs contain highly +repetitive patterns. For example, a `java_library` rule +may depend on hundreds of Java source files all generated by the +same `genrule`; in the factored graph, all these files +are represented by a single node. This behavior may be disabled +with the `--nograph:factored` option. + +#### `--graph:node_limit {{ '' }}n{{ '' }}` {#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 +disables truncation. Due to the factored form in which graphs are +usually printed, the node labels may be very long. GraphViz cannot +handle labels exceeding 1024 characters, which is the default value +of this option. This option has no effect unless +`--output=graph` is being used. + +#### `--[no]graph:factored` {#graph-factored} + +By default, graphs are displayed in factored form, as explained +[above](#output-graph). +When `--nograph:factored` is specified, graphs are +printed without factoring. This makes visualization using GraphViz +impractical, but the simpler format may ease processing by other +tools (such as grep). This option has no effect +unless `--output=graph` is being used. + +### XML {#xml} + +```--output xml``` + +This option causes the resulting targets to be printed in an XML +form. The output starts with an XML header such as this + +``` + + +``` + + + +and then continues with an XML element for each target +in the result graph, in topological order (unless +[unordered results](#result-order) are requested), +and then finishes with a terminating + +``` + +``` + +Simple entries are emitted for targets of `file` kind: + +``` + + +``` + +But for rules, the XML is structured and contains definitions of all +the attributes of the rule, including those whose value was not +explicitly specified in the rule's `BUILD` file. + +Additionally, the result includes `rule-input` and +`rule-output` elements so that the topology of the +dependency graph can be reconstructed without having to know that, +for example, the elements of the `srcs` attribute are +forward dependencies (prerequisites) and the contents of the +`outs` attribute are backward dependencies (consumers). + +`rule-input` elements for [implicit dependencies](#implicit_deps) are suppressed if +`--noimplicit_deps` is specified. + +``` + + + + + + + ... + + + + + + + + + + + + ... + +``` + +Every XML element for a target contains a `name` +attribute, whose value is the target's label, and +a `location` attribute, whose value is the target's +location as printed by the [`--output location`](#print-target-location). + +#### `--[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` {#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 +were not specified in the `BUILD` file, or the default value was +provided explicitly). This option causes such attribute values to +be included in the XML output. + +### 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){: .external}. + +### 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 +example, if `//foo:bar` depends on `@other-repo//baz:lib`, then +`bazel query 'deps(//foo:bar)'` will list `@other-repo//baz:lib` as a +dependency.