Funciones

Contenido

• Paquete
• package_group
• exports_files
• glob
• select
• subpackages

Paquete

package(default_deprecation, default_package_metadata, default_testonly, default_visibility, features)

Esta función declara metadatos que se aplican a cada regla del paquete. Se usa como máximo una vez dentro de un paquete (archivo BUILD).

Para la contraparte que declara metadatos que se aplican a cada regla de todo el repositorio, usa la función repo() en el REPO.bazel archivo en la raíz de tu repositorio. La función repo() toma exactamente los mismos argumentos que package().

Se debe llamar a la función package() justo después de todas las instrucciones load() en la parte superior del archivo, antes de cualquier regla.

Argumentos

Ejemplos

package(default_visibility = ["//foo:target"])

package_group

package_group(name, packages, includes)

Esta función define un conjunto de paquetes y asocia una etiqueta con el conjunto. Se puede hacer referencia a la etiqueta en visibility atributos.

Los grupos de paquetes se usan principalmente para el control de visibilidad. Se puede hacer referencia a un objetivo visible públicamente desde cada paquete del árbol de origen. Solo se puede hacer referencia a un objetivo visible de forma privada dentro de su propio paquete (no en subpaquetes). Entre estos extremos, un objetivo puede permitir el acceso a su propio paquete, además de cualquiera de los paquetes que describen uno o más grupos de paquetes. Para obtener una explicación más detallada del sistema de visibilidad, consulta el atributo de visibilidad.

Se considera que un paquete determinado está en el grupo si coincide con el packages atributo o si ya está contenido en uno de los otros grupos de paquetes mencionados en el includes atributo.

Técnicamente, los grupos de paquetes son objetivos, pero no se crean con reglas y no tienen ninguna protección de visibilidad.

Argumentos

Ejemplos

La siguiente package_group declaración especifica un grupo de paquetes llamado "tropical" que contiene frutas tropicales.

package_group(
    name = "tropical",
    packages = [
        "//fruits/mango",
        "//fruits/orange",
        "//fruits/papaya/...",
    ],
)

Las siguientes declaraciones especifican los grupos de paquetes de una aplicación ficticia:

package_group(
    name = "fooapp",
    includes = [
        ":controller",
        ":model",
        ":view",
    ],
)

package_group(
    name = "model",
    packages = ["//fooapp/database"],
)

package_group(
    name = "view",
    packages = [
        "//fooapp/swingui",
        "//fooapp/webui",
    ],
)

package_group(
    name = "controller",
    packages = ["//fooapp/algorithm"],
)

exports_files

exports_files([label, ...], visibility, licenses)

exports_files() especifica una lista de archivos que pertenecen a este paquete y que se exportan a otros paquetes.

El archivo BUILD de un paquete solo puede hacer referencia directamente a los archivos fuente que pertenecen a otro paquete si se exportan de forma explícita con una exports_files() instrucción. Obtén más información sobre la visibilidad de los archivos.

Como comportamiento heredado, también se exportan los archivos mencionados como entrada a una regla con la visibilidad predeterminada hasta que se invierte la marca --incompatible_no_implicit_file_export. Sin embargo, no se debe confiar en este comportamiento y se debe migrar de forma activa.

Argumentos

El argumento es una lista de nombres de archivos dentro del paquete actual. También se puede especificar una declaración de visibilidad. En este caso, los archivos serán visibles para los objetivos especificados. Si no se especifica la visibilidad, los archivos serán visibles para todos los paquetes, incluso si se especificó una visibilidad predeterminada del paquete en la package función. También se pueden especificar las licencias.

Ejemplo

En el siguiente ejemplo, se exporta golden.txt, un archivo de texto del paquete test_data, de modo que otros paquetes puedan usarlo, por ejemplo, en el atributo data de las pruebas.

# from //test_data/BUILD

exports_files(["golden.txt"])

glob

glob(include, exclude=[], exclude_directories=1, allow_empty=True)

Glob es una función auxiliar que encuentra todos los archivos que coinciden con ciertos patrones de ruta de acceso, y muestra una lista nueva, mutable y ordenada de sus rutas de acceso. Glob solo busca archivos en su propio paquete y solo busca archivos fuente (no archivos generados ni otros objetivos).

La etiqueta de un archivo fuente se incluye en el resultado si la ruta de acceso relativa al paquete del archivo coincide con cualquiera de los patrones include y ninguno de los exclude patrones.

Las listas include y exclude contienen patrones de ruta de acceso que son relativos al paquete actual. Cada patrón puede constar de uno o más segmentos de ruta de acceso. Como es habitual con las rutas de acceso de Unix, estos segmentos están separados por /. Los segmentos del patrón coinciden con los segmentos de la ruta de acceso. Los segmentos pueden contener el comodín *, que coincide con cualquier substring en el segmento de ruta de acceso (incluso la substring vacía), excepto el separador de directorio /. Este comodín se puede usar varias veces dentro de un segmento de ruta de acceso. Además, el comodín ** puede coincidir con cero o más segmentos de ruta de acceso completos, pero debe declararse como un segmento de ruta de acceso independiente.

• foo/bar.txt coincide exactamente con el archivo foo/bar.txt de este paquete (a menos que foo/ sea un subpaquete).
• foo/*.txt coincide con todos los archivos del directorio foo/ si el archivo termina con .txt (a menos que foo/ sea un subpaquete).
• foo/a*.htm* coincide con todos los archivos del foo/ directorio que comienzan con a, luego tienen una cadena arbitraria (podría estar vacía), luego tienen .htm y terminan con otra cadena arbitraria (a menos que foo/ sea un subpaquete), como foo/axx.htm y foo/a.html o foo/axxx.html.
• foo/* coincide con todos los archivos del directorio foo/ (a menos que foo/ sea un subpaquete). No coincide con el directorio foo en sí, incluso si exclude_directories está configurado en 0.
• foo/** coincide con todos los archivos de todos los subdirectorios que no son subpaquetes en el subdirectorio de primer nivel del paquete foo/. Si exclude_directories está configurado en 0, foo el directorio también coincide con el patrón. En este caso, se considera que ** coincide con cero segmentos de ruta de acceso.
• **/a.txt coincide con los archivos a.txt en el directorio de este paquete , además de los subdirectorios que no son subpaquetes.
• **/bar/**/*.txt coincide con todos los archivos .txt de todos los subdirectorios que no son subpaquetes de este paquete, si al menos un directorio de la ruta de acceso resultante se llama bar, como xxx/bar/yyy/zzz/a.txt o bar/a.txt (recuerda que ** también coincide con cero segmentos) o bar/zzz/a.txt
• ** coincide con todos los archivos de todos los subdirectorios que no son subpaquetes de este paquete.
• foo**/a.txt es un patrón no válido, ya que ** debe ser independiente como segmento.
• foo/ es un patrón no válido, ya que el segundo segmento definido después de / es una cadena vacía.

Si el argumento exclude_directories está habilitado (establecido en 1), los archivos de tipo directorio se omitirán de los resultados (valor predeterminado 1).

Si el allow_empty argumento se establece en False, la glob función mostrará un error si el resultado fuera la lista vacía.

Existen varias limitaciones y advertencias importantes:

1. Dado que glob() se ejecuta durante la evaluación del archivo BUILD, glob() solo coincide con los archivos de tu árbol de origen, nunca archivos generados. Si compilas un objetivo que requiere archivos fuente y generados, debes agregar una lista explícita de archivos generados al glob. Consulta el ejemplo siguiente con :mylib y :gen_java_srcs.

2. Si una regla tiene el mismo nombre que un archivo fuente coincidente, la regla "ocultará" el archivo.

   Para comprender esto, recuerda que glob() muestra una lista de rutas de acceso, por lo que usar glob() en el atributo de otras reglas (p.ej., srcs = glob(["*.cc"])) tiene el mismo efecto que enumerar las rutas de acceso coincidentes de forma explícita. Si, por ejemplo, glob() produce ["Foo.java", "bar/Baz.java"] pero también hay una regla en el paquete llamada "Foo.java" (lo que se permite, aunque Bazel advierte sobre ello), entonces el consumidor de glob() usará la regla "Foo.java" (sus resultados) en lugar del archivo "Foo.java". Consulta el problema #10395 de GitHub para obtener más detalles.

3. Los globs pueden coincidir con archivos en subdirectorios. Además, los nombres de los subdirectorios pueden tener comodines. Sin embargo…

4. Las etiquetas no pueden cruzar el límite del paquete, y el glob no coincide con los archivos de los subpaquetes.

   Por ejemplo, la expresión glob **/*.cc en el paquete x no incluye x/y/z.cc si x/y existe como paquete (ya sea como x/y/BUILD o en otro lugar de la ruta de acceso del paquete). Esto significa que el resultado de la expresión glob depende de la existencia de archivos BUILD, es decir, la misma expresión glob incluiría x/y/z.cc si no hubiera un paquete llamado x/y o si se marcara como borrado con la --deleted_packages marca.

5. La restricción anterior se aplica a todas las expresiones glob, sin importar qué comodines usen.
6. Un archivo oculto con un nombre de archivo que comienza con . coincide por completo con ambos comodines ** y *. Si deseas que coincida un archivo oculto con un patrón compuesto, tu patrón debe comenzar con un .. Por ejemplo, * y .*.txt coincidirán con .foo.txt, pero *.txt no. Los directorios ocultos también coinciden de la misma manera. Los directorios ocultos pueden incluir archivos que no son necesarios como entradas y pueden aumentar la cantidad de archivos globbed innecesarios y el consumo de memoria. Para excluir directorios ocultos, agrégalos al argumento de la lista "exclude".
7. El comodín "**" tiene un caso extremo: el patrón "**" no coincide con la ruta de acceso del directorio del paquete. Es decir, glob(["**"], exclude_directories = False) coincide con todos los archivos y directorios de forma transitiva estrictamente en el directorio del paquete actual (pero, por supuesto, no ingresa en los directorios de los subpaquetes; consulta la nota anterior al respecto).

En general, debes intentar proporcionar una extensión adecuada (p.ej., *.html) en lugar de usar un '*' sin formato para un patrón glob. El nombre más explícito se documenta automáticamente y garantiza que no coincidas accidentalmente con archivos de copia de seguridad ni archivos de guardado automático de emacs/vi/etc.

Cuando escribes reglas de compilación, puedes enumerar los elementos del glob. Esto permite generar reglas individuales para cada entrada, por ejemplo. Consulta la sección de ejemplo de glob expandido que se incluye más abajo.

Ejemplos de glob

Crea una biblioteca de Java compilada a partir de todos los archivos Java de este directorio, y todos los archivos generados por la regla :gen_java_srcs.

java_library(
    name = "mylib",
    srcs = glob(["*.java"]) + [":gen_java_srcs"],
    deps = "...",
)

genrule(
    name = "gen_java_srcs",
    outs = [
        "Foo.java",
        "Bar.java",
    ],
    ...
)

Incluye todos los archivos txt en el directorio testdata, excepto experimental.txt. Ten en cuenta que no se incluirán los archivos de los subdirectorios de testdata. Si deseas que se incluyan esos archivos, usa un glob recursivo (**).

sh_test(
    name = "mytest",
    srcs = ["mytest.sh"],
    data = glob(
        ["testdata/*.txt"],
        exclude = ["testdata/experimental.txt"],
    ),
)

Ejemplos de glob recursivo

Haz que la prueba dependa de todos los archivos txt del directorio testdata y de cualquiera de sus subdirectorios (y sus subdirectorios, y así sucesivamente). Se ignoran los subdirectorios que contienen un archivo BUILD. (Consulta las limitaciones y advertencias anteriores).

sh_test(
    name = "mytest",
    srcs = ["mytest.sh"],
    data = glob(["testdata/**/*.txt"]),
)

Crea una biblioteca compilada a partir de todos los archivos Java de este directorio y todos los subdirectorios, excepto aquellos cuya ruta de acceso incluye un directorio llamado testing. Se debe evitar este patrón si es posible, ya que puede reducir la incrementalidad de la compilación y, por lo tanto, aumentar los tiempos de compilación.

java_library(
    name = "mylib",
    srcs = glob(
        ["**/*.java"],
        exclude = ["**/testing/**"],
    ),
)

Ejemplos de glob expandido

Crea una genrule individual para *_test.cc en el directorio actual que cuente la cantidad de líneas del archivo.

# Conveniently, the build language supports list comprehensions.
[genrule(
    name = "count_lines_" + f[:-3],  # strip ".cc"
    srcs = [f],
    outs = ["%s-linecount.txt" % f[:-3]],
    cmd = "wc -l $< >$@",
 ) for f in glob(["*_test.cc"])]

Si el archivo BUILD anterior está en el paquete //foo y el paquete contiene tres archivos coincidentes, a_test.cc, b_test.cc y c_test.cc, ejecutar bazel query '//foo:all' mostrará todas las reglas que se generaron:

$ bazel query '//foo:all' | sort
//foo:count_lines_a_test
//foo:count_lines_b_test
//foo:count_lines_c_test

select

select(
    {conditionA: valuesA, conditionB: valuesB, ...},
    no_match_error = "custom message"
)

select() es la función auxiliar que hace que un atributo de regla configurable. Puede reemplazar el lado derecho de casi cualquier asignación de atributos, de modo que su valor dependa de las marcas de Bazel de la línea de comandos. Puedes usar esto, por ejemplo, para definir dependencias específicas de la plataforma o para incorporar diferentes recursos según si una regla se compila en modo "desarrollador" vs. "versión".

El uso básico es el siguiente:

sh_binary(
    name = "mytarget",
    srcs = select({
        ":conditionA": ["mytarget_a.sh"],
        ":conditionB": ["mytarget_b.sh"],
        "//conditions:default": ["mytarget_default.sh"]
    })
)

Esto hace que el atributo srcs de un sh_binary sea configurable reemplazando su asignación normal de lista de etiquetas por una llamada select que asigna condiciones de configuración a valores coincidentes. Cada condición es una referencia de etiqueta a un config_setting o constraint_value, que "coincide" si la configuración del objetivo coincide con un conjunto de valores esperado. El valor de mytarget#srcs se convierte en la lista de etiquetas que coincida con la invocación actual.

Notas:

• Se selecciona exactamente una condición en cualquier invocación.
• Si coinciden varias condiciones y una es una especialización de las otras, la especialización tiene prioridad. La condición B se considera una especialización de la condición A si B tiene las mismas marcas y valores de restricción que A, además de algunas marcas o valores de restricción adicionales. Esto también significa que la resolución de especialización no está diseñada para crear un orden como se muestra en el Ejemplo 2 a continuación.
• Si coinciden varias condiciones y una no es una especialización de todas las demás, Bazel falla con un error, a menos que todas las condiciones se resuelvan en el mismo valor.
• Se considera que la pseudoetiqueta especial //conditions:default coincide si no coincide ninguna otra condición. Si se omite esta condición, debe coincidir alguna otra regla para evitar un error.
• select se puede incorporar dentro de una asignación de atributos más grande. Por lo tanto, srcs = ["common.sh"] + select({ ":conditionA": ["myrule_a.sh"], ...}) y srcs = select({ ":conditionA": ["a.sh"]}) + select({ ":conditionB": ["b.sh"]}) son expresiones válidas.
• select funciona con la mayoría de los atributos, pero no con todos. Los atributos incompatibles se marcan como nonconfigurable en su documentación.

  subpackages

  subpackages(include, exclude=[], allow_empty=True)

  subpackages() es una función auxiliar, similar a glob() que enumera subpaquetes en lugar de archivos y directorios. Usa los mismos patrones de ruta de acceso que glob() y puede coincidir con cualquier subpaquete que sea un descendiente directo del archivo BUILD que se carga actualmente. Consulta glob para obtener una explicación detallada y ejemplos de patrones de inclusión y exclusión.

  La lista resultante de subpaquetes que se muestra está ordenada y contiene rutas de acceso relativas al paquete de carga actual que coinciden con los patrones dados en include y no con los de exclude.

  Ejemplo

  En el siguiente ejemplo, se enumeran todos los subpaquetes directos del paquete foo/BUILD.

  # The following BUILD files exist:
  # foo/BUILD
  # foo/bar/baz/BUILD
  # foo/bar/but/bad/BUILD
  # foo/sub/BUILD
  # foo/sub/deeper/BUILD
  #
  # In foo/BUILD a call to
  subs1 = subpackages(include = ["**"])
  
  # results in subs1 == ["sub", "bar/baz", "bar/but/bad"]
  #
  # 'sub/deeper' is not included because it is a subpackage of 'foo/sub' not of
  # 'foo'
  
  subs2 = subpackages(include = ["bar/*"])
  # results in subs2 = ["bar/baz"]
  #
  # Since 'bar' is not a subpackage itself, this looks for any subpackages under
  # all first level subdirectories of 'bar'.
  
  subs3 = subpackages(include = ["bar/**"])
  # results in subs3 = ["bar/baz", "bar/but/bad"]
  #
  # Since bar is not a subpackage itself, this looks for any subpackages which are
  # (1) under all subdirectories of 'bar' which can be at any level, (2) not a
  # subpackage of another subpackages.
  
  subs4 = subpackages(include = ["sub"])
  subs5 = subpackages(include = ["sub/*"])
  subs6 = subpackages(include = ["sub/**"])
  # results in subs4 and subs6 being ["sub"]
  # results in subs5 = [].
  #
  # In subs4, expression "sub" checks whether 'foo/sub' is a package (i.e. is a
  # subpackage of 'foo').
  # In subs5, "sub/*" looks for subpackages under directory 'foo/sub'. Since
  # 'foo/sub' is already a subpackage itself, the subdirectories will not be
  # traversed anymore.
  # In subs6, 'foo/sub' is a subpackage itself and matches pattern "sub/**", so it
  # is returned. But the subdirectories of 'foo/sub' will not be traversed
  # anymore.
  

  En general, se prefiere que, en lugar de llamar a esta función directamente que los usuarios usen el módulo "subpackages" de skylib.