Escribe archivos de configuración de Bazelrc

Informar un problema Ver fuente

Bazel acepta muchas opciones. Algunas opciones varían con frecuencia (por ejemplo, --subcommands), mientras que otras permanecen iguales en varias compilaciones (como --package_path). Para evitar especificar estas opciones sin cambios para cada compilación (y otros comandos), puedes especificar opciones en un archivo de configuración, llamado .bazelrc.

¿Dónde están los archivos .bazelrc?

Bazel busca archivos de configuración opcionales en las siguientes ubicaciones, en el orden que se muestra a continuación. Las opciones se interpretan en este orden, por lo que las opciones en los archivos posteriores pueden anular un valor de un archivo anterior si surge un conflicto. Todas las opciones que controlan cuáles de estos archivos se cargan son opciones de inicio, lo que significa que deben ocurrir después de bazel y antes del comando (build, test, etcétera).

  1. El archivo RC del sistema, a menos que esté presente --nosystem_rc

    Ruta:

    • En Linux, macOS o Unix: /etc/bazel.bazelrc
    • En Windows: %ProgramData%\bazel.bazelrc

    Si el archivo no existe, no se generará un error.

    Si se requiere otra ubicación especificada por el sistema, debes compilar un objeto binario de Bazel personalizado y anular el valor de BAZEL_SYSTEM_BAZELRC_PATH en //src/main/cpp:option_processor. La ubicación especificada por el sistema puede contener referencias de variables de entorno, como ${VAR_NAME} en Unix o %VAR_NAME% en Windows.

  2. El archivo RC de Workspace, a menos que esté presente --noworkspace_rc

    Ruta de acceso: .bazelrc en el directorio de tu lugar de trabajo (junto al archivo WORKSPACE principal).

    Si el archivo no existe, no se generará un error.

  3. El archivo RC principal, a menos que esté presente --nohome_rc

    Ruta:

    • En Linux, macOS o Unix: $HOME/.bazelrc
    • En Windows: %USERPROFILE%\.bazelrc si existe o %HOME%/.bazelrc

    Si el archivo no existe, no se generará un error.

  4. El archivo RC especificado por el usuario, si se especifica con --bazelrc=file

    Esta marca es opcional, pero también se puede especificar varias veces.

    /dev/null indica que se ignorarán todos los --bazelrc adicionales, lo que es útil para inhabilitar la búsqueda de un archivo RC del usuario, como en las compilaciones de lanzamiento.

    Por ejemplo:

    --bazelrc=x.rc --bazelrc=y.rc --bazelrc=/dev/null --bazelrc=z.rc
    
    • Se leyeron x.rc y y.rc.
    • Se ignora z.rc debido a los /dev/null anteriores.

Además de este archivo de configuración opcional, Bazel busca un archivo rc global. Para obtener más información, consulta la sección de Bazelrc global.

Sintaxis y semántica de .bazelrc

Como todos los archivos "rc" de UNIX, el archivo .bazelrc es un archivo de texto con una gramática basada en líneas. Se ignoran las líneas vacías y las que comienzan con # (comentarios). Cada línea contiene una secuencia de palabras, a las que se les asignan tokens según las mismas reglas de la shell Bourne.

Importaciones

Las líneas que comienzan con import o try-import son especiales: úsalas para cargar otros archivos "rc". Para especificar una ruta de acceso relativa a la raíz del lugar de trabajo, escribe import %workspace%/path/to/bazelrc.

La diferencia entre import y try-import es que Bazel falla si falta el archivo import (o no se puede leer), pero no es así en el caso de un archivo try-import.

Prioridad de la importación:

  • Las opciones del archivo importado tienen prioridad sobre las opciones especificadas antes de la sentencia de importación.
  • Las opciones especificadas después de la declaración de importación tienen prioridad sobre las opciones del archivo importado.
  • Las opciones de los archivos importados más tarde tienen prioridad sobre los archivos que se importaron antes.

Valores predeterminados de las opciones

La mayoría de las líneas de Bazelrc definen valores de opción predeterminados. La primera palabra de cada línea especifica cuándo se aplican estos valores predeterminados:

  • startup: Son las opciones de inicio, que anteceden al comando y se describen en bazel help startup_options.
  • common: Son opciones que se deben aplicar a todos los comandos de Bazel que los admiten. Si un comando no admite una opción especificada de esta manera, la opción se ignora, siempre y cuando sea válida para algún comando de Bazel. Ten en cuenta que esto solo se aplica a los nombres de opciones: si el comando actual acepta una opción con el nombre especificado, pero no admite el valor especificado, fallará.
  • always: Son opciones que se aplican a todos los comandos de Bazel. Si un comando no admite una opción especificada de esta manera, fallará.
  • command: Es el comando de Bazel, como build o query al que se aplican las opciones. Estas opciones también se aplican a todos los comandos que se heredan del comando especificado. (Por ejemplo, test hereda de build).

Cada una de estas líneas se puede usar más de una vez, y los argumentos que siguen a la primera palabra se combinan como si hubieran aparecido en una sola línea. (los usuarios de CVS, otra herramienta con una interfaz de línea de comandos "navaja suiza", encontrarán una sintaxis similar a la de .cvsrc). Por ejemplo, las siguientes líneas:

build --test_tmpdir=/tmp/foo --verbose_failures
build --test_tmpdir=/tmp/bar

se combinan de la siguiente manera:

build --test_tmpdir=/tmp/foo --verbose_failures --test_tmpdir=/tmp/bar

Por lo tanto, las marcas eficaces son --verbose_failures y --test_tmpdir=/tmp/bar.

Prioridad de la opción:

  • Las opciones de la línea de comandos siempre tienen prioridad sobre las de los archivos RC. Por ejemplo, si un archivo rc indica build -c opt, pero la marca de la línea de comandos es -c dbg, tiene prioridad la marca de la línea de comandos.
  • Dentro del archivo rc, la prioridad se rige por la especificidad: las líneas de un comando más específico tienen prioridad sobre las líneas de un comando menos específico.

    La especificidad se define por herencia. Algunos comandos heredan opciones de otros, lo que hace que el comando de herencia sea más específico que el comando base. Por ejemplo, test se hereda del comando build, por lo que todas las marcas bazel build son válidas para bazel test, y todas las líneas build también se aplican a bazel test, a menos que haya una línea test para la misma opción. Si el archivo RC dice lo siguiente:

    test -c dbg --test_env=PATH
    build -c opt --verbose_failures
    

    luego, bazel build //foo usará -c opt --verbose_failures y bazel test //foo usará --verbose_failures -c dbg --test_env=PATH.

    El gráfico de herencia (especificidad) es el siguiente:

    • Cada comando se hereda de common
    • Los siguientes comandos se heredan de build (y son más específicos que): test, run, clean, mobile-install, info, print_action, config, cquery y aquery.
    • coverage hereda de test
  • Dos líneas que especifican opciones para el mismo comando con la misma especificidad se analizan en el orden en que aparecen dentro del archivo.

  • Debido a que esta regla de precedencia no coincide con el orden de los archivos, será más fácil de leer si sigues el orden de prioridad dentro de los archivos RC: comienza con las opciones common en la parte superior y termina con los comandos más específicos en la parte inferior del archivo. De esta manera, el orden en el que se leen las opciones es el mismo que el de aplicación, que es más intuitivo.

Los argumentos especificados en una línea de un archivo rc pueden incluir argumentos que no son opciones, como los nombres de destinos de compilación, etcétera. Estas, al igual que las opciones especificadas en los mismos archivos, tienen menor prioridad que sus elementos del mismo nivel en la línea de comandos y siempre se anteponen a la lista explícita de argumentos que no son opciones.

--config

Además de establecer los valores predeterminados de las opciones, el archivo rc se puede usar para agrupar opciones y proporcionar una abreviatura de las agrupaciones comunes. Para ello, se agrega un sufijo :name al comando. Estas opciones se ignoran de forma predeterminada, pero se incluirán cuando la opción --config=name esté presente, ya sea en la línea de comandos o en un archivo .bazelrc, de manera recursiva, incluso dentro de otra definición de configuración. Las opciones que especifica command:name solo se expandirán para los comandos aplicables, en el orden de prioridad descrito anteriormente.

--config=foo se expande a las opciones definidas en los archivos rc “locales” a fin de que las opciones especificadas para la configuración tengan la misma prioridad que la opción --config=foo.

Esta sintaxis no se extiende al uso de startup para configurar opciones de inicio. Se ignorará la configuración de startup:config-name --some_startup_option en el archivo .bazelrc.

--enable_platform_specific_config

Los parámetros de configuración específicos de la plataforma en .bazelrc se pueden habilitar automáticamente mediante --enable_platform_specific_config. Por ejemplo, si el SO del host es Linux y se ejecuta el comando build, se habilitará la configuración build:linux de forma automática. Los identificadores de SO compatibles son linux, macos, windows, freebsd y openbsd. Habilitar esta marca equivale a usar --config=linux en Linux, --config=windows en Windows, etcétera.

Consulta --enable_platform_specific_config.

Ejemplo

Este es un archivo ~/.bazelrc de ejemplo:

# Bob's Bazel option defaults

startup --host_jvm_args=-XX:-UseParallelGC
import /home/bobs_project/bazelrc
build --show_timestamps --keep_going --jobs 600
build --color=yes
query --keep_going

# Definition of --config=memcheck
build:memcheck --strip=never --test_timeout=3600

Otros archivos que rigen el comportamiento de Bazel

.bazelignore

Puedes especificar directorios dentro del lugar de trabajo que deseas que Bazel ignore, como proyectos relacionados que usan otros sistemas de compilación. Coloca un archivo llamado .bazelignore en la raíz del lugar de trabajo y agrega los directorios que deseas que Bazel ignore, uno por línea. Las entradas están relacionadas con la raíz del lugar de trabajo.

El archivo global de Bazelrc

Bazel lee los archivos opcionales de Bazelrc en este orden:

  1. Archivo rc del sistema ubicado en etc/bazel.bazelrc.
  2. Archivo rc del lugar de trabajo ubicado en $workspace/tools/bazel.rc.
  3. Archivo rc-home ubicado en $HOME/.bazelrc

Cada archivo de Bazelrc que se enumera aquí tiene una marca correspondiente que se puede usar para inhabilitarlos (p.ej., --nosystem_rc, --noworkspace_rc, --nohome_rc). También puedes hacer que Bazel ignore todos los bazelrc si pasas la opción de inicio --ignore_all_rc_files.