Etiquetas

Informar un problema Ver fuente Nightly · 7.4 . 7.3 · 7.2 · 7.1 · 7.0 · 6.5

Una etiqueta es un identificador para un objetivo. Una etiqueta típica en su versión canónica completa formulario se ve así:

@@myrepo//my/app/main:app_binary

La primera parte de la etiqueta es el nombre del repositorio, @@myrepo. El doble @ la sintaxis significa que se trata de un repositorio canónico name, que es único dentro de espacio de trabajo. Las etiquetas con nombres de repositorio canónicos identifican de forma inequívoca un objetivo, sin importar en qué contexto aparezcan.

A menudo, el nombre del repo canónico es una cadena arcana que se parece a @@rules_java~7.1.0~toolchains~local_jdk Lo que se ve con mayor frecuencia etiquetas con un nombre aparente de repositorio que se ve así:

@myrepo//my/app/main:app_binary

La única diferencia es que el nombre del repositorio tiene el prefijo uno @ en lugar de dos. Hace referencia a un repositorio con el nombre aparente myrepo, que podría ser diferente. según el contexto en el que aparece esta etiqueta.

En el caso típico en que una etiqueta hace referencia al mismo repositorio desde el cual cuando se usa, se puede omitir el nombre del repositorio. Dentro de @@myrepo, la primera la etiqueta suele escribirse como

//my/app/main:app_binary

La segunda parte de la etiqueta es el nombre de paquete no calificado my/app/main, la ruta de acceso al paquete en relación con la raíz del repositorio. Juntos, el nombre del repositorio y el el nombre del paquete no calificado desde el nombre del paquete completamente calificado @@myrepo//my/app/main Cuando la etiqueta hace referencia al mismo paquete en el que se usa, se puede omitir el nombre del paquete (y, de manera opcional, el dos puntos). Por lo tanto, dentro de @@myrepo//my/app/main, esta etiqueta se puede escribir de las siguientes maneras:

app_binary
:app_binary

Por regla general, se omiten los dos puntos en los archivos, pero se retendrá para las reglas, pero que de otro modo no sea significativo.

La parte de la etiqueta después de los dos puntos, app_binary es el objetivo no calificado de la fuente de datos. Cuando coincide con el último componente de la ruta del paquete, este y el dos puntos, puede omitirse. Por lo tanto, estas dos etiquetas son equivalentes:

//my/app/lib
//my/app/lib:lib

El nombre de un destino de archivo en un subdirectorio del paquete es la ruta de acceso del archivo en relación con la raíz del paquete (el directorio que contiene el archivo BUILD). Por lo tanto, este archivo se encuentra en el subdirectorio my/app/main/testdata del repositorio:

//my/app/main:testdata/input.txt

Las cadenas como //my/app y @@some_repo//my/app tienen dos significados dependiendo de el contexto en el que se usan: cuando Bazel espera una etiqueta, significan //my/app:app y @@some_repo//my/app:app, respectivamente. Sin embargo, cuando Bazel espera un paquete (p. ej., en las especificaciones de package_group), hace referencia al paquete que contiene esa etiqueta.

Un error común en los archivos BUILD es usar //my/app para hacer referencia a un paquete o a todos los destinos de un paquete, lo que no es correcto. Recuerda que es equivalente a //my/app:app, por lo que nombra el destino app en el my/app del repositorio actual.

Sin embargo, se recomienda el uso de //my/app para hacer referencia a un paquete en la especificación de un archivo package_group o .bzl, ya que comunica claramente que el nombre del paquete es absoluto y se encuentra en el directorio de nivel superior del espacio de trabajo.

Las etiquetas relativas no se pueden usar para hacer referencia a destinos en otros paquetes. En este caso, siempre se deben especificar el identificador del repositorio y el nombre del paquete. Por ejemplo, si el árbol de origen contiene el paquete my/app y el paquete my/app/testdata (cada uno de estos dos directorios tiene su propio archivo BUILD), el último paquete contiene un archivo llamado testdepot.zip. Aquí hay dos formas (una incorrecta y una correcta) de referirse a este archivo dentro de //my/app:BUILD

Incorrecto: testdata es un paquete diferente, por lo que no puedes usar una ruta de acceso relativa.

testdata/testdepot.zip

Correcto: Consulta testdata con su ruta completa

//my/app/testdata:testdepot.zip

Las etiquetas que comienzan con @@// son referencias a la clave principal de código abierto, que seguirá funcionando incluso desde repositorios externos. Por lo tanto, @@//a/b/c es diferente de //a/b/c cuando se hace referencia a él desde un repositorio externo. El primero hace referencia al repositorio principal, mientras que el segundo Busca //a/b/c en el repositorio externo. Esto resulta especialmente relevante cuando se escriben reglas en el archivo repositorio que se refiera a destinos en el repositorio principal y será usarse en repositorios externos.

Para obtener información sobre las diferentes formas en que puedes hacer referencia a los objetivos, consulta patrones del objetivo.

Especificación léxica de una etiqueta

La sintaxis de la etiqueta desalienta el uso de metacaracteres que tienen un significado especial para las etiquetas shell. Esto ayuda a evitar problemas de comillas involuntarias y facilita la construcción de herramientas y secuencias de comandos que manipulan etiquetas, como el Lenguaje de consulta de Bazel.

A continuación, se incluyen los detalles precisos de los nombres de destino permitidos.

Nombres de destino: package-name:target-name

target-name es el nombre del destino dentro del paquete. El nombre de una regla Es el valor del atributo name en la declaración de la regla en un elemento BUILD. file; el nombre de un archivo es su nombre de ruta en relación con el directorio que contiene el archivo BUILD.

Los nombres de destino deben estar compuestos en su totalidad por caracteres extraídos del conjunto a-z, AZ, 09 y los símbolos de puntuación !%-@^_"#$&'()*-+,;<=>?[]{|}~/..

Los nombres de archivo deben ser rutas de acceso relativas en formato normal, lo que significa que no deben comenzar ni terminar con una barra diagonal (por ejemplo, /foo y foo/ están prohibidas) ni contener varias barras diagonales consecutivas como separadores de ruta (por ejemplo, foo//bar). Del mismo modo, las referencias de nivel superior (..) y las referencias de directorio actual (./) están prohibidas.

Incorrecto: No uses ".." para hacer referencia a archivos en otros paquetes

Correcto: Uso `//package-name:filename`

Si bien es común usar / en el nombre de un destino de archivo, evita usar / en los nombres de las reglas. Esto puede confundir al lector, en especial cuando se usa la forma abreviada de una etiqueta. La etiqueta //foo/bar/wiz siempre es una abreviatura para //foo/bar/wiz:wiz, incluso si no existe tal paquete foo/bar/wiz; it nunca hace referencia a //foo:bar/wiz, aunque ese destino exista.

Sin embargo, hay algunas situaciones en las que el uso de una barra resulta conveniente o incluso necesarias. Por ejemplo, el nombre de ciertas reglas debe coincidir con su archivo de origen principal, que puede residir en un subdirectorio del paquete.

Nombres de paquetes: //package-name:target-name

El nombre de un paquete es el nombre del directorio que contiene su archivo BUILD, en relación con el directorio de nivel superior del repositorio que lo contiene. Por ejemplo: my/app.

Los nombres de los paquetes deben estar compuestos por caracteres del conjunto A-Z, a-z, 0-9, /, -, ., @ y _, y no pueden comenzar con una barra.

Para un lenguaje con una estructura de directorio importante para su módulo (por ejemplo, Java), es importante elegir nombres de directorios que sean identificadores válidos en el idioma.

Aunque Bazel admite destinos en el paquete raíz del espacio de trabajo (por ejemplo, //:foo), es mejor dejar ese paquete vacío para que todos los paquetes significativos tengan nombres descriptivos.

Los nombres de los paquetes no pueden contener la subcadena // ni terminar con una barra diagonal.

Reglas

Una regla especifica la relación entre las entradas y salidas, y los pasos para compilar los resultados. Las reglas pueden ser de muchos tipos diferentes (a veces, llamadas clase de reglas), que producen bibliotecas y ejecutables compilados, ejecutables de prueba y otros resultados compatibles, como se describe en la Enciclopedia de compilación.

Los archivos BUILD declaran destinos invocando reglas.

En el siguiente ejemplo, vemos la declaración del my_app de destino. con la regla cc_binary.

cc_binary(
    name = "my_app",
    srcs = ["my_app.cc"],
    deps = [
        "//absl/base",
        "//absl/strings",
    ],
)

Cada invocación de regla tiene un atributo name (que debe ser un nombre de destino válido) que declara un destino dentro del paquete del archivo BUILD.

Cada regla tiene un conjunto de atributos. Los atributos aplicables para una regla determinada y el significado y la semántica de cada atributo son una función del tipo de regla. Consulta la Enciclopedia de compilación para obtener una lista de reglas y sus atributos correspondientes. Cada atributo tiene un nombre y un tipo. Algunos de los tipos comunes que puede tener un atributo son números enteros, etiquetas y listas. de etiquetas, cadena, lista de cadenas, etiqueta de salida, lista de etiquetas de salida. No todos los atributos deben especificarse en cada regla. Así, los atributos forman un diccionario desde claves (nombres) hasta valores opcionales escritos.

El atributo srcs presente en muchas reglas tiene el tipo "lista de etiquetas". Su valor, si está presente, es una lista de etiquetas, cada una de las cuales es el nombre de un objetivo que es una entrada para esta regla.

En algunos casos, el nombre del tipo de regla es algo arbitrario, y lo más interesante son los nombres de los archivos que genera la regla, y esto es cierto para genrules. Para obtener más información, consulta Reglas generales: genrule.

En otros casos, el nombre es significativo: por ejemplo, en el caso de las reglas *_binary y *_test, el nombre de la regla determina el nombre del ejecutable que produce la compilación.

Este grafo acíclico dirigido sobre los destinos se denomina grafo de destino o grafo de dependencias de compilación, y es el dominio sobre el que opera la herramienta de consulta de Bazel.

Destinos Archivos BUILD