Guía de estilo de BUILD

El formato de los archivos BUILD sigue el mismo enfoque que Go, en el que una herramienta estandarizada se encarga de la mayoría de los problemas de formato. Buildifier es una herramienta que analiza y emite el código fuente con un estilo estándar. Por lo tanto, cada archivo BUILD se formatea de la misma manera automatizada, lo que hace que el formato no sea un problema durante las revisiones de código. También facilita que las herramientas comprendan, editen y generen BUILD archivos.

El formato del archivo BUILD debe coincidir con el resultado de buildifier.

Ejemplo de formato

# Test code implementing the Foo controller.
package(default_testonly = True)

py_test(
    name = "foo_test",
    srcs = glob(["*.py"]),
    data = [
        "//data/production/foo:startfoo",
        "//foo",
        "//third_party/java/jdk:jdk-k8",
    ],
    flaky = True,
    deps = [
        ":check_bar_lib",
        ":foo_data_check",
        ":pick_foo_port",
        "//pyglib",
        "//testing/pybase",
    ],
)

Estructura de archivos

Recomendación: Usa el siguiente orden (cada elemento es opcional):

• Descripción del paquete (un comentario)

• Todas las instrucciones load()

• La función package()

• Llamadas a reglas y macros

Buildifier distingue entre un comentario independiente y un comentario adjunto a un elemento. Si un comentario no está adjunto a un elemento específico, usa una línea vacía después de él. La distinción es importante cuando se realizan cambios automatizados (por ejemplo, para conservar o quitar un comentario cuando se borra una regla).

# Standalone comment (such as to make a section in a file)

# Comment for the cc_library below
cc_library(name = "cc")

Referencias a destinos en el paquete actual

Se debe hacer referencia a los archivos por sus rutas de acceso relativas al directorio del paquete (sin usar nunca referencias ascendentes, como ..). Los archivos generados deben tener el prefijo ":" para indicar que no son fuentes. Los archivos fuente no deben tener el prefijo :. Las reglas deben tener el prefijo :. Por ejemplo, si x.cc es un archivo fuente:

cc_library(
    name = "lib",
    srcs = ["x.cc"],
    hdrs = [":gen_header"],
)

genrule(
    name = "gen_header",
    srcs = [],
    outs = ["x.h"],
    cmd = "echo 'int x();' > $@",
)

Nombres de destino

Los nombres de destino deben ser descriptivos. Si un destino contiene un archivo fuente, el destino generalmente debe tener un nombre derivado de esa fuente (por ejemplo, una cc_library para chat.cc podría llamarse chat, o una java_library para DirectMessage.java podría llamarse direct_message).

El destino homónimo de un paquete (el destino con el mismo nombre que el directorio contenedor) debe proporcionar la funcionalidad que describe el nombre del directorio. Si no existe ese destino, no crees un destino homónimo destino.

Es preferible usar el nombre corto cuando se hace referencia a un destino homónimo (//x en lugar de //x:x). Si estás en el mismo paquete, es preferible la referencia local (:x en lugar de //x).

Evita usar nombres de destino "reservados" que tengan un significado especial. Esto incluye all, __pkg__ y __subpackages__. Estos nombres tienen una semántica especial y pueden causar confusión y comportamientos inesperados cuando se usan.

En ausencia de una convención de equipo predominante, estas son algunas recomendaciones no vinculantes que se usan ampliamente en Google:

• En general, usa "snake_case"
  • Para un java_library con un src, esto significa usar un nombre que no sea el mismo que el nombre de archivo sin la extensión.
  • Para las reglas de Java *_binary y *_test, usa "Upper CamelCase". Esto permite que el nombre de destino coincida con uno de los srcs. Para java_test, esto permite que el atributo test_class se infiera del nombre del destino.
• Si hay varias variantes de un destino en particular, agrega un sufijo para desambiguar (como. :foo_dev, :foo_prod o :bar_x86, :bar_x64)
• Sufijo _test destinos con _test, _unittest, Test o Tests
• Evita los sufijos sin sentido como _lib o _library (a menos que sea necesario para evitar conflictos entre un destino _library y su _binary correspondiente)
• Para los destinos relacionados con proto:
  • Los destinos proto_library deben tener nombres que terminen en _proto
  • Las reglas específicas del lenguaje *_proto_library deben coincidir con el proto subyacente , pero reemplazar _proto por un sufijo específico del lenguaje, como:
    • cc_proto_library: _cc_proto
    • java_proto_library: _java_proto
    • java_lite_proto_library: _java_proto_lite

Visibilidad

La visibilidad debe tener un alcance lo más ajustado posible, sin dejar de permitir el acceso mediante pruebas y dependencias inversas. Usa __pkg__ y __subpackages__ según corresponda.

Evita configurar el paquete default_visibility en //visibility:public. //visibility:public solo debe configurarse de forma individual para los destinos en la API pública del proyecto. Podrían ser bibliotecas diseñadas para que dependan de proyectos externos o archivos binarios que se puedan usar en el proceso de compilación de un proyecto externo.

Dependencias

Las dependencias deben restringirse a las dependencias directas (las dependencias que necesitan las fuentes que se enumeran en la regla). No enumeres las dependencias transitivas.

Las dependencias locales del paquete deben enumerarse primero y hacer referencia a ellas de una manera compatible con la Referencias a destinos en el paquete actual sección anterior (no por su nombre de paquete absoluto).

Es preferible enumerar las dependencias directamente, como una sola lista. Colocar las dependencias "comunes" de varios destinos en una variable reduce la capacidad de mantenimiento, impide que las herramientas cambien las dependencias de un destino y puede generar dependencias sin usar.

Globs

Indica "sin destinos" con []. No uses un glob que no coincida con nada: es más propenso a errores y menos obvio que una lista vacía.

Recurrente

No uses globs recursivos para que coincidan con los archivos fuente (por ejemplo, glob(["**/*.java"])).

Los globs recursivos dificultan el razonamiento sobre los archivos BUILD porque omiten los subdirectorios que contienen archivos BUILD.

Por lo general, los globs recursivos son menos eficientes que tener un archivo BUILD por directorio con un gráfico de dependencias definido entre ellos, ya que esto permite un mejor almacenamiento en caché remoto y paralelismo.

Se recomienda crear un archivo BUILD en cada directorio y definir un gráfico de dependencias entre ellos.

No recurrente

Por lo general, los globs no recursivos son aceptables.

Otras convenciones

• Usa mayúsculas y guiones bajos para declarar constantes (como GLOBAL_CONSTANT), usa minúsculas y guiones bajos para declarar variables (como my_variable).

• Las etiquetas nunca deben dividirse, incluso si tienen más de 79 caracteres. Las etiquetas deben ser literales de cadena siempre que sea posible. Motivo: Facilita la búsqueda y el reemplazo. También mejora la legibilidad.

• El valor del atributo name debe ser una cadena constante literal (excepto en las macros). Motivo: Las herramientas externas usan el atributo name para hacer referencia a una regla. Necesitan encontrar reglas sin tener que interpretar el código.

• Cuando configures atributos de tipo booleano, usa valores booleanos, no valores enteros. Por motivos heredados, las reglas aún convierten números enteros en booleanos según sea necesario, pero esto no se recomienda. Motivo: flaky = 1 podría interpretarse de forma incorrecta como "quitar este destino volviéndolo a ejecutar una vez". flaky = True dice de forma inequívoca "esta prueba es inestable".

Diferencias con la guía de estilo de Python

Si bien la compatibilidad con la guía de estilo de Python es un objetivo, existen algunas diferencias:

• No hay un límite estricto de longitud de línea. Los comentarios largos y las cadenas largas suelen dividirse en 79 columnas, pero no es obligatorio. No se debe aplicar en las revisiones de código ni en las secuencias de comandos de envío previo. Motivo: Las etiquetas pueden ser largas y exceder este límite. Es común que las herramientas generen o editen archivos BUILD, lo que no funciona bien con un límite de longitud de línea.

• No se admite la concatenación implícita de cadenas. Usa el operador +. Motivo: Los archivos BUILD contienen muchas listas de cadenas. Es fácil olvidar una coma, lo que genera un resultado completamente diferente. Esto ha creado muchos errores en el pasado. Consulta también este debate.

• Usa espacios alrededor del signo = para los argumentos de palabras clave en las reglas. Motivo: Los argumentos con nombre son mucho más frecuentes que en Python y siempre están en una línea separada. Los espacios mejoran la legibilidad. Esta convención existe desde hace mucho tiempo y no vale la pena modificar todos los archivos BUILD existentes.

• De forma predeterminada, usa comillas dobles para las cadenas. Motivo: Esto no está especificado en la guía de estilo de Python, pero recomienda la coherencia. Por lo tanto, decidimos usar solo cadenas entre comillas dobles. Muchos lenguajes usan comillas dobles para los literales de cadena.

• Usa una sola línea en blanco entre dos definiciones de nivel superior. Motivo: La estructura de un archivo BUILD no es como un archivo típico de Python. Solo tiene instrucciones de nivel superior. El uso de una sola línea en blanco hace que los archivos BUILD sean más cortos.