Skip to main content

Cquery Environment

Functions​

  • allbuildfiles
  • allpaths: Computes all dependency paths.
  • attrfilter: Rule attribute filtering.
  • attrregexfilter: Rule attribute filtering with regex.
  • buildfile: Finds the build file where given target is defined.
  • configuration_deps: A filter function that can be used in the query expression of deps query function.
  • deps
  • except: Computes the arguments that are in argument A but not in argument B.
  • exec_deps: A filter function that can be used in the query expression of deps query function.
  • filter: Filter using regex partial match.
  • first_order_deps: A filter function that can be used in the query expression of deps query function.
  • inputs: Returns all inputs non-transitively
  • intersect: Computes the set intersection over the given arguments.
  • kind: Filter targets by rule type.
  • labels: Not implemented.
  • nattrfilter: Negative rule attribute filtering. It is the opposite of attrfilter.
  • owner: Targets owning the given file.
  • rbuildfiles
  • rdeps: Find the reverse dependencies of the targets in the given target universe.
  • somepath: Shortest dependency path between two sets of targets.
  • target_deps: A filter function that can be used in the query expression of deps query function.
  • targets_in_buildfile
  • testsof
  • toolchain_deps: A filter function that can be used in the query expression of deps query function.
  • union: Computes the set union over the given arguments.

allbuildfiles(universe: target expression)​

allpaths(from: target expression, to: target expression, captured_expr: ?query expression)​

Computes all dependency paths.

The allpaths(from, to) function evaluates to the graph formed by paths between the target expressions from and to, following the dependencies between nodes. For example, the value of buck query "allpaths('//foo:bar', '//foo/bar/lib:baz')" is the dependency graph rooted at the single target node //foo:bar, that includes all target nodes that depend (transitively) on //foo/bar/lib:baz.

The two arguments to allpaths() can themselves be expressions. For example, the command: buck query "allpaths(kind(java_library, '//...'), '//foo:bar')" shows all the paths between any java_library in the repository and the target //foo:bar.

We recommend using allpaths() with the --output-format=dot parameter to generate a graphviz file that can then be rendered as an image. For example:

$ buck query "allpaths('//foo:bar', '//foo/bar/lib:baz')" --output-format=dot --output-file=result.dot
$ dot -Tpng result.dot -o image.png

Graphviz is an open-source graph-visualization software tool. Graphviz uses the dot language to describe graphs.

attrfilter(attr: string, value: string, targets: target expression)​

Rule attribute filtering.

The attrfilter(attribute, value, targets) operator evaluates the given target expression and filters the resulting build targets to those where the specified attribute contains the specified value. In this context, the term attribute refers to an argument in a build rule, such as name, headers, srcs, or deps.

  • If the attribute is a single value, say name, it is compared to the specified value, and the target is returned if they match.
  • If the attribute is a list, the target is returned if that list contains the specified value.
  • If the attribute is a dictionary, the target is returned if the value exists in either the keys or the values of the dictionary.

For example: buck2 query "attrfilter(deps, '//foo:bar', '//...')" returns the build targets in the repository that depend on //foo:bar, or more precisely: those build targets that include //foo:bar in their deps argument list.

attrregexfilter(attr: string, value: string, targets: target expression)​

Rule attribute filtering with regex.

The attrregexfilter(attribute, value, targets) operator is identical to the attrfilter(attribute, value, targets) operator except that it takes a regular expression as the second argument. It evaluates the given target expression and filters the resulting build targets to those where the specified attribute matches the specified pattern. In this context, the term attribute refers to an argument in a build rule, such as name, headers, srcs, or deps.

  • If the attribute is a single value, say name, it is matched against the specified pattern, and the target is returned if they match.
  • If the attribute is a list, the target is returned if that list contains a value that matches the specified pattern.
  • If the attribute is a dictionary, the target is returned if the pattern match is found in either the keys or the values of the dictionary.

buildfile(targets: target expression)​

Finds the build file where given target is defined.

The targets parameter is a specific target or target pattern. It specifies the targets to find build file dependencies for. In order to find the build file associated with a source file, combine the owner operator with buildfile. Examples: buck2 uquery "buildfile(//buck2/app/buck2_action_impl_tests:buck2_action_impl_tests)" buck2 uquery "buildfile(owner(context.rs))" Both return the build file location: fbcode/buck2/app/buck2_action_impl_tests/TARGETS

configuration_deps()​

A filter function that can be used in the query expression of deps query function.

Returns the output of deps function for configuration dependencies (that appear as conditions in selects).

Example: buck2 cquery "deps('//foo:bar', 1, configuration_deps())"

deps(targets: target expression, depth: ?integer, captured_expr: ?query expression)​

except(left: any value, right: any value)​

Computes the arguments that are in argument A but not in argument B.

Can be used with the - symbol. This operator is NOT commutative.

The parser treats this operator as left-associative and of equal precedence, so we recommend that you use parentheses if you need to ensure a specific order of evaluation. A parenthesized expression resolves to the value of the expression it encloses.

Example: buck2 aquery "deps('//foo:bar') except deps('//baz:lib')" is the same as buck2 aquery "deps('//foo:bar') - deps('//baz:lib')" Both return the targets that //foo:bar depends on and that //baz:lib does NOT depend on.

exec_deps()​

A filter function that can be used in the query expression of deps query function.

Returns the output of deps function for execution dependencies (build time dependencies), ex. compiler used as a part of the build.

Example: buck2 cquery "deps('//foo:bar', 1, exec_deps())"

filter(regex: string, set: target or file expression)​

Filter using regex partial match.

Target are matched against their fully qualified name. Files are matched against their repo path like repo//foo/bar/baz.py.

first_order_deps()​

A filter function that can be used in the query expression of deps query function.

Returns the output of deps function for the immediate dependencies of the given targets. Output is equivalent to deps(<targets>, 1).

Example: buck2 cquery "deps('//foo:bar', 1, first_order_deps())" is equivalent to buck2 cquery "deps('//foo:bar', 1)"

inputs(targets: target expression)​

Returns all inputs non-transitively

Returns the files that are inputs to the targets expression, ignoring all dependencies. Returns only the files which are an immediate input to the rule function and thus are needed to go through analysis phase (i.e. produce providers). You could consider the inputs() and owner() operators to be inverses of each other.

buck2 cquery "inputs(fbcode//buck2/dice/...)" returns the input files for the fbcode//buck2/dice/... targets.

intersect(left: any value, right: any value)​

Computes the set intersection over the given arguments.

Can be used with the ^ symbol. This operator is commutative.

The parser treats this operator as left-associative and of equal precedence, so we recommend that you use parentheses if you need to ensure a specific order of evaluation. A parenthesized expression resolves to the value of the expression it encloses.

Example: buck2 aquery "deps('//foo:bar') intersect deps('//baz:lib')" is the same as buck2 aquery "deps('//foo:bar') ^ deps('//baz:lib')" Both return the targets that appear in the transitive closure of //foo:bar and //baz:lib.

kind(regex: string, targets: target expression)​

Filter targets by rule type.

Returns a subset of targets where the rule type matches the specified regex. The specified pattern can be a regular expression.

For example:

$ buck2 query "kind('java.*', deps('//foo:bar'))"

This command returns targets matching rule type java.* (e.g., java_library, java_binary) in the transitive dependencies of //foo:bar.

labels(attr: string, targets: target expression)​

Not implemented.

This function won't be implemented in the future, because buck2 query core does not support returning both files and targets from a single function.

In buck1 it returns targets and files referenced by the given attribute in the given targets.

nattrfilter(attr: string, value: string, targets: target expression)​

Negative rule attribute filtering. It is the opposite of attrfilter.

The nattrfilter(attribute, value, targets) operator evaluates the given target expression and filters the resulting build targets to those where the specified attribute doesn't contain the specified value. In this context, the term attribute refers to an argument in a build rule, such as name, headers, srcs, or deps.

  • If the attribute is a single value, say name, it is compared to the specified value, and the target is returned if they don't match.
  • If the attribute is a list, the target is returned if that list doesn't contain the specified value.
  • If the attribute is a dictionary, the target is returned if the value doesn't exist in both the keys and the values of the dictionary.

For example: buck2 query "nattrfilter(deps, '//foo:bar', '//...')" returns the build targets in the repository that don't depend on //foo:bar, or more precisely: those build targets that don't include //foo:bar in their deps argument list.

owner(files: file expression)​

Targets owning the given file.

Returns all targets that have a specified file as an input.

owner() and inputs() functions are inverses of each other.

If the specified file has multiple owning targets, a set of targets is returned. If no owner exists, an empty set is returned.

For example:

$ buck2 uquery "owner('app/buck2/src/lib.rs')"

//buck2/app/buck2:buck2-unittest
//buck2/app/buck2:buck2

rbuildfiles(universe: file expression, argset: file expression)​

rdeps(universe: target expression, targets: target expression, depth: ?integer, captured_expr: ?query expression)​

Find the reverse dependencies of the targets in the given target universe.

The first parameter universe defines where to look for reverse dependencies. The second parameter targets is a specific target or target pattern. It specifies the targets to find reverse dependencies for. The third argument depth is an optional integer literal specifying an upper bound on the depth of the search. A value of one (1) specifies that buck query should return only direct dependencies. If the depth parameter is omitted, the search is unbounded. The fourth argument captured_expr is an optional expression that can be used to filter the results.

The returned values include the nodes from the targets argument itself.

For example following uquery:

$ buck2 uquery "rdeps(//buck2/..., //buck2/dice/dice:dice, 1)"

returns all targets under //buck2/... that depend on //buck2/dice/dice:dice.

somepath(from: target expression, to: target expression, captured_expr: ?query expression)​

Shortest dependency path between two sets of targets.

  • The first parameter from represents the upstream targets (e.g., final binary).
  • The second parameter to represents the downstream targets (e.g., a library).

Results are returned in order from top to bottom (upstream to downstream).

If multiple paths exist, the returned path is unspecified. If no path exists, an empty set is returned.

For example:

$ buck2 uquery 'somepath(//buck2:buck2, //buck2/app/buck2_node:buck2_node)'

//buck2:buck2
//buck2/app/buck2:buck2-bin
//buck2/app/buck2_analysis:buck2_analysis
//buck2/app/buck2_node:buck2_node

target_deps()​

A filter function that can be used in the query expression of deps query function.

Returns the target dependencies of each dependency of the given targets, excluding any configuration, toolchain and execution dependencies (build time dependencies) like compiler used as a part of the build.

Example: buck2 cquery "deps('//foo:bar', 1, target_deps())"

targets_in_buildfile(files: file expression)​

testsof(targets: target expression)​

toolchain_deps()​

A filter function that can be used in the query expression of deps query function.

Returns the output of deps function for toolchain dependencies.

Example: buck2 cquery "deps('//foo:bar', 1, toolchain_deps())"

union(left: any value, right: any value)​

Computes the set union over the given arguments.

Can be used with the + symbol. This operator is commutative.

The parser treats all this operator as left-associative and of equal precedence, so we recommend that you use parentheses if you need to ensure a specific order of evaluation. A parenthesized expression resolves to the value of the expression it encloses.

Example: buck2 aquery "deps('//foo:bar') union deps('//baz:lib')" is the same as buck2 aquery "deps('//foo:bar') + deps('//baz:lib')" Both return the aggregation of the targets that //foo:bar and //baz:lib depend on.

Value Types​

  • string: for example, non_quoted_string or "quoted string"

  • integer: must be positive and fit in u32

  • target expression: either a literal or the return value of a function

    This could be a literal build target ("cell//some:target") or a pattern ("cell//package:" or "cell//recursive/...") or the result of another function that returns a target expression. For queries in CLI commands (like buck2 query), literals can be relative to the current working dir (like some:target or ...).

  • file expression: either a literal or the return value of a function

    This could be a file literal like path/to/a.file or the return value of a function that returns files (for example, the buildfile() function).

  • target or file expression: either a file expression or target expression

    This could be a literal like path/to/a.file or "cell//some:target", or the return value of a function that returns files or targets.

  • query expression: a valid query expression, evaluated in a function-specific context

    This is used for functions that capture an expression and evaluate it in another context. For example, the deps() function can accept an expression that it uses to find the children of a node to customize the deps traversal.

  • any value: any query value