Consulta del gráfico de acciones (aquery)

Informa un problema Ver código fuente

El comando aquery te permite consultar las acciones en tu grafo de compilación. Funciona en el grafo de destino configurado después del análisis y expone información sobre acciones, artefactos y sus relaciones.

aquery es útil cuando te interesan las propiedades de las acciones/artefactos generados a partir del grafo de destino configurado. Por ejemplo, los comandos reales se ejecutan y sus entradas, salidas y nemotécnicos.

La herramienta acepta varias opciones de líneas de comandos. En particular, el comando de consulta se ejecuta sobre una compilación normal de Bazel y hereda el conjunto de opciones disponibles durante una compilación.

Es compatible con el mismo conjunto de funciones que también está disponible para query tradicional, pero con siblings, buildfiles y tests.

Ejemplo de resultado aquery (sin detalles específicos):

$ bazel aquery 'deps(//some:label)'
action 'Writing file some_file_name'
  Mnemonic: ...
  Target: ...
  Configuration: ...
  ActionKey: ...
  Inputs: [...]
  Outputs: [...]

Sintaxis básica

A continuación, se muestra un ejemplo simple de la sintaxis de aquery:

bazel aquery "aquery_function(function(//target))"

La expresión de consulta (entre comillas) consta de lo siguiente:

  • aquery_function(...): Son funciones específicas de aquery. Obtén más detalles a continuación.
  • function(...): Son las funciones estándar como query tradicionales.
  • //target es la etiqueta del destino interesado.
# aquery examples:
# Get the action graph generated while building //src/target_a
$ bazel aquery '//src/target_a'

# Get the action graph generated while building all dependencies of //src/target_a
$ bazel aquery 'deps(//src/target_a)'

# Get the action graph generated while building all dependencies of //src/target_a
# whose inputs filenames match the regex ".*cpp".
$ bazel aquery 'inputs(".*cpp", deps(//src/target_a))'

Usa funciones de consulta

Hay tres funciones aquery:

  • inputs: Filtra acciones por entradas.
  • outputs: Filtra acciones por resultados
  • mnemonic: Filtre las acciones por nombre nemotécnico

expr ::= inputs(word, expr)

El operador inputs muestra las acciones generadas a partir de la compilación de expr, cuyos nombres de archivo de entrada coinciden con la regex que proporciona word.

$ bazel aquery 'inputs(".*cpp", deps(//src/target_a))'

Las funciones outputs y mnemonic comparten una sintaxis similar.

También puede combinar funciones para lograr la operación AND. Por ejemplo:

  $ bazel aquery 'mnemonic("Cpp.*", (inputs(".*cpp", inputs("foo.*", //src/target_a))))'

Con el comando anterior, se encontrarían todas las acciones involucradas en la compilación de //src/target_a, cuyos mnemónicos coinciden con "Cpp.*" y las entradas coinciden con los patrones ".*cpp" y "foo.*".

Un ejemplo del error de sintaxis producido:

        $ bazel aquery 'deps(inputs(".*cpp", //src/target_a))'
        ERROR: aquery filter functions (inputs, outputs, mnemonic) produce actions,
        and therefore can't be the input of other function types: deps
        deps(inputs(".*cpp", //src/target_a))

Opciones

Opciones de compilación

aquery se ejecuta sobre una compilación normal de Bazel y, por lo tanto, hereda el conjunto de opciones disponibles durante una compilación.

Opciones de consulta

--output=(text|summary|proto|jsonproto|textproto), default=text

El formato de salida predeterminado (text) es legible; usa proto, textproto o jsonproto para un formato legible. El mensaje de protocolo es analysis.ActionGraphContainer.

--include_commandline, default=true

Incluye el contenido de las líneas de comandos de la acción en el resultado (posiblemente grande).

--include_artifacts, default=true

Incluye los nombres de las entradas y salidas de acciones de la salida (posiblemente grande).

--include_aspects, default=true

Indica si se deben incluir acciones generadas por Aspect en el resultado.

--include_param_files, default=false

Incluye el contenido de los archivos de parámetros que se usan en el comando (potencialmente grande).

--include_file_write_contents, default=false

Incluir contenidos del archivo para la acción actions.write() y el contenido del archivo de manifiesto para la acción SourceSymlinkManifest. El contenido del archivo se muestra en el campo file_contents con --output=xxxproto. Con --output=text, el resultado tiene la línea FileWriteContents: [<base64-encoded file contents>].

--skyframe_state, default=false

Sin realizar análisis adicionales, vuelca el gráfico de acciones de Skyframe.

Otras herramientas y funciones

Realiza consultas en el estado de Skyframe

Skyframe es el modelo de evaluación y de incrementalidad de Bazel. En cada instancia del servidor de Bazel, Skyframe almacena el grafo de dependencia creado a partir de las ejecuciones anteriores de la fase de análisis.

En algunos casos, resulta útil consultar el gráfico de acción en Skyframe. Un ejemplo de caso de uso sería el siguiente:

  1. Run bazel build //target_a
  2. Run bazel build //target_b
  3. Se generó el archivo foo.out.

Como usuario de Bazel, quiero determinar si foo.out se generó a partir de la compilación //target_a o //target_b.

Uno podría ejecutar bazel aquery 'outputs("foo.out", //target_a)' y bazel aquery 'outputs("foo.out", //target_b)' a fin de determinar la acción responsable de crear foo.out y, a su vez, el destino. Sin embargo, la cantidad de destinos diferentes compilados con anterioridad puede ser mayor que 2, lo que dificulta la ejecución de varios comandos de aquery.

Como alternativa, se puede usar la marca --skyframe_state:

  # List all actions on Skyframe's action graph
  $ bazel aquery --output=proto --skyframe_state

  # or

  # List all actions on Skyframe's action graph, whose output matches "foo.out"
  $ bazel aquery --output=proto --skyframe_state 'outputs("foo.out")'

Con el modo --skyframe_state, aquery toma el contenido del grafo de acciones que Skyframe mantiene en la instancia de Bazel (opcional) realiza el filtrado y muestra el contenido, sin volver a ejecutar la fase de análisis.

Consideraciones especiales

Formato de salida

Actualmente, --skyframe_state solo está disponible para --output=proto y --output=textproto

No inclusión de etiquetas de destino en la expresión de consulta

Por el momento, --skyframe_state consulta todo el gráfico de acciones que existe en Skyframe, sin importar los objetivos. Tener la etiqueta de destino especificada en la consulta junto con --skyframe_state se considera un error de sintaxis:

  # WRONG: Target Included
  $ bazel aquery --output=proto --skyframe_state **//target_a**
  ERROR: Error while parsing '//target_a)': Specifying build target(s) [//target_a] with --skyframe_state is currently not supported.

  # WRONG: Target Included
  $ bazel aquery --output=proto --skyframe_state 'inputs(".*.java", **//target_a**)'
  ERROR: Error while parsing '//target_a)': Specifying build target(s) [//target_a] with --skyframe_state is currently not supported.

  # CORRECT: Without Target
  $ bazel aquery --output=proto --skyframe_state
  $ bazel aquery --output=proto --skyframe_state 'inputs(".*.java")'

Compara los resultados de consultas

Puedes comparar los resultados de dos invocaciones de consulta diferentes con la herramienta aquery_differ. Por ejemplo, cuando realizas algunos cambios en tu definición de regla y deseas verificar que las líneas de comandos que se ejecutan no hayan cambiado. aquery_differ es la herramienta para eso.

La herramienta está disponible en el repositorio bazelbuild/bazel. Para usarlo, clona el repositorio en tu máquina local. Ejemplo de uso:

  $ bazel run //tools/aquery_differ -- \
  --before=/path/to/before.proto \
  --after=/path/to/after.proto \
  --input_type=proto \
  --attrs=cmdline \
  --attrs=inputs

El comando anterior muestra la diferencia entre los resultados de consultas before y after: las acciones presentes en un elemento, pero no las demás, las acciones con diferentes líneas de entrada y entradas en cada resultado de consulta, ...”. El resultado del comando anterior sería el siguiente:

  Aquery output 'after' change contains an action that generates the following outputs that aquery output 'before' change doesn't:
  ...
  /list of output files/
  ...

  [cmdline]
  Difference in the action that generates the following output(s):
    /path/to/abc.out
  --- /path/to/before.proto
  +++ /path/to/after.proto
  @@ -1,3 +1,3 @@
    ...
    /cmdline diff, in unified diff format/
    ...

Opciones de comando

--before, --after: Son los archivos de salida de consultas que se compararán.

--input_type=(proto|text_proto), default=proto: Es el formato de los archivos de entrada. Se proporciona asistencia para el resultado de la consulta proto y textproto.

--attrs=(cmdline|inputs), default=cmdline: Los atributos de las acciones que se compararán.

Aspecto en perspectiva

Es posible aplicar aspectos uno encima del otro. El resultado de la consulta de la acción que generan estos aspectos incluye la ruta de acceso de aspecto, que es la secuencia de los aspectos que se aplican al objetivo que generó la acción.

Ejemplo de Aspect-on-Aspect:

  t0
  ^
  | <- a1
  t1
  ^
  | <- a2
  t2

Supongamos que i es un objetivo de la regla i, que aplica un Aspecto i a sus dependencias.

Supongamos que a2 genera una acción X cuando se aplica al objetivo t0. La salida de texto de bazel aquery --include_aspects 'deps(//t2)' para la acción X sería la siguiente:

  action ...
  Mnemonic: ...
  Target: //my_pkg:t0
  Configuration: ...
  AspectDescriptors: [//my_pkg:rule.bzl%**a2**(foo=...)
    -> //my_pkg:rule.bzl%**a1**(bar=...)]
  ...

Esto significa que la acción X se generó mediante el aspecto a2 aplicado en a1(t0), en el que a1(t0) es el resultado del aspecto a1 aplicado en el destino t0.

Cada AspectDescriptor tiene el siguiente formato:

  AspectClass([param=value,...])

AspectClass podría ser el nombre de la clase Aspect (para los aspectos nativos) o bzl_file%aspect_name (para los aspectos de Starlark). AspectDescriptor se ordenan por topología dentro del gráfico de dependencias.

Cómo vincular con el perfil JSON

Mientras que la consulta proporciona información sobre las acciones que se ejecutan en una compilación (por qué se ejecutan, sus entradas y salidas), el perfil JSON nos indica el tiempo y la duración de su ejecución. Es posible combinar estos 2 conjuntos de información a través de un denominador común: el resultado principal de una acción.

Para incluir los resultados de las acciones en el perfil JSON, genera el perfil con --experimental_include_primary_output --noexperimental_slim_json_profile. Los perfiles delgados no son compatibles con la inclusión de resultados principales. El resultado principal de una acción se incluye de forma predeterminada en una consulta.

Actualmente, no proporcionamos una herramienta canónica para combinar estas 2 fuentes de datos, pero deberías poder crear tu propia secuencia de comandos con la información anterior.

Errores conocidos

Cómo administrar acciones compartidas

A veces, las acciones se comparten entre destinos configurados.

En la fase de ejecución, esas acciones compartidas se consideran simplemente como una y solo se ejecutan una vez. Sin embargo, la consulta opera en el grafo de acción previo a la ejecución, posterior al análisis y, por lo tanto, los trata como acciones separadas cuyos artefactos de salida tienen exactamente el mismo execPath. Como resultado, los artefactos equivalentes aparecen duplicados.

La lista de problemas de consultas o funciones planificadas se puede encontrar en GitHub.

Preguntas frecuentes

La ActionAction permanece igual aunque el contenido de un archivo de entrada haya cambiado.

En el contexto de una consulta, el ActionKey se refiere al String que se obtiene de ActionAnalysisMetadata#getKey:

  Returns a string encoding all of the significant behaviour of this Action that might affect the
  output. The general contract of `getKey` is this: if the work to be performed by the
  execution of this action changes, the key must change.

  ...

  Examples of changes that should affect the key are:

  - Changes to the BUILD file that materially affect the rule which gave rise to this Action.
  - Changes to the command-line options, environment, or other global configuration resources
      which affect the behaviour of this kind of Action (other than changes to the names of the
      input/output files, which are handled externally).
  - An upgrade to the build tools which changes the program logic of this kind of Action
      (typically this is achieved by incorporating a UUID into the key, which is changed each
      time the program logic of this action changes).
  Note the following exception: for actions that discover inputs, the key must change if any
  input names change or else action validation may falsely validate.

Esto excluye los cambios en el contenido de los archivos de entrada y no debe confundirse con RemoteCacheClient#ActionKey.

Actualizaciones

Si tienes problemas o quieres solicitar características, envía un informe aquí.