| --- |
| layout: documentation |
| title: Bazel Query How-To |
| --- |
| <h1>Bazel query how-to</h1> |
| |
| <p> |
| This is a quick tutorial to get you started using Bazel's query language to |
| trace dependencies in your code. |
| </p> |
| |
| For a language details and <code>--output</code> flag details, please see the reference |
| manuals, <a href="query.html">Bazel query reference</a> and <a href="cquery.html">Bazel cquery reference</a>. |
| You can get help by typing <code>bazel help query</code> or <code>bazel help cquery</code> on the command line. |
| |
| <p> |
| To execute a query while ignoring errors such as missing targets, use the |
| <code>--keep_going</code> flag. |
| </p> |
| |
| <h2>Contents</h2> |
| |
| <ul> |
| <li><a href="#Finding_the_Dependencies_of_a_Ru">Finding the Dependencies of a Rule</a></li> |
| <li><a href="#Tracing_the_Dependency_Chain_bet">Tracing the Dependency Chain between Two |
| Packages</a> |
| <ul><li><a href="#Aside_implicit_dependencies">Aside: implicit dependencies</a></li></ul></li> |
| <li><a href="#Reverse_Dependencies">Reverse Dependencies</a></li> |
| <li><a href="#Miscellaneous_Uses">Miscellaneous Uses</a> |
| <ul><li><a href="#What_exists_">What exists ...</a> |
| <ul><li><a href="#What_packages_exist_beneath_foo_">What packages exist beneath |
| <code>foo</code>?</a></li> |
| <li><a href="#What_rules_are_defined_in_the_foo">What rules are defined in the <code>foo</code> |
| package?</a></li> |
| <li><a href="#What_files_are_generated_by_rule">What files are generated by rules in the <code>foo</code> |
| package?</a></li> |
| <li><a href="#What_targets_are_generated_by_macro">What targets are generated by starlark macro |
| <code>foo</code>?</a></li> |
| <li><a href="#What_s_the_set_of_BUILD_files_ne">What's the set of BUILD files needed to build |
| <code>//foo</code>?</a></li> |
| <li><a href="#What_are_the_individual_tests_th">What are the individual tests that a <code>test_suite</code> expands |
| to?</a> |
| <ul><li><a href="#Which_of_those_are_C_tests_">Which of those are C++ tests?</a></li> |
| <li><a href="#Which_of_those_are_small_Medium_">Which of those are small? Medium? |
| Large?</a></li></ul></li> |
| <li><a href="#What_are_the_tests_beneath_foo_t">What are the tests beneath <code>foo</code> that match a |
| pattern?</a></li> |
| <li><a href="#What_package_contains_file_java_">What package contains file |
| <code>path/to/file/bar.java</code>? |
| </a></li> |
| <li><a href="#What_is_the_build_label_for_java">What is the build label for |
| <code>path/to/file/bar.java</code>? |
| </a></li> |
| <li><a href="#What_build_rule_contains_file_ja">What build rule contains file |
| <code>path/to/file/bar.java</code> as a |
| source?</a></li></ul></li> |
| <li><a href="#What_package_dependencies_exist_">What package dependencies exist ...</a> |
| <ul><li><a href="#What_packages_does_foo_depend_on">What packages does <code>foo</code> depend on? (What do I need to check out |
| to build <code>foo</code>)</a></li> |
| <li><a href="#What_packages_does_the_foo_">What packages does the <code>foo</code> tree depend on, excluding |
| <code>foo/contrib</code>?</a></li></ul></li> |
| <li><a href="#What_rule_dependencies_exist_">What rule dependencies exist ...</a> |
| <ul><li><a href="#What_genproto_rules_does_bar_">What genproto rules does bar depend |
| upon?</a></li> |
| <li><a href="#Find_the_definition_of_some_JNI_">Find the definition of some JNI (C++) library that is transitively |
| depended upon by a Java binary rule in the servlet |
| tree.</a> |
| <ul><li><a href="#_Now_find_the_definitions_of_all">...Now find the definitions of all the Java binaries that |
| depend on them</a></li></ul></li></ul></li> |
| <li><a href="#What_file_dependencies_exist_">What file dependencies exist ...</a> |
| <ul><li><a href="#What_s_the_complete_set_of_Java_">What's the complete set of Java source files required to build |
| QUX?</a></li> |
| <li><a href="#What_is_the_complete_set_of_Java">What is the complete set of Java source files required to build |
| QUX's tests?</a></li></ul></li> |
| <li><a href="#What_differences_in_dependencies">What differences in dependencies between X and Y exist |
| ...</a> |
| <ul><li><a href="#What_targets_does_foo_depend_on_">What targets does <code>//foo</code> depend on that <code>//foo:foolib</code> does |
| not?</a></li> |
| <li><a href="#What_C_libraries_do_the_foo_test">What C++ libraries do the <code>foo</code> tests depend on that the <code>//foo</code> |
| production binary does <em>not</em> depend |
| on?</a></li></ul></li> |
| <li><a href="#Why_does_this_dependency_exist_">Why does this dependency exist ...</a> |
| <ul><li><a href="#Why_does_bar_depend_on_groups">Why does <code>bar</code> depend on |
| <code>groups2</code>?</a></li> |
| <li><a href="#Show_me_a_path_from_docker_updater">Show me a path from <code>docker/updater:updater_systest</code> (a <code>py_test</code>) |
| to some <code>cc_library</code> that it depends |
| upon:</a></li> |
| <li><a href="#Why_does_library_photos_frontend">Why does library <code>//photos/frontend:lib</code> depend on two variants of |
| the same library <code>//third_party/jpeglib</code> and |
| <code>//third_party/jpeg</code>?</a></li></ul></li> |
| <li><a href="#What_depends_on_">What depends on ...</a> |
| <ul><li><a href="#What_rules_under_bar_depend_o">What rules under bar depend on Y?</a></li> |
| <li><a href="#What_are_the_intra_package_direct_rdeps">What targets directly depend on T, in T's |
| package</a></li></ul></li> |
| <li><a href="#How_do_I_break_a_dependency_">How do I break a dependency ...</a> |
| <ul><li><a href="#What_dependency_paths_do_I_have_">What dependency paths do I have to break to make <code>bar</code> no longer |
| depend on X?</a></li></ul></li> |
| <li><a href="#Misc_">Misc ...</a> |
| <ul><li><a href="#How_many_sequential_steps_are_th">How many sequential steps are there in the <code>ServletSmokeTests</code> |
| build?</a></li></ul></li></ul></li> |
| </ul> |
| |
| <p><a name="Finding_the_Dependencies_of_a_Ru"></a></p> |
| |
| <h2>Finding the Dependencies of a Rule</h2> |
| |
| <p>To see the dependencies of <code>//foo</code>, use the |
| <code>deps</code> function in bazel query:</p> |
| |
| <pre> |
| $ bazel query "deps(//foo)" |
| //foo:foo |
| //foo:foo-dep |
| ... |
| </pre> |
| |
| <p>This is the set of all targets required to build <code>//foo</code>.</p> |
| |
| <p><a name="Tracing_the_Dependency_Chain_bet"></a></p> |
| |
| <h2>Tracing the Dependency Chain between Two Packages</h2> |
| |
| <p>The library <code>//third_party/zlib:zlibonly</code> isn't in the BUILD file for |
| <code>//foo</code>, but it is an indirect dependency. How can |
| we trace this dependency path? There are two useful functions here: |
| <code>allpaths</code> and <code>somepath</code>. You may also want to exclude |
| tooling dependencies with <code>--notool_deps</code> if you care only about |
| what is included in the artifact you built, and not every possible job. |
| |
| <p>To visualize the graph of all dependencies, pipe the bazel query output through |
| the <code>dot</code> command-line tool:</p> |
| <pre> |
| $ bazel query "allpaths(//foo, third_party/...)" --notool_deps --output graph | dot -Tpng > graph.png |
| </pre> |
| |
| <p>When a dependency graph is big and complicated, it can be helpful start with a single path:</p> |
| |
| <pre> |
| $ bazel query "somepath(//foo:foo, third_party/zlib:zlibonly)" |
| //foo:foo |
| //translations/tools:translator |
| //translations/base:base |
| //third_party/py/MySQL:MySQL |
| //third_party/py/MySQL:_MySQL.so |
| //third_party/mysql:mysql |
| //third_party/zlib:zlibonly |
| </pre> |
| |
| <p>If you do not specify <code>--output graph</code> with <code>allpaths</code>, |
| you will get a flattened list of the dependency graph.</p> |
| <pre> |
| $ bazel query "allpaths(//foo, third_party/...)" |
| ...many errors detected in BUILD files... |
| //foo:foo |
| //translations/tools:translator |
| //translations/tools:aggregator |
| //translations/base:base |
| //tools/pkg:pex |
| //tools/pkg:pex_phase_one |
| //tools/pkg:pex_lib |
| //third_party/python:python_lib |
| //translations/tools:messages |
| //third_party/py/xml:xml |
| //third_party/py/xml:utils/boolean.so |
| //third_party/py/xml:parsers/sgmlop.so |
| //third_party/py/xml:parsers/pyexpat.so |
| //third_party/py/MySQL:MySQL |
| //third_party/py/MySQL:_MySQL.so |
| //third_party/mysql:mysql |
| //third_party/openssl:openssl |
| //third_party/zlib:zlibonly |
| //third_party/zlib:zlibonly_v1_2_3 |
| //third_party/python:headers |
| //third_party/openssl:crypto |
| </pre> |
| |
| <p><a name="Aside_implicit_dependencies"></a></p> |
| |
| <h3>Aside: implicit dependencies</h3> |
| |
| <p>The BUILD file for <code>//foo</code> never references |
| <code>//translations/tools:aggregator</code>. So, where's the direct dependency?</p> |
| |
| <p>Certain rules include implicit dependencies on additional libraries or tools. |
| For example, to build a <code>genproto</code> rule, you need first to build the Protocol |
| Compiler, so every <code>genproto</code> rule carries an implicit dependency on the |
| protocol compiler. These dependencies are not mentioned in the build file, |
| but added in by the build tool. The full set of implicit dependencies is |
| currently undocumented. Using <code>--noimplicit_deps</code> allows you to filter out |
| these deps from your query results. |
| |
| <p><a name="Reverse_Dependencies"></a></p> |
| |
| <h2>Reverse Dependencies</h2> |
| |
| <p>You might want to know the set of targets that depends on some target. e.g., |
| if you're going to change some code, you might want to know what other code |
| you're about to break. You can use <code>rdeps(u, x)</code> to find the reverse |
| dependencies of the targets in <code>x</code> within the transitive closure of <code>u</code>.</p> |
| |
| Bazel's <a href="query.html#sky-query">Sky Query</a> |
| supports the <code>allrdeps</code> function which allows you to query rdeps in the entire |
| universe of the build. |
| <p><a name="Miscellaneous_Uses"></a></p> |
| |
| <h2>Miscellaneous Uses</h2> |
| |
| <p>You can use <code>bazel query</code> to analyze many dependency relationships.</p> |
| |
| <p><a name="What_exists_"></a></p> |
| |
| <h3>What exists ...</h3> |
| |
| <p><a name="What_packages_exist_beneath_foo_"></a></p> |
| |
| <h4>What packages exist beneath <code>foo</code>?</h4> |
| |
| <pre>bazel query 'foo/...' --output package</pre> |
| |
| <p><a name="What_rules_are_defined_in_the_gw"></a></p> |
| |
| <h4>What rules are defined in the <code>foo</code> package?</h4> |
| |
| <pre>bazel query 'kind(rule, foo:*)' --output label_kind</pre> |
| |
| <p><a name="What_files_are_generated_by_rule"></a></p> |
| |
| <h4>What files are generated by rules in the <code>foo</code> package?</h4> |
| |
| <pre>bazel query 'kind("generated file", //foo:*)'</pre> |
| |
| <p><a name="What_targets_are_generated_by_macro"></a></p> |
| |
| <h4>What targets are generated by starlark macro <code>foo</code>?</h4> |
| |
| <pre>bazel query 'attr(generator_function, foo, //path/to/search/...)'</pre> |
| |
| <p><a name="What_s_the_set_of_BUILD_files_ne"></a></p> |
| |
| <h4>What's the set of BUILD files needed to build <code>//foo</code>?</h4> |
| |
| <pre>bazel query 'buildfiles(deps(//foo))' | cut -f1 -d:</pre> |
| |
| <p><a name="What_are_the_individual_tests_th"></a></p> |
| |
| <h4>What are the individual tests that a <code>test_suite</code> expands to?</h4> |
| |
| <pre>bazel query 'tests(//foo:smoke_tests)'</pre> |
| |
| <p><a name="Which_of_those_are_C_tests_"></a></p> |
| |
| <h4>Which of those are C++ tests?</h4> |
| |
| <pre>bazel query 'kind(cc_.*, tests(//foo:smoke_tests))'</pre> |
| |
| <p><a name="Which_of_those_are_small_Medium_"></a></p> |
| |
| <h4>Which of those are small? Medium? Large?</h4> |
| |
| <pre> |
| bazel query 'attr(size, small, tests(//foo:smoke_tests))' |
| |
| bazel query 'attr(size, medium, tests(//foo:smoke_tests))' |
| |
| bazel query 'attr(size, large, tests(//foo:smoke_tests))' |
| </pre> |
| |
| <p><a name="What_are_the_tests_beneath_foo_t"></a></p> |
| |
| <h4>What are the tests beneath <code>foo</code> that match a pattern?</h4> |
| |
| <pre>bazel query 'filter("pa?t", kind(".*_test rule", //foo/...))'</pre> |
| |
| <p>The pattern is a regex and is applied to the full name of the rule. It's similar to doing</p> |
| |
| <pre>bazel query 'kind(".*_test rule", //foo/...)' | grep -E 'pa?t'</pre> |
| |
| <p><a name="What_package_contains_file_java_"></a></p> |
| |
| <h4>What package contains file <code>path/to/file/bar.java</code>?</h4> |
| |
| <pre> bazel query path/to/file/bar.java --output=package</pre> |
| |
| <p><a name="What_is_the_build_label_for_java"></a></p> |
| |
| <h4>What is the build label for <code>path/to/file/bar.java?</code></h4> |
| |
| <pre>bazel query path/to/file/bar.java</pre> |
| |
| <p><a name="What_build_rule_contains_file_ja"></a></p> |
| |
| <h4>What rule target(s) contain file <code>path/to/file/bar.java</code> as a source?</h4> |
| |
| <pre> |
| fullname=$(bazel query path/to/file/bar.java) |
| bazel query "attr('srcs', $fullname, ${fullname//:*/}:*)" |
| </pre> |
| |
| <p><a name="What_package_dependencies_exist_"></a></p> |
| |
| <h3>What package dependencies exist ...</h3> |
| |
| <p><a name="What_packages_does_foo_depend_on"></a></p> |
| |
| <h4>What packages does <code>foo</code> depend on? (What do I need to check out to build <code>foo</code>)</h4> |
| |
| <pre>bazel query 'buildfiles(deps(//foo:foo))' --output package</pre> |
| |
| <p>Note, <code>buildfiles</code> is required in order to correctly obtain all files |
| referenced by <code>subinclude</code>; see the reference manual for details.</p> |
| |
| <p><a name="What_packages_does_the_foo_"></a></p> |
| |
| <h4>What packages does the <code>foo</code> tree depend on, excluding <code>foo/contrib</code>?</h4> |
| |
| <pre>bazel query 'deps(foo/... except foo/contrib/...)' --output package</pre> |
| |
| <p><a name="What_rule_dependencies_exist_"></a></p> |
| |
| <h3>What rule dependencies exist ...</h3> |
| |
| <p><a name="What_genproto_rules_does_bar_"></a></p> |
| |
| <h4>What genproto rules does bar depend upon?</h4> |
| |
| <pre>bazel query 'kind(genproto, deps(bar/...))'</pre> |
| |
| <p><a name="Find_the_definition_of_some_JNI_"></a></p> |
| |
| <h4>Find the definition of some JNI (C++) library that is transitively depended upon by a Java binary rule in the servlet tree.</h4> |
| |
| <pre>bazel query 'some(kind(cc_.*library, deps(kind(java_binary, //java/com/example/frontend/...))))' --output location</pre> |
| <p><a name="_Now_find_the_definitions_of_all"></a></p> |
| |
| <h5>...Now find the definitions of all the Java binaries that depend on them</h5> |
| |
| <pre>bazel query 'let jbs = kind(java_binary, //java/com/example/frontend/...) in |
| let cls = kind(cc_.*library, deps($jbs)) in |
| $jbs intersect allpaths($jbs, $cls)' |
| </pre> |
| |
| <p><a name="What_file_dependencies_exist_"></a></p> |
| |
| <h3>What file dependencies exist ...</h3> |
| |
| <p><a name="What_s_the_complete_set_of_Java_"></a></p> |
| |
| <h4>What's the complete set of Java source files required to build foo?</h4> |
| |
| <p>Source files:</p> |
| |
| <pre>bazel query 'kind("source file", deps(//path/to/target/foo/...))' | grep java$</pre> |
| |
| <p>Generated files:</p> |
| |
| <pre>bazel query 'kind("generated file", deps(//path/to/target/foo/...))' | grep java$</pre> |
| |
| <p><a name="What_is_the_complete_set_of_Java"></a></p> |
| |
| <h4>What is the complete set of Java source files required to build QUX's tests?</h4> |
| |
| <p>Source files:</p> |
| |
| <pre>bazel query 'kind("source file", deps(kind(".*_test rule", javatests/com/example/qux/...)))' | grep java$</pre> |
| |
| <p>Generated files:</p> |
| |
| <pre>bazel query 'kind("generated file", deps(kind(".*_test rule", javatests/com/example/qux/...)))' | grep java$</pre> |
| |
| <p><a name="What_differences_in_dependencies"></a></p> |
| |
| <h3>What differences in dependencies between X and Y exist ...</h3> |
| |
| <p><a name="What_targets_does_foo_depend_on_"></a></p> |
| |
| <h4>What targets does <code>//foo</code> depend on that <code>//foo:foolib</code> does not?</h4> |
| |
| <pre>bazel query 'deps(//foo) except deps(//foo:foolib)'</pre> |
| |
| <p><a name="What_C_libraries_do_the_foo_test"></a></p> |
| |
| <h4>What C++ libraries do the <code>foo</code> tests depend on that the <code>//foo</code> production binary does <em>not</em> depend on?</h4> |
| |
| <pre>bazel query 'kind("cc_library", deps(kind(".*test rule", foo/...)) except deps(//foo))'</pre> |
| |
| <p><a name="Why_does_this_dependency_exist_"></a></p> |
| |
| <h3>Why does this dependency exist ...</h3> |
| |
| <p><a name="Why_does_bar_depend_on_groups"></a></p> |
| |
| <h4>Why does <code>bar</code> depend on <code>groups2</code>?</h4> |
| |
| <pre>bazel query 'somepath(bar/...,groups2/...:*)'</pre> |
| |
| <p>Once you have the results of this query, you will often find that a single |
| target stands out as being an unexpected or egregious and undesirable |
| dependency of <code>bar</code>. The query can then be further refined to:</p> |
| |
| <p><a name="Show_me_a_path_from_docker_updater"></a></p> |
| |
| <h4>Show me a path from <code>docker/updater:updater_systest</code> (a <code>py_test</code>) to some <code>cc_library</code> that it depends upon:</h4> |
| |
| <pre>bazel query 'let cc = kind(cc_library, deps(docker/updater:updater_systest)) in |
| somepath(docker/updater:updater_systest, $cc)'</pre> |
| |
| <p><a name="Why_does_library_photos_frontend"></a></p> |
| |
| <h4>Why does library <code>//photos/frontend:lib</code> depend on two variants of the same library <code>//third_party/jpeglib</code> and <code>//third_party/jpeg</code>?</h4> |
| |
| <p>This query boils down to: "show me the subgraph of <code>//photos/frontend:lib</code> that |
| depends on both libraries". When shown in topological order, the last element |
| of the result is the most likely culprit.</p> |
| |
| <pre>bazel query 'allpaths(//photos/frontend:lib, //third_party/jpeglib) |
| intersect |
| allpaths(//photos/frontend:lib, //third_party/jpeg)' |
| //photos/frontend:lib |
| //photos/frontend:lib_impl |
| //photos/frontend:lib_dispatcher |
| //photos/frontend:icons |
| //photos/frontend/modules/gadgets:gadget_icon |
| //photos/thumbnailer:thumbnail_lib |
| //third_party/jpeg/img:renderer |
| </pre> |
| |
| <p><a name="What_depends_on_"></a></p> |
| |
| <h3>What depends on ...</h3> |
| |
| <p><a name="What_rules_under_bar_depend_o"></a></p> |
| |
| <h4>What rules under bar depend on Y?</h4> |
| |
| <pre>bazel query 'bar/... intersect allpaths(bar/..., Y)'</pre> |
| |
| <p>Note: <code>X intersect allpaths(X, Y)</code> is the general idiom for the query "which X |
| depend on Y?" If expression X is non-trivial, it may be convenient to bind a |
| name to it using <code>let</code> to avoid duplication.</p> |
| |
| <p><a name="What_are_the_intra_package_direct_rdeps"></a></p> |
| |
| <h4>What targets directly depend on T, in T's package?</h4> |
| |
| <pre>bazel query 'same_pkg_direct_rdeps(T)'</pre> |
| |
| <p><a name="How_do_I_break_a_dependency_"></a></p> |
| |
| <h3>How do I break a dependency ...</h3> |
| |
| <p><!-- TODO find a convincing value of X to plug in here --> |
| <a name="What_dependency_paths_do_I_have_"></a></p> |
| |
| <h4>What dependency paths do I have to break to make <code>bar</code> no longer depend on X?</h4> |
| |
| <p>To output the graph to a <code>png</code> file:</p> |
| |
| <pre>bazel query 'allpaths(bar/...,X)' --output graph | dot -Tpng > /tmp/dep.png</pre> |
| |
| <p><a name="Misc_"></a></p> |
| |
| <h3>Misc ...</h3> |
| |
| <p><a name="How_many_sequential_steps_are_th"></a></p> |
| |
| <h4>How many sequential steps are there in the <code>//foo-tests</code> build?</h4> |
| |
| <p>Unfortunately, the query language can't currently give you the longest path |
| from x to y, but it can find the (or rather <em>a</em>) most distant node from the |
| starting point, or show you the <em>lengths</em> of the longest path from x to every |
| y that it depends on. Use <code>maxrank</code>:</p> |
| |
| <pre>bazel query 'deps(//foo-tests)' --output maxrank | tail -1 |
| 85 //third_party/zlib:zutil.c</pre> |
| |
| <p>The result indicates that there exist paths of length 85 that must occur in |
| order in this build.</p> |
