En esta página, se explica cómo crear reglas de repositorio y se proporcionan ejemplos para obtener más detalles.
Un repositorio externo es una regla que solo se puede usar
en el archivo WORKSPACE y habilita la operación no hermética en la fase de carga
de Bazel. Cada regla de repositorio externo crea su propio espacio de trabajo, con sus propios archivos y artefactos BUILD. Se pueden usar para depender de bibliotecas de terceros (como bibliotecas empaquetadas de Maven), pero también para generar archivos BUILD específicos del host en el que se ejecuta Bazel.
Creación de reglas de repositorio
En un archivo .bzl, usa la función repository_rule para crear una nueva regla de repositorio y almacenarla en una variable global.
Una regla de repositorio personalizada se puede usar de la misma manera que una regla de repositorio nativo. Tiene un atributo name obligatorio, y cada destino presente en sus archivos de compilación se puede denominar @<name>//package:target, donde <name> es el valor del atributo name.
La regla se carga cuando la compilas de forma explícita o si es una dependencia de la compilación. En este caso, Bazel ejecutará su función implementation. En esta función, se describe cómo crear el repositorio, su contenido y los archivos BUILD.
Atributos
Un atributo es un argumento de regla, como url o sha256. Cuando definas una regla de repositorio, debes enumerar los atributos y sus tipos.
local_repository = repository_rule(
implementation=_impl,
local=True,
attrs={"path": attr.string(mandatory=True)})
Para acceder a un atributo, usa repository_ctx.attr.<attribute_name>.
Todos los repository_rule tienen atributos definidos de forma implícita (al igual que las reglas de compilación). Los dos atributos implícitos son name (al igual que para las reglas de compilación) y repo_mapping. Se puede acceder al nombre de una regla de repositorio con repository_ctx.name. El significado de repo_mapping es el mismo que el de las reglas del repositorio nativo local_repository y new_local_repository.
Si el nombre de un atributo comienza con _, es privado y los usuarios no pueden configurarlo.
Función de implementación
Cada regla de repositorio requiere una función implementation. Contiene la lógica real de la regla y se ejecuta estrictamente en la fase de carga.
La función tiene exactamente un parámetro de entrada, repository_ctx. La función muestra None para indicar que la regla es reproducible según los parámetros especificados, o bien un diccionario con un conjunto de parámetros para esa regla que la convertiría en una reproducible que genera el mismo repositorio. Por ejemplo, para una regla que realiza un seguimiento de un repositorio de git, eso significaría mostrar un identificador de confirmación específico en lugar de una rama flotante que se especificó originalmente.
El parámetro de entrada repository_ctx se puede usar para acceder a los valores de los atributos y a las funciones no herméticas (encontrar un objeto binario, ejecutarlo, crear un archivo en el repositorio o descargar un archivo de Internet). Consulta la biblioteca para obtener más información. Ejemplo:
def _impl(repository_ctx):
repository_ctx.symlink(repository_ctx.attr.path, "")
local_repository = repository_rule(
implementation=_impl,
...)
¿Cuándo se ejecuta la función de implementación?
Si el repositorio se declara como local, el cambio en una dependencia del gráfico de dependencias (incluido el archivo WORKSPACE) provocará la ejecución de la función de implementación.
La función de implementación se puede reiniciar si falta una dependencia que solicita. El comienzo de la función de implementación se volverá a ejecutar después de que se resuelva la dependencia. Para evitar reinicios innecesarios (que son costosos, ya que es posible que se deba repetir el acceso a la red), los argumentos de etiqueta se precargan, siempre que todos los argumentos de etiqueta se puedan resolver en un archivo existente. Ten en cuenta que resolver una ruta de acceso desde una cadena o una etiqueta que se construyó solo durante la ejecución de la función podría provocar un reinicio.
Por último, en el caso de los repositorios que no son de local, solo un cambio en las siguientes dependencias podría provocar un reinicio:
- Archivos
.bzlnecesarios para definir la regla del repositorio - Declaración de la regla del repositorio en el archivo
WORKSPACE. - Es el valor de cualquier variable de entorno declarada con el atributo
environde la funciónrepository_rule. El valor de esas variables de entorno se puede aplicar desde la línea de comandos con la marca--action_env(pero esta marca invalidará cada acción de la compilación). - Es el contenido de cualquier archivo que usa y al que hace referencia una etiqueta (por ejemplo,
//mypkg:label.txt, nomypkg/label.txt).
Cómo forzar la actualización de repositorios externos
A veces, un repositorio externo puede quedar desactualizado sin ningún cambio en su definición o dependencias. Por ejemplo, un repositorio que recupera fuentes puede seguir una rama en particular de un repositorio de terceros, y las confirmaciones nuevas están disponibles en esa rama. En este caso, puedes pedirle a bazel que vuelva a recuperar todos los repositorios externos de forma incondicional llamando a bazel sync.
Además, algunas reglas inspeccionan la máquina local y pueden quedar
anticuadas si se actualiza. Aquí, puedes pedirle a bazel que solo vuelva a recuperar aquellos repositorios externos en los que la definición de repository_rule tenga el atributo configure establecido. Usa bazel sync --configure.
Ejemplos
Cadena de herramientas configurada automáticamente para C++: Usa una regla de repositorio para crear automáticamente los archivos de configuración de C++ para Bazel buscando el compilador de C++ local, el entorno y las marcas que admite el compilador de C++.
Los repositorios de Go usan varios
repository_rulepara definir la lista de dependencias necesarias para usar las reglas de Go.rules_jvm_external crea un repositorio externo llamado
@mavende forma predeterminada que genera destinos de compilación para cada artefacto de Maven en el árbol de dependencias transitivas.