Consulta del gráfico de acción (aquery)

Informar un problema Ver fuente Por la noche · 7.2 · 7.1 · 7.0 · 6.5 · 6.4

El comando aquery te permite consultar acciones en el gráfico de compilación. Opera en el gráfico de destino configurado posterior al análisis y expone información sobre Acciones, Artefactos y sus relaciones.

aquery es útil cuando te interesan las propiedades de las acciones o los artefactos. generada desde el gráfico de destino configurado. Por ejemplo, los comandos reales ejecutan y sus entradas, resultados y mnemotecnias.

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

Admite el mismo conjunto de funciones que también está disponible para los query pero siblings, buildfiles y tests

Un resultado de ejemplo de 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(...): Funciones específicas de aquery Obtén más detalles a continuación.
• function(...): Son las funciones estándar. que el query tradicional.
• //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 aquery

Hay tres funciones aquery:

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

expr ::= inputs(word, expr)

El operador inputs muestra las acciones generadas desde la compilación expr. cuyos nombres de archivo de entrada coincidan con la regex proporcionada por word.

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

Las funciones outputs y mnemonic comparten una sintaxis similar.

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

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

El comando anterior encontraría todas las acciones relacionadas con la compilación de //src/target_a. cuyos mnemónicos coinciden con "Cpp.*" y las entradas coinciden con los patrones ".*cpp" y "foo.*".

Importante: Las funciones de consulta no se pueden anidar dentro de funciones que no sean de consulta. Conceptualmente, esto tiene sentido, ya que el resultado de las funciones de aquery es Actions, y no objetivos configurados.

Este es 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 de Bazel normal y, por lo tanto, hereda el conjunto de opciones disponibles durante la compilación.

Opciones de consulta

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

El formato de salida predeterminado (text) es legible por humanos. Usa proto, textproto o jsonproto para un formato apto para la lectura automática. El mensaje de protocolo es analysis.ActionGraphContainer.

--include_commandline, default=true

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

--include_artifacts, default=true

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

--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 usaron en el comando (posiblemente grandes).

Advertencia: Habilitar esta marca habilitará automáticamente la marca --include_commandline.

--include_file_write_contents, default=false

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

--skyframe_state, default=false

Sin realizar un análisis adicional, vuelca el gráfico de acción de Skyframe.

Nota: Por el momento, no se admite la especificación de un destino con --skyframe_state. Esta marca solo está disponible con --output=proto o --output=textproto.

Otras herramientas y funciones

Consulta el estado de Skyframe

Skyframe es la evaluación y de incrementalidad de Bazel. En cada instancia del servidor de Bazel, Skyframe almacena el gráfico de dependencias. construida 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:

1. Ejecuta bazel build //target_a
2. Ejecuta 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)' para determinar la acción responsable para crear foo.out y, a su vez, el destino. Sin embargo, la cantidad de diferentes objetivos creados previamente puede ser mayor que 2, lo que hace que ejecutar varios aquery genera complicaciones.

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 gráfico de acción. que Skyframe mantiene en la instancia de Bazel, (opcional) realiza el filtrado en ella y genera el contenido sin volver a ejecutar la fase de análisis.

Consideraciones especiales

Formato de salida

Por el momento, --skyframe_state solo está disponible para --output=proto y --output=textproto

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

Actualmente, --skyframe_state consulta todo el gráfico de acciones que existe en Skyframe. independientemente de 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 resultados de consultas

Puedes comparar los resultados de dos invocaciones de consulta diferentes con la herramienta aquery_differ. Por ejemplo, si haces algunos cambios en la definición de tu regla y quieres verificar que el las líneas de comandos que se ejecutaban no cambiaron. 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 la consulta before y after: qué acciones estaban presentes en una pero no en la otra y cuáles tienen valores distintos línea de comandos o entradas en cada resultado de consulta, ...). Ejecutar el comando anterior sería el siguiente resultado:

  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: Los archivos de salida de BigQuery que se compararán

--input_type=(proto|text_proto), default=proto: Es el formato de la entrada. archivos. Se proporciona compatibilidad con el resultado de las consultas proto y textproto.

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

Aspecto en aspecto

Es posible que los Aspectos se apliquen uno encima del otro. El resultado de la consulta de la acción que genera estos Aspectos incluirían la Ruta de acceso del Aspecto, que es la secuencia de Aspectos aplicados al objetivo que generó la acción.

Ejemplo de aspecto en aspecto:

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

Sea _i un objetivo de la regla r_i, que aplica un Aspecto a_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:

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

Esto significa que el aspecto a2 generó la acción X en a1(t0), donde a1(t0) es el resultado del aspecto a1 aplicado al objetivo t0.

Cada AspectDescriptor tiene el siguiente formato:

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

AspectClass puede ser el nombre de la clase Aspect (para aspectos nativos). bzl_file%aspect_name (para aspectos de Starlark). AspectDescriptor son ordenadas en el orden topológico de gráfico de dependencia.

Vincula con el perfil JSON

Mientras que una consulta proporciona información sobre las acciones que se ejecutan en una compilación (por qué se ejecutan, sus entradas y salidas), el perfil de JSON nos indica el momento 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 acciones de salida 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 salidas 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 estar poder crear tu propia secuencia de comandos con la información anterior.

Problemas conocidos

Cómo controlar acciones compartidas

A veces, las acciones compartido entre los destinos configurados.

En la fase de ejecución, esas acciones compartidas se se considera como una sola y solo se ejecuta una vez. Sin embargo, una consulta opera en el gráfico de acción previo a la ejecución y después del análisis y, por lo tanto, trata estas como acciones separadas cuyos artefactos de salida tienen exactamente el mismo execPath. Como resultado, los artefactos equivalentes aparecen duplicados.

Puedes encontrar la lista de problemas o funciones planificadas de una consulta en GitHub:

Preguntas frecuentes

El ActionKey permanece igual aunque cambie el contenido de un archivo de entrada.

En el contexto de una consulta, ActionKey hace referencia al String obtenido 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 algún problema o quieres solicitar funciones, infórmalo aquí.