Contenido
paquete
package(default_deprecation, default_package_metadata, default_testonly, default_visibility, features)
Esta función declara los metadatos que se aplican a cada regla en el paquete. Se usa como máximo una vez en un paquete (archivo BUILD).
Para el equivalente que declara que los metadatos se aplican a cada regla del repositorio completo, usa la función repo()
en el archivo REPO.bazel
ubicado en la raíz del repositorio.
La función repo()
toma exactamente los mismos argumentos que package()
.
Se debe llamar a la función package() inmediatamente después de todas las sentencias load() en la parte superior del archivo, antes de cualquier regla.
Argumentos
Atributo | Descripción |
---|---|
default_applicable_licenses |
Alias de |
default_visibility |
Lista de etiquetas; el valor predeterminado es La visibilidad predeterminada de las reglas en este paquete. Cada regla de este paquete tiene la visibilidad especificada en este atributo, a menos que se especifique lo contrario en el atributo |
default_deprecation |
Cadena; el valor predeterminado es Establece el mensaje
|
default_package_metadata |
Lista de etiquetas; el valor predeterminado es Establece una lista predeterminada de destinos de metadatos que se aplican a todos los demás destinos del paquete. Por lo general, estos son objetivos relacionados con declaraciones de licencia y paquetes de OSS. Consulta rules_license para ver ejemplos. |
default_testonly |
Booleano; el valor predeterminado es Configura la propiedad
En los paquetes de |
features |
Enumera cadenas; el valor predeterminado es Configura varias marcas que afectan la semántica de este archivo BUILD. Esta función es utilizada principalmente por los trabajadores del sistema de compilación para etiquetar paquetes que necesitan algún tipo de manejo especial. No lo uses a menos que alguien que trabaje en el sistema de compilación lo solicite explícitamente. |
Ejemplos
La siguiente declaración declara que las reglas de este paquete solo son visibles para los miembros del grupo de paquetes//foo:target
. Las declaraciones de visibilidad individuales en una regla, si están presentes, anulan esta especificación.
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 los atributos visibility
.
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 en el árbol de fuentes. Solo se puede hacer referencia a un destino 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 más cualquiera de los paquetes descritos por uno o más grupos de paquetes. Para obtener una explicación más detallada del sistema de visibilidad, consulta el atributo visibility.
Se considera que un paquete determinado está en el grupo si coincide con el atributo packages
o si ya está contenido en uno de los otros grupos de paquetes mencionados en el atributo includes
.
Los grupos de paquetes son objetivos técnicos, pero no se crean mediante reglas y no tienen ninguna protección de visibilidad.
Argumentos
Atributo | Descripción |
---|---|
name |
Nombre (obligatorio) Un nombre único para este destino. |
packages |
Lista de cadenas; el valor predeterminado es Una lista de cero o más especificaciones de paquetes. Cada cadena de especificación del paquete puede tener una de las siguientes formas:
Además, los dos primeros tipos de especificaciones de paquetes también pueden tener el prefijo El grupo de paquetes contiene cualquier paquete que coincida con al menos una de sus especificaciones positivas y ninguna de sus especificaciones negativas. Por ejemplo, el valor Además de la visibilidad pública, no hay manera de especificar paquetes directamente fuera del repositorio actual. Si falta este atributo, equivale a configurarlo en una lista vacía, lo que también equivale a configurarlo en una lista que solo contenga Nota: Antes de Bazel 6.0, la especificación Nota: Antes de Bazel 6.0, cuando este atributo se serializa como parte de |
includes |
Lista de etiquetas; el valor predeterminado es Son 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
grupo de paquetes. Es transitivo: si el grupo de paquetes Cuando se usa junto con las especificaciones de paquetes anuladas, ten en cuenta que el conjunto de paquetes para cada grupo se calcula primero de forma independiente y, luego, los resultados se unen. Esto significa que las especificaciones anuladas en un grupo no tienen efecto en las especificaciones de otro grupo. |
Ejemplos
La siguiente declaración package_group
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 que se exportan a otros paquetes.
El archivo BUILD de un paquete solo puede hacer referencia directamente a los archivos de origen que pertenecen a otro paquete si se exportan explícitamente con una declaración exports_files()
. Obtén más información acerca de la visibilidad de los archivos.
Como comportamiento heredado, también los archivos mencionados como entrada a una regla se exportan con la visibilidad predeterminada hasta que se cambia 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 destinos 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 función package
. También se pueden especificar las licencias.
Ejemplo
En el siguiente ejemplo, se exporta golden.txt
, un archivo de texto del paquete test_data
, para 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 patrones de ruta de acceso específicos y muestra una lista nueva, mutable y ordenada de sus rutas de acceso. Glob solo busca archivos en su propio paquete y busca solo archivos de origen (no archivos generados ni otros destinos).
La etiqueta de un archivo de origen se incluye en el resultado si la ruta relativa al paquete del archivo coincide con alguno de los patrones include
y con ninguno de los patrones exclude
.
Las listas include
y exclude
contienen patrones de ruta de acceso relacionados 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 del patrón se comparan con los segmentos de la ruta. Los segmentos pueden contener el comodín *
: coincide con cualquier substring en el segmento de la ruta de acceso (incluso la substring vacía), sin incluir 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 independiente.
foo/bar.txt
coincide exactamente con el archivofoo/bar.txt
de este paquete (a menos quefoo/
sea un subpaquete).foo/*.txt
coincide con todos los archivos del directoriofoo/
si el archivo termina en.txt
(a menos quefoo/
sea un subpaquete).foo/a*.htm*
coincide con cada archivo del directoriofoo/
que comienza cona
, tiene una cadena arbitraria (puede estar vacía), después tiene.htm
y termina con otra cadena arbitraria (a menos quefoo/
sea un subpaquete); comofoo/axx.htm
,foo/a.html
ofoo/axxx.html
foo/*
coincide con todos los archivos del directoriofoo/
(a menos quefoo/
sea un subpaquete); no coincide con el directoriofoo
, incluso siexclude_directories
se establece en 0.foo/**
coincide con cada archivo en cada subdirectorio que no pertenece a subpaquetes en el subdirectorio del primer nivel del paquetefoo/
. Siexclude_directories
se establece en 0, el directoriofoo
también coincide con el patrón. En este caso, se considera que**
coincide con segmentos de la ruta de acceso cero.**/a.txt
coincide con los archivosa.txt
en el directorio de este paquete y en los subdirectorios que no son de subdirectorios.**/bar/**/*.txt
coincide con cada archivo.txt
en cada subdirectorio sin subpaquete de este paquete, si al menos un directorio en la ruta de acceso resultante se llamabar
, comoxxx/bar/yyy/zzz/a.txt
obar/a.txt
(recuerda que**
también coincide con cero segmentos) obar/zzz/a.txt
**
coincide con todos los archivos de cada subdirectorio que no son subpaquetes de este paquete.foo**/a.txt
no es un patrón válido, ya que**
debe interpretarse por sí solo como un segmento.foo/
no es un patrón válido, ya que el segundo segmento definido después de/
es una string vacía.
Si el argumento exclude_directories
está habilitado (establecido en 1), los archivos de tipo de directorio se omitirán de los resultados (valor predeterminado 1).
Si el argumento allow_empty
se establece en False
, la función glob
arrojará un error si el resultado, de lo contrario, sería la lista vacía.
Existen varias limitaciones y advertencias importantes:
-
Como
glob()
se ejecuta durante la evaluación de archivos BUILD,glob()
coincide solo con archivos en tu árbol de fuentes, nunca con archivos generados. Si estás compilando un destino que requiere archivos fuente y generados, debes agregar al glob una lista explícita de los archivos generados. Consulta el siguiente ejemplo con:mylib
y:gen_java_srcs
. -
Si una regla tiene el mismo nombre que un archivo de origen coincidente, la regla “sombrará” el archivo.
Para entender esto, recuerda que
glob()
muestra una lista de rutas de acceso, por lo que usarglob()
en el atributo de otras reglas (p.ej.,srcs = glob(["*.cc"])
) tiene el mismo efecto que enumerar las rutas de acceso coincidentes de manera explícita. Por ejemplo, siglob()
genera["Foo.java", "bar/Baz.java"]
, pero también hay una regla en el paquete llamada "Foo.java" (lo cual está permitido, aunque Bazel advierte al respecto), el consumidor deglob()
usará la regla "Foo.java" (sus resultados) en lugar del archivo "Foo.java". Consulta el problema n.o 10395 de GitHub para obtener más detalles. - Los Globs pueden hacer coincidir archivos en subdirectorios. Y los nombres de subdirectorios pueden usar comodines. Sin embargo…
-
Las etiquetas no pueden cruzar el límite del paquete y glob no coincide con los archivos de los subpaquetes.
Por ejemplo, la expresión glob
**/*.cc
en el paquetex
no incluyex/y/z.cc
six/y
existe como un paquete (ya sea comox/y/BUILD
o en otro lugar de la ruta del paquete). Esto significa que el resultado de la expresión glob en realidad depende de la existencia de archivos BUILD, es decir, la misma expresión glob incluiríax/y/z.cc
si no hubiera un paquete llamadox/y
o si se marcó como borrado con la marca --deleted_packages. - La restricción anterior se aplica a todas las expresiones glob, sin importar los comodines que usen.
-
Un archivo oculto con un nombre de archivo que comienza con
.
coincide completamente con los comodines**
y*
. Si deseas hacer coincidir un archivo oculto con un patrón compuesto, el patrón debe comenzar con un.
. Por ejemplo,*
y.*.txt
coincidirán con.foo.txt
, pero*.txt
no. Los directorios ocultos también se comparan de la misma manera. Los directorios ocultos pueden incluir archivos que no se requieren como entradas y pueden aumentar la cantidad de archivos globados innecesariamente y el consumo de memoria. Para excluir directorios ocultos, agrégalos al argumento de lista "Exclude". -
El comodín "**" tiene un caso límite: el patrón
"**"
no coincide con la ruta de acceso del directorio del paquete. Es decir,glob(["**"], exclude_directories = 0)
coincide de forma transitiva con todos los archivos y directorios del directorio del paquete actual (pero, por supuesto, no ingresa en los directorios de subpaquetes; consulta la nota anterior al respecto).
En general, debes intentar proporcionar una extensión adecuada (p.ej., *.html) en lugar de usar un “*” básico para un patrón glob. El nombre más explícito se documenta a sí mismo y garantiza que no hagas coincidir por accidente archivos de copia de seguridad o archivos de guardado automático emacs/vi/....
Al escribir reglas de compilación, puedes enumerar los elementos del glob. Esto permite generar reglas individuales para cada entrada, por ejemplo. Consulta la sección del ejemplo de glob expandido a continuación.
Ejemplos de glob
Crea una biblioteca 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 en 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 globs recursivos
Haz que la prueba dependa de todos los archivos txt del directorio testdata y de cualquiera de sus subdirectorios (y sus subdirectorios, etc.). Se ignoran los subdirectorios que contienen un archivo BUILD. (consulta las limitaciones y advertencias más arriba).
sh_test( name = "mytest", srcs = ["mytest.sh"], data = glob(["testdata/**/*.txt"]), )
Crear una biblioteca compilada a partir de todos los archivos Java de este directorio y de todos los subdirectorios, excepto aquellos cuya ruta de acceso incluya un directorio llamado Testing. De ser posible, este patrón debe evitarse, ya que puede reducir la incrementalidad de 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 en el 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 se encuentra en el paquete //foo y el paquete contiene tres
archivos coincidentes, a_test.cc, b_test.cc y c_test.cc, entonces se ejecuta
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 hace que un atributo de regla sea 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 usarlo, por ejemplo, para definir dependencias específicas de la plataforma o incorporar diferentes recursos en función de si una regla se compila en el modo de "desarrollador" o de "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
se pueda configurar mediante el reemplazo de 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 destino coincide con un conjunto de valores esperados. Luego, el valor de mytarget#srcs
se convierte en la lista de etiquetas que coincide con la invocación actual.
Notas:
- Se selecciona exactamente una condición en cualquier invocación.
- Si varias condiciones coinciden y una es una especialización de las demás, 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 más algunas marcas o valores de restricción adicionales. Esto también significa que la resolución de la especialización no está diseñada para crear un orden como se muestra en el ejemplo 2 a continuación.
- Si varias condiciones coinciden 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 seudoetiqueta especial
//conditions:default
coincide si no coincide ninguna otra condición. Si esta condición se omite, otra regla debe coincidir para evitar un error. select
se puede incorporar dentro de una asignación de atributo más grande. Por lo tanto,srcs = ["common.sh"] + select({ ":conditionA": ["myrule_a.sh"], ...})
ysrcs = 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 comononconfigurable
en su documentación.subpaquetes
subpackages(include, exclude=[], allow_empty=True)
subpackages()
es una función auxiliar, similar aglob()
, que enumera subpaquetes en lugar de archivos y directorios. Usa los mismos patrones de ruta de acceso queglob()
y puede coincidir con cualquier subpaquete que sea subordinado directo del archivo BUILD que se está cargando en ese momento. 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 muestran está en orden y contiene rutas relacionadas con el paquete de carga actual que coinciden con los patrones indicados en
include
y no con los deexclude
.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 directamente a esta función, los usuarios usen el módulo "subpaquetes" de skylib.