Trabaja con dependencias externas

Bazel puede depender de destinos de otros proyectos. Las dependencias de estos otros proyectos se denominan dependencias externas.

El archivo WORKSPACE (o el archivo WORKSPACE.bazel) en el directorio del espacio de trabajo le indica a Bazel cómo obtener las fuentes de otros proyectos. Estos otros proyectos pueden contener uno o más BUILD archivos con sus propios destinos. Los archivos BUILD dentro de el proyecto principal pueden depender de estos destinos externos usando sus nombres del archivo WORKSPACE.

Por ejemplo, supongamos que hay dos proyectos en un sistema:

/
  home/
    user/
      project1/
        WORKSPACE
        BUILD
        srcs/
          ...
      project2/
        WORKSPACE
        BUILD
        my-libs/

Si project1 quisiera depender de un destino, :foo, definido en /home/user/project2/BUILD, podría especificar que se puede encontrar un repositorio llamado project2 en /home/user/project2. Luego, los destinos en /home/user/project1/BUILD podrían depender de @project2//:foo.

El archivo WORKSPACE permite que los usuarios dependan de destinos de otras partes del sistema de archivos o que se descarguen de Internet. Usa la misma sintaxis que los archivos BUILD, pero permite un conjunto diferente de reglas llamadas reglas de repositorio (a veces también conocidas como reglas de espacio de trabajo). Bazel incluye algunas reglas de repositorio integradas y un conjunto de reglas de repositorio de Starlark incorporadas. Los usuarios también pueden escribir reglas de repositorio personalizadas para obtener un comportamiento más complejo.

Tipos admitidos de dependencias externas

Se pueden usar algunos tipos básicos de dependencias externas:

• Dependencias de otros proyectos de Bazel
• Dependencias de proyectos que no son de Bazel
• Dependencias de paquetes externos

Depende de otros proyectos de Bazel

Si deseas usar destinos de un segundo proyecto de Bazel, puedes usar local_repository, git_repository o http_archive para crear un vínculo simbólico desde el sistema de archivos local, hacer referencia a un repositorio de Git o descargarlo (respectivamente).

Por ejemplo, supongamos que estás trabajando en un proyecto, my-project/, y deseas depender de los destinos del proyecto de tu compañero de trabajo, coworkers-project/. Ambos proyectos usan Bazel, por lo que puedes agregar el proyecto de tu compañero de trabajo como una dependencia externa y, luego, usar cualquier destino que tu compañero de trabajo haya definido desde tus propios archivos BUILD. Agregarías lo siguiente a my_project/WORKSPACE:

local_repository(
    name = "coworkers_project",
    path = "/path/to/coworkers-project",
)

Si tu compañero de trabajo tiene un destino //foo:bar, tu proyecto puede hacer referencia a él como @coworkers_project//foo:bar. Los nombres de proyectos externos deben ser nombres de espacios de trabajo válidos.

Depende de proyectos que no son de Bazel

Las reglas con el prefijo new_, como new_local_repository, te permiten crear destinos a partir de proyectos que no usan Bazel.

Por ejemplo, supongamos que estás trabajando en un proyecto, my-project/, y deseas depender del proyecto de tu compañero de trabajo, coworkers-project/. El proyecto de tu compañero de trabajo usa make para compilar, pero te gustaría depender de uno de los archivos .so que genera. Para ello, agrega lo siguiente a my_project/WORKSPACE:

new_local_repository(
    name = "coworkers_project",
    path = "/path/to/coworkers-project",
    build_file = "coworker.BUILD",
)

build_file especifica un archivo BUILD para superponer en el proyecto existente, por ejemplo:

cc_library(
    name = "some-lib",
    srcs = glob(["**"]),
    visibility = ["//visibility:public"],
)

Luego, puedes depender de @coworkers_project//:some-lib desde los archivos BUILD de tu proyecto.

Depende de paquetes externos

Artefactos y repositorios de Maven

Usa el conjunto de reglas rules_jvm_external para descargar artefactos de repositorios de Maven y hacerlos disponibles como dependencias de Java.

Recupera dependencias

De forma predeterminada, las dependencias externas se recuperan según sea necesario durante bazel build. Si deseas recuperar previamente las dependencias necesarias para un conjunto específico de destinos, usa bazel fetch. Para recuperar todas las dependencias externas de forma incondicional, usa bazel sync. Como los repositorios recuperados se almacenan en la base de salida, la recuperación se realiza por espacio de trabajo.

Dependencias de sombreado

Siempre que sea posible, se recomienda tener una política de versión única en tu proyecto. Esto es necesario para las dependencias con las que compilas y que terminan en tu objeto binario final. Sin embargo, en los casos en que esto no es cierto, es posible sombrear dependencias. Considera la siguiente situación:

myproject/WORKSPACE

workspace(name = "myproject")

local_repository(
    name = "A",
    path = "../A",
)
local_repository(
    name = "B",
    path = "../B",
)

A/WORKSPACE

workspace(name = "A")

load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
http_archive(
    name = "testrunner",
    urls = ["https://github.com/testrunner/v1.zip"],
    sha256 = "...",
)

B/WORKSPACE

workspace(name = "B")

load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
http_archive(
    name = "testrunner",
    urls = ["https://github.com/testrunner/v2.zip"],
    sha256 = "..."
)

Ambas dependencias A y B dependen de testrunner, pero dependen de diferentes versiones de testrunner. No hay ningún motivo para que estos ejecutores de pruebas no coexistan de forma pacífica dentro de myproject. Sin embargo, entrarán en conflicto entre sí, ya que tienen el mismo nombre. Para declarar ambas dependencias, actualiza myproject/WORKSPACE:

workspace(name = "myproject")

load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
http_archive(
    name = "testrunner-v1",
    urls = ["https://github.com/testrunner/v1.zip"],
    sha256 = "..."
)
http_archive(
    name = "testrunner-v2",
    urls = ["https://github.com/testrunner/v2.zip"],
    sha256 = "..."
)
local_repository(
    name = "A",
    path = "../A",
    repo_mapping = {"@testrunner" : "@testrunner-v1"}
)
local_repository(
    name = "B",
    path = "../B",
    repo_mapping = {"@testrunner" : "@testrunner-v2"}
)

Este mecanismo también se puede usar para unir diamantes. Por ejemplo, si A y B tuvieran la misma dependencia, pero la llamaran con nombres diferentes, esas dependencias se pueden unir en myproject/WORKSPACE.

Cómo anular repositorios desde la línea de comandos

Para anular un repositorio declarado con un repositorio local desde la línea de comandos, usa la --override_repository marca. El uso de esta marca cambia el contenido de los repositorios externos sin cambiar el código fuente.

Por ejemplo, para anular @foo al directorio local /path/to/local/foo, pasa la marca --override_repository=foo=/path/to/local/foo.

A continuación, se presentan algunos de los casos prácticos:

• Depurar problemas. Por ejemplo, puedes anular un http_archive repositorio a un directorio local en el que puedes realizar cambios con mayor facilidad.
• Proveedores. Si te encuentras en un entorno en el que no puedes realizar llamadas de red, anula las reglas de repositorio basadas en la red para que apunten a directorios locales en su lugar.

Usa proxies

Bazel tomará las direcciones de proxy de las HTTPS_PROXY y HTTP_PROXY variables de entorno, y las usará para descargar archivos HTTP/HTTPS (si se especifican).

Compatibilidad con IPv6

En las máquinas solo IPv6, Bazel podrá descargar dependencias con sin cambios. Sin embargo, en las máquinas IPv4/IPv6 de pila doble, Bazel sigue la misma convención que Java: si IPv4 está habilitado, se prefiere IPv4. En algunas situaciones, por ejemplo, cuando la red IPv4 no puede resolver o alcanzar direcciones externas, esto puede provocar excepciones Network unreachable y fallas de compilación. En estos casos, puedes anular el comportamiento de Bazel para preferir IPv6 usando la propiedad del sistema java.net.preferIPv6Addresses=true. Específicamente, son las siguientes:

• Usa la opción de inicio --host_jvm_args=-Djava.net.preferIPv6Addresses=true , por ejemplo, agregando la siguiente línea en tu .bazelrc archivo:

  startup --host_jvm_args=-Djava.net.preferIPv6Addresses=true

• Si ejecutas destinos de compilación de Java que también necesitan conectarse a Internet (a veces, las pruebas de integración lo necesitan), también usa --jvmopt=-Djava.net.preferIPv6Addresses=true marca de herramienta, por ejemplo, con la siguiente línea en tu archivo .bazelrc:

  build --jvmopt=-Djava.net.preferIPv6Addresses

• Si usas rules_jvm_external, por ejemplo, para la resolución de la versión de dependencia, también agrega -Djava.net.preferIPv6Addresses=true a la COURSIER_OPTS variable de entorno para proporcionar opciones de JVM para Coursier

Dependencias transitivas

Bazel solo lee las dependencias que se enumeran en tu archivo WORKSPACE. Si tu proyecto (A) depende de otro proyecto (B) que enumera una dependencia en un tercer proyecto (C) en su archivo WORKSPACE, deberás agregar B y C al archivo WORKSPACE de tu proyecto. Este requisito puede aumentar el WORKSPACE tamaño del archivo, pero limita las posibilidades de que una biblioteca incluya C en la versión 1.0 y otra incluya C en la versión 2.0.

Almacenamiento en caché de dependencias externas

De forma predeterminada, Bazel solo volverá a descargar dependencias externas si su definición cambia. Bazel también tiene en cuenta los cambios en los archivos a los que se hace referencia en la definición (como parches o BUILD archivos).

Para forzar una nueva descarga, usa bazel sync.

Diseño

Todas las dependencias externas se descargan en un directorio en el subdirectorio external de la base de salida. En el caso de un repositorio local, se crea un vínculo simbólico en lugar de crear un directorio nuevo. Para ver el directorio external, ejecuta lo siguiente:

ls $(bazel info output_base)/external

Ten en cuenta que, si ejecutas bazel clean, no se borrará el directorio externo. Para quitar todos los artefactos externos, usa bazel clean --expunge.

Compilaciones sin conexión

A veces, es conveniente o necesario ejecutar una compilación sin conexión. Para casos de uso simples, como viajar en avión, prefetching los repositorios necesarios con bazel fetch o bazel sync puede ser suficiente. Además, si usas la opción --nofetch, se puede inhabilitar la recuperación de repositorios adicionales durante la compilación.

Para las compilaciones sin conexión verdaderas, en las que una entidad diferente de Bazel debe proporcionar los archivos necesarios, Bazel admite la opción --distdir. Cada vez que una regla de repositorio le pide a Bazel que recupere un archivo a través de ctx.download o ctx.download_and_extract y proporciona una suma de hash del archivo necesario, Bazel primero buscará en los directorios especificados por esa opción un archivo que coincida con el nombre base de la primera URL proporcionada y usará esa copia local si coincide el hash.

Bazel usa esta técnica para iniciar sin conexión desde el artefacto de distribución. Para ello, recopila todas las dependencias externas necesarias en un distdir_tar.

Sin embargo, Bazel permite la ejecución de comandos arbitrarios en reglas de repositorio, sin saber si llaman a la red. Por lo tanto, Bazel no tiene ninguna opción para forzar que las compilaciones estén completamente sin conexión. Por lo tanto, para probar si una compilación funciona correctamente sin conexión, se requiere un bloqueo externo de la red, como lo hace Bazel en su prueba de inicio.

Prácticas recomendadas

Reglas de repositorio

En general, una regla de repositorio debe ser responsable de lo siguiente:

• Detectar la configuración del sistema y escribirla en archivos
• Buscar recursos en otras partes del sistema
• Descargar recursos de URLs
• Generar o crear vínculos simbólicos de archivos BUILD en el directorio del repositorio externo

Evita usar repository_ctx.execute cuando sea posible. Por ejemplo, cuando se usa una biblioteca C++ que no es de Bazel y que tiene una compilación con Make, es preferible usar repository_ctx.download() y, luego, escribir un archivo BUILD que lo compile, en lugar de ejecutar ctx.execute(["make"]).

Prefiere http_archive a git_repository y new_git_repository. Estos son los motivos:

• Las reglas de repositorio de Git dependen del sistema git(1), mientras que el descargador HTTP está integrado en Bazel y no tiene dependencias del sistema.
• http_archive admite una lista de urls como espejos, y git_repository solo admite un remote único.
• http_archive funciona con la caché del repositorio, pero no con git_repository. Consulta #5116 para obtener más información.

No uses bind(). Consulta "Considera quitar bind" para obtener un debate extenso sobre sus problemas y alternativas.