Funciones

Contenido

• paquete
• package_group
• exports_files
• glob
• seleccionar
• subpaquetes

paquete

package(default_deprecation, default_testonly, default_visibility, features)

Esta función declara los metadatos que se aplican a todas las reglas subsiguientes del . Se utiliza como máximo una vez dentro de un paquete (archivo BUILD).

La función package() debe llamarse inmediatamente después de todas las sentencias load() en la parte superior de la antes de cualquier regla.

Argumentos

Atributo	Descripción
default_visibility	List of labels; optional La visibilidad predeterminada de las reglas en este paquete. Cada regla de este paquete tiene la visibilidad especificada en este a menos que se especifique lo contrario en el visibility de la regla. Para obtener información detallada sobre la sintaxis de esta consulta la documentación de visibilidad. La visibilidad predeterminada del paquete no se aplica a exports_files, que es pública de forma predeterminada.
default_deprecation	String; optional Establece el predeterminado Mensaje deprecation para todas las reglas de este paquete.
default_testonly	Boolean; optional; default is False except as noted Establece el predeterminado La propiedad testonly para todas las reglas de este paquete. En los paquetes de javatests, el valor predeterminado es 1.
features	List strings; optional Configura varias marcas que afectan la semántica de este archivo BUILD. Esta función es utilizada principalmente por las personas que trabajan en el sistema de compilación para etiqueta paquetes que necesitan algún tipo de manejo especial. No uses esta opción, a menos que solicitado explícitamente por alguien que trabaja en el sistema de compilación.

Ejemplos

En la declaración que aparece a continuación, se declara que las reglas de este paquete se visible solo para los miembros del paquete grupo //foo:target. Declaraciones de visibilidad individuales en una regla, si está presente, anulará esta especificación.

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

package_group

package_group(name, packages, includes)

Esta función define un conjunto de packages. y asocia una etiqueta al conjunto. Se puede hacer referencia a la etiqueta en visibility.

Los grupos de paquetes se usan principalmente para el control de visibilidad. Es visible para el público destino desde cada paquete del árbol del código fuente. Un servicio privado solo se puede hacer referencia al destino visible dentro de su propio paquete (no de los subpaquetes). Entre estos extremos, un destino puede permitir el acceso a su propio paquete y cualquier de los paquetes descritos por uno o más grupos de paquetes. Para obtener información más detallada más detallada sobre el sistema de visibilidad, consulta la visibilidad .

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

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

Argumentos

Atributo	Descripción
name	Name; required Un nombre único para este destino.
packages	List of strings; optional Una lista de cero o más especificaciones del paquete. Cada cadena de especificación del paquete puede tener uno de los siguientes valores Formularios: El nombre completo de un paquete, sin su repositorio, que comienza con un barra doble. Por ejemplo, //foo/bar especifica el paquete. que tenga ese nombre y que se encuentre en el mismo repositorio que el paquete grupo. Como se muestra más arriba, pero con un /... al final. Por ejemplo, //foo/... especifica el conjunto de //foo y todos sus subpaquetes. //... especifica todos los paquetes de la carpeta actual. en un repositorio de confianza. Las cadenas public o private, que especifican respectivamente cada paquete o ningún paquete. (Este formulario requiere la marca --incompatible_package_group_has_public_syntax a configurar). Además, los dos primeros tipos de especificaciones de paquete también pueden tener el prefijo - para indicar que se negaron. El grupo de paquetes contiene cualquier paquete que coincida con al menos uno de sus especificaciones positivas y ninguna de sus especificaciones negativas Por ejemplo, el valor [//foo/..., -//foo/tests/...] incluye todos los subpaquetes de //foo que no son subpaquetes de //foo/tests. (//foo en sí mismo es se incluye mientras que //foo/tests no lo es). Además de la visibilidad pública, no hay forma de especificar directamente fuera del repositorio actual. Si falta este atributo, es lo mismo que establecerlo en un lista vacía, que también es lo mismo que configurarla en una lista que contiene solo private. Nota: Antes de Bazel 6.0, la especificación //... tenían un comportamiento heredado igual a public. Esta el comportamiento se corrige --incompatible_fix_package_group_reporoot_syntax es habilitado, que es la opción predeterminada después de Bazel 6.0. Nota: Antes de Bazel 6.0, este atributo se serializaba como parte de bazel query --output=proto (o --output=xml), se omiten las barras iniciales. Para instancia, //pkg/foo/... se mostrará como \"pkg/foo/...\" Este comportamiento se corrige cuando --incompatible_package_group_includes_double_slash es habilitado, que es la opción predeterminada después de Bazel 6.0.
includes	List of labels; optional Otros grupos de paquetes que se incluyen en este. Las etiquetas de este atributo deben hacer referencia a otros grupos de paquetes. Los paquetes de los grupos de paquetes a los que se hace referencia forman parte de este . Es transitivo; si el grupo de paquetes a incluye el grupo de paquetes b y b. incluye el grupo de paquetes c; entonces, cada paquete de c también será miembro de a. Si se usan junto con las especificaciones del paquete negadas, ten en cuenta que el de paquetes para cada grupo se calcula primero de forma independiente, y las los resultados se unen. Esto significa que los objetivos las especificaciones de un grupo no tienen ningún efecto en las especificaciones de con otro grupo.

Ejemplos

En la siguiente declaración package_group, se 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 un aplicación:

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 que se exportan a otros paquetes.

Es posible que el archivo BUILD para un paquete solo haga referencia directamente a archivos de origen que pertenezcan a a otro paquete si se exportan de forma explícita con un exports_files(). Más información sobre visibilidad de los archivos.

Como comportamiento heredado, también se exportan los archivos mencionados como entrada para una regla. con la visibilidad predeterminada hasta que la marca --incompatible_no_implicit_file_export está invertido. Sin embargo, este comportamiento no se debe confiar ni activamente desde donde se migraron.

Argumentos

El argumento es una lista de nombres de archivos dentro del paquete actual. R También puedes especificar la declaración de visibilidad. en este caso, los archivos serán visibles para los destinos especificados. Si no se especifica la visibilidad, los archivos serán visibles para todos los paquetes, incluso si la visibilidad predeterminada de un paquete especificadas en el package . Las licencias también se pueden especificar.

Ejemplo

En el siguiente ejemplo, se exporta golden.txt, un archivo de texto del paquete test_data, de modo que otros paquetes lo pueden usar, por ejemplo, en el atributo data de 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 busca únicamente archivos de origen (no los archivos generados ni otros objetivos).

Una etiqueta de archivo de origen se incluye en el resultado si la etiqueta la ruta de acceso coincide con cualquiera de los patrones include y ninguno de los Patrones de exclude.

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

Ejemplos:

• foo/bar.txt coincide exactamente con el archivo foo/bar.txt en este paquete
• 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 de foo/. que comienza con a, luego tiene una cadena arbitraria (podría estar vacío), entonces tiene .htm y termina con otra cadena arbitraria; como foo/axx.htm y foo/a.html, o foo/axxx.html
• **/a.txt coincide con cada archivo a.txt en cada subdirectorio de este paquete
• **/bar/**/*.txt coincide con cada archivo .txt en cada subdirectorio de este paquete, si al menos un directorio en la ruta resultante se llamada 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 cada subdirectorio de este paquete
• foo**/a.txt no es un patrón válido, porque ** debe se presentan por sí solos como un segmento

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

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

Existen varias limitaciones y advertencias importantes:

1. Como glob() se ejecuta durante la evaluación de archivos BUILD, glob() establece coincidencias solo con los archivos del árbol de fuentes, nunca archivos generados. Si estás creando un objetivo que requiere tanto de origen y los archivos generados, debes agregar una lista explícita de los archivos al glob. Consulta el ejemplo a continuación con :mylib y :gen_java_srcs.

2. Si una regla tiene el mismo nombre que un archivo de origen coincidente, la regla “sombra” el archivo.

   Para entenderlo, recuerda que glob() muestra una lista de rutas de acceso, por lo que usar glob() en otras reglas atributo (p.ej., srcs = glob(["*.cc"])) tiene el mismo efecto que enumerar las rutas coincidentes de forma explícita. Si, por ejemplo, glob() rinde ["Foo.java", "bar/Baz.java"], pero también hay una regla en la paquete llamado "Foo.java" (lo cual está permitido, aunque Bazel lo advierte) entonces, el consumidor de glob() usará el archivo "Foo.java" regla (sus resultados) en lugar de la “Foo.java” . Consulta GitHub error #10395 para obtener más detalles.

3. Los globs pueden coincidir con los archivos en los subdirectorios. Y los nombres de los subdirectorios pueden usar comodines. Sin embargo…

4. Las etiquetas no pueden cruzar el límite del paquete, y glob lo hace. no coinciden con los archivos en 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 del paquete). Esta significa que el resultado de la expresión glob depende del tipo la existencia de archivos BUILD, es decir, la misma expresión glob se incluir x/y/z.cc si no se llamó a un paquete x/y o se marcó como eliminado mediante el elemento --deleted_packages marca.

5. La restricción anterior se aplica a todas las expresiones glob, sin importar qué comodines usan.
6. Un archivo oculto cuyo nombre de archivo comienza con . coincide completamente con los comodines ** y *. Si quieres hacer coincidir un archivo oculto con un patrón compuesto, este debe comenzar con un .. Por ejemplo: * y .*.txt coincidirán con .foo.txt, pero *.txt no lo hará. Los directorios ocultos también se hacen coincidir de la misma manera. Directorios ocultos pueden incluir archivos que no son necesarios como entradas y pueden aumentar la cantidad innecesaria de archivos globulares y el consumo de memoria. Para excluir: directorios ocultos, agrégalos a la sección list.
7. La casilla de verificación "**" comodín tiene una sentencia case: el patrón "**" no coincide con la ruta de acceso al directorio del paquete. Es decir, por ejemplo, glob(["**"], exclude_directories = 0) coincide con todos los archivos y directorios de forma transitiva en el directorio del paquete actual. (pero, por supuesto, no accede a directorios de subpaquetes; consulta la al respecto).

En general, debes intentar proporcionar una extensión adecuada (p.ej., *.html) en lugar de usar “*” para un patrón glob. El nombre más explícito se documenta automáticamente y garantiza que no hagas coincidir accidentalmente archivos guardados automáticamente, o emacs/vi/...

Cuando escribes reglas de compilación, puedes enumerar los elementos del glob. Esta permite generar, por ejemplo, reglas individuales para cada entrada. Consulta la ejemplo de glob expandido a continuación.

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 datos de prueba. 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 recursiva

Se debe hacer que la prueba dependa de todos los archivos txt del directorio testdata y de cualquier archivo de sus subdirectorios (y sus subdirectorios, etc.). Se ignoran los subdirectorios que contienen un archivo BUILD. (Ver limitaciones y las 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 de todos excepto aquellos cuya ruta de acceso incluya un directorio llamado "testing". Si es posible, se debe evitar este patrón, ya que puede reducir la cantidad 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 cuenta el número 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 CREAMIENTO anterior está en el paquete //foo y el paquete contiene tres archivos coincidentes, a_test.cc, b_test.cc y c_test.cc, y luego se ejecutará bazel query '//foo:all' mostrará una lista de 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 crea un atributo de regla. configurable. Puede reemplazar el lado derecho de casi cualquier asignación de atributos, por lo que su valor depende de las marcas de Bazel de la línea de comandos Puedes usarla, por ejemplo, para definir dependencias específicas de la plataforma o Incorporar diferentes recursos en función de si se creó una regla en "desarrollador" y "lanzamiento" .

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 configurable mediante el reemplazo de su etiqueta normal asignación de lista con una llamada select que asigna condiciones de configuración con los valores coincidentes. Cada condición es una etiqueta. referencia a un config_setting o constraint_value, que “coincide” si la configuración del destino coincide con un conjunto esperado de salida. Luego, el valor de mytarget#srcs se convierte en el que sea de etiquetas coincida con la invocación actual.

Notas:

• Se seleccionó exactamente una condición en cualquier invocación.
• Si varias condiciones coinciden y una es una especialización de las demás, prevalece la especialización. La condición B se considera una especialización de la condición A si B tiene las mismas marcas y restricciones como A, más algunas marcas adicionales o valores de restricción. Esto también significa que la resolución de especialización no está diseñada para crear un orden como como se muestra en el ejemplo 2 a continuación.
• Si varias condiciones coinciden y una no es una especialización de todas las Otras, Bazel falla con un error, a menos que todas las condiciones se resuelvan en el mismo valor.
• La seudoetiqueta especial //conditions:default es considera como coincidencia si no coincide ninguna otra condición. Si esta condición se excluya, alguna otra regla debe coincidir para evitar errores.
• select se puede incorporar dentro de una asignación de atributos. 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. Incompatibles están marcados como nonconfigurable en su documentación.

  subpaquetes

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

  subpackages() es una función auxiliar, similar a glob(). que enumera subpaquetes, en lugar de archivos y directorios. Utiliza la misma de ruta de acceso como glob() y puede coincidir con cualquier subpaquete que sea un subordinado directo del archivo BUILD que se carga actualmente. Consulta glob para obtener una explicación detallada y ejemplos de include y excluir patrones.

  La lista resultante de subpaquetes mostrados está en orden y contiene rutas de acceso relativas al paquete de carga actual que coincidan con los patrones dados en include y no en 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/sub/BUILD
  # foo/sub/deeper/BUILD
  #
  # In foo/BUILD a call to
  subs = subpackages(include = ["**"])
  
  # results in subs == ["sub", "bar/baz"]
  #
  # 'sub/deeper' is not included because it is a subpackage of 'foo/sub' not of
  # 'foo'
  

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