Guía de estilo .bzl

Informar un problema Ver fuente Noche {/2/}}

En esta página, se abordan los lineamientos de estilo básicos de Starlark y, además, se incluye información sobre macros y reglas.

Starlark es un lenguaje que define cómo se compila el software y, por lo tanto, es un lenguaje de programación y uno de configuración.

Usarás Starlark para escribir archivos BUILD, macros y reglas de compilación. Las macros y reglas son, en esencia, metalenguajes; definen cómo se escriben los archivos BUILD. El objetivo de los archivos BUILD es que sean simples y repetitivos.

Todo el software se lee más seguido de lo que está escrito. Esto se aplica, en especial, a Starlark, ya que los ingenieros leen los archivos BUILD para comprender las dependencias de sus objetivos y los detalles de las compilaciones. Esta lectura suele ocurrir al pasar, con prisa o en paralelo a completar alguna otra tarea. En consecuencia, la simplicidad y la legibilidad son muy importantes para que los usuarios puedan analizar y comprender los archivos BUILD rápidamente.

Cuando un usuario abre un archivo BUILD, quiere conocer rápidamente la lista de destinos del archivo, revisar la lista de fuentes de esa biblioteca de C++ o quitar una dependencia de ese objeto binario de Java. Cada vez que agregas una capa de abstracción, dificultas que un usuario realice estas tareas.

Los archivos BUILD también se analizan y actualizan con muchas herramientas diferentes. Es posible que las herramientas no puedan editar tu archivo BUILD si usa abstracciones. Si usas tus archivos BUILD de forma simple, podrás obtener mejores herramientas. A medida que crece una base de código, es cada vez más frecuente realizar cambios en muchos archivos BUILD para actualizar una biblioteca o realizar una limpieza.

Consejo general

Estilo

Estilo de Python

Si tienes dudas, sigue la guía de estilo PEP 8 siempre que sea posible. En particular, usa cuatro espacios en lugar de dos para que la sangría siga la convención de Python.

Dado que Starlark no es Python, no se aplican algunos aspectos del estilo de Python. Por ejemplo, PEP 8 recomienda que las comparaciones con singletons se realicen con is, que no es un operador en Starlark.

Cadena de documentos

Documenta archivos y funciones con docstrings. Usa una docstring en la parte superior de cada archivo .bzl y una docstring para cada función pública.

Reglas y aspectos de los documentos

Las reglas y los aspectos, junto con sus atributos, así como los proveedores y sus campos, deben documentarse mediante el argumento doc.

Convención para asignar nombres

  • Los nombres de las variables y las funciones usan minúsculas y palabras separadas por guiones bajos ([a-z][a-z0-9_]*), como cc_library.
  • Los valores privados de nivel superior comienzan con un guion bajo. Bazel exige que los valores privados no se puedan usar de otros archivos. Las variables locales no deben usar el prefijo de guion bajo.

Longitudes de línea

Al igual que en los archivos BUILD, no hay un límite estricto de longitud de línea, ya que las etiquetas pueden ser largas. Cuando sea posible, intenta usar un máximo de 79 caracteres por línea (según la guía de estilo de Python, PEP 8). Este lineamiento no debe aplicarse estrictamente: los editores deben mostrar más de 80 columnas, los cambios automatizados suelen introducir líneas más largas y las personas no deberían dedicar tiempo a dividir las líneas que ya son legibles.

Argumentos de palabras clave

En los argumentos de palabras clave, se prefieren los espacios alrededor del signo igual:

def fct(name, srcs):
    filtered_srcs = my_filter(source = srcs)
    native.cc_library(
        name = name,
        srcs = filtered_srcs,
        testonly = True,
    )

Valores booleanos

Da preferencia a los valores True y False (en lugar de 1 y 0) para valores booleanos (como cuando se usa un atributo booleano en una regla).

No uses la función print() en el código de producción, ya que solo está diseñada para la depuración y enviará spam a todos los usuarios indirectos y directos del archivo .bzl. La única excepción es que puedes enviar código que use print() si está inhabilitado de forma predeterminada y solo se puede habilitar editando la fuente, por ejemplo, si todos los usos de print() están protegidos por if DEBUG:, y DEBUG está codificado como False. Ten en cuenta si estas afirmaciones son lo suficientemente útiles como para justificar su impacto en la legibilidad.

Macros

Una macro es una función que crea una instancia de una o más reglas durante la fase de carga. En general, usa reglas siempre que sea posible en lugar de macros. El gráfico de compilación que ve el usuario no es el mismo que usa Bazel durante la compilación. Las macros se expanden antes de que Bazel haga cualquier análisis del gráfico de compilación.

Debido a esto, cuando algo sale mal, el usuario deberá comprender la implementación de la macro para solucionar problemas de compilación. Además, los resultados de bazel query pueden ser difíciles de interpretar porque los objetivos que se muestran en los resultados provienen de la expansión de macros. Por último, los aspectos no tienen en cuenta las macros, por lo que las herramientas según los aspectos (IDE y otros) podrían fallar.

Un uso seguro de las macros es definir destinos adicionales a los que se debe hacer referencia directamente en la CLI de Bazel o en los archivos de COMPILACIÓN. En ese caso, solo los usuarios finales de esos destinos deben conocerlos, y los problemas de compilación que introduzcan las macros nunca están lejos de su uso.

Para las macros que definen objetivos generados (detalles de implementación de la macro a los que no se debe hacer referencia en la CLI o que dependen de destinos que no son de los que se creó una instancia), sigue estas prácticas recomendadas:

  • Una macro debería tomar un argumento name y definir un objetivo con ese nombre. Ese objetivo se convierte en el objetivo principal de la macro.
  • Los objetivos generados, es decir, todos los demás objetivos definidos por una macro, deben cumplir con los siguientes requisitos:
    • Tienen sus nombres con el prefijo <name> o _<name>. Por ejemplo, con name = '%s_bar' % (name).
    • Tienen visibilidad restringida (//visibility:private).
    • Incluye una etiqueta manual para evitar la expansión en destinos comodín (:all, ..., :*, etcétera).
  • El name solo debe usarse para derivar nombres de destinos definidos por la macro, no para nada más. Por ejemplo, no uses el nombre para derivar una dependencia o un archivo de entrada que la macro no haya generado.
  • Todos los destinos creados en la macro deben acoplarse de alguna manera al objetivo principal.
  • Mantén la coherencia de los nombres de los parámetros de la macro. Si un parámetro se pasa como un valor de atributo al destino principal, mantén su nombre. Si el parámetro de una macro tiene el mismo propósito que un atributo de regla común, como deps, asigna un nombre al atributo (consulta a continuación).
  • Cuando llames a una macro, usa solo argumentos de palabras clave. Esto es coherente con las reglas y mejora en gran medida la legibilidad.

Los ingenieros suelen escribir macros cuando la API de Starlark de reglas relevantes es insuficiente para su caso de uso específico, sin importar si la regla se define dentro de Bazel en código nativo o en Starlark. Si tienes este problema, pregúntale al autor de la regla si puede extender la API para lograr tus objetivos.

Como regla general, cuanto más se parezcan las macros a las reglas, mejor.

Consulta también las macros.

Reglas

  • Las reglas, los aspectos y sus atributos deben usar nombres en minúscula (“snake case”).
  • Los nombres de las reglas son sustantivos que describen el tipo principal de artefacto que produce la regla desde el punto de vista de sus dependencias (o, para las reglas de hoja, el usuario). No es necesariamente un sufijo de archivo. Por ejemplo, una regla que produce artefactos de C++ destinados a usarse como extensiones de Python podría llamarse py_extension. Para la mayoría de los lenguajes, las reglas típicas incluyen las siguientes:
    • *_library: Es una unidad o "módulo" de compilación.
    • *_binary: Es un destino que produce un ejecutable o una unidad de implementación.
    • *_test: Es un objetivo de prueba. Esto puede incluir varias pruebas. Puedes esperar que todas las pruebas de un destino *_test sean variaciones del mismo tema, por ejemplo, probar una sola biblioteca.
    • *_import: Un destino que encapsula un artefacto compilado previamente, como un .jar o un .dll que se usa durante la compilación.
  • Usa nombres y tipos coherentes para los atributos. Entre los atributos que se aplican de manera general, se incluyen los siguientes:
    • srcs: label_list, lo que permite archivos de origen, que suelen ser creados por personas.
    • deps: label_list, por lo general, no permite archivos: dependencias de compilación.
    • data: label_list, lo que permite archivos, como archivos de datos, como datos de prueba, etcétera
    • runtime_deps: label_list: Son dependencias del entorno de ejecución que no se necesitan para la compilación.
  • En el caso de los atributos con comportamiento no evidente (por ejemplo, plantillas de cadenas con sustituciones especiales o herramientas que se invoquen con requisitos específicos), proporciona documentación con el argumento de palabra clave doc en la declaración del atributo (attr.label_list() o similar).
  • Las funciones de implementación de reglas casi siempre deben ser funciones privadas (nombradas con un guion bajo inicial). Un estilo común consiste en asignar el nombre _myrule_impl a la función de implementación para myrule.
  • Pasa información entre tus reglas mediante una interfaz provider bien definida. Declara y documenta los campos del proveedor.
  • Diseña la regla teniendo en cuenta la extensibilidad. Ten en cuenta que es posible que otras reglas quieran interactuar con ella, acceder a los proveedores y reutilizar las acciones que crees.
  • Sigue los lineamientos de rendimiento en tus reglas.