En esta página, se supone que estás familiarizado con Bazel y se proporcionan lineamientos y sugerencias para estructurar tus proyectos y aprovechar al máximo las funciones de Bazel.
Los objetivos generales son los siguientes:
- Usar dependencias detalladas para permitir el paralelismo y la incrementalidad
- Mantener las dependencias bien encapsuladas
- Crear código bien estructurado y que se pueda probar
- Crear una configuración de compilación que sea fácil de comprender y mantener
Estos lineamientos no son requisitos: pocos proyectos podrán cumplir todos. Como dice la página del manual de lint, "Se otorgará una recompensa especial a la primera persona que produzca un programa real que no genere errores con una verificación estricta." Sin embargo, incorporar la mayor cantidad posible de estos principios debería hacer que un proyecto sea más legible, menos propenso a errores y más rápido de compilar.
En esta página, se usan los niveles de requisitos que se describen en este RFC.
Cómo ejecutar compilaciones y pruebas
Un proyecto siempre debería poder ejecutar bazel build //... y
bazel test //... correctamente en su rama estable. Los destinos que son necesarios
pero que no se compilan en determinadas circunstancias (por ejemplo, requieren marcas de compilación
específicas, no se compilan en una plataforma determinada o requieren acuerdos de licencia) deben etiquetarse de la manera más
específica posible (por ejemplo, "requires-osx"). Este
etiquetado permite que los destinos se filtren en un nivel más detallado que la etiqueta
"manual" y permite que alguien que inspecciona el archivo BUILD comprenda cuáles son las
restricciones de un destino.
Y las dependencias de terceros
Puedes declarar dependencias de terceros de la siguiente manera:
- Decláralas como repositorios remotos en el
MODULE.bazelarchivo. - O bien, colócalas en un directorio llamado
third_party/en el directorio de tu espacio de trabajo.
Dependencia de objetos binarios
Siempre que sea posible, todo debe compilarse desde la fuente. Por lo general, esto significa
que, en lugar de depender de una biblioteca some-library.so, crearías un archivo
BUILD y compilarías some-library.so desde sus fuentes y, luego, dependerías de ese
destino.
La compilación desde la fuente siempre garantiza que una compilación no use una biblioteca que se compiló con marcas incompatibles o una arquitectura diferente. También hay algunas funciones, como la cobertura, el análisis estático o el análisis dinámico, que solo funcionan en la fuente.
Control de versiones
Siempre que sea posible, es preferible compilar todo el código desde el encabezado. Cuando se deben
usar versiones, evita incluir la versión en el nombre del destino (por ejemplo, //guava, no //guava-20.0). Esta denominación facilita la actualización de la biblioteca (solo se debe actualizar un
destino). También es más resistente a los problemas de dependencia de diamantes: si una biblioteca depende de guava-19.0 y otra depende de guava-20.0,
podrías terminar con una biblioteca que intenta depender de dos versiones diferentes.
Si creaste un alias engañoso para dirigir ambos destinos a una guava biblioteca,
los archivos BUILD son engañosos.
Cómo usar el archivo .bazelrc
Para las opciones específicas del proyecto, usa el archivo de configuración tu
workspace/.bazelrc (consulta el formato bazelrc).
Si deseas admitir opciones por usuario para tu proyecto que no deseas registrar en el control de código fuente, incluye la siguiente línea:
try-import %workspace%/user.bazelrc
(o cualquier otro nombre de archivo) en tu workspace/.bazelrc
y agrega user.bazelrc a tu .gitignore.
El archivo bazelrc-preset.bzl {: .external} de código abierto genera un archivo bazelrc personalizado que coincide con tu versión de Bazel y proporciona un conjunto preestablecido de marcas recomendadas.
Paquetes
Cada directorio que contiene archivos compilables debe ser un paquete. Si un archivo BUILD
hace referencia a archivos en subdirectorios (por ejemplo, srcs = ["a/b/C.java"]), es
un signo de que se debe agregar un archivo BUILD a ese subdirectorio. Cuanto más tiempo
exista esta estructura, más probable será que se creen dependencias circulares de forma
inadvertida, que el alcance de un destino se extienda y que se deba actualizar una cantidad cada vez mayor
de dependencias inversas.