Skip to main content

cquery

This document provides an overview of the commands and options available under buck2 cquery.

buck2 cquery​

Perform queries on the configured target graph

The configured target graph includes information about the configuration (platforms) and transitions involved in building targets. In the configured graph, selects are fully resolved. The same target may appear in multiple different configurations (when printed, the configuration is after the target in parentheses).

A user can specify a --target-universe flag to control how literals are resolved. When provided, any literals will resolve to all matching targets within the universe (which includes the targets passed as the universe and all transitive deps of them). When not provided, we implicitly set the universe to be rooted at every target literal in the cquery.

Run buck2 docs cquery or https://buck2.build/docs/users/query/cquery/ for more documentation about the functions available in cquery expressions.

Examples:

Print all the attributes of a target

buck2 cquery //java/com/example/app:amazing --output-all-attributes

List the deps of a target (special characters in a target will require quotes):

buck2 cquery 'deps("//java/com/example/app:amazing+more")'

Usage: buck2 cquery [OPTIONS] <QUERY> [QUERY_ARGS]...

Arguments:​

  • <QUERY> the query to evaluate

  • <QUERY_ARGS> list of literals for a multi-query (one containing %s or %Ss)

Common Options:​

Common options are documented on the Common Options page.

Options:​

  • -A, --output-all-attributes Output all attributes, equivalent of --output-attribute ''.

    Avoid using this flag in automation because it may be expensive to produce certain attributes, and because it makes harder to track which special attributes are used.

  • -B, --output-basic-attributes Output basic attributes, namely those the user can supply, plus rule type and package name

  • -a, --output-attribute <ATTRIBUTE> Regular expressions to match attributes. Regular expressions are used in "search" mode, so for example empty string matches all attributes including special attributes.

    When using in automation, please specify the regular expression to match the attribute precisely, for example --output-attribute '^headers$' to make it easier to track which special attributes are used.

  • --output-attributes <ATTRIBUTE> Deprecated: Use --output-attribute instead.

    List of space-separated attributes to output, --output-attributes attr1 attr2.

  • --json Output in JSON format

  • --dot Output in Graphviz Dot format

  • --dot-compact Output in a more compact format than Graphviz Dot

  • --output-format <dot|dot_compact|json|starlark|html> Output format (default: list).

    dot - dot graph format.

    dot_compact - compact alternative to dot format.

    json - JSON format.

    starlark - targets are printed like starlark code that would produce them. html - html file containing interactive target graph.

    • Possible values:
      • dot
      • json
      • dot_compact
      • starlark
      • html

  • --show-providers Show the providers of the query result instead of the attributes and labels

  • -u, --target-universe <TARGET_UNIVERSE> Comma separated list of targets to construct a configured target universe.

    When the option is specified, command targets are be resolved in this universe. Additionally, --target-platforms= and --modifier= flags are be used to configure the universe targets, not the command targets.

    This argument is particularly recommended on most non-trivial cqueries. In the absence of this argument, buck2 will use the target literals in your cquery expression as the value for this argument, which may not be what you want.

  • --target-platforms <PLATFORM> Configuration target (one) to use to configure targets

  • -m, --modifier <VALUE> A configuration modifier to configure all targets on the command line. This may be a constraint value target.

  • --disable-starlark-types Disable runtime type checking in Starlark interpreter.

    This option is not stable, and can be used only locally to diagnose evaluation performance problems.

  • --stack Record or show target call stacks.

    Starlark call stacks will be included in duplicate targets error.

    If a command outputs targets (like targets command), starlark call stacks will be printed after the targets.

  • --profile-patterns <PROFILE_PATTERNS> Enables profiling for all evaluations whose evaluation identifier matches one of the provided patterns.

    Some examples identifiers: analysis/cell//buck2/app/buck2_action_impl:buck2_action_impl (cfg:linux-x86_64#27ac5723e0c99706) load/cell//build_defs/json.bzl load/prelude//playground/test.bxl load/cell//build_defs/json.bzl@other_cell load_buildfile/fbcode//third-party-buck/platform010/build/ncurses load_packagefile/fbcode//cli/rust/cli_delegate anon_analysis/anon//:_anon_link_rule (anon: 766183dc9b6f680a) (fbcode//buck2/platform/execution:linux-x86_64#08961b14cfb182aa) bxl/prelude//playground/test.bxl:playground

    You can pass --profile-patterns=.* to enable no-op profiling for everything (additionally pass --profile-patterns-mode=none to use no-op profiling to just get a list of all the identifiers).

    The profile results will be written to individual .profile files in <ROOT_OUTPUT>/<data+time>-<uuid>/ where ROOT_OUTPUT comes from the --profile-patterns-output flag. In that directory there will also be a file listing all the identifiers that were profiled.

    Enabling/disabling profiling of an evaluation will invalidate the results of that evaluation and it will be recomputed. In some cases, this will cause other work to also need to be redone (for example, invalidating the result of loading PACKAGE files causes all consumers to be recomputed). But if you keep profiling options consistent between commands, only the work that is otherwise invalidated will be redone (and only for those would profiling results be created).

    You must also pass --profile-patterns-mode and --profile-patterns-output.

  • --profile-patterns-output <PATH>

  • --profile-patterns-mode <PROFILE_PATTERNS_MODE> Profile mode.

    Memory profiling modes have suffixes either -allocated or -retained.

    -retained means memory kept in frozen starlark heaps after analysis completes. -retained does not work when profiling loading, because no memory is retained after loading and frozen heap is not even created. This is probably what you want when profiling analysis.

    -allocated means allocated memory, including memory which is later garbage collected.

    • Possible values:
      • time-flame
      • heap-allocated
      • heap-retained
      • heap-flame-allocated
      • heap-flame-retained
      • heap-summary-allocated
      • heap-summary-retained
      • statement
      • bytecode
      • bytecode-pairs
      • typecheck
      • coverage
      • none

  • --profile-mode <PROFILE_MODE> Profile target loading.

    When this option is enabled, Buck will profile every BUCK file loaded during the query and merge the results into a single profile. The command may return cached profile data if BUCK files were not invalidated.

    • Possible values:
      • time-flame
      • heap-allocated
      • heap-retained
      • heap-flame-allocated
      • heap-flame-retained
      • heap-summary-allocated
      • heap-summary-retained
      • statement
      • bytecode
      • bytecode-pairs
      • typecheck
      • coverage
      • none

  • --profile-output <PROFILE_OUTPUT> Where to write profile output