Project: /_project.yaml Book: /_book.yaml

Query guide

{% include “_buttons.html” %}

This page covers how to get started using Bazel's query language to trace dependencies in your code.

For a language details and --output flag details, please see the reference manuals, Bazel query reference and Bazel cquery reference. You can get help by typing bazel help query or bazel help cquery on the command line.

To execute a query while ignoring errors such as missing targets, use the --keep_going flag.

Finding the dependencies of a rule {:#finding-rule-dependencies}

To see the dependencies of //foo, use the deps function in bazel query:

This is the set of all targets required to build //foo.

Tracing the dependency chain between two packages {:#tracing-dependency-chain}

The library //third_party/zlib:zlibonly isn't in the BUILD file for //foo, but it is an indirect dependency. How can we trace this dependency path? There are two useful functions here: allpaths and somepath. You may also want to exclude tooling dependencies with --notool_deps if you care only about what is included in the artifact you built, and not every possible job.

To visualize the graph of all dependencies, pipe the bazel query output through the dot command-line tool:

Note: dot supports other image formats, just replace svg with the format identifier, for example, png.

When a dependency graph is big and complicated, it can be helpful start with a single path:

If you do not specify --output graph with allpaths, you will get a flattened list of the dependency graph.

Aside: implicit dependencies {:#implicit-dependencies}

The BUILD file for //foo never references //translations/tools:aggregator. So, where's the direct dependency?

Certain rules include implicit dependencies on additional libraries or tools. For example, to build a genproto rule, you need first to build the Protocol Compiler, so every genproto rule carries an implicit dependency on the protocol compiler. These dependencies are not mentioned in the build file, but added in by the build tool. The full set of implicit dependencies is currently undocumented. Using --noimplicit_deps allows you to filter out these deps from your query results. For cquery, this will include resolved toolchains.

Reverse dependencies {:#reverse-dependencies}

You might want to know the set of targets that depends on some target. For instance, if you‘re going to change some code, you might want to know what other code you’re about to break. You can use rdeps(u, x) to find the reverse dependencies of the targets in x within the transitive closure of u.

Bazel's Sky Query supports the allrdeps function which allows you to query reverse dependencies in a universe you specify.

Miscellaneous uses {:#miscellaneous-uses}

You can use bazel query to analyze many dependency relationships.

What exists ... {:#what-exists}

What packages exist beneath foo? {:#what-exists-beneath-foo}

What rules are defined in the foo package? {:#rules-defined-in-foo}

What files are generated by rules in the foo package? {:#files-generated-by-rules}

What targets are generated by starlark macro foo? {:#targets-generated-by-foo}

What's the set of BUILD files needed to build //foo? {:#build-files-required}

What are the individual tests that a test_suite expands to? {:#individual-tests-in-testsuite}

Which of those are C++ tests? {:#cxx-tests}

Which of those are small? Medium? Large? {:#size-of-tests}

What are the tests beneath foo that match a pattern? {:#tests-beneath-foo}

The pattern is a regex and is applied to the full name of the rule. It's similar to doing

What package contains file path/to/file/bar.java? {:#barjava-package}

What is the build label for path/to/file/bar.java? {:#barjava-build-label}

What rule target(s) contain file path/to/file/bar.java as a source? {:#barjava-rule-targets}

What package dependencies exist ... {:#package-dependencies}

What packages does foo depend on? (What do I need to check out to build foo) {:#packages-foo-depends-on}

Note: buildfiles is required in order to correctly obtain all files referenced by subinclude; see the reference manual for details.

What packages does the foo tree depend on, excluding foo/contrib? {:#packages-foo-tree-depends-on}

What rule dependencies exist ... {:#rule-dependencies}

What genproto rules does bar depend upon? {:#genproto-rules}

Find the definition of some JNI (C++) library that is transitively depended upon by a Java binary rule in the servlet tree. {:#jni-library}

...Now find the definitions of all the Java binaries that depend on them {:#java-binaries}

What file dependencies exist ... {:#file-dependencies}

What's the complete set of Java source files required to build foo? {:#java-source-files}

Source files:

Generated files:

What is the complete set of Java source files required to build QUX's tests? {:qux-tests}

Source files:

Generated files:

What differences in dependencies between X and Y exist ... {:#differences-in-dependencies}

What targets does //foo depend on that //foo:foolib does not? {:#foo-targets}

What C++ libraries do the foo tests depend on that the //foo production binary does not depend on? {:#foo-cxx-libraries}

Why does this dependency exist ... {:#why-dependencies}

Why does bar depend on groups2? {:#dependency-bar-groups2}

Once you have the results of this query, you will often find that a single target stands out as being an unexpected or egregious and undesirable dependency of bar. The query can then be further refined to:

Show me a path from docker/updater:updater_systest (a py_test) to some cc_library that it depends upon: {:#path-docker-cclibrary}

Why does library //photos/frontend:lib depend on two variants of the same library //third_party/jpeglib and //third_party/jpeg? {:#library-two-variants}

This query boils down to: “show me the subgraph of //photos/frontend:lib that depends on both libraries”. When shown in topological order, the last element of the result is the most likely culprit.

What depends on ... {:#depends-on}

What rules under bar depend on Y? {:#rules-bar-y}

Note: X intersect allpaths(X, Y) is the general idiom for the query “which X depend on Y?” If expression X is non-trivial, it may be convenient to bind a name to it using let to avoid duplication.

What targets directly depend on T, in T's package? {:#targets-t}

How do I break a dependency ... {:#break-dependency}

What dependency paths do I have to break to make bar no longer depend on X? {:#break-dependency-bar-x}

To output the graph to a svg file:

Misc {:#misc}

How many sequential steps are there in the //foo-tests build? {:#steps-footests}

Unfortunately, the query language can't currently give you the longest path from x to y, but it can find the (or rather a) most distant node from the starting point, or show you the lengths of the longest path from x to every y that it depends on. Use maxrank:

The result indicates that there exist paths of length 85 that must occur in order in this build.