El comando aquery
te permite consultar acciones en tu gráfico de compilación.
Funciona 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 artefactos generados a partir del gráfico de destino configurado. Por ejemplo, los comandos reales que se ejecutan
y sus entradas/salidas/mnemónicos.
La herramienta acepta varias opciones de 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
tradicionales, pero siblings
, buildfiles
y tests
.
Resultado de aquery
de ejemplo (sin detalles específicos):
$ bazel aquery 'deps(//some:label)' action 'Writing file some_file_name' Mnemonic: ... Target: ... Configuration: ... ActionKey: ... Inputs: [...] Outputs: [...]
Sintaxis básica
Un ejemplo simple de la sintaxis de aquery
es el siguiente:
bazel aquery "aquery_function(function(//target))"
La expresión de consulta (entre comillas) consta de lo siguiente:
aquery_function(...)
: Son funciones específicas deaquery
. Puedes encontrar más detalles a continuación.function(...)
: Son las funciones estándar como elquery
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))'
Uso de funciones de consulta
Existen tres funciones aquery
:
inputs
: Filtra acciones por entradas.outputs
: Filtra acciones por resultados.mnemonic
: filtra las acciones por mnemotécnica.
expr ::= inputs(word, expr)
El operador inputs
muestra las acciones que se generan 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 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 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.*"
.
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 Aquery
--output=(text|summary|proto|jsonproto|textproto), default=text
El formato de salida predeterminado (text
) es legible; usa proto
, textproto
o jsonproto
para obtener un formato legible por máquina.
El mensaje proto 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 usados en el comando (posiblemente grandes).
--include_file_write_contents, default=false
Incluye el contenido del archivo de la acción actions.write()
y el del archivo de manifiesto de la acción SourceSymlinkManifest
. El contenido del archivo se muestra en el campo file_contents
con --output=
xxxproto
.
Con --output=text
, el resultado tiene una línea FileWriteContents: [<base64-encoded file contents>]
--skyframe_state, default=false
Sin realizar un análisis adicional, vuelca el Action Graph de Skyframe.
Otras herramientas y funciones
Cómo realizar 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 gráfico de dependencia construido a partir de las ejecuciones anteriores de la fase de análisis.
En algunos casos, es útil consultar el Action Graph en Skyframe. Un ejemplo de caso de uso sería el siguiente:
- Run
bazel build //target_a
- Run
bazel build //target_b
- Se generó el archivo
foo.out
.
Como usuario de Bazel, quiero determinar si foo.out
se generó a partir de la compilación de //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 averiguar la acción responsable de crear foo.out
y, a su vez, el objetivo. Sin embargo, la cantidad de destinos diferentes compilados previamente 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 gráfico de acción que Skyframe conserva en la instancia de Bazel (opcionalmente) realiza un filtrado 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 consulta
Actualmente, --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")'
Comparación de resultados de aquery
Puedes comparar los resultados de dos invocaciones de aquery diferentes con la herramienta de aquery_differ
.
Por ejemplo, cuando realizas algunos cambios en la definición de la regla y deseas verificar que las líneas de comandos que se ejecutan no hayan cambiado. aquery_differ
es la herramienta para hacerlo.
La herramienta está disponible en el repositorio bazelbuild/bazel. Para usarlo, clona el repositorio en tu máquina local. Un 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 una consulta before
y after
: qué acciones estaban presentes en una, pero no en la otra, qué acciones tienen diferentes líneas de comandos o entradas en cada resultado de una consulta, ...). El resultado de la ejecución 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
: Los archivos de salida de aquery que se compararán
--input_type=(proto|text_proto), default=proto
: Es el formato de los archivos de entrada. Se proporciona compatibilidad para el resultado de una consulta proto
y textproto
.
--attrs=(cmdline|inputs), default=cmdline
: Son los atributos de las acciones que se compararán.
Aspecto en función
Es posible que los Aspectos se apliquen una encima de la otra. Entonces, el resultado de una consulta de la acción generada por estos Aspectos incluiría la ruta de Aspect, que es la secuencia de Aspectos aplicados al destino que generó la acción.
Un ejemplo de aspecto en aspecto:
t0 ^ | <- a1 t1 ^ | <- a2 t2
Deja que i sea el objetivo de la regla ri, que aplica un Aspecto ai a sus dependencias.
Supongamos que a2 genera una acción X cuando se aplica al objetivo t0. El resultado de texto de bazel aquery --include_aspects 'deps(//t2)'
para la acción X sería el 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 de Aspecto (para Aspectos nativos) o bzl_file%aspect_name
(para Aspectos de Starlark). Las AspectDescriptor
se ordenan en el orden topológico del gráfico de dependencia.
Cómo vincular con el perfil JSON
Mientras una consulta proporciona información sobre las acciones que se ejecutan en una compilación (por qué se ejecutan y sus entradas/salidas), el perfil JSON nos indica el momento y la duración de su ejecución. Es posible combinar estos 2 conjuntos de información mediante 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 las salidas principales. El resultado principal de una acción se incluye de forma predeterminada mediante una consulta.
En la actualidad, no proporcionamos una herramienta canónica para combinar estas 2 fuentes de datos, pero deberías poder compilar 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 simplemente se consideran una sola y solo se ejecutan una vez.
Sin embargo, una consulta opera en el gráfico de acción previo a la ejecución y posterior al análisis y, por lo tanto, trata estas acciones como acciones independientes cuyos artefactos de salida tienen exactamente el mismo execPath
. Como resultado, los artefactos equivalentes aparecen duplicados.
La lista de problemas de consulta/características planificadas se puede encontrar en GitHub.
Preguntas frecuentes
La ActionKey permanece igual, aunque el contenido de un archivo de entrada cambie.
En el contexto de una consulta, ActionKey
hace referencia a la String
obtenida 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 inconveniente o quieres solicitar funciones, infórmalo aquí.