En esta página, se da por sentado que conoces Bazel y se proporcionan lineamientos y sugerencias para estructurar tus proyectos de modo que aproveches al máximo sus funciones.
Los objetivos generales son los siguientes:
- Para usar dependencias detalladas que permitan el paralelismo y la incrementalidad.
- Para mantener las dependencias bien encapsuladas.
- Para que el código esté bien estructurado y se pueda probar.
- Crear una configuración de compilación que sea fácil de entender y mantener.
Estos lineamientos no son requisitos: pocos proyectos podrán cumplir con todos ellos. Como dice la página man de lint: "Se presentará una recompensa especial a la primera persona por producir un programa real que no produzca errores con una revisión estricta". Sin embargo, incorporar tantos de estos principios como sea posible 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 esta RFC.
Ejecuta compilaciones y pruebas
Un proyecto siempre debe 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 (como requerir marcas de compilación específicas, no compilarse en una plataforma determinada o requerir contratos de licencia) deben etiquetarse de la manera más específica posible (por ejemplo, "requires-osx"). Este etiquetado permite filtrar los destinos a un nivel más detallado que la etiqueta "manual" y permite que alguien que inspeccione el archivo BUILD comprenda cuáles son las restricciones de un destino.
Y las dependencias de terceros
Puedes declarar dependencias de terceros de las siguientes maneras:
- Decláralo como repositorio remoto en el archivo
MODULE.bazel. - También puedes colocarlos en un directorio llamado
third_party/en el directorio de tu lugar de trabajo.
Según los objetos binarios
Siempre que sea posible, todo se debe compilar 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 a partir de sus fuentes y, luego, dependerías de ese destino.
Siempre compilar desde la fuente 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
Prefiere compilar todo el código desde la parte superior siempre que sea posible. Cuando se deben usar versiones, evita incluirlas en el nombre de destino (por ejemplo, //guava, no //guava-20.0). Este nombre 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 diamante: 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 ambas instrucciones a una biblioteca guava, los archivos BUILD son engañosos.
Usa el archivo .bazelrc
Para obtener opciones específicas del proyecto, usa el archivo de configuración tu workspace/.bazelrc (consulta formato bazelrc).
Si deseas admitir opciones por usuario para tu proyecto que no quieres registrar en el control del 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.
Paquetes
Cada directorio que contenga archivos compilables debe ser un paquete. Si un archivo BUILD hace referencia a archivos en subdirectorios (como srcs = ["a/b/C.java"]), es un indicador de que se debe agregar un archivo BUILD a ese subdirectorio. Cuanto más larga sea la estructura, es más probable que se creen dependencias circulares de forma involuntaria, que se cree corrupción el alcance de un objetivo y que se deba actualizar una cantidad cada vez mayor de dependencias inversas.