aquery

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

buck2 aquery

Perform queries on the action graph (experimental)

The action graph consists of all the declared actions for a build, with dependencies when one action consumes the outputs of another action.

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

Examples:

Print the action producing a target's default output

buck2 aquery //java/com/example/app:amazing

List all the commands for run actions for building a target

buck2 aquery 'kind(run, deps("//java/com/example/app:amazing+more"))' --output-attribute=cmd

Dynamic outputs (ctx.actions.dynamic_output):

Currently, aquery interacts poorly with dynamic outputs. It may return incorrect results or otherwise behave unexpectedly.

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

Arguments:

• <QUERY> the query to evaluate

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

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

• --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.

• -c, --config <SECTION.OPTION=VALUE> List of config options

• --config-file <PATH> List of config file paths

• --fake-host <HOST>

  • Possible values:
    • default
    • linux
    • macos
    • windows

• --fake-arch <ARCH>

  • Possible values:
    • default
    • aarch64
    • x8664

• --fake-xcode-version <VERSION-BUILD> Value must be formatted as: version-build (e.g., 14.3.0-14C18 or 14.1-14B47b)

• --reuse-current-config Re-uses any --config values (inline or via modefiles) if there's a previous command, otherwise the flag is ignored.

  If there is a previous command and --reuse-current-config is set, then the old config is used, ignoring any overrides.

  If there is no previous command but the flag was set, then the flag is ignored, the command behaves as if the flag was not set at all.

• --preemptible <PREEMPTIBLE> Used to configure when this command could be preempted by another command for the same isolation dir.

  Normally, when you run two commands - from different terminals, say - buck2 will attempt to run them in parallel. However, if the two commands are based on different state, that is they either have different configs or different filesystem states, buck2 cannot run them in parallel. The default behavior in this case is to block the second command until the first completes.

  • Possible values:
    • never: (default) When another command starts that cannot run in parallel with this one, block that command
    • always: When another command starts, interrupt this command, even if they could run in parallel. There is no good reason to use this other than that it provides slightly nicer superconsole output
    • ondifferentstate: When another command starts that cannot run in parallel with this one, interrupt this command

• --exit-when <EXIT_WHEN> Whether to proceed with or fail this invocation based on the daemon state

  • Possible values:
    • never: (default) Execute this command normally
    • differentstate: Fail this command if another command is already running with a different state
    • notidle: Fail this command if another command is already running (regardless of daemon state)

• --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

• --console <super|simple|...> Which console to use for this command

  • Default value: auto
  • Possible values:
    • auto
    • none
    • simple
    • simplenotty
    • simpletty
    • super

• --ui <UI> Configure additional superconsole ui components.

  Accepts a comma-separated list of superconsole components to add. Possible values are:

  dice - shows information about evaluated dice nodes debugevents - shows information about the flow of events from buckd

  These components can be turned on/off interactively. Press 'h' for help when superconsole is active.

  • Possible values:
    • dice
    • debugevents
    • io: I/O panel
    • re: RE panel

• --no-interactive-console Disable console interactions

• --event-log <PATH> Write events to this log file

• --write-build-id <PATH> Write command invocation id into this file

• --unstable-write-invocation-record <PATH> Write the invocation record (as JSON) to this path. No guarantees whatsoever are made regarding the stability of the format

• --command-report-path <PATH> Write the command report to this path. A command report is always written to buck-out/v2/<uuid>/command_report even without this flag