Cquery (configurable query)
Overview
cquery
is a variant
of query
that correctly handles
select()
and build
options' effects on the build graph.
It achieves this by running over the results of Bazel's
analysis
phase, which integrates these effects. query
, by constrast,
runs over the results of Bazel's loading phase, before options are evaluated.
For example:
$ cat > tree/BUILD <<EOF sh_library( name = "ash", deps = select({ ":excelsior": [":manna-ash"], ":americana": [":white-ash"], "//conditions:default": [":common-ash"], }), ) sh_library(name = "manna-ash") sh_library(name = "white-ash") sh_library(name = "common-ash") config_setting( name = "excelsior", values = {"define": "species=excelsior"}, ) config_setting( name = "americana", values = {"define": "species=americana"}, ) EOF
# Traditional query: query doesn't know which select() branch will be chosen # so it conservatively lists all of them. $ bazel query "deps(//tree:ash)" --noimplicit_deps //tree:ash //tree:white-ash //tree:manna-ash //tree:common-ash # cquery: cquery lets you set build options at the command line and chooses # the exact dependencies that implies. $ bazel cquery "deps(//tree:ash)" --define species=excelsior --noimplicit_deps //tree:ash (hash-of-config) //tree:manna-ash (hash-of-config)
Each result includes information about the configuration in which the target
was built. For most targets, this is an (opaque) hash of the build options
and values in that configuration. Host-configured targets are marked
(HOST)
. Non-generated source files, like those commonly
found in srcs
, have no need for configuration and are
marked (null)
.
Since cquery
runs over the configured target graph. it doesn't
have insight into artifacts like build actions nor access to
test_suite
rules as they are not configured targets. For the former,
see aquery
.
Basic syntax
A simple cquery
call looks like:
bazel cquery "function(//target)"
The query expression "function(//target)"
consists of the following:
-
function(...)
is the function to run on the target.cquery
supports most ofquery
's functions, plus a few new ones. //target
is the expression fed to the function. In this example, the expression is a simple target. But the query language also allows nesting of functions. See the Query How-To for examples.
cquery
requires a target to run through the
loading
and analysis
phases. Unless otherwise specified, cquery
parses the target(s)
listed in the query
expression. See --universe_scope
for querying dependencies of top-level build targets.
Target pattern evaluation
//foo
has a different meaning for cquery
than
for query
. This is because cquery
evaluates configured targets and the build graph may have multiple
configured versions of //foo
.
For cquery
, a target pattern in the query expression evaluates
to every configured target with a label that matches that pattern. Output is
deterministic, but cquery
makes no ordering guarantee beyond the
core query ordering contract.
This produces subtler results for query expressions than with query
.
For example, the following can produce multiple results:
# Analyzes //foo in the target configuration, but also analyzes # //genrule_with_foo_as_tool which depends on a host-configured # //foo. So there are two configured target instances of //foo in # the build graph. $ bazel cquery //foo --universe_scope=//foo,//genrule_with_foo_as_tool //foo (9f87702f17541d32a56488e3b8be8a98e52b06945f7) //foo (HOST)
If you want to precisely declare which instance to query over, use
the config
function.
See query
's target pattern
documentation for more information on target patterns.
Functions
Of the set of functions
supported by query
, cquery
supports
all
but visible
,
siblings
,
buildfiles
,
and tests
.
cquery
also introduces the following new functions:
config
expr ::= config(expr, word)
The config
operator attempts to find the configured target for
the label denoted by the first argument and configuration specified by the
second argument.
Valid values for the second argument
are "target"
, "host"
, "null"
, or a
custom configuration hash. Hashes can be retrieved from $
bazel config
or a prevous cquery
's output.
Examples:
$ bazel cquery "config(//bar, host)" --universe_scope=//foo
$ bazel cquery "deps(//foo)" //bar (HOST) //baz (3732cc8c6d40d97) $ bazel cquery "config(//baz, 3732cc8c6d40d97)"
If not all results of the first argument can be found in the specified configuration, only those that can be found are returned. If no results can be found in the specified configuration, the query fails.
Options
Build options
cquery
runs over a regular Bazel build and thus inherits the
set of
options
available during a build.
Cquery options
--universe_scope
(comma-separated list)
Often, the dependencies of configured targets go through transitions, which causes their configuration to differ from their dependent. This flag allows you to query a target as if it were built as a dependency or a transitive dependency of another target. For example:
# x/BUILD genrule( name = "my_gen", srcs = ["x.in"], outs = ["x.cc"], cmd = "$(locations :tool) $< >$@", tools = [":tool"], ) cc_library( name = "tool", )
Genrules configure their tools in the host configuration so the following queries would produce the following outputs:
Query | Target Built | Output |
---|---|---|
bazel cquery "//x:tool" | //x:tool | //x:tool(targetconfig) |
bazel cquery "//x:tool" --universe_scope="//x:my_gen" | //x:my_gen | //x:tool(hostconfig) |
If this flag is set, its contents are built. If it's not set, all targets
mentioned in the query expression are built instead. The transitive closure of the
built targets are used as the universe of the query. Either way, the targets to
be built must be buildable at the top level (that is, compatible with top-level
options). cquery
returns results in the transitive closure of these
top-level targets.
Even if it's possible to build all targets in a query expression at the top
level, it may be beneficial to not do so. For example, explicitly setting
--universe_scope
could prevent building targets multiple times in
configurations you don't care about. It could also help specify which configuration version of a
target you're looking for (since it's not currently possible
to fully specify this any other way). We recommend that you set this
flag if your query expression is more complex than deps(//foo)
.
--implicit_deps
(boolean, default=True)
Setting this flag to false filters out all results that aren't explicitly set in the BUILD file and instead set elsewhere by Bazel.
--tool_deps
(boolean, default=True)
Setting this flag to false filters out all configured targets for which the
path from the queried target to them crosses a transition between the target
configuration and the
non-target configurations.
If the queried target is in the target configuration, setting --notool_deps
will
only return targets that also are in the target configuration. If the queried
target is in a non-target configuration, setting --notool_deps
will only return
targets also in non-target configurations.
Output formats
By default, cquery outputs results in a dependency-ordered list of label and configuration pairs. There are other options for exposing the results as well.
Transitions
--transitions=lite --transitions=full
Configuration transitions are used to build targets underneath the top level targets in different configurations than the top level targets.
For example, a target might impose a transition to the host transition on all
dependencies in its tools
attribute. These are known as attribute
transitions. Rules can also impose transitions on their own configurations,
known as rule class transitions. This output format outputs information about
these transitions such as what type they are and the effect they have on build
options.
This output format is triggered by the --transitions
flag which by default is set to
NONE
. It can be set to FULL
or LITE
mode. FULL
mode outputs information about rule class transitions and attribute transitions including a detailed
diff of the options before and after the transition. LITE
mode outputs the same information
without the options diff.
Proto
--output=proto
This option causes the resulting targets to be printed in a binary protocol buffer form. The definition of the protocol buffer can be found at src/main/protobuf/analysis.proto.
--[no]proto:include_configurations
By default, cquery results return configuration information as part of each configured target. If you'd like to omit this information and get proto output that is formatted exactly like query's proto output, set this flag to false .
See query's proto output documentation for more proto output-related options.
Note: while selects are resolved both at the top level of returned
targets and within attributes, all possible inputs for selects are still
included as rule_input
fields.
cquery vs. query
cquery
and query
complement each other and excel in
different niches. Consider the following to decide which is right for you:
-
cquery
follows specificselect()
branches to model the exact graph you build.query
doesn't know which branch the build chooses, so overapproximates by including all branches. -
cquery
's precision requires building more of the graph thanquery
does. Specifically,cquery
evaluates configured targets whilequery
only evaluates targets. This takes more time and uses more memory. -
cquery
's intepretation of the query language introduces ambiguity thatquery
avoids. For example, if"//foo"
exists in two configurations, which one shouldcquery "deps(//foo)"
use? Theconfig
function can help with this. -
As a newer tool,
cquery
lacks support for certain use cases. See Known issues for details.
Known issues
-
All targets that
cquery
"builds" must have the same configuration.Before evaluating queries,
cquery
triggers a build up to just before the point where build actions would execute. The targets it "builds" are by default selected from all labels that appear in the query expression (this can be overridden with--universe_scope
). These must have the same configuration.While these generally share the top-level "target" configuration, rules can change their own configuration with incoming edge transitions. This is where cquery falls short.
Workaround: If possible, set
--universe_scope
to a stricter scope. For example:# This command attempts to build the transitive closures of both //foo and # //bar. //bar uses an incoming edge transition to change its --cpu flag. $ bazel cquery 'somepath(//foo, //bar)' ERROR: Error doing post analysis query: Top-level targets //foo and //bar have different configurations (top-level targets with different configurations is not supported) # This command only builds the transitive closure of //foo, under which # //bar should exist in the correct configuration. $ bazel cquery 'somepath(//foo, //bar)' --universe_scope=//foo
-
No support
for aspects.
Aspects can add additional dependencies which
cquery
will not see. This can manifest as seeing a failure on target X while building target Y but acquery somepath(Y, X)
andcquery deps(Y) | grep 'X'
will return no results because somewhere in the path between Y and X there's an aspect dependency. -
No support
for
--output=graph
or--output=xml
. -
No support for recursive target patterns (
"/..."
). -
Non-deterministic output.
cquery
does not automatically wipe the build graph from previous commands and is therefore prone to picking up results from past queries. For example,genquery
exerts a host transition on itstools
attribute - that is, it configures its tools in the host configuration.We can see the lingering effects of that transition below.
$ cat > foo/BUILD <<<EOF genrule( name = "my_gen", srcs = ["x.in"], outs = ["x.cc"], cmd = "$(locations :tool) $< >$@", tools = [":tool"], ) cc_library( name = "tool", ) EOF $ bazel cquery "//foo:tool" tool(target_config) $ bazel cquery "deps(//foo:my_gen)" my_gen (target_config) tool (host_config) ... $ bazel cquery "//foo:tool" tool(host_config)
Workaround: change any startup option to force re-analysis of configured targets. For example, add
--test_arg=<whatever>
to your build command.
Updates
The Bazel configurability team is continuously improving cquery
. If you want to
ask questions, stay updated, or get involved, contact
the Bazel team at one of these channels.