Prácticas recomendadas

Informar un problema Ver fuente . Por la noche · 7.3 · 7.2 · 7.1 · 7.0 · 6.5

En esta página, se asume que estás familiarizado con Bazel y se proporcionan lineamientos y consejos sobre cómo estructurar tus proyectos para aprovechar al máximo las funciones de Bazel.

Los objetivos generales son los siguientes:

  • Usar dependencias detalladas para permitir 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.

Estas pautas 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 para producir un programa real que no produzca errores en una verificación estricta". Sin embargo, incorporar muchos 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.

Esta página utiliza los niveles de requisitos descritos en este RFC.

Ejecuta compilaciones y pruebas

Un proyecto siempre debe poder ejecutar bazel build //... y bazel test //... se realizó correctamente en su rama estable. Objetivos necesarios pero no lo hagas en ciertas circunstancias (como cuando se requiera una compilación marcas, no deben crearse en una plataforma determinada, exigir contratos de licencia) deben etiquetada de la forma más específica posible (por ejemplo, “requires-osx”). Esta el etiquetado permite filtrar las orientaciones a un nivel más detallado que el "manual" etiqueta y permite que alguien revise el archivo BUILD para comprender lo que las restricciones de un objetivo.

Y las dependencias de terceros

Puedes declarar dependencias de terceros:

  • Declara los repositorios como repositorios remotos en el archivo WORKSPACE.
  • También puedes colocarlos en un directorio llamado third_party/ en el directorio de tu lugar de trabajo.

Según los objetos binarios

Todo debe compilarse a partir del código fuente siempre que sea posible. Generalmente, esto significa que, en lugar de depender de una biblioteca some-library.so, crearías un BUILD y compila some-library.so a partir de sus fuentes; luego, dependerá de eso objetivo.

Siempre compilar a partir del código fuente garantiza que una compilación no use una biblioteca que se compiló con marcadores incompatibles o con una arquitectura diferente. También hay algunas funciones, como la cobertura, el análisis estático o el análisis dinámico, que solo trabajar en la fuente.

Control de versiones

Es preferible compilar todo el código desde head siempre que sea posible. Cuando las versiones usado, evita incluir la versión en el nombre del destino (por ejemplo, //guava, no //guava-20.0). Este nombre facilita la actualización de la biblioteca (solo una el destino debe actualizarse). También es más resistente a la dependencia de diamantes Problemas: si una biblioteca depende de guava-19.0 y la 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 apuntar ambos objetivos a una biblioteca guava, entonces los archivos BUILD son engañosos.

Usa el archivo .bazelrc

Para opciones específicas del proyecto, usa el archivo de configuración workspace/.bazelrc (consulta el formato bazelrc).

Si deseas admitir opciones por usuario para tu proyecto que no deseas registrar el control de código fuente, incluye la siguiente línea:

try-import %workspace%/user.bazelrc

(o cualquier otro nombre de archivo) en tu archivo workspace/.bazelrc. y agrega user.bazelrc a tu .gitignore.

Paquetes

Cada directorio que contiene archivos compilables debe ser un paquete. Si es un BUILD archivo se refiere a los archivos en subdirectorios (como, srcs = ["a/b/C.java"]), es una señal de que se debe agregar un archivo BUILD a ese subdirectorio. Cuanto más largo existe esta estructura, es probable que las dependencias circulares sean se crea involuntariamente, el alcance del objetivo se verá sigiloso y aumentará la cantidad de dependencias inversas tendrá que actualizarse.