Comandos y opciones

En esta página, se describen las opciones disponibles con varios comandos de Bazel, como bazel build, bazel run y bazel test. Esta página complementa la lista de comandos de Bazel en Cómo compilar con Bazel.

Sintaxis de destino

Algunos comandos, como build o test, pueden operar en una lista de destinos. Usan una sintaxis más flexible que las etiquetas, que se documenta en Cómo especificar destinos para compilar.

Opciones

En las siguientes secciones, se describen las opciones disponibles durante una compilación. Cuando se usa --long en un comando de ayuda, los mensajes de ayuda en línea proporcionan información resumida sobre el significado, el tipo y el valor predeterminado de cada opción.

La mayoría de las opciones solo se pueden especificar una vez. Cuando se especifica varias veces, prevalece la última instancia. Las opciones que se pueden especificar varias veces se identifican en la ayuda en línea con el texto "se puede usar varias veces".

Ubicación del paquete

--package_path

ADVERTENCIA: La opción --package_path dejó de estar disponible. Bazel prefiere que los paquetes del repositorio principal se encuentren en la raíz del espacio de trabajo.

Esta opción especifica el conjunto de directorios en los que se busca el archivo BUILD de un paquete determinado.

Bazel encuentra sus paquetes buscando la ruta de acceso del paquete. Es una lista ordenada de directorios de Bazel separados por dos puntos, en la que cada uno es la raíz de un árbol de fuentes parcial.

Para especificar una ruta de paquete personalizada con la opción --package_path, haz lo siguiente:

  % bazel build --package_path %workspace%:/some/other/root

Los elementos de ruta de acceso del paquete se pueden especificar en tres formatos:

1. Si el primer carácter es /, la ruta es absoluta.
2. Si la ruta de acceso comienza con %workspace%, se toma en relación con el directorio de Bazel de cierre más cercano. Por ejemplo, si tu directorio de trabajo es /home/bob/clients/bob_client/bazel/foo, la cadena %workspace% en la ruta del paquete se expande a /home/bob/clients/bob_client/bazel.
3. Todo lo demás se toma en relación con el directorio de trabajo. Por lo general, no es lo que quieres hacer y puede comportarse de forma inesperada si usas Bazel desde directorios que se encuentran debajo del espacio de trabajo de Bazel. Por ejemplo, si usas el elemento package-path . y, luego, cambias el directorio a /home/bob/clients/bob_client/bazel/foo, los paquetes se resolverán desde el directorio /home/bob/clients/bob_client/bazel/foo.

Si usas una ruta de acceso de paquete no predeterminada, especifícala en tu archivo de configuración de Bazel para mayor comodidad.

Bazel no requiere que haya paquetes en el directorio actual, por lo que puedes realizar una compilación desde un espacio de trabajo de Bazel vacío si todos los paquetes necesarios se pueden encontrar en otro lugar de la ruta de acceso del paquete.

Ejemplo: Compilación a partir de un cliente vacío

  % mkdir -p foo/bazel
  % cd foo/bazel
  % touch MODULE.bazel
  % bazel build --package_path /some/other/path //foo

--deleted_packages

Esta opción especifica una lista de paquetes separados por comas que Bazel debería considerar borrados y no intentar cargar desde ningún directorio en la ruta del paquete. Se puede usar para simular el borrado de paquetes sin borrarlos realmente. Esta opción se puede pasar varias veces, en cuyo caso se concatenan las listas individuales.

Verificación de errores

Estas opciones controlan las verificaciones de errores o las advertencias de Bazel.

--[no]check_visibility

Si esta opción se establece como falsa, las verificaciones de visibilidad se degradan a advertencias. El valor predeterminado de esta opción es verdadero, por lo que, de forma predeterminada, se realiza la verificación de visibilidad.

--output_filter=regex

La opción --output_filter solo mostrará advertencias de compilación y compilación para los destinos que coincidan con la expresión regular. Si un destino no coincide con la expresión regular proporcionada y su ejecución se realiza correctamente, se descartan su salida estándar y su error estándar.

Estos son algunos valores típicos para esta opción:

Marcas de herramientas

Estas opciones controlan qué opciones pasará Bazel a otras herramientas.

--copt=cc-option

Esta opción toma un argumento que se pasará al compilador. El argumento se pasará al compilador cada vez que se invoque para el preprocesamiento, la compilación o el ensamblaje de código C, C++ o ensamblador. No se pasará cuando se vincule.

Esta opción se puede usar varias veces. Por ejemplo:

  % bazel build --copt="-g0" --copt="-fpic" //foo

compilará la biblioteca foo sin tablas de depuración, lo que generará código independiente de la posición.

--host_copt=cc-option

Esta opción toma un argumento que se pasará al compilador para los archivos fuente que se compilan en la configuración de ejecución. Esto es análogo a la opción --copt, pero solo se aplica a la configuración de ejecución.

--host_conlyopt=cc-option

Esta opción toma un argumento que se pasará al compilador para los archivos de origen C que se compilan en la configuración de ejecución. Es análogo a la opción --conlyopt, pero solo se aplica a la configuración de ejecución.

--host_cxxopt=cc-option

Esta opción toma un argumento que se pasará al compilador para los archivos de origen C++ que se compilan en la configuración de ejecución. Esto es análogo a la opción --cxxopt, pero solo se aplica a la configuración de ejecución.

--host_linkopt=linker-option

Esta opción toma un argumento que se pasará al vinculador para los archivos fuente que se compilan en la configuración de ejecución. Es análogo a la opción --linkopt, pero solo se aplica a la configuración de ejecución.

--conlyopt=cc-option

Esta opción toma un argumento que se pasará al compilador cuando se compilen archivos de origen C.

Es similar a --copt, pero solo se aplica a la compilación de C, no a la compilación ni a la vinculación de C++. Por lo tanto, puedes pasar opciones específicas de C (como -Wno-pointer-sign) con --conlyopt.

--cxxopt=cc-option

Esta opción toma un argumento que se pasará al compilador cuando se compilen archivos de origen C++.

Es similar a --copt, pero solo se aplica a la compilación de C++, no a la compilación ni a la vinculación de C. Por lo tanto, puedes pasar opciones específicas de C++ (como -fpermissive o -fno-implicit-templates) con --cxxopt.

Por ejemplo:

  % bazel build --cxxopt="-fpermissive" --cxxopt="-Wno-error" //foo/cruddy_code

--linkopt=linker-option

Esta opción toma un argumento que se pasará al compilador durante la vinculación.

Es similar a --copt, pero solo se aplica a la vinculación, no a la compilación. Por lo tanto, puedes pasar opciones de compilador que solo tienen sentido en el momento de la vinculación (como -lssp o -Wl,--wrap,abort) con --linkopt. Por ejemplo:

  % bazel build --copt="-fmudflap" --linkopt="-lmudflap" //foo/buggy_code

Las reglas de compilación también pueden especificar opciones de vinculación en sus atributos. La configuración de esta opción siempre tiene prioridad. Consulta también cc_library.linkopts.

--strip (always|never|sometimes)

Esta opción determina si Bazel quitará la información de depuración de todos los archivos binarios y las bibliotecas compartidas invocando el vinculador con la opción -Wl,--strip-debug. --strip=always significa que siempre se debe quitar la información de depuración. --strip=never significa que nunca se debe quitar la información de depuración. El valor predeterminado de --strip=sometimes significa que se debe quitar si --compilation_mode es fastbuild.

  % bazel build --strip=always //foo:bar

compilará el destino y quitará la información de depuración de todos los archivos binarios generados.

La opción --strip de Bazel corresponde a la opción --strip-debug de ld: solo quita la información de depuración. Si por algún motivo deseas quitar todos los símbolos, no solo los de depuración, deberás usar la opción --strip-all de ld, lo que puedes hacer pasando --linkopt=-Wl,--strip-all a Bazel. También ten en cuenta que configurar la marca --strip de Bazel anulará --linkopt=-Wl,--strip-all, por lo que solo debes configurar una u otra.

Si solo compilas un solo objeto binario y deseas quitar todos los símbolos, también puedes pasar --stripopt=--strip-all y compilar de forma explícita la versión //foo:bar.stripped del destino. Como se describe en la sección sobre --stripopt, esto aplica una acción de descarte después de que se vincula el objeto binario final, en lugar de incluir el descarte en todas las acciones de vinculación de la compilación.

--stripopt=strip-option

Esta es una opción adicional para pasar al comando strip cuando se genera un binario *.stripped. El valor predeterminado es -S -p. Esta opción se puede usar varias veces.

--fdo_instrument=profile-output-dir

La opción --fdo_instrument permite generar un resultado del perfil de FDO (optimización dirigida por comentarios) cuando se ejecuta el archivo binario de C/C++ compilado. En el caso de GCC, el argumento proporcionado se usa como prefijo de directorio para un árbol de directorios de archivos por objeto de archivos .gcda que contienen información de perfil para cada archivo .o.

Una vez que se haya generado el árbol de datos del perfil, se debe comprimir y proporcionar a la opción --fdo_optimize=profile-zip de Bazel para habilitar la compilación optimizada para FDO.

Para el compilador de LLVM, el argumento también es el directorio en el que se vuelcan los archivos de datos de perfil de LLVM sin procesar. Por ejemplo: --fdo_instrument=/path/to/rawprof/dir/

Las opciones --fdo_instrument y --fdo_optimize no se pueden usar al mismo tiempo.

--fdo_optimize=profile-zip

La opción --fdo_optimize permite usar la información de perfil por archivo de objeto para realizar optimizaciones de FDO (optimización dirigida por comentarios) durante la compilación. En el caso de GCC, el argumento proporcionado es el archivo zip que contiene el árbol de archivos .gcda generado anteriormente, que incluye información de perfil para cada archivo .o.

Como alternativa, el argumento proporcionado puede apuntar a un perfil automático identificado por la extensión .afdo.

Para el compilador de LLVM, el argumento proporcionado debe apuntar al archivo de salida del perfil de LLVM indexado que preparó la herramienta llvm-profdata y debe tener la extensión .profdata.

Las opciones --fdo_instrument y --fdo_optimize no se pueden usar al mismo tiempo.

--java_language_version=version

Esta opción especifica la versión de las fuentes de Java. Por ejemplo:

  % bazel build --java_language_version=8 java/com/example/common/foo:all

Compila y permite solo construcciones compatibles con la especificación de Java 8. El valor predeterminado es 11. --> Los valores posibles son 8, 9, 10, 11, 17 y 21, y se pueden extender registrando cadenas de herramientas de Java personalizadas con default_java_toolchain.

--tool_java_language_version=version

Es la versión del lenguaje Java que se usa para compilar herramientas que se ejecutan durante una compilación. El valor predeterminado es 11.

--java_runtime_version=version

Esta opción especifica la versión de JVM que se usará para ejecutar el código y las pruebas. Por ejemplo:

  % bazel run --java_runtime_version=remotejdk_11 java/com/example/common/foo:java_application

descarga el JDK 11 desde un repositorio remoto y ejecuta la aplicación Java con él.

El valor predeterminado es local_jdk. Los valores posibles son local_jdk, local_jdk_version, remotejdk_11, remotejdk_17 y remotejdk_21. Puedes extender los valores registrando una JVM personalizada con las reglas de repositorio local_java_repository o remote_java_repository.

--tool_java_runtime_version=version

Es la versión de la JVM que se usa para ejecutar las herramientas necesarias durante una compilación. El valor predeterminado es remotejdk_11.

--jvmopt=jvm-option

Esta opción permite que se pasen argumentos de opciones a la VM de Java. Se puede usar con un argumento grande o varias veces con argumentos individuales. Por ejemplo:

  % bazel build --jvmopt="-server -Xms256m" java/com/example/common/foo:all

usará la VM del servidor para iniciar todos los archivos binarios de Java y establecerá el tamaño del montón de inicio de la VM en 256 MB.

--javacopt=javac-option

Esta opción permite pasar argumentos de opciones a javac. Se puede usar con un argumento grande o varias veces con argumentos individuales. Por ejemplo:

  % bazel build --javacopt="-g:source,lines" //myprojects:prog

volverá a compilar un java_binary con la información de depuración predeterminada de javac (en lugar de la predeterminada de Bazel).

La opción se pasa a javac después de las opciones predeterminadas integradas de Bazel para javac y antes de las opciones por regla. La última especificación de cualquier opción para javac gana. Las opciones predeterminadas para javac son las siguientes:

  -source 8 -target 8 -encoding UTF-8

--strict_java_deps (default|strict|off|warn|error)

Esta opción controla si javac verifica las dependencias directas faltantes. Los destinos de Java deben declarar explícitamente todos los destinos que se usan directamente como dependencias. Esta marca indica a javac que determine los archivos .jar que se usan realmente para verificar el tipo de cada archivo .java y que muestre una advertencia o un error si no son el resultado de una dependencia directa del destino actual.

• off significa que la verificación está inhabilitada.
• warn significa que javac generará advertencias estándar de Java del tipo [strict] para cada dependencia directa faltante.
• default, strict y error significan que javac generará errores en lugar de advertencias, lo que provocará que no se compile el destino actual si se encuentran dependencias directas faltantes. Este también es el comportamiento predeterminado cuando no se especifica la marca.

Semántica de compilación

Estas opciones afectan los comandos de compilación o el contenido del archivo de salida.

--compilation_mode (fastbuild|opt|dbg) (-c)

La opción --compilation_mode (a menudo abreviada como -c, especialmente -c opt) toma un argumento de fastbuild, dbg o opt, y afecta varias opciones de generación de código C/C++, como el nivel de optimización y la integridad de las tablas de depuración. Bazel usa un directorio de salida diferente para cada modo de compilación, por lo que puedes cambiar de modo sin necesidad de realizar una recompilación completa cada vez.

• fastbuild significa compilar lo más rápido posible: generar la mínima información de depuración (-gmlt -Wl,-S) y no optimizar. Es el valor predeterminado. Nota: -DNDEBUG no se establecerá.
• dbg significa compilar con la depuración habilitada (-g), de modo que puedas usar gdb (o algún otro depurador).
• opt significa que la compilación se realiza con la optimización habilitada y con las llamadas a assert() inhabilitadas (-O2 -DNDEBUG). No se generará información de depuración en el modo opt, a menos que también pases --copt -g.

--cpu=cpu

Esta opción especifica la arquitectura de CPU objetivo que se usará para la compilación de archivos binarios durante la compilación.

--action_env=VAR=VALUE

Especifica el conjunto de variables de entorno disponibles durante la ejecución de todas las acciones. Las variables se pueden especificar por nombre, en cuyo caso el valor se tomará del entorno de invocación, o bien por el par name=value que establece el valor independientemente del entorno de invocación.

Esta marca --action_env se puede especificar varias veces. Si se asigna un valor a la misma variable en varias marcas de --action_env, prevalecerá la asignación más reciente.

--experimental_action_listener=label

La opción experimental_action_listener indica a Bazel que use los detalles de la regla action_listener especificada por label para insertar extra_actions en el gráfico de compilación.

--[no]experimental_extra_action_top_level_only

Si esta opción se establece como verdadera, las acciones adicionales especificadas por la opción de línea de comandos --experimental_action_listener solo se programarán para los destinos de nivel superior.

--experimental_extra_action_filter=regex

La opción experimental_extra_action_filter indica a Bazel que filtre el conjunto de destinos para los que se programará extra_actions.

Esta marca solo se aplica en combinación con la marca --experimental_action_listener.

De forma predeterminada, todos los extra_actions en el cierre transitivo de los destinos solicitados para compilar se programan para su ejecución. --experimental_extra_action_filter restringirá la programación a extra_actions cuya etiqueta del propietario coincida con la expresión regular especificada.

En el siguiente ejemplo, se limitará la programación de extra_actions para que solo se aplique a las acciones cuya etiqueta del propietario contenga "/bar/":

% bazel build --experimental_action_listener=//test:al //foo/... \
  --experimental_extra_action_filter=.*/bar/.*

--host_cpu=cpu

Esta opción especifica el nombre de la arquitectura de CPU que se debe usar para compilar herramientas del host.

--android_platforms=platform[,platform]*

Son las plataformas para compilar el deps transitivo de las reglas android_binary (específicamente para las dependencias nativas, como C++). Por ejemplo, si un cc_library aparece en el deps transitivo de una regla android_binary, se compilará una vez para cada plataforma especificada con --android_platforms para la regla android_binary y se incluirá en el resultado final.

Esta marca no tiene un valor predeterminado: se debe definir y usar una plataforma de Android personalizada.

Se crea un archivo .so y se empaqueta en el APK para cada plataforma especificada con --android_platforms. El nombre del archivo .so antepone el prefijo "lib" al nombre de la regla android_binary. Por ejemplo, si el nombre de android_binary es "foo", el archivo es libfoo.so.

--per_file_copt=[+-]regex[,[+-]regex]...@option[,option]...

Cuando está presente, cualquier archivo C++ con una etiqueta o una ruta de ejecución que coincida con una de las expresiones regulares de inclusión y no coincida con ninguna de las expresiones de exclusión se compilará con las opciones proporcionadas. La coincidencia de etiquetas usa la forma canónica de la etiqueta (es decir, //package:label_name).

La ruta de ejecución es la ruta relativa al directorio de tu espacio de trabajo, incluido el nombre base (con la extensión) del archivo C++. También incluye cualquier prefijo dependiente de la plataforma.

Para que coincidan los archivos generados (como los resultados de genrule), Bazel solo puede usar la ruta de ejecución. En este caso, la expresión regular no debe comenzar con "//", ya que no coincide con ninguna ruta de ejecución. Los nombres de paquetes se pueden usar de la siguiente manera: --per_file_copt=base/.*\.pb\.cc@-g0. Esto coincidirá con todos los archivos .pb.cc en un directorio llamado base.

Esta opción se puede usar varias veces.

La opción se aplica independientemente del modo de compilación que se use. Por ejemplo, es posible compilar con --compilation_mode=opt y compilar de forma selectiva algunos archivos con una optimización más potente activada o con la optimización inhabilitada.

Advertencia: Si algunos archivos se compilan de forma selectiva con símbolos de depuración, es posible que estos se quiten durante la vinculación. Esto se puede evitar configurando --strip=never.

Sintaxis: [+-]regex[,[+-]regex]...@option[,option]..., donde regex representa una expresión regular a la que se le puede agregar el prefijo + para identificar patrones de inclusión y - para identificar patrones de exclusión. option representa una opción arbitraria que se pasa al compilador de C++. Si una opción contiene un ,, debe entrecomillarse de la siguiente manera: \,. Las opciones también pueden contener @, ya que solo el primer @ se usa para separar las expresiones regulares de las opciones.

Ejemplo: --per_file_copt=//foo:.*\.cc,-//foo:file\.cc@-O0,-fprofile-arcs agrega las opciones -O0 y -fprofile-arcs a la línea de comandos del compilador de C++ para todos los archivos .cc en //foo/, excepto file.cc.

--dynamic_mode=mode

Determina si los objetos binarios de C++ se vincularán de forma dinámica, lo que interactúa con el atributo linkstatic en las reglas de compilación.

Modos:

• default: Permite que Bazel elija si se vincula de forma dinámica. Consulta linkstatic para obtener más información.
• fully: Vincula todos los objetivos de forma dinámica. Esto acelerará el tiempo de vinculación y reducirá el tamaño de los archivos binarios resultantes.
• off: Vincula todos los destinos en el modo mayormente estático. Si -static se configura en linkopts, los destinos cambiarán a completamente estáticos.

--fission (yes|no|[dbg][,opt][,fastbuild])

Habilita Fission, que escribe información de depuración de C++ en archivos .dwo dedicados en lugar de archivos .o, donde de otro modo se escribiría. Esto reduce sustancialmente el tamaño de entrada a las vinculaciones y puede reducir los tiempos de vinculación.

Cuando se establece en [dbg][,opt][,fastbuild] (por ejemplo, --fission=dbg,fastbuild), Fission se habilita solo para el conjunto especificado de modos de compilación. Esto es útil para la configuración de bazelrc. Cuando se establece en yes, Fission se habilita de forma universal. Cuando se establece en no, Fission se inhabilita de forma universal. La cantidad predeterminada es no.

--force_ignore_dash_static

Si se establece esta marca, se ignoran todas las opciones de -static en los linkopts de los archivos BUILD de las reglas cc_*. Esto solo se diseñó como una solución alternativa para las compilaciones de refuerzo de C++.

--[no]force_pic

Si está habilitado, todas las compilaciones de C++ producen código independiente de la posición ("-fPIC"), las vinculaciones prefieren las bibliotecas prediseñadas PIC a las bibliotecas no PIC y las vinculaciones producen ejecutables independientes de la posición ("-pie"). La opción predeterminada está inhabilitada.

--android_resource_shrinking

Selecciona si se debe realizar la reducción de recursos para las reglas de android_binary. Establece el valor predeterminado para el atributo shrink_resources en las reglas de android_binary. Consulta la documentación de esa regla para obtener más detalles. La configuración predeterminada es desactivada.

--custom_malloc=malloc-library-target

Cuando se especifica, siempre usa la implementación de malloc proporcionada, anulando todos los atributos malloc="target", incluso en aquellos destinos que usan el valor predeterminado (por no especificar ningún malloc).

--crosstool_top=label

Esta opción especifica la ubicación del conjunto de compiladores de crosstool que se usará para toda la compilación de C++ durante una compilación. Bazel buscará un archivo CROSSTOOL en esa ubicación y lo usará para determinar automáticamente la configuración de --compiler.

--host_crosstool_top=label

Si no se especifica, Bazel usa el valor de --crosstool_top para compilar código en la configuración de ejecución, como las herramientas que se ejecutan durante la compilación. El propósito principal de esta marca es habilitar la compilación cruzada.

--apple_crosstool_top=label

Es la herramienta de compilación cruzada que se usa para compilar reglas de C/C++ en el deps transitivo de las reglas objc*, ios* y apple*. Para esos destinos, esta marca anula --crosstool_top.

--compiler=version

Esta opción especifica la versión del compilador de C/C++ (como gcc-4.1.0) que se usará para la compilación de objetos binarios durante la compilación. Si deseas compilar con una herramienta de compilación cruzada personalizada, debes usar un archivo CROSSTOOL en lugar de especificar esta marca.

--android_sdk=label

Obsoleta. No se debe especificar directamente.

Esta opción especifica la cadena de herramientas del SDK y la plataforma de Android, y la biblioteca de tiempo de ejecución de Android que se usarán para compilar cualquier regla relacionada con Android.

El SDK de Android se seleccionará automáticamente si se define una regla android_sdk_repository en el archivo WORKSPACE.

--java_toolchain=label

Es una operación nula. Se mantiene solo por retrocompatibilidad.

--host_java_toolchain=label

Es una operación nula. Se mantiene solo por retrocompatibilidad.

--javabase=(label)

Es una operación nula. Se mantiene solo por retrocompatibilidad.

--host_javabase=label

Es una operación nula. Se mantiene solo por retrocompatibilidad.

Estrategia de ejecución

Estas opciones afectan la forma en que Bazel ejecutará la compilación. No deberían tener ningún efecto significativo en los archivos de salida que genera la compilación. Por lo general, su efecto principal se relaciona con la velocidad de la compilación.

--spawn_strategy=strategy

Esta opción controla dónde y cómo se ejecutan los comandos.

• standalone hace que los comandos se ejecuten como subprocesos locales. Este valor dejó de estar disponible. En su lugar, utiliza local.
• sandboxed hace que los comandos se ejecuten dentro de una zona de pruebas en la máquina local. Esto requiere que todos los archivos de entrada, las dependencias de datos y las herramientas se enumeren como dependencias directas en los atributos srcs, data y tools. Bazel habilita la zona de pruebas local de forma predeterminada en los sistemas que admiten la ejecución en zona de pruebas.
• local hace que los comandos se ejecuten como subprocesos locales.
• worker hace que los comandos se ejecuten con un trabajador persistente, si está disponible.
• docker hace que los comandos se ejecuten dentro de una zona de pruebas de Docker en la máquina local. Esto requiere que Docker esté instalado.
• remote hace que los comandos se ejecuten de forma remota; esto solo está disponible si se configuró un ejecutor remoto por separado.

--strategy mnemonic=strategy

Esta opción controla dónde y cómo se ejecutan los comandos, y anula --spawn_strategy (y --genrule_strategy con el mnemónico Genrule) para cada mnemónico. Consulta --spawn_strategy para conocer las estrategias admitidas y sus efectos.

--strategy_regexp=<filter,filter,...>=<strategy>

Esta opción especifica qué estrategia se debe usar para ejecutar comandos que tienen descripciones que coinciden con un determinado regex_filter. Consulta --per_file_copt para obtener detalles sobre la coincidencia de regex_filter. Consulta --spawn_strategy para conocer las estrategias admitidas y sus efectos.

Se usa el último regex_filter que coincide con la descripción. Esta opción anula otras marcas para especificar la estrategia.

• Ejemplo: --strategy_regexp=//foo.*\\.cc,-//foo/bar=local significa ejecutar acciones con la estrategia local si sus descripciones coinciden con //foo.*.cc, pero no con //foo/bar.
• Ejemplo: --strategy_regexp='Compiling.*/bar=local' --strategy_regexp=Compiling=sandboxed ejecuta "Compiling //foo/bar/baz" con la estrategia sandboxed, pero invertir el orden lo ejecuta con local.
• Ejemplo: --strategy_regexp='Compiling.*/bar=local,sandboxed' ejecuta "Compiling //foo/bar/baz" con la estrategia local y recurre a sandboxed si falla.

--genrule_strategy=strategy

Esta es una abreviatura obsoleta de --strategy=Genrule=strategy.

--jobs=n (-j)

Esta opción, que toma un argumento de número entero, especifica un límite en la cantidad de trabajos que se deben ejecutar de forma simultánea durante la fase de ejecución de la compilación.

--progress_report_interval=n

Bazel imprime periódicamente un informe de progreso sobre los trabajos que aún no finalizaron (como las pruebas de larga duración). Esta opción establece la frecuencia de informes. El progreso se imprimirá cada n segundos.

El valor predeterminado es 0, lo que significa que se usa un algoritmo incremental: el primer informe se imprimirá después de 10 segundos, luego de 30 segundos y, después de eso, el progreso se informará una vez por minuto.

Cuando bazel usa el control del cursor, como se especifica en --curses, el progreso se informa cada segundo.

--local_{ram,cpu}_resources resources or resource expression

Estas opciones especifican la cantidad de recursos locales (RAM en MB y cantidad de núcleos lógicos de CPU) que Bazel puede tener en cuenta cuando programa actividades de compilación y prueba para que se ejecuten de forma local. Toman un número entero o una palabra clave (HOST_RAM o HOST_CPUS) seguida de forma opcional por [-|*float] (por ejemplo, --local_cpu_resources=2, --local_ram_resources=HOST_RAM*.5, --local_cpu_resources=HOST_CPUS-1). Las marcas son independientes; se puede establecer una o ambas. De forma predeterminada, Bazel estima la cantidad de RAM y la cantidad de núcleos de CPU directamente a partir de la configuración del sistema local.

--[no]build_runfile_links

Esta opción, que está habilitada de forma predeterminada, especifica si los vínculos simbólicos de los archivos ejecutables para pruebas y archivos binarios se deben compilar en el directorio de salida. Usar --nobuild_runfile_links puede ser útil para validar si todos los destinos se compilan sin incurrir en la sobrecarga de compilar los árboles de runfiles.

Cuando se ejecutan pruebas (o aplicaciones), sus dependencias de datos de tiempo de ejecución se recopilan en un solo lugar. Dentro del árbol de salida de Bazel, este árbol de "runfiles" suele tener su raíz como hermano del archivo binario o la prueba correspondientes. Durante la ejecución de la prueba, se puede acceder a los archivos ejecutables con rutas de acceso del formato $TEST_SRCDIR/canonical_repo_name/packagename/filename. El árbol de runfiles garantiza que las pruebas tengan acceso a todos los archivos de los que tienen una dependencia declarada y a nada más. De forma predeterminada, el árbol de archivos ejecutables se implementa construyendo un conjunto de vínculos simbólicos a los archivos requeridos. A medida que crece el conjunto de vínculos, también lo hace el costo de esta operación, y para algunas compilaciones grandes, puede contribuir de manera significativa al tiempo de compilación general, en particular porque cada prueba (o aplicación) individual requiere su propio árbol de archivos ejecutables.

--[no]build_runfile_manifests

Esta opción, que está habilitada de forma predeterminada, especifica si los manifiestos de archivos ejecutables deben escribirse en el árbol de salida. Inhabilitarlo implica --nobuild_runfile_links.

Se puede inhabilitar cuando se ejecutan pruebas de forma remota, ya que los árboles de archivos ejecutables se crearán de forma remota a partir de manifiestos en memoria.

--[no]discard_analysis_cache

Cuando esta opción está habilitada, Bazel descarta la caché de análisis justo antes de que comience la ejecución, lo que libera memoria adicional (alrededor del 10%) para la fase de ejecución. La desventaja es que las compilaciones incrementales posteriores serán más lentas. Consulta también el modo de ahorro de memoria.

--[no]keep_going (-k)

Al igual que en GNU Make, la fase de ejecución de una compilación se detiene cuando se encuentra el primer error. A veces, es útil intentar compilar la mayor cantidad posible, incluso ante errores. Esta opción habilita ese comportamiento y, cuando se especifica, la compilación intentará compilar cada destino cuyos requisitos previos se hayan compilado correctamente, pero ignorará los errores.

Si bien esta opción suele asociarse con la fase de ejecución de una compilación, también afecta la fase de análisis: si se especifican varios destinos en un comando de compilación, pero solo algunos de ellos se pueden analizar correctamente, la compilación se detendrá con un error, a menos que se especifique --keep_going, en cuyo caso la compilación continuará con la fase de ejecución, pero solo para los destinos que se analizaron correctamente.

--[no]use_ijars

Esta opción cambia la forma en que Bazel compila los destinos java_library. En lugar de usar el resultado de un java_library para compilar destinos java_library dependientes, Bazel creará archivos .jar de interfaz que solo contengan las firmas de los miembros no privados (métodos y campos de acceso públicos, protegidos y predeterminados [de paquete]) y usará los archivos .jar de interfaz para compilar los destinos dependientes. Esto permite evitar la recompilación cuando solo se realizan cambios en los cuerpos de los métodos o en los miembros privados de una clase.

--[no]interface_shared_objects

Esta opción habilita los objetos compartidos de interfaz, lo que hace que los archivos binarios y otras bibliotecas compartidas dependan de la interfaz de un objeto compartido, en lugar de su implementación. Cuando solo cambia la implementación, Bazel puede evitar volver a compilar innecesariamente los destinos que dependen de la biblioteca compartida modificada.

Selección de salida

Estas opciones determinan qué se compilará o probará.

--[no]build

Esta opción hace que se produzca la fase de ejecución de la compilación. Está activada de forma predeterminada. Cuando está desactivada, se omite la fase de ejecución y solo se realizan las dos primeras fases: carga y análisis.

Esta opción puede ser útil para validar archivos BUILD y detectar errores en las entradas, sin compilar nada.

--[no]build_tests_only

Si se especifica, Bazel compilará solo lo necesario para ejecutar las reglas *_test y test_suite que no se filtraron debido a su tamaño, tiempo de espera, etiqueta o lenguaje. Si se especifica, Bazel ignorará otros destinos especificados en la línea de comandos. De forma predeterminada, esta opción está inhabilitada y Bazel compilará todo lo solicitado, incluidas las reglas *_test y test_suite que se filtran de las pruebas. Esto es útil porque es posible que la ejecución de bazel test --build_tests_only foo/... no detecte todas las interrupciones de compilación en el árbol foo.

--[no]check_up_to_date

Esta opción hace que Bazel no realice una compilación, sino que solo verifique si todos los destinos especificados están actualizados. Si es así, la compilación se completa correctamente, como de costumbre. Sin embargo, si algún archivo está desactualizado, en lugar de compilarse, se informa un error y falla la compilación. Esta opción puede ser útil para determinar si se realizó una compilación más recientemente que una edición de la fuente (por ejemplo, para las verificaciones previas al envío) sin incurrir en el costo de una compilación.

Consulta también --check_tests_up_to_date.

--[no]compile_one_dependency

Compila una sola dependencia de los archivos de argumentos. Esto es útil para verificar la sintaxis de los archivos fuente en los IDE, por ejemplo, recompilando un solo destino que depende del archivo fuente para detectar errores lo antes posible en el ciclo de edición, compilación y prueba. Este argumento afecta la forma en que se interpretan todos los argumentos que no son marcas: cada argumento debe ser una etiqueta de destino de archivo o un nombre de archivo simple relativo al directorio de trabajo actual, y se compila una regla que depende de cada nombre de archivo fuente. En el caso de las fuentes de C++ y Java, se eligen de forma preferencial las reglas que se encuentran en el mismo espacio de idioma. En el caso de varias reglas con la misma preferencia, se elige la que aparece primero en el archivo BUILD. Un patrón de destino con nombre explícito que no hace referencia a un archivo fuente genera un error.

--save_temps

La opción --save_temps hace que se guarden los resultados temporales del compilador. Estos incluyen archivos .s (código de ensamblador), .i (C preprocesado) y .ii (C++ preprocesado). Estos resultados suelen ser útiles para la depuración. Las versiones temporales solo se generarán para el conjunto de destinos especificados en la línea de comandos.

Actualmente, la marca --save_temps solo funciona para las reglas cc_*.

Para asegurarte de que Bazel imprima la ubicación de los archivos de salida adicionales, verifica que el parámetro de configuración --show_result n sea lo suficientemente alto.

--build_tag_filters=tag[,tag]*

Si se especifica, Bazel solo compilará los destinos que tengan al menos una etiqueta obligatoria (si se especifica alguna) y que no tengan ninguna etiqueta excluida. El filtro de etiquetas de compilación se especifica como una lista de palabras clave de etiquetas delimitadas por comas, precedidas opcionalmente por el signo "-" que se usa para indicar las etiquetas excluidas. Las etiquetas obligatorias también pueden tener un signo “+” delante.

Cuando se ejecutan pruebas, Bazel ignora --build_tag_filters para los destinos de prueba, que se compilan y ejecutan incluso si no coinciden con este filtro. Para evitar compilarlos, filtra los destinos de prueba con --test_tag_filters o exclúyelos de forma explícita.

--test_size_filters=size[,size]*

Si se especifica, Bazel solo probará (o compilará si también se especifica --build_tests_only) los destinos de prueba con el tamaño determinado. El filtro de tamaño de prueba se especifica como una lista delimitada por comas de valores de tamaño de prueba permitidos (pequeño, mediano, grande o enorme), precedida opcionalmente por el signo "-" que se usa para indicar los tamaños de prueba excluidos. Por ejemplo:

  % bazel test --test_size_filters=small,medium //foo:all

y

  % bazel test --test_size_filters=-large,-enormous //foo:all

solo probará las pruebas pequeñas y medianas dentro de //foo.

De forma predeterminada, no se aplica el filtrado por tamaño de la prueba.

--test_timeout_filters=timeout[,timeout]*

Si se especifica, Bazel probará (o compilará si también se especifica --build_tests_only) solo los destinos de prueba con el tiempo de espera determinado. El filtro de tiempo de espera de la prueba se especifica como una lista delimitada por comas de los valores de tiempo de espera de la prueba permitidos (corto, moderado, largo o eterno), precedidos opcionalmente por el signo "-" que se usa para indicar los tiempos de espera de la prueba excluidos. Consulta --test_size_filters para ver ejemplos de sintaxis.

De forma predeterminada, no se aplica el filtrado de tiempo de espera de la prueba.

--test_tag_filters=tag[,tag]*

Si se especifica, Bazel probará (o compilará si también se especifica --build_tests_only) solo los destinos de prueba que tengan al menos una etiqueta obligatoria (si se especifica alguna) y no tengan ninguna etiqueta excluida. El filtro de etiquetas de prueba se especifica como una lista de palabras clave de etiquetas delimitadas por comas, precedidas opcionalmente por el signo "-" que se usa para indicar las etiquetas excluidas. Las etiquetas obligatorias también pueden tener un signo “+” delante.

Por ejemplo:

  % bazel test --test_tag_filters=performance,stress,-flaky //myproject:all

probará los destinos etiquetados con performance o stress, pero no etiquetados con flaky.

De forma predeterminada, no se aplica el filtrado de etiquetas de prueba. Ten en cuenta que también puedes filtrar por las etiquetas size y local de la prueba de esta manera.

--test_lang_filters=string[,string]*

Especifica una lista de cadenas separadas por comas que hacen referencia a los nombres de las clases de reglas de prueba. Para hacer referencia a la clase de regla foo_test, usa la cadena "foo". Bazel probará (o compilará si también se especifica --build_tests_only) solo los destinos de las clases de reglas a las que se hace referencia. Para excluir esos destinos, usa la cadena "-foo". Por ejemplo:

  % bazel test --test_lang_filters=foo,bar //baz/...

solo probará los destinos que sean instancias de foo_test o bar_test en //baz/..., mientras que

  % bazel test --test_lang_filters=-foo,-bar //baz/...

probará todos los destinos en //baz/..., excepto las instancias foo_test y bar_test.

--test_filter=filter-expression

Especifica un filtro que el ejecutor de pruebas puede usar para elegir un subconjunto de pruebas para ejecutar. Se compilan todos los destinos especificados en la invocación, pero, según la expresión, solo se pueden ejecutar algunos de ellos. En algunos casos, solo se ejecutan ciertos métodos de prueba.

La interpretación particular de filter-expression depende del framework de pruebas responsable de ejecutar la prueba. Puede ser un comodín, una subcadena o una expresión regular. --test_filter es una forma conveniente de pasar diferentes argumentos de filtro de --test_arg, pero no todos los frameworks lo admiten.

Verbosidad

Estas opciones controlan la verbosidad del resultado de Bazel, ya sea en la terminal o en archivos de registro adicionales.

--explain=logfile

Esta opción, que requiere un argumento de nombre de archivo, hace que el verificador de dependencias en la fase de ejecución de bazel build explique, para cada paso de compilación, por qué se ejecuta o que está actualizado. La explicación se escribe en logfile.

Si se producen recompilaciones inesperadas, esta opción puede ayudarte a comprender el motivo. Agrégalo a tu .bazelrc para que se registren todas las compilaciones posteriores y, luego, inspecciona el registro cuando veas que se ejecuta un paso de ejecución de forma inesperada. Esta opción puede generar una pequeña penalización en el rendimiento, por lo que te recomendamos que la quites cuando ya no la necesites.

--verbose_explanations

Esta opción aumenta la verbosidad de las explicaciones generadas cuando se habilita la opción --explain.

En particular, si las explicaciones detalladas están habilitadas y se vuelve a compilar un archivo de salida porque cambió el comando que se usó para compilarlo, la salida en el archivo de explicación incluirá los detalles completos del nuevo comando (al menos para la mayoría de los comandos).

Usar esta opción puede aumentar significativamente la longitud del archivo de explicación generado y la penalización de rendimiento por usar --explain.

Si --explain no está habilitado, --verbose_explanations no tiene ningún efecto.

--profile=file

Esta opción, que toma un argumento de nombre de archivo, hace que Bazel escriba datos de generación de perfiles en un archivo. Luego, los datos se pueden analizar o analizar con el comando bazel analyze-profile. El perfil de compilación puede ser útil para comprender en qué parte del comando build de Bazel se invierte el tiempo.

--[no]show_loading_progress

Esta opción hace que Bazel genere mensajes de progreso de carga de paquetes. Si está inhabilitada, no se mostrarán los mensajes.

--[no]show_progress

Esta opción hace que se muestren mensajes de progreso. Está activada de forma predeterminada. Cuando se inhabilita, se suprimen los mensajes de progreso.

--show_progress_rate_limit=n

Esta opción hace que Bazel muestre, como máximo, un mensaje de progreso cada n segundos, donde n es un número real. El valor predeterminado para esta opción es 0.02, lo que significa que Bazel limitará los mensajes de progreso a uno cada 0.02 segundos.

--show_result=n

Esta opción controla la impresión de la información del resultado al final de un comando bazel build. De forma predeterminada, si se especificó un solo destino de compilación, Bazel imprime un mensaje que indica si el destino se actualizó correctamente o no y, si es así, la lista de archivos de salida que creó el destino. Si se especificaron varios objetivos, no se muestra la información del resultado.

Si bien la información del resultado puede ser útil para las compilaciones de un solo destino o de algunos destinos, para las compilaciones grandes (como un árbol de proyectos de nivel superior completo), esta información puede ser abrumadora y distraer. Esta opción permite controlarla. --show_result toma un argumento entero, que es la cantidad máxima de objetivos para los que se debe imprimir la información completa del resultado. De forma predeterminada, el valor es 1. Por encima de este umbral, no se muestra información de los resultados para los objetivos individuales. Por lo tanto, el cero hace que la información del resultado se suprima siempre, y un valor muy grande hace que el resultado se imprima siempre.

Los usuarios pueden elegir un valor intermedio si alternan con frecuencia entre la compilación de un grupo pequeño de destinos (por ejemplo, durante el ciclo de compilación, edición y prueba) y un grupo grande de destinos (por ejemplo, cuando establecen un nuevo espacio de trabajo o ejecutan pruebas de regresión). En el primer caso, la información del resultado es muy útil, mientras que en el segundo lo es menos. Al igual que con todas las opciones, esto se puede especificar de forma implícita a través del archivo .bazelrc.

Los archivos se imprimen de manera que sea fácil copiar y pegar el nombre de archivo en la shell para ejecutar los ejecutables compilados. Los scripts que controlan una compilación pueden analizar fácilmente los mensajes "actualizado" o "falló" de cada destino.

--sandbox_debug

Esta opción hace que Bazel imprima información de depuración adicional cuando se usa el aislamiento de procesos para la ejecución de acciones. Esta opción también conserva los directorios de zona de pruebas, de modo que se puedan examinar los archivos visibles para las acciones durante la ejecución.

--subcommands (-s)

Esta opción hace que la fase de ejecución de Bazel imprima la línea de comandos completa de cada comando antes de ejecutarlo.

  >>>>> # //examples/cpp:hello-world [action 'Linking examples/cpp/hello-world']
  (cd /home/johndoe/.cache/bazel/_bazel_johndoe/4c084335afceb392cfbe7c31afee3a9f/bazel && \
    exec env - \
    /usr/bin/gcc -o bazel-out/local-fastbuild/bin/examples/cpp/hello-world -B/usr/bin/ -Wl,-z,relro,-z,now -no-canonical-prefixes -pass-exit-codes -Wl,-S -Wl,@bazel-out/local_linux-fastbuild/bin/examples/cpp/hello-world-2.params)

Cuando es posible, los comandos se imprimen en una sintaxis compatible con Bourne Shell, de modo que se puedan copiar y pegar fácilmente en un símbolo del sistema de shell. (Los paréntesis que rodean el comando se proporcionan para proteger tu shell de las llamadas cd y exec. Asegúrate de copiarlos). Sin embargo, algunos comandos se implementan de forma interna en Bazel, como la creación de árboles de vínculos simbólicos. En estos casos, no se muestra ninguna línea de comandos.

--subcommands=pretty_print se puede pasar para imprimir los argumentos del comando como una lista en lugar de una sola línea. Esto puede ayudar a que las líneas de comandos largas sean más legibles.

Consulta también --verbose_failures a continuación.

Para registrar los subcomandos en un archivo con un formato compatible con las herramientas, consulta --execution_log_json_file y --execution_log_binary_file.

--verbose_failures

Esta opción hace que la fase de ejecución de Bazel imprima la línea de comandos completa para los comandos que fallaron. Esto puede ser invaluable para depurar una compilación con errores.

Los comandos con errores se imprimen en una sintaxis compatible con Bourne Shell, adecuada para copiar y pegar en un símbolo del sistema.

Estado del espacio de trabajo

Usa estas opciones para "marcar" los archivos binarios compilados con Bazel, es decir, para incorporar información adicional en ellos, como la revisión del control de código fuente o cualquier otra información relacionada con el espacio de trabajo. Puedes usar este mecanismo con reglas que admitan el atributo stamp, como genrule, cc_binary y muchos más.

--workspace_status_command=program

Esta marca te permite especificar un archivo binario que Bazel ejecuta antes de cada compilación. El programa puede informar sobre el estado del espacio de trabajo, como la revisión actual del control de código fuente.

El valor de la marca debe ser una ruta de acceso a un programa nativo. En Linux o macOS, puede ser cualquier ejecutable. En Windows, debe ser un archivo binario nativo, por lo general, un archivo ".exe", ".bat" o ".cmd".

El programa debe imprimir cero o más pares clave/valor en la salida estándar, una entrada en cada línea y, luego, salir con cero (de lo contrario, la compilación fallará). Los nombres de las claves pueden ser cualquiera, pero solo pueden usar letras mayúsculas y guiones bajos. El primer espacio después del nombre de la clave la separa del valor. El valor es el resto de la línea (incluidos los espacios en blanco adicionales). Ni la clave ni el valor pueden abarcar varias líneas. Las claves no deben duplicarse.

Bazel divide las claves en dos buckets: "estable" y "volátil". (Los nombres "estable" y "volátil" son un poco contradictorios, así que no te preocupes demasiado por ellos).

Luego, Bazel escribe los pares clave-valor en dos archivos:

• bazel-out/stable-status.txt contiene todas las claves y los valores en los que el nombre de la clave comienza con STABLE_.
• bazel-out/volatile-status.txt contiene el resto de las claves y sus valores.

El contrato es el siguiente:

• Los valores de las claves "estables" deben cambiar con poca frecuencia, si es posible. Si cambia el contenido de bazel-out/stable-status.txt, Bazel invalida las acciones que dependen de él. En otras palabras, si cambia el valor de una clave estable, Bazel volverá a ejecutar las acciones con marca de tiempo. Por lo tanto, el estado estable no debe contener elementos como marcas de tiempo, ya que cambian todo el tiempo y harían que Bazel volviera a ejecutar acciones con marcas de tiempo en cada compilación.

  Bazel siempre genera las siguientes claves estables:

  • BUILD_EMBED_LABEL: valor de --embed_label
  • BUILD_HOST: Es el nombre de la máquina host en la que se ejecuta Bazel.
  • BUILD_USER: Es el nombre del usuario con el que se ejecuta Bazel.

• Los valores de las claves "volátiles" pueden cambiar con frecuencia. Bazel espera que cambien todo el tiempo, como lo hacen las marcas de tiempo, y actualiza debidamente el archivo bazel-out/volatile-status.txt. Sin embargo, para evitar volver a ejecutar acciones con marcas todo el tiempo, Bazel simula que el archivo volátil nunca cambia. En otras palabras, si el archivo de estado volátil es el único cuyo contenido cambió, Bazel no invalidará las acciones que dependen de él. Si cambiaron otras entradas de las acciones, Bazel volverá a ejecutar esa acción, y la acción verá el estado volátil actualizado, pero el cambio de estado volátil por sí solo no invalidará la acción.

  Bazel siempre genera las siguientes claves volátiles:

  • BUILD_TIMESTAMP: Hora de la compilación en segundos desde la época de Unix (el valor de System.currentTimeMillis() dividido por mil)
  • FORMATTED_DATE: Hora de la compilación. Se muestra en formato yyyy MMM d HH mm ss EEE(por ejemplo, 2023 Jun 2 01 44 29 Fri) en UTC.

En Linux o macOS, puedes pasar --workspace_status_command=/bin/true para inhabilitar la recuperación del estado del espacio de trabajo, ya que true no hace nada, se completa correctamente (sale con cero) y no imprime ningún resultado. En Windows, puedes pasar la ruta de acceso de true.exe de MSYS para obtener el mismo efecto.

Si el comando de estado del espacio de trabajo falla (sale con un valor distinto de cero) por algún motivo, la compilación fallará.

Programa de ejemplo en Linux con Git:

#!/bin/bash
echo "CURRENT_TIME $(date +%s)"
echo "RANDOM_HASH $(cat /proc/sys/kernel/random/uuid)"
echo "STABLE_GIT_COMMIT $(git rev-parse HEAD)"
echo "STABLE_USER_NAME $USER"

Pasa la ruta de acceso de este programa con --workspace_status_command, y el archivo de estado estable incluirá las líneas STABLE, mientras que el archivo de estado volátil incluirá el resto de las líneas.

--[no]stamp

Esta opción, junto con el atributo de regla stamp, controla si se debe incorporar información de compilación en los archivos binarios.

El estampado se puede habilitar o inhabilitar de forma explícita por regla con el atributo stamp. Consulta la Enciclopedia de compilaciones para obtener más detalles. Cuando una regla establece stamp = -1 (el valor predeterminado para las reglas de *_binary), esta opción determina si se habilita el sellado.

Bazel nunca estampa los archivos binarios que se compilan para la configuración de ejecución, independientemente de esta opción o el atributo stamp. En el caso de las reglas que establecen stamp = 0 (el valor predeterminado para las reglas de *_test), la marca de tiempo se inhabilita independientemente de --[no]stamp. Si se especifica --stamp, no se obliga a recompilar los destinos si sus dependencias no cambiaron.

En general, establecer --nostamp es conveniente para el rendimiento de la compilación, ya que reduce la volatilidad de la entrada y maximiza el almacenamiento en caché de la compilación.

Plataforma

Usa estas opciones para controlar las plataformas de host y de destino que configuran el funcionamiento de las compilaciones, y para controlar qué plataformas de ejecución y cadenas de herramientas están disponibles para las reglas de Bazel.

Consulta la información general sobre plataformas y cadenas de herramientas.

--platforms=labels

Son las etiquetas de las reglas de la plataforma que describen las plataformas objetivo para el comando actual.

--host_platform=label

Es la etiqueta de una regla de plataforma que describe el sistema host.

--extra_execution_platforms=labels

Son las plataformas disponibles como plataformas de ejecución para ejecutar acciones. Las plataformas se pueden especificar por objetivo exacto o como un patrón de objetivo. Estas plataformas se considerarán antes de las que se declaren en los archivos MODULE.bazel con register_execution_platforms(). Esta opción acepta una lista de plataformas separadas por comas en orden de prioridad. Si la marca se pasa varias veces, la más reciente anula las anteriores.

--extra_toolchains=labels

Son las reglas de la cadena de herramientas que se deben tener en cuenta durante la resolución de la cadena de herramientas. Las cadenas de herramientas se pueden especificar por destino exacto o como un patrón de destino. Estas cadenas de herramientas se considerarán antes de las que se declaren en los archivos MODULE.bazel con register_toolchains().

--toolchain_resolution_debug=regex

Imprime información de depuración mientras busca cadenas de herramientas si el tipo de cadena de herramientas coincide con la regex. Si hay varias expresiones regulares, sepáralas con comas. La expresión regular se puede negar con un - al principio. Esto puede ayudar a los desarrolladores de reglas de Bazel o Starlark con errores de depuración debido a cadenas de herramientas faltantes.

Varios

--flag_alias=alias_name=target_path

Es una marca de conveniencia que se usa para vincular parámetros de configuración de compilación de Starlark más largos a un nombre más corto. Para obtener más detalles, consulta Configuraciones de Starlark.

--symlink_prefix=string

Cambia el prefijo de los symlinks de conveniencia generados. El valor predeterminado para el prefijo de symlink es bazel-, que creará los symlinks bazel-bin, bazel-testlogs y bazel-genfiles.

Si no se pueden crear los vínculos simbólicos por algún motivo, se emite una advertencia, pero la compilación se sigue considerando exitosa. En particular, esto te permite compilar en un directorio de solo lectura o en uno en el que no tienes permiso para escribir. Las rutas de acceso que se impriman en los mensajes informativos al final de una compilación solo usarán la forma abreviada relativa al vínculo simbólico si los vínculos simbólicos apuntan a la ubicación esperada. En otras palabras, puedes confiar en la exactitud de esas rutas de acceso, incluso si no puedes confiar en que se creen los vínculos simbólicos.

Estos son algunos valores comunes de esta opción:

• Suprimir la creación de vínculos simbólicos: --symlink_prefix=/ hará que Bazel no cree ni actualice ningún vínculo simbólico, incluidos los vínculos simbólicos bazel-out y bazel-<workspace>. Usa esta opción para suprimir por completo la creación de vínculos simbólicos.

• Reduce el desorden: --symlink_prefix=.bazel/ hará que Bazel cree vínculos simbólicos llamados bin (etc.) dentro de un directorio oculto .bazel.

--platform_suffix=string

Agrega un sufijo al nombre corto de la configuración, que se usa para determinar el directorio de salida. Si configuras esta opción con diferentes valores, los archivos se colocarán en diferentes directorios, por ejemplo, para mejorar las tasas de aciertos de caché en las compilaciones que, de otro modo, sobrescribirían los archivos de salida entre sí, o para conservar los archivos de salida para comparaciones.

--default_visibility=(private|public)

Es una marca temporal para probar los cambios en la visibilidad predeterminada de Bazel. No está diseñado para uso general, pero se documenta para mayor claridad.

--starlark_cpu_profile=_file_

Esta marca, cuyo valor es el nombre de un archivo, hace que Bazel recopile estadísticas sobre el uso de CPU de todos los subprocesos de Starlark y escriba el perfil, en formato pprof, en el archivo con nombre.

Usa esta opción para identificar las funciones de Starlark que ralentizan la carga y el análisis debido a un exceso de procesamiento. Por ejemplo:

$ bazel build --nobuild --starlark_cpu_profile=/tmp/pprof.gz my/project/...
$ pprof /tmp/pprof.gz
(pprof) top
Type: CPU
Time: Feb 6, 2020 at 12:06pm (PST)
Duration: 5.26s, Total samples = 3.34s (63.55%)
Showing nodes accounting for 3.34s, 100% of 3.34s total
      flat  flat%   sum%        cum   cum%
     1.86s 55.69% 55.69%      1.86s 55.69%  sort_source_files
     1.02s 30.54% 86.23%      1.02s 30.54%  expand_all_combinations
     0.44s 13.17% 99.40%      0.44s 13.17%  range
     0.02s   0.6%   100%      3.34s   100%  sorted
         0     0%   100%      1.38s 41.32%  my/project/main/BUILD
         0     0%   100%      1.96s 58.68%  my/project/library.bzl
         0     0%   100%      3.34s   100%  main

Para obtener diferentes vistas de los mismos datos, prueba los comandos pprof svg, web y list.

Usa Bazel para los lanzamientos

Bazel es utilizado tanto por los ingenieros de software durante el ciclo de desarrollo como por los ingenieros de versiones cuando preparan los archivos binarios para la implementación en producción. En esta sección, se proporciona una lista de sugerencias para los ingenieros de versiones que usan Bazel.

Opciones significativas

Cuando se usa Bazel para las compilaciones de lanzamiento, surgen los mismos problemas que con otros lenguajes de secuencias de comandos que realizan una compilación. Para obtener más detalles, consulta Cómo llamar a Bazel desde secuencias de comandos. En particular, se recomiendan las siguientes opciones:

• --bazelrc=/dev/null
• --nokeep_state_after_build

Estas opciones también son importantes:

• --package_path
• --symlink_prefix: Para administrar compilaciones para múltiples configuraciones, puede ser conveniente distinguir cada compilación con un identificador distinto, como "64bit" vs. "32bit". Esta opción diferencia los vínculos simbólicos bazel-bin (etc.).

Cómo ejecutar pruebas

Para compilar y ejecutar pruebas con Bazel, escribe bazel test seguido del nombre de los destinos de prueba.

De forma predeterminada, este comando realiza actividades simultáneas de compilación y prueba, ya que compila todos los destinos especificados (incluidos los destinos que no son de prueba especificados en la línea de comandos) y prueba los destinos *_test y test_suite en cuanto se compilan sus requisitos previos, lo que significa que la ejecución de la prueba se intercala con la compilación. Por lo general, esto genera mejoras significativas en la velocidad.

Opciones para bazel test

--cache_test_results=(yes|no|auto) (-t)

Si esta opción se configura como "auto" (el valor predeterminado), Bazel solo volverá a ejecutar una prueba si se cumple alguna de las siguientes condiciones:

• Bazel detecta cambios en la prueba o sus dependencias.
• La prueba se marca como external.
• Se solicitaron varias ejecuciones de prueba con --runs_per_test
• Se produjo un error en la prueba.

Si es "no", todas las pruebas se ejecutarán de forma incondicional.

Si la respuesta es "sí", el comportamiento del almacenamiento en caché será el mismo que el automático, excepto que puede almacenar en caché las fallas de las pruebas y las ejecuciones de pruebas con --runs_per_test.

Los usuarios que habilitaron esta opción de forma predeterminada en su archivo .bazelrc pueden encontrar las abreviaturas -t (activado) o -t- (desactivado) convenientes para anular el valor predeterminado en una ejecución en particular.

--check_tests_up_to_date

Esta opción le indica a Bazel que no ejecute las pruebas, sino que solo verifique y registre los resultados de las pruebas almacenados en caché. Si hay pruebas que no se compilaron ni ejecutaron anteriormente, o cuyos resultados están desactualizados (por ejemplo, porque cambió el código fuente o las opciones de compilación), Bazel mostrará un mensaje de error ("test result is not up-to-date"), registrará el estado de la prueba como "NO STATUS" (en rojo, si está habilitada la salida de color) y mostrará un código de salida distinto de cero.

Esta opción también implica el comportamiento de --check_up_to_date.

Esta opción puede ser útil para las verificaciones previas al envío.

--test_verbose_timeout_warnings

Esta opción le indica a Bazel que advierta explícitamente al usuario si el tiempo de espera de una prueba es significativamente más largo que el tiempo de ejecución real de la prueba. Si bien el tiempo de espera de una prueba debe configurarse de manera que no sea inestable, una prueba que tenga un tiempo de espera demasiado generoso puede ocultar problemas reales que surjan de forma inesperada.

Por ejemplo, una prueba que normalmente se ejecuta en uno o dos minutos no debería tener un tiempo de espera de ETERNAL o LONG, ya que son demasiado generosos.

Esta opción es útil para ayudar a los usuarios a decidir un buen valor de tiempo de espera o verificar los valores de tiempo de espera existentes.

--[no]test_keep_going

De forma predeterminada, todas las pruebas se ejecutan hasta completarse. Sin embargo, si esta marca está inhabilitada, la compilación se anula en cualquier prueba que no se apruebe. No se ejecutan los pasos de compilación ni las invocaciones de prueba posteriores, y se cancelan las invocaciones en curso. No especifiques --notest_keep_going y --keep_going.

--flaky_test_attempts=attempts

Esta opción especifica la cantidad máxima de veces que se debe intentar una prueba si falla por algún motivo. En el resumen de la prueba, se indica como FLAKY una prueba que falla inicialmente, pero que finalmente se realiza con éxito. Sin embargo, se considera que se aprobó cuando se trata de identificar el código de salida de Bazel o la cantidad total de pruebas aprobadas. Las pruebas que fallan en todos los intentos permitidos se consideran fallidas.

De forma predeterminada (cuando no se especifica esta opción o cuando se establece en el valor predeterminado), solo se permite un intento para las pruebas normales y 3 para las reglas de prueba con el atributo flaky establecido. Puedes especificar un valor entero para anular el límite máximo de intentos de prueba. Bazel permite un máximo de 10 intentos de prueba para evitar el abuso del sistema.

--runs_per_test=[regex@]number

Esta opción especifica la cantidad de veces que se debe ejecutar cada prueba. Todas las ejecuciones de pruebas se tratan como pruebas independientes (la funcionalidad de resguardo se aplicará a cada una de ellas de forma independiente).

El estado de un destino con ejecuciones fallidas depende del valor de la marca --runs_per_test_detects_flakes:

• Si está ausente, cualquier ejecución fallida provocará que falle toda la prueba.
• Si está presente y dos ejecuciones del mismo fragmento devuelven PASS y FAIL, la prueba recibirá el estado de inestable (a menos que otras ejecuciones con errores hagan que falle).

Si se especifica un solo número, todas las pruebas se ejecutarán esa cantidad de veces. Como alternativa, se puede especificar una expresión regular con la sintaxis regex@number. Esto limita el efecto de --runs_per_test a los objetivos que coinciden con la expresión regular (--runs_per_test=^//pizza:.*@4 ejecuta todas las pruebas en //pizza/ 4 veces). Esta forma de --runs_per_test se puede especificar más de una vez.

--[no]runs_per_test_detects_flakes

Si se especifica esta opción (de forma predeterminada, no se especifica), Bazel detectará las particiones de pruebas no confiables a través de --runs_per_test. Si falla una o más ejecuciones para un solo fragmento y se aprueba una o más ejecuciones para el mismo fragmento, el destino se considerará no confiable con la marca. Si no se especifica, el destino informará un estado de falla.

--test_summary=output_style

Especifica cómo se debe mostrar el resumen de los resultados de la prueba.

• short imprime los resultados de cada prueba junto con el nombre del archivo que contiene el resultado de la prueba si esta falló. Este es el valor predeterminado.
• terse como short, pero aún más corto: solo imprime información sobre las pruebas que no se aprobaron.
• detailed imprime cada caso de prueba individual que falló, no solo cada prueba. Se omiten los nombres de los archivos de salida de la prueba.
• none no imprime el resumen de la prueba.

--test_output=output_style

Especifica cómo se debe mostrar el resultado de la prueba:

• summary muestra un resumen de si cada prueba se aprobó o falló. También muestra el nombre del archivo de registro de salida para las pruebas fallidas. El resumen se imprimirá al final de la compilación (durante la compilación, solo se verán mensajes de progreso simples cuando las pruebas comiencen, se aprueben o fallen). Este es el comportamiento predeterminado.
• errors envía la salida combinada de stdout/stderr de las pruebas fallidas solo a stdout inmediatamente después de que se completa la prueba, lo que garantiza que la salida de las pruebas simultáneas no se intercale entre sí. Imprime un resumen de la compilación, como se muestra en el resultado del resumen anterior.
• all es similar a errors, pero imprime el resultado de todas las pruebas, incluidas las que se aprobaron.
• streamed transmite la salida stdout/stderr de cada prueba en tiempo real.

--java_debug

Esta opción hace que la máquina virtual de Java de una prueba de Java espere una conexión de un depurador compatible con JDWP antes de iniciar la prueba. Esta opción implica --test_output=streamed.

--[no]verbose_test_summary

De forma predeterminada, esta opción está habilitada, lo que hace que los tiempos de prueba y otra información adicional (como los intentos de prueba) se impriman en el resumen de la prueba. Si se especifica --noverbose_test_summary, el resumen de la prueba solo incluirá el nombre, el estado y el indicador de prueba almacenada en caché, y se formateará para que no supere los 80 caracteres cuando sea posible.

--test_tmpdir=path

Especifica el directorio temporal para las pruebas que se ejecutan de forma local. Cada prueba se ejecutará en un subdirectorio independiente dentro de este directorio. El directorio se limpiará al comienzo de cada comando bazel test. De forma predeterminada, Bazel colocará este directorio en el directorio base de salida de Bazel.

--test_timeout=seconds O --test_timeout=seconds,seconds,seconds,seconds

Anula el valor de tiempo de espera para todas las pruebas usando la cantidad especificada de segundos como un nuevo valor de tiempo de espera. Si solo se proporciona un valor, se usará para todas las categorías de tiempo de espera de la prueba.

Como alternativa, se pueden proporcionar cuatro valores separados por comas que especifican los tiempos de espera individuales para las pruebas cortas, moderadas, largas y eternas (en ese orden). En cualquiera de las formas, el tiempo de espera predeterminado para las categorías de tiempo de espera determinadas, según se define en la página Writing Tests, reemplazará el valor cero o negativo de cualquiera de los tamaños de prueba. De forma predeterminada, Bazel usará estos tiempos de espera para todas las pruebas, ya que inferirá el límite de tiempo de espera del tamaño de la prueba, ya sea que el tamaño se establezca de forma implícita o explícita.

Las pruebas que indiquen explícitamente su categoría de tiempo de espera como distinta de su tamaño recibirán el mismo valor que si ese tiempo de espera se hubiera establecido de forma implícita con la etiqueta de tamaño. Por lo tanto, una prueba de tamaño "pequeño" que declare un tiempo de espera "largo" tendrá el mismo tiempo de espera efectivo que una prueba "grande" sin un tiempo de espera explícito.

--test_arg=arg

Pasa opciones, marcas o argumentos de la línea de comandos a cada proceso de prueba. Esta opción se puede usar varias veces para pasar varios argumentos. Por ejemplo, --test_arg=--logtostderr --test_arg=--v=3.

Ten en cuenta que, a diferencia del comando bazel run, no puedes pasar argumentos de prueba directamente como en bazel test -- target --logtostderr --v=3. Esto se debe a que los argumentos externos que se pasan a bazel test se interpretan como destinos de prueba adicionales. Es decir, --logtostderr y --v=3 se interpretarían como un objetivo de prueba cada uno. Esta ambigüedad no existe para un comando bazel run, que solo acepta un destino.

--test_arg se puede pasar a un comando bazel run, pero se ignora a menos que el destino que se ejecute sea un destino de prueba. (Al igual que con cualquier otra marca, si se pasa en un comando bazel run después de un token --, Bazel no la procesa, sino que la reenvía textualmente al destino ejecutado).

--test_env=variable=_value_ O --test_env=variable

Especifica variables adicionales que se deben insertar en el entorno de prueba para cada prueba. Si no se especifica value, se heredará del entorno de shell que se usó para iniciar el comando bazel test.

Se puede acceder al entorno desde una prueba con System.getenv("var") (Java), getenv("var") (C o C++)

--run_under=command-prefix

Especifica un prefijo que el ejecutor de pruebas insertará delante del comando de prueba antes de ejecutarlo. El command-prefix se divide en palabras con las reglas de tokenización de Bourne Shell y, luego, la lista de palabras se antepone al comando que se ejecutará.

Si la primera palabra es una etiqueta completamente calificada (comienza con //), se compila. Luego, la etiqueta se sustituye por la ubicación del ejecutable correspondiente que se antepone al comando que se ejecutará junto con las demás palabras.

Se aplican algunas advertencias:

• La RUTA DE ACCESO que se usa para ejecutar pruebas puede ser diferente de la RUTA DE ACCESO de tu entorno, por lo que es posible que debas usar una ruta de acceso absoluta para el comando --run_under (la primera palabra en command-prefix).
• stdin no está conectado, por lo que no se puede usar --run_under para comandos interactivos.

Ejemplos:

        --run_under=/usr/bin/strace
        --run_under='/usr/bin/strace -c'
        --run_under=/usr/bin/valgrind
        --run_under='/usr/bin/valgrind --quiet --num-callers=20'

Selección de pruebas

Como se documenta en Opciones de selección de salida, puedes filtrar las pruebas por tamaño, tiempo de espera, etiqueta o idioma. Un filtro de nombres general conveniente puede reenviar argumentos de filtro particulares al ejecutor de pruebas.

Otras opciones para bazel test

La sintaxis y las opciones restantes son exactamente iguales a las de bazel build.

Ejecución de archivos ejecutables

El comando bazel run es similar a bazel build, excepto que se usa para compilar y ejecutar un solo destino. A continuación, se muestra una sesión típica (//java/myapp:myapp saluda y muestra sus argumentos):

  % bazel run java/myapp:myapp -- --arg1 --arg2
  INFO: Analyzed target //java/myapp:myapp (13 packages loaded, 27 targets configured).
  INFO: Found 1 target...
  Target //java/myapp:myapp up-to-date:
    bazel-bin/java/myapp/myapp
  INFO: Elapsed time: 14.290s, Critical Path: 5.54s, ...
  INFO: Build completed successfully, 4 total actions
  INFO: Running command line: bazel-bin/java/myapp/myapp <args omitted>
  Hello there
  $EXEC_ROOT/java/myapp/myapp
  --arg1
  --arg2

bazel run es similar, pero no idéntico, a invocar directamente el binario compilado por Bazel, y su comportamiento es diferente según si el binario que se invocará es una prueba o no.

Cuando el objeto binario no es una prueba, el directorio de trabajo actual será el árbol de runfiles del objeto binario.

Cuando el binario es una prueba, el directorio de trabajo actual será la raíz de ejecución y se hará un intento de buena fe para replicar el entorno en el que se suelen ejecutar las pruebas. Sin embargo, la emulación no es perfecta, y las pruebas que tienen varios fragmentos no se pueden ejecutar de esta manera (se puede usar la opción de línea de comandos --test_sharding_strategy=disabled para solucionar este problema).

Las siguientes variables de entorno adicionales también están disponibles para el ejecutable:

• BUILD_WORKSPACE_DIRECTORY: Es la raíz del espacio de trabajo en el que se ejecutó la compilación.
• BUILD_WORKING_DIRECTORY: Es el directorio de trabajo actual desde el que se ejecutó Bazel.

Por ejemplo, se pueden usar para interpretar nombres de archivos en la línea de comandos de una manera fácil de usar.

Opciones para bazel run

--run_under=command-prefix

Tiene el mismo efecto que la opción --run_under para bazel test (consulta la sección anterior), excepto que se aplica al comando que ejecuta bazel run en lugar de a las pruebas que ejecuta bazel test y no se puede ejecutar con una etiqueta.

Cómo filtrar los resultados de los registros de Bazel

Cuando se invoca un objeto binario con bazel run, Bazel imprime el resultado del registro de Bazel y del objeto binario que se invoca. Para que los registros sean menos detallados, puedes suprimir los resultados de Bazel con las marcas --ui_event_filters y --noshow_progress.

Por ejemplo: bazel run --ui_event_filters=-info,-stdout,-stderr --noshow_progress //java/myapp:myapp

Ejecuta pruebas

bazel run también puede ejecutar archivos binarios de prueba, lo que tiene el efecto de ejecutar la prueba en una aproximación cercana del entorno descrito en Cómo escribir pruebas. Ten en cuenta que ninguno de los argumentos de --test_* tiene efecto cuando se ejecuta una prueba de esta manera, excepto --test_arg .

Cómo limpiar los resultados de la compilación

El comando clean

Bazel tiene un comando clean, análogo al de Make. Borra los directorios de salida de todas las configuraciones de compilación que realizó esta instancia de Bazel, o bien todo el árbol de trabajo que creó esta instancia de Bazel, y restablece las cachés internas. Si se ejecuta sin ninguna opción de línea de comandos, se limpiará el directorio de salida de todas las configuraciones.

Recuerda que cada instancia de Bazel está asociada a un solo espacio de trabajo, por lo que el comando clean borrará todos los resultados de todas las compilaciones que hayas realizado con esa instancia de Bazel en ese espacio de trabajo.

Para quitar por completo todo el árbol de trabajo creado por una instancia de Bazel, puedes especificar la opción --expunge. Cuando se ejecuta con --expunge, el comando clean simplemente quita todo el árbol base de salida que, además del resultado de la compilación, contiene todos los archivos temporales creados por Bazel. También detiene el servidor de Bazel después de la limpieza, lo que equivale al comando shutdown. Por ejemplo, para limpiar todos los registros de disco y memoria de una instancia de Bazel, puedes especificar lo siguiente:

  % bazel clean --expunge

Como alternativa, puedes purgar en segundo plano con --expunge_async. Es seguro invocar un comando de Bazel en el mismo cliente mientras se sigue ejecutando la eliminación asíncrona.

El comando clean se proporciona principalmente como un medio para recuperar espacio en disco para los espacios de trabajo que ya no son necesarios. Las compilaciones incrementales de Bazel pueden no ser perfectas, por lo que se puede usar clean para recuperar un estado coherente cuando surjan problemas.

El diseño de Bazel es tal que estos problemas se pueden corregir y estos errores tienen una alta prioridad para corregirse. Si alguna vez encuentras una compilación incremental incorrecta, envía un informe de errores y notifícalos en las herramientas en lugar de usar clean.

Cómo consultar el gráfico de dependencias

Bazel incluye un lenguaje de consulta para hacer preguntas sobre el gráfico de dependencias que se usa durante la compilación. El lenguaje de consulta se usa con dos comandos: query y cquery. La principal diferencia entre los dos comandos es que query se ejecuta después de la fase de carga y cquery se ejecuta después de la fase de análisis. Estas herramientas son una ayuda invaluable para muchas tareas de ingeniería de software.

El lenguaje de consultas se basa en la idea de operaciones algebraicas sobre gráficos y se documenta en detalle en

Referencia de Bazel Query Consulta ese documento para obtener ejemplos y opciones de línea de comandos específicas de la búsqueda.

La herramienta de consultas acepta varias opciones de línea de comandos. --output selecciona el formato de salida. --[no]keep_going (inhabilitado de forma predeterminada) hace que la herramienta de consultas siga avanzando ante errores. Este comportamiento se puede inhabilitar si no se acepta un resultado incompleto en caso de errores.

La opción --[no]tool_deps, habilitada de forma predeterminada, hace que las dependencias en configuraciones que no son de destino se incluyan en el gráfico de dependencias sobre el que opera la consulta.

La opción --[no]implicit_deps, que está habilitada de forma predeterminada, hace que las dependencias implícitas se incluyan en el gráfico de dependencias sobre el que opera la consulta. Una dependencia implícita es aquella que no se especifica de forma explícita en el archivo BUILD, sino que la agrega Bazel.

Ejemplo: "Muestra las ubicaciones de las definiciones (en archivos BUILD) de todas las genrules necesarias para compilar todas las pruebas en el árbol de PEBL".

  bazel query --output location 'kind(genrule, deps(kind(".*_test rule", foo/bar/pebl/...)))'

Cómo consultar el gráfico de acciones

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

La herramienta acepta varias opciones de línea de comandos. --output selecciona el formato de salida. El formato de salida predeterminado (text) es legible para los humanos. Usa proto o textproto para obtener un formato legible por máquinas. 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 query tradicional, pero siblings, buildfiles y tests.

Para obtener más detalles, consulta Consulta del gráfico de acciones.

Comandos y opciones varios

help

El comando help proporciona ayuda en línea. De forma predeterminada, muestra un resumen de los comandos y temas de ayuda disponibles, como se muestra en Compilación con Bazel. Si especificas un argumento, se mostrará ayuda detallada sobre un tema en particular. La mayoría de los temas son comandos de Bazel, como build o query, pero hay algunos temas de ayuda adicionales que no corresponden a comandos.

--[no]long (-l)

De forma predeterminada, bazel help [topic] solo imprime un resumen de las opciones pertinentes para un tema. Si se especifica la opción --long, también se imprime el tipo, el valor predeterminado y la descripción completa de cada opción.

shutdown

Los procesos del servidor de Bazel se pueden detener con el comando shutdown. Este comando hace que el servidor de Bazel se cierre en cuanto quede inactivo (por ejemplo, después de que se completen las compilaciones o los otros comandos que estén en curso). Para obtener más información, consulta Implementación cliente/servidor.

Los servidores de Bazel se detienen después de un tiempo de espera por inactividad, por lo que este comando rara vez es necesario. Sin embargo, puede ser útil en secuencias de comandos cuando se sabe que no se producirán más compilaciones en un espacio de trabajo determinado.

shutdown acepta una opción, --iff_heap_size_greater_than _n_, que requiere un argumento de número entero (en MB). Si se especifica, esto hace que el cierre dependa de la cantidad de memoria ya consumida. Esto es útil para las secuencias de comandos que inician muchas compilaciones, ya que cualquier pérdida de memoria en el servidor de Bazel podría provocar que falle de forma espuria en ocasiones. Realizar un reinicio condicional evita esta situación.

info

El comando info imprime varios valores asociados con la instancia del servidor de Bazel o con una configuración de compilación específica. (Las secuencias de comandos que controlan una compilación pueden usar estos argumentos).

El comando info también permite un solo argumento (opcional), que es el nombre de una de las claves de la siguiente lista. En este caso, bazel info key solo imprimirá el valor de esa clave. (Esto es especialmente conveniente cuando se escribe un script de Bazel, ya que evita la necesidad de canalizar el resultado a través de sed -ne /key:/s/key://p:

Datos independientes de la configuración

• release: Es la etiqueta de versión de esta instancia de Bazel o "versión de desarrollo" si no se trata de un archivo binario lanzado.
• workspace la ruta de acceso absoluta al directorio del espacio de trabajo base.

• install_base: Es la ruta de acceso absoluta al directorio de instalación que usa esta instancia de Bazel para el usuario actual. Bazel instala sus ejecutables requeridos internamente debajo de este directorio.

• output_base: Es la ruta de acceso absoluta al directorio de salida base que usa esta instancia de Bazel para la combinación actual de usuario y espacio de trabajo. Bazel coloca todos sus datos temporales y resultados de compilación debajo de este directorio.

• execution_root: Es la ruta de acceso absoluta al directorio raíz de ejecución en output_base. Este directorio es la raíz de todos los archivos a los que pueden acceder los comandos que se ejecutan durante la compilación y es el directorio de trabajo de esos comandos. Si el directorio del espacio de trabajo tiene permiso de escritura, se colocará allí un vínculo simbólico llamado bazel-<workspace> que apunta a este directorio.

• output_path: Es la ruta de acceso absoluta al directorio de salida debajo de la raíz de ejecución que se usa para todos los archivos que se generan como resultado de los comandos de compilación. Si el directorio del espacio de trabajo tiene permiso de escritura, se colocará allí un vínculo simbólico llamado bazel-out que apunta a este directorio.

• server_pid: Es el ID del proceso del servidor de Bazel.

• server_log: Es la ruta de acceso absoluta al archivo de registro de depuración del servidor de Bazel. Este archivo contiene información de depuración para todos los comandos durante la vida útil del servidor de Bazel y está destinado al consumo humano por parte de los desarrolladores y usuarios avanzados de Bazel.

• command_log: Es la ruta de acceso absoluta al archivo de registro de comandos. Contiene los flujos intercalados de stdout y stderr del comando de Bazel más reciente. Ten en cuenta que ejecutar bazel info sobrescribirá el contenido de este archivo, ya que se convertirá en el comando de Bazel más reciente. Sin embargo, la ubicación del archivo de registro de comandos no cambiará, a menos que modifiques la configuración de las opciones --output_base o --output_user_root.

• used-heap-size, committed-heap-size, max-heap-size: Informa varios parámetros del tamaño del heap de la JVM. Respectivamente: memoria que se usa actualmente, memoria que el sistema garantiza que está disponible para la JVM y asignación máxima posible.

• gc-count, gc-time: Es el recuento acumulativo de las recolecciones de elementos no utilizados desde el inicio de este servidor de Bazel y el tiempo dedicado a realizarlas. Ten en cuenta que estos valores no se restablecen al comienzo de cada compilación.

• package_path: Es una lista de rutas separadas por dos puntos en las que Bazel buscaría paquetes. Tiene el mismo formato que el argumento de la línea de comandos de compilación --package_path.

Ejemplo: ID del proceso del servidor de Bazel.

% bazel info server_pid
1285

Datos específicos de la configuración

Estos datos pueden verse afectados por las opciones de configuración que se pasan a bazel info, por ejemplo, --cpu, --compilation_mode, etcétera. El comando info acepta todas las opciones que controlan el análisis de dependencias, ya que algunas de ellas determinan la ubicación del directorio de salida de una compilación, la elección del compilador, etcétera.

• bazel-bin, bazel-testlogs, bazel-genfiles: Informa la ruta de acceso absoluta a los directorios bazel-* en los que se encuentran los programas generados por la compilación. Por lo general, aunque no siempre, es lo mismo que los vínculos simbólicos bazel-* creados en el directorio del espacio de trabajo base después de una compilación exitosa. Sin embargo, si el directorio del espacio de trabajo es de solo lectura, no se pueden crear vínculos simbólicos bazel-*. Los secuencias de comandos que usan el valor informado por bazel info, en lugar de suponer la existencia del vínculo simbólico, serán más sólidos.
• El entorno de"Make" completo Si se especifica la marca --show_make_env, también se muestran todas las variables del entorno de "Make" de la configuración actual (como CC, GLIBC_VERSION, etcétera). Estas son las variables a las que se accede con la sintaxis $(CC) o varref("CC") dentro de los archivos BUILD.

Ejemplo: El compilador de C++ para la configuración actual. Esta es la variable $(CC) en el entorno de "Make", por lo que se necesita la marca --show_make_env.

  % bazel info --show_make_env -c opt COMPILATION_MODE
  opt

Ejemplo: El directorio de salida bazel-bin para la configuración actual. Se garantiza que esto es correcto incluso en los casos en los que no se puede crear el symlink bazel-bin por algún motivo (por ejemplo, si compilas desde un directorio de solo lectura).

% bazel info --cpu=piii bazel-bin
/var/tmp/_bazel_johndoe/fbd0e8a34f61ce5d491e3da69d959fe6/execroot/io_bazel/bazel-out/piii-opt/bin
% bazel info --cpu=k8 bazel-bin
/var/tmp/_bazel_johndoe/fbd0e8a34f61ce5d491e3da69d959fe6/execroot/io_bazel/bazel-out/k8-opt/bin

version y --version

El comando version imprime detalles de la versión sobre el binario de Bazel compilado, incluida la lista de cambios en la que se compiló y la fecha. Son particularmente útiles para determinar si tienes la versión más reciente de Bazel o si informas errores. Algunos de los valores interesantes son los siguientes:

• changelist: Es la lista de cambios en la que se lanzó esta versión de Bazel.
• label: Es la etiqueta de versión de esta instancia de Bazel o "versión de desarrollo" si no se trata de un archivo binario lanzado. Es muy útil cuando se informan errores.

bazel --version, sin ningún otro argumento, emitirá el mismo resultado que bazel version --gnu_format, excepto que no tendrá el efecto secundario de iniciar potencialmente un servidor de Bazel o descomprimir el archivo del servidor. bazel --version se puede ejecutar desde cualquier lugar, ya que no requiere un directorio de espacio de trabajo.

mobile-install

El comando mobile-install instala apps en dispositivos móviles. Actualmente, solo se admiten dispositivos Android que ejecutan ART.

Consulta bazel mobile-install para obtener más información.

Se admiten las siguientes opciones:

--incremental

Si se configura, Bazel intenta instalar la app de forma incremental, es decir, solo las partes que cambiaron desde la última compilación. No se pueden actualizar los recursos a los que se hace referencia desde AndroidManifest.xml, el código nativo o los recursos de Java (como los que se referencian con Class.getResource()). Si estos elementos cambian, se debe omitir esta opción. Al contrario del espíritu de Bazel y debido a las limitaciones de la plataforma de Android, es responsabilidad del usuario saber cuándo este comando es suficiente y cuándo se necesita una instalación completa.

Si usas un dispositivo con Marshmallow o una versión posterior, considera la marca --split_apks.

--split_apks

Indica si se deben usar APKs divididos para instalar y actualizar la aplicación en el dispositivo. Solo funciona con dispositivos con Marshmallow o versiones posteriores. Ten en cuenta que la marca --incremental no es necesaria cuando se usa --split_apks.

--start_app

Inicia la app en un estado limpio después de la instalación. Equivale a --start=COLD.

--debug_app

Espera a que se adjunte el depurador antes de iniciar la app en un estado limpio después de la instalación. Equivale a --start=DEBUG.

--start=_start_type_

Indica cómo se debe iniciar la app después de instalarla. Los _start_type_s admitidos son los siguientes:

• NO No inicia la app. Este es el valor predeterminado.
• COLD Inicia la app desde un estado limpio después de la instalación.
• WARM Conserva y restablece el estado de la aplicación en las instalaciones incrementales.
• DEBUG Espera al depurador antes de iniciar la app en un estado limpio después de la instalación.

--adb=path

Indica el objeto binario adb que se usará.

El valor predeterminado es usar adb en el SDK de Android especificado por --android_sdk.

--adb_arg=serial

Son argumentos adicionales para adb. Estos preceden al subcomando en la línea de comandos y, por lo general, se usan para especificar en qué dispositivo se realizará la instalación. Por ejemplo, para seleccionar el dispositivo o emulador de Android que se usará, haz lo siguiente:

% bazel mobile-install --adb_arg=-s --adb_arg=deadbeef

invoca adb como

adb -s deadbeef install ...

--incremental_install_verbosity=number

Es el nivel de detalle de la instalación incremental. Se establece en 1 para que los registros de depuración se impriman en la consola.

dump

El comando dump imprime en stdout un volcado del estado interno del servidor de Bazel. Este comando está destinado principalmente a los desarrolladores de Bazel, por lo que no se especifica su resultado y está sujeto a cambios.

De forma predeterminada, el comando solo imprimirá un mensaje de ayuda que describa las posibles opciones para volcar áreas específicas del estado de Bazel. Para volcar el estado interno, se debe especificar al menos una de las opciones.

Se admiten las siguientes opciones:

• --action_cache vuelca el contenido de la caché de acciones.
• --packages vuelca el contenido de la caché del paquete.
• --skyframe vuelca el estado del gráfico de dependencias interno de Bazel.
• --rules vuelca el resumen de reglas para cada regla y clase de aspecto, incluidos los recuentos y los recuentos de acciones. Esto incluye las reglas nativas y las de Starlark. Si el seguimiento de la memoria está habilitado, también se imprimirá el consumo de memoria de las reglas.
• --skylark_memory vuelca un archivo .gz compatible con pprof en la ruta de acceso especificada. Debes habilitar el seguimiento de la memoria para que esto funcione.

Seguimiento de la memoria

Algunos comandos dump requieren seguimiento de la memoria. Para activar esta opción, debes pasar marcas de inicio a Bazel:

• --host_jvm_args=-javaagent:$BAZEL/third_party/allocation_instrumenter/java-allocation-instrumenter-3.3.4.jar
• --host_jvm_args=-DRULE_MEMORY_TRACKER=1

El java-agent se registra en Bazel en third_party/allocation_instrumenter/java-allocation-instrumenter-3.3.4.jar, así que asegúrate de ajustar $BAZEL según dónde guardes tu repositorio de Bazel.

No olvides seguir pasando estas opciones a Bazel para cada comando, o el servidor se reiniciará.

Ejemplo:

    % bazel --host_jvm_args=-javaagent:$BAZEL/third_party/allocation_instrumenter/java-allocation-instrumenter-3.3.4.jar \
    --host_jvm_args=-DRULE_MEMORY_TRACKER=1 \
    build --nobuild <targets>

    # Dump rules
    % bazel --host_jvm_args=-javaagent:$BAZEL/third_party/allocation_instrumenter/java-allocation-instrumenter-3.3.4.jar \
    --host_jvm_args=-DRULE_MEMORY_TRACKER=1 \
    dump --rules

    # Dump Starlark heap and analyze it with pprof
    % bazel --host_jvm_args=-javaagent:$BAZEL/third_party/allocation_instrumenter/java-allocation-instrumenter-3.3.4.jar \
    --host_jvm_args=-DRULE_MEMORY_TRACKER=1 \
    dump --skylark_memory=$HOME/prof.gz
    % pprof -flame $HOME/prof.gz

analyze-profile

El comando analyze-profile analiza un perfil de seguimiento JSON recopilado previamente durante una invocación de Bazel.

canonicalize-flags

El comando canonicalize-flags, que toma una lista de opciones para un comando de Bazel y devuelve una lista de opciones que tienen el mismo efecto. La nueva lista de opciones es canónica. Por ejemplo, dos listas de opciones con el mismo efecto se canonizan en la misma lista nueva.

La opción --for_command se puede usar para seleccionar entre diferentes comandos. En este momento, solo se admiten build y test. Las opciones que no admite el comando determinado provocan un error.

A continuación, se muestra un ejemplo:

  % bazel canonicalize-flags -- --config=any_name --test_tag_filters="-lint"
  --config=any_name
  --test_tag_filters=-lint

Opciones de inicio

Las opciones que se describen en esta sección afectan el inicio de la máquina virtual de Java que usa el proceso del servidor de Bazel y se aplican a todos los comandos posteriores que controla ese servidor. Si ya hay un servidor de Bazel en ejecución y las opciones de inicio no coinciden, se reiniciará.

Todas las opciones que se describen en esta sección se deben especificar con la sintaxis --key=value o --key value. Además, estas opciones deben aparecer antes del nombre del comando de Bazel. Usa startup --key=value para enumerarlos en un archivo .bazelrc.

--output_base=dir

Esta opción requiere un argumento de ruta de acceso, que debe especificar un directorio con permiso de escritura. Bazel usará esta ubicación para escribir todos sus resultados. La base de salida también es la clave con la que el cliente ubica el servidor de Bazel. Si cambias la base de salida, cambiarás el servidor que controlará el comando.

De forma predeterminada, la base de salida se deriva del nombre de acceso del usuario y del nombre del directorio del espacio de trabajo (en realidad, su resumen MD5), por lo que un valor típico se ve de la siguiente manera: /var/tmp/google/_bazel_johndoe/d41d8cd98f00b204e9800998ecf8427e.

Por ejemplo:

 OUTPUT_BASE=/var/tmp/google/_bazel_johndoe/custom_output_base
% bazel --output_base ${OUTPUT_BASE}1 build //foo  &  bazel --output_base ${OUTPUT_BASE}2 build //bar

En este comando, los dos comandos de Bazel se ejecutan de forma simultánea (debido al operador & de la shell), y cada uno usa una instancia diferente del servidor de Bazel (debido a las diferentes bases de salida). En cambio, si se hubiera usado la base de salida predeterminada en ambos comandos, ambas solicitudes se enviarían al mismo servidor, que las controlaría de forma secuencial: primero, compilaría //foo y, luego, una compilación incremental de //bar.

--output_user_root=dir

Apunta al directorio raíz en el que se crean las bases de instalación y de salida. El directorio no debe existir o debe ser propiedad del usuario que realiza la llamada. En el pasado, se permitía que apuntara a un directorio compartido entre varios usuarios, pero ya no se permite. Esto se puede permitir una vez que se resuelva el problema #11100.

Si se especifica la opción --output_base, se anula el uso de --output_user_root para calcular la base del resultado.

La ubicación de la base de instalaciones se calcula en función de --output_user_root, más la identidad MD5 de los archivos binarios incorporados de Bazel.

Puedes usar la opción --output_user_root para elegir una ubicación base alternativa para toda la salida de Bazel (base de instalación y base de salida) si hay una mejor ubicación en el diseño de tu sistema de archivos.

--server_javabase=dir

Especifica la máquina virtual de Java en la que se ejecuta Bazel. El valor debe ser una ruta de acceso al directorio que contiene un JDK o JRE. No debe ser una etiqueta. Esta opción debe aparecer antes de cualquier comando de Bazel, por ejemplo:

  % bazel --server_javabase=/usr/local/buildtools/java/jdk11 build //foo

Esta marca no afecta las JVM que usan los subprocesos de Bazel, como aplicaciones, pruebas, herramientas, etcétera. En su lugar, usa las opciones de compilación --javabase o --host_javabase.

Anteriormente, esta marca se llamaba --host_javabase (a veces, se la conoce como --host_javabase del “lado izquierdo”), pero se le cambió el nombre para evitar confusiones con la marca de compilación --host_javabase (a veces, se la conoce como --host_javabase del “lado derecho”).

--host_jvm_args=string

Especifica una opción de inicio que se pasará a la máquina virtual de Java en la que se ejecuta Bazel. Esto se puede usar para establecer el tamaño de la pila, por ejemplo:

  % bazel --host_jvm_args="-Xss256K" build //foo

Esta opción se puede usar varias veces con argumentos individuales. Ten en cuenta que rara vez se debería necesitar configurar esta marca. También puedes pasar una lista de cadenas separadas por espacios, cada una de las cuales se interpretará como un argumento de JVM independiente, pero esta función pronto dejará de estar disponible.

Esto no afecta a ninguna JVM que usen los subprocesos de Bazel: aplicaciones, pruebas, herramientas, etcétera. Para pasar opciones de JVM a programas ejecutables de Java, ya sea que se ejecuten con bazel run o en la línea de comandos, debes usar el argumento --jvm_flags que admiten todos los programas java_binary y java_test. Como alternativa para las pruebas, usa bazel test --test_arg=--jvm_flags=foo ....

--host_jvm_debug

Esta opción hace que la máquina virtual de Java espere una conexión de un depurador compatible con JDWP antes de llamar al método principal de Bazel. Este método está destinado principalmente a los desarrolladores de Bazel.

--autodetect_server_javabase

Esta opción hace que Bazel busque automáticamente un JDK instalado en el inicio y que vuelva al JRE instalado si el JRE integrado no está disponible. --explicit_server_javabase se puede usar para elegir un JRE explícito con el que ejecutar Bazel.

--batch

El modo por lotes hace que Bazel no use el modo cliente/servidor estándar, sino que ejecute un proceso de Bazel Java para un solo comando, que se ha utilizado para una semántica más predecible con respecto al control de señales y trabajos, y la herencia de variables de entorno, y es necesario para ejecutar Bazel en una cárcel de chroot.

El modo por lotes conserva la semántica de encolamiento adecuada dentro del mismo output_base. Es decir, las invocaciones simultáneas se procesarán en orden, sin superposiciones. Si se ejecuta un Bazel en modo de lote en un cliente con un servidor en ejecución, primero se detiene el servidor antes de procesar el comando.

Bazel se ejecutará más lento en el modo por lotes o con las alternativas descritas anteriormente. Esto se debe a que, entre otras cosas, la caché de archivos de compilación reside en la memoria, por lo que no se conserva entre las invocaciones secuenciales por lotes. Por lo tanto, usar el modo por lotes suele tener más sentido en los casos en los que el rendimiento es menos crítico, como las compilaciones continuas.

--max_idle_secs=n

Esta opción especifica cuánto tiempo, en segundos, debe esperar el proceso del servidor de Bazel después de la última solicitud del cliente antes de salir. El valor predeterminado es 10800 (3 horas). --max_idle_secs=0 hará que el proceso del servidor de Bazel persista de forma indefinida.

Los secuencias de comandos que invocan a Bazel pueden usar esta opción para garantizar que no dejen procesos del servidor de Bazel en la máquina de un usuario cuando no se estarían ejecutando de otro modo. Por ejemplo, un script previo al envío podría invocar bazel query para garantizar que el cambio pendiente de un usuario no introduzca dependencias no deseadas. Sin embargo, si el usuario no realizó una compilación reciente en ese espacio de trabajo, no sería conveniente que la secuencia de comandos de envío previo iniciara un servidor de Bazel solo para que permaneciera inactivo durante el resto del día. Si se especifica un valor pequeño de --max_idle_secs en la solicitud de búsqueda, la secuencia de comandos puede garantizar que, si provocó el inicio de un nuevo servidor, este se cerrará de inmediato, pero, si ya había un servidor en ejecución, este seguirá ejecutándose hasta que haya estado inactivo durante el tiempo habitual. Por supuesto, se restablecerá el temporizador de inactividad del servidor existente.

--[no]shutdown_on_low_sys_mem

Si está habilitado y --max_idle_secs se establece en una duración positiva, después de que el servidor de compilación haya estado inactivo durante un tiempo, apaga el servidor cuando el sistema tenga poca memoria. Solo en Linux.

Además de ejecutar una verificación de inactividad correspondiente a max_idle_secs, el servidor de compilación comenzará a supervisar la memoria del sistema disponible después de que el servidor haya estado inactivo durante un tiempo. Si la memoria del sistema disponible se reduce de forma crítica, el servidor se cerrará.

--[no]block_for_lock

Si está habilitado, Bazel esperará a que se completen otros comandos de Bazel que mantengan el bloqueo del servidor antes de continuar. Si se inhabilita, Bazel saldrá con un error si no puede adquirir el bloqueo de inmediato y continuar.

Los desarrolladores pueden usar esto en las verificaciones previas a la confirmación para evitar esperas prolongadas causadas por otro comando de Bazel en el mismo cliente.

--io_nice_level=n

Establece un nivel de 0 a 7 para la programación de E/S de mejor esfuerzo. El 0 es la prioridad más alta y el 7, la más baja. El programador anticipatorio solo puede cumplir con la prioridad 4. Se ignoran los valores negativos.

--batch_cpu_scheduling

Usa la programación de CPU batch para Bazel. Esta política es útil para las cargas de trabajo que no son interactivas, pero que no desean reducir su valor de nice. Consulta “man 2 sched_setscheduler”. Esta política puede proporcionar una mejor interactividad del sistema a expensas de la capacidad de procesamiento de Bazel.

Otras opciones

--[no]announce_rc

Controla si Bazel anuncia las opciones de inicio y las opciones de comando que se leen de los archivos bazelrc cuando se inicia.

--color (yes|no|auto)

Esta opción determina si Bazel usará colores para destacar su salida en la pantalla.

Si esta opción se configura como yes, se habilita el resultado de color. Si esta opción se configura como auto, Bazel usará la salida de color solo si la salida se envía a una terminal y la variable de entorno TERM se establece en un valor que no sea dumb, emacs o xterm-mono. Si esta opción se establece en no, se inhabilita la salida de color, independientemente de si la salida se dirige a una terminal y de la configuración de la variable de entorno TERM.

--config=name

Selecciona una sección de configuración adicional de los archivos rc. Para el command actual, también extrae las opciones de command:name si existe tal sección. Se puede especificar varias veces para agregar marcas de varias secciones de configuración. Las expansiones pueden hacer referencia a otras definiciones (por ejemplo, las expansiones se pueden encadenar).

--curses (yes|no|auto)

Esta opción determina si Bazel usará controles de cursor en la salida de la pantalla. Esto genera menos datos de desplazamiento y un flujo de salida de Bazel más compacto y fácil de leer. Esto funciona bien con --color.

Si esta opción está configurada como yes, se habilita el uso de los controles del cursor. Si esta opción se establece en no, se inhabilita el uso de los controles del cursor. Si esta opción se configura como auto, el uso de los controles del cursor se habilitará en las mismas condiciones que para --color=auto.

--[no]show_timestamps

Si se especifica, se agrega una marca de tiempo a cada mensaje generado por Bazel, en la que se indica la hora en la que se mostró el mensaje.