En esta página, se supone que conoces 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
- Para que el código esté bien estructurado y 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 cumplirlos todos. Como se indica en 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 la 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.
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 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 filtrar los destinos en un nivel más detallado que la etiqueta "manual" y permite que quien inspecciona el archivo BUILD comprenda cuáles son las restricciones de un destino.
Y las dependencias de terceros
Puedes declarar dependencias de terceros:
- Decláralos como repositorios remotos en el archivo
MODULE.bazel. - O bien, colócalos 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 a partir de sus fuentes, y luego dependerías de ese destino.
Compilar siempre desde el código 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 el código fuente.
Control de versiones
Siempre que sea posible, prefiere compilar todo el código desde el encabezado. Cuando se deban usar versiones, evita incluir la versión en el nombre del destino (por ejemplo, //guava, no //guava-20.0). Esta convención de nomenclatura facilita la actualización de la biblioteca (solo se debe actualizar un destino). También es más resistente a los problemas de dependencias en forma 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 que ambos destinos apunten a una biblioteca guava, 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 de tu workspace/.bazelrc (consulta el formato de bazelrc).
Si quieres admitir opciones por usuario para tu proyecto que no quieres 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 de código abierto bazelrc-preset.bzl {: .external} genera un archivo bazelrc personalizado que coincide con tu versión de Bazel y proporciona un conjunto predeterminado de marcas recomendadas.
Paquetes
Cada directorio que contiene archivos compilables debe ser un paquete. Si un archivo BUILD hace referencia a archivos en subdirectorios (como srcs = ["a/b/C.java"]), es señal 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.