O Bazel oferece suporte a dependências externas, arquivos de origem (texto e binários) 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 Maven ou um diretório na sua máquina local fora do espaço de trabalho atual.
A partir do Bazel 6.0, há duas maneiras de gerenciar dependências externas com o Bazel:
o sistema WORKSPACE
tradicional, focado em repositório, e
o sistema MODULE.bazel
mais recente com foco em módulo (codinome Bzlmod
e ativado com a flag --enable_bzlmod
). Os dois sistemas podem ser usados
juntos, mas o Bzlmod está substituindo o sistema WORKSPACE
em versões futuras do
Bzlmod. Consulte 1Bz0.mod para saber como fazer isso{/1.
Este documento explica os conceitos relacionados ao gerenciamento de dependências externas no Bazel, antes de entrar em mais detalhes sobre os dois sistemas.
Conceitos
Repositório
Um diretório com um arquivo WORKSPACE
ou WORKSPACE.bazel
, contendo arquivos
de origem a serem usados em um build do Bazel. Muitas vezes abreviado para repo.
Repositório principal
O repositório em que o comando atual do Bazel está sendo executado.
Espaço de trabalho
O ambiente compartilhado por todos os comandos do Bazel é executado no mesmo repositório principal.
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 canônico do repositório
O nome canônico pelo qual um repositório pode ser acessado. Dentro do contexto de um
espaço de trabalho, cada repositório tem um único nome canônico. Um destino dentro de um repositório
com nome canônico canonical_name
pode ser abordado pelo rótulo
@@canonical_name//pac/kage: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//pac/kage: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 o 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 repo 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.
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 seguinte comando para ver o conteúdo do repositório com o nome canônico canonical_name
:
ls $(bazel info output_base)/external/ canonical_name
Gerenciar dependências externas com o Bzlmod
O Bzlmod, o novo subsistema de dependência externa, não funciona diretamente com definições de repositório. Em vez disso, ele cria um gráfico de dependência de módulos, executa extensões sobre o gráfico e define repositórios de acordo.
Um módulo do Bazel é um projeto do Bazel que pode ter várias
versões, e cada uma delas publica metadados sobre outros módulos de que
ele depende. Um módulo precisa ter um arquivo MODULE.bazel
na raiz do repositório, ao lado do
arquivo WORKSPACE
. Esse arquivo é o manifesto do módulo, declarando o nome,
a versão, a lista de dependências, entre outras informações. Confira um exemplo
básico:
module(name = "my-module", version = "1.0")
bazel_dep(name = "rules_cc", version = "0.0.1")
bazel_dep(name = "protobuf", version = "3.19.0")
Um módulo só precisa listar as dependências diretas, que o Bzlmod procura 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
(na maioria dos casos, usando http_archive
).
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 outros repositórios. Essas extensões têm recursos semelhantes às regras de repositório, permitindo que elas realizem 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 e, ao mesmo tempo, respeita o gráfico de dependência criado com base nos módulos do Bazel.
Links externos no Bzlmod
- Exemplos de uso do Bzlmod em bazelbuild/examples (em inglês)
- Revisão das dependências externas do Bazel (documento de design original do Bzlmod)
- Palestra na BaselCon 2021 sobre o Bzlmod
- Palestra do dia da comunidade do Bazel sobre o Bzlmod
Definir repositórios com WORKSPACE
Historicamente, é possível gerenciar dependências externas definindo repositórios no
arquivo WORKSPACE
(ou WORKSPACE.bazel
). Esse arquivo tem uma sintaxe semelhante aos
arquivos BUILD
, empregando 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 nome canônico foo
. No sistema WORKSPACE
, por padrão, o nome canônico de um repositório também é o nome aparente dele para
todos os outros repositórios.
Desvantagens do sistema WORKSPACE
Nos anos desde o lançamento do sistema WORKSPACE
, os usuários relataram
muitos pontos problemáticos, incluindo:
- O Bazel não avalia os arquivos
WORKSPACE
de nenhuma dependência. Portanto, todas as dependências transitivas precisam ser definidas no arquivoWORKSPACE
do repo 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 usandohttp_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 deB
eC
;B
eC
dependem de versões diferentes deD
).
- Isso tem problemas próprios: as macros não podem
Devido às deficiências do WORKSPACE, o Bzlmod vai substituir o sistema WORKSPACE legado em versões futuras do Bazel. Leia o guia de migração do Bzlmod (em inglês) para saber como migrar para o Bzlmod.