Visão geral das dependências externas

Report an issue View source Nightly · 8.2 · 8.1 · 8.0 · 7.6 · 7.5

O Bazel oferece suporte a dependências externas, arquivos de origem (texto e binário) usados no build que não são do seu espaço de trabalho. Por exemplo, eles podem ser um conjunto de regras hospedado em um repositório do GitHub, um artefato do Maven ou um diretório na sua máquina local fora do espaço de trabalho atual.

Este documento apresenta uma visão geral do sistema antes de examinar alguns dos conceitos com mais detalhes.

Visão geral do sistema

O sistema de dependência externa do Bazel funciona com base em módulos do Bazel, cada um deles é um projeto do Bazel com versão, e repositórios (ou repos), que são árvores de diretórios que contêm arquivos de origem.

O Bazel começa no módulo raiz, ou seja, no projeto em que você está trabalhando. Como todos os módulos, ele precisa ter um arquivo MODULE.bazel na raiz do diretório, declarando os metadados básicos e as dependências diretas. Confira um exemplo básico abaixo:

module(name = "my-module", version = "1.0")

bazel_dep(name = "rules_cc", version = "0.1.1")
bazel_dep(name = "platforms", version = "0.0.11")

A partir daí, o Bazel procura todos os módulos de dependência transitiva em um registro do Bazel. Por padrão, o registro central do Bazel. O registro fornece os arquivos MODULE.bazel das dependências, o que permite que o Bazel descubra todo o gráfico de dependência transitiva antes de realizar a resolução de versão.

Após a resolução de versão, em que uma versão é selecionada para cada módulo, o Bazel consulta o registro novamente para saber como definir um repositório para cada módulo, ou seja, como as origens de cada módulo de dependência devem ser buscadas. Na maioria das vezes, esses são apenas arquivos extraídos e baixados da Internet.

Os módulos também podem especificar partes personalizadas de dados chamadas de tags, que são usadas por extensões de módulo após a resolução do módulo para definir repositórios adicionais. Essas extensões podem realizar ações como E/S de arquivos e envio de solicitações de rede. Entre outras coisas, eles permitem que o Bazel interaja com outros sistemas de gerenciamento de pacotes, respeitando o gráfico de dependência criado a partir dos módulos do Bazel.

Os três tipos de repositórios, o repositório principal (que é a árvore de origem em que você está trabalhando), os repositórios que representam módulos de dependência transitiva e os repositórios criados por extensões de módulo, formam o espaço de trabalho. Os repositórios externos (não principais) são buscados sob demanda, por exemplo, quando são referidos por rótulos (como @repo//pkg:target) em arquivos BUILD.

Vantagens

O sistema de dependências externas do Bazel oferece uma ampla gama de benefícios.

Resolução automática de dependências

  • Resolução de versão determinística: o Bazel adota o algoritmo de resolução de versão MVS determinístico, minimizando conflitos e resolvendo problemas de dependência de diamante.
  • Gerenciamento de dependências simplificado: o MODULE.bazel declara apenas dependências diretas, enquanto as dependências transitivas são resolvidas automaticamente, oferecendo uma visão geral mais clara das dependências do projeto.
  • Visibilidade de dependência estrita: somente dependências diretas são visíveis, garantindo a correção e a previsibilidade.

Integração do ecossistema

  • Registro central do Bazel: um repositório centralizado para descobrir e gerenciar dependências comuns como módulos do Bazel.
  • Adoção de projetos que não são do Bazel: quando um projeto que não é do Bazel (geralmente uma biblioteca C++) é adaptado para o Bazel e disponibilizado no BCR, ele simplifica a integração para toda a comunidade e elimina esforços duplicados e conflitos de arquivos BUILD personalizados.
  • Integração unificada com gerenciadores de pacotes específicos da linguagem: as Rulesets simplificam a integração com gerenciadores de pacotes externos para dependências que não são do Bazel, incluindo:

Recursos avançados

  • Extensões de módulo: os recursos use_repo_rule e de extensão de módulo permitem o uso flexível de regras de repositório personalizadas e lógica de resolução para introduzir dependências que não são do Bazel.
  • Comando bazel mod: o subcomando oferece maneiras eficientes de inspecionar dependências externas. Você sabe exatamente como uma dependência externa é definida e de onde ela vem.
  • Modo do fornecedor: pré-busque as dependências externas exatas necessárias para facilitar os builds off-line.
  • Lockfile: o arquivo de bloqueio melhora a reprodutibilidade do build e acelera a resolução de dependências.
  • (Próximas) Atestados de procedência de BCR: fortaleça a segurança da cadeia de suprimentos garantindo a procedência verificada de dependências.

Conceitos

Esta seção oferece mais detalhes sobre conceitos relacionados a dependências externas.

Módulo

Um projeto do Bazel que pode ter várias versões, cada uma com dependências de outros módulos.

Em um espaço de trabalho local do Bazel, um módulo é representado por um repositório.

Para mais detalhes, consulte Módulos do Bazel.

Repositório

Uma árvore de diretórios com um arquivo de marcador de limite na raiz, contendo arquivos de origem que podem ser usados em um build do Bazel. Muitas vezes abreviado para repo.

Um arquivo de marcador de limite do repositório pode ser MODULE.bazel (sinaliza que esse repositório representa um módulo do Bazel), REPO.bazel (consulte abaixo) ou, em contextos legados, WORKSPACE ou WORKSPACE.bazel. Qualquer arquivo de marcador de limite de repositório vai indicar o limite de um repositório. Vários desses arquivos podem coexistir em um diretório.

Repositório principal

O repositório em que o comando atual do Bazel está sendo executado.

A raiz do repositório principal também é conhecida como raiz do espaço de trabalho.

Espaço de trabalho

O ambiente compartilhado por todos os comandos do Bazel é executado no mesmo repositório principal. Ele abrange o repositório principal e o conjunto de todos os repositórios externos definidos.

Historicamente, os conceitos de "repositório" e "espaço de trabalho" foram confundidos. O termo "espaço de trabalho" foi usado com frequência para se referir ao repositório principal e, às vezes, até como sinônimo de "repositório".

Nome do repositório canônico

O nome canônico pelo qual um repositório pode ser acessado. No contexto de um workspace, cada repositório tem um único nome canônico. Um destino dentro de um repositório cujo nome canônico é canonical_name pode ser abordado pelo rótulo @@canonical_name//package:target (observe o duplo @).

O repositório principal sempre tem a string vazia como o nome canônico.

Nome do repositório aparente

O nome de um repositório é endereçável no contexto de outro repositório. Isso pode ser considerado o "apelido" de um repositório: o repositório com o nome canônico michael pode ter o nome aparente mike no contexto do repositório alice, mas pode ter o nome aparente mickey no contexto do repositório bob. Nesse caso, um destino dentro de michael pode ser abordado pelo rótulo @mike//package:target no contexto de alice (observe o único @).

Por outro lado, isso pode ser entendido como um mapeamento de repositório: cada repositório mantém um mapeamento do "nome aparente do repositório" para um "nome canônico do repositório".

Regra de repositório

Um esquema para definições de repositório que informa ao Bazel como materializar um repositório. Por exemplo, pode ser "fazer o download de um arquivo zip de um determinado URL e extraí-lo", ou "buscar um determinado artefato do Maven e disponibilizá-lo como um alvo java_import", ou simplesmente "criar um link simbólico para um diretório local". Cada repositório é definido chamando uma regra de repositório com um número adequado de argumentos.

Consulte Regras do repositório para mais informações sobre como escrever suas próprias regras de repositório.

As regras de repositório mais comuns são http_archive, que faz o download de um arquivo de um URL e o extrai, e local_repository, que cria um link simbólico para um diretório local que já é um repositório do Bazel.

Buscar um repositório

A ação de disponibilizar um repositório no disco local executando a regra de repositório associada. Os repositórios definidos em um workspace não estão disponíveis no disco local antes de serem buscados.

Normalmente, o Bazel só busca um repositório quando precisa de algo dele e o repositório ainda não foi buscado. Se o repositório já tiver sido buscado antes, o Bazel só vai fazer o reenvio se a definição dele tiver mudado.

O comando fetch pode ser usado para iniciar uma pré-busca de um repositório, alvo ou todos os repositórios necessários para realizar qualquer build. Esse recurso ativa builds off-line usando a opção --nofetch.

A opção --fetch serve para gerenciar o acesso à rede. O valor padrão é "true". No entanto, quando definido como falso (--nofetch), o comando vai usar qualquer versão em cache da dependência. Se nenhuma existir, o comando vai resultar em falha.

Consulte Opções de busca para mais informações sobre como controlar a busca.

Layout do diretório

Depois de ser buscado, o repositório pode ser encontrado no subdiretório external na base de saída, com o nome canônico.

Execute o comando a seguir para conferir o conteúdo do repositório com o nome canônico canonical_name:

ls $(bazel info output_base)/external/ canonical_name

Arquivo REPO.bazel

O arquivo REPO.bazel é usado para marcar o limite superior da árvore de diretórios que constitui um repositório. Ele não precisa conter nada para servir como um arquivo de limite de repositório. No entanto, ele também pode ser usado para especificar alguns atributos comuns para todos os destinos de build no repositório.

A sintaxe de um arquivo REPO.bazel é semelhante aos arquivos BUILD, exceto pelo fato de que nenhuma instrução load é aceita. A função repo() recebe os mesmos argumentos que a função package() em arquivos BUILD. Enquanto package() especifica atributos comuns para todos os destinos de build dentro do pacote, repo() faz isso de forma análoga para todos os destinos de build dentro do repositório.

Por exemplo, é possível especificar uma licença comum para todos os destinos no repositório com o seguinte arquivo REPO.bazel:

repo(
    default_package_metadata = ["//:my_license"],
)

O sistema WORKSPACE legado

Em versões mais antigas do Bazel (antes da 9.0), as dependências externas eram introduzidas definindo repositórios no arquivo WORKSPACE (ou WORKSPACE.bazel). Esse arquivo tem uma sintaxe semelhante aos arquivos BUILD, usando regras de repositório em vez de regras de build.

O snippet a seguir é um exemplo de uso da regra de repositório http_archive no arquivo WORKSPACE:

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

O snippet define um repositório com o nome canônico foo. No sistema WORKSPACE, por padrão, o nome canônico de um repositório também é o nome aparente para todos os outros repositórios.

Consulte a lista completa de funções disponíveis em arquivos WORKSPACE.

Desvantagens do sistema WORKSPACE

Nos anos após o lançamento do sistema WORKSPACE, os usuários relataram muitos problemas, incluindo:

  • O Bazel não avalia os arquivos WORKSPACE de nenhuma dependência. Portanto, todas as dependências transitivas precisam ser definidas no arquivo WORKSPACE do repositório principal, além das dependências diretas.
  • Para contornar esse problema, os projetos adotaram o padrão "deps.bzl", em que definem uma macro que, por sua vez, define vários repositórios e pede aos usuários que chamem essa macro nos arquivos WORKSPACE.
    • Isso tem problemas próprios: as macros não podem load outros arquivos .bzl. Portanto, esses projetos precisam definir as dependências transitivas nessa macro "deps" ou contornar o problema fazendo com que o usuário chame várias macros "deps" em camadas.
    • O Bazel avalia o arquivo WORKSPACE sequencialmente. Além disso, as dependências são especificadas usando http_archive com URLs, sem nenhuma informação de versão. Isso significa que não há uma maneira confiável de realizar a resolução de versão no caso de dependências de diamante (A depende de B e C; B e C dependem de versões diferentes de D).

Devido às deficiências do WORKSPACE, o novo sistema baseado em módulos (apelidado de "Bzlmod") substituiu gradualmente o sistema legada WORKSPACE entre o Bazel 6 e o 9. Leia o guia de migração do Bzlmod para saber como migrar para o Bzlmod.