Lugares de trabajo, paquetes y objetivos

Bazel compila software a partir del código fuente organizado en un árbol de directorios llamado lugar de trabajo. Los archivos de origen en el lugar de trabajo están organizados en una jerarquía de paquetes anidada. Cada paquete es un directorio que contiene un conjunto de archivos fuente relacionados y un archivo BUILD. El archivo BUILD especifica qué salidas de software se pueden compilar desde la fuente.

Lugar de trabajo

Un lugar de trabajo es un árbol de directorios de tu sistema de archivos que contiene los archivos de origen del software que deseas compilar. Cada lugar de trabajo tiene un archivo de texto llamado WORKSPACE que puede estar vacío o puede contener referencias a dependencias externas necesarias para compilar los resultados.

Los directorios que contienen un archivo llamado WORKSPACE se consideran la raíz de un lugar de trabajo. Por lo tanto, Bazel ignora cualquier árbol de directorio de un lugar de trabajo que tenga permisos de administrador en un subdirectorio que contenga un archivo WORKSPACE, ya que forman otro lugar de trabajo.

Bazel también admite archivos WORKSPACE.bazel como alias de archivos WORKSPACE. Si ambos archivos existen, se usa WORKSPACE.bazel.

Repositorios

El código se organiza en repositorios. El directorio que contiene el archivo WORKSPACE es la raíz del repositorio principal, también llamado @. Otros repositorios (externos) se definen en el archivo WORKSPACE con reglas de lugar de trabajo.

Las reglas del lugar de trabajo incluidas en Bazel están documentadas en la sección Reglas de lugar de trabajo en la Enciclopedia de compilación y en la documentación sobre las reglas del repositorio de Starlark incorporadas.

Como los repositorios externos son repositorios en sí mismos, a menudo también contienen un archivo WORKSPACE. Sin embargo, Bazel ignora estos archivos WORKSPACE adicionales. En particular, los repositorios que dependen de forma transitiva no se agregan automáticamente.

Paquetes

La unidad principal de la organización de código en un repositorio es el paquete. Un paquete es una colección de archivos relacionados y una especificación de cómo se pueden usar para producir artefactos de salida.

Un paquete se define como un directorio que contiene un archivo llamado BUILD (o BUILD.bazel). Un paquete incluye todos los archivos en su directorio, más todos los subdirectorios de este, excepto aquellos que contienen un archivo BUILD. A partir de esta definición, ningún archivo o directorio puede formar parte de dos paquetes diferentes.

Por ejemplo, en el siguiente árbol de directorio hay dos paquetes, my/app y el subpaquete my/app/tests. Ten en cuenta que my/app/data no es un paquete, sino un directorio que pertenece al paquete my/app.

src/my/app/BUILD
src/my/app/app.cc
src/my/app/data/input.txt
src/my/app/tests/BUILD
src/my/app/tests/test.cc

Destinos

Un paquete es un contenedor de objetivos, que se definen en el archivo BUILD del paquete. La mayoría de los destinos son de dos tipos principales, files y rules.

Los archivos se dividen en dos tipos. Por lo general, los archivos fuente se escriben con esfuerzo de las personas y se registran en el repositorio. Los archivos generados, a veces llamados archivos derivados, o archivos de salida, no se registran, pero se generan a partir de archivos de origen.

El segundo tipo de objetivo se declara con una regla. Cada instancia de regla especifica la relación entre un conjunto de entradas y un conjunto de archivos de salida. Las entradas de una regla pueden ser archivos fuente, pero también pueden ser los resultados de otras reglas.

En la mayoría de los casos, si la entrada a una regla es un archivo de origen o un archivo generado, lo que importa es el contenido de ese archivo. Esto facilita el reemplazo de un archivo fuente complejo por un archivo generado producido por una regla, como cuando la carga de mantener un archivo altamente estructurado se vuelve demasiado tedioso y alguien escribe un programa para derivarlo. Los consumidores de ese archivo no deben realizar ningún cambio. En cambio, un archivo generado puede reemplazarse con facilidad por un archivo de origen solo con cambios locales.

Las entradas de una regla también pueden incluir otras reglas. El significado preciso de dichas relaciones suele ser bastante complejo y depende del lenguaje o las reglas, pero es intuitivamente simple: una regla de biblioteca C++ A podría tener otra regla de biblioteca C++ para una entrada. El efecto de esta dependencia es que los archivos de encabezado de B están disponibles para A durante la compilación, los símbolos de B están disponibles para A durante la vinculación y los datos de tiempo de ejecución de B están disponibles para A durante la ejecución.

Una variante de todas las reglas es que los archivos generados por una regla siempre pertenecen al mismo paquete que la regla; no es posible generar archivos en otro paquete. Sin embargo, no es inusual que las entradas provengan de otro paquete.

Los grupos de paquetes son conjuntos de paquetes cuyo propósito es limitar la accesibilidad de ciertas reglas. Los grupos de paquetes se definen mediante la función package_group. Tienen tres propiedades: la lista de paquetes que contienen, su nombre y otros grupos de paquetes que incluyen. Las únicas formas permitidas de hacer referencia a ellas son desde el atributo visibility de las reglas o desde el atributo default_visibility de la función package; no generan ni consumen archivos. Para obtener más información, consulta la documentación de package_group.

Etiquetas