O Bazel cria softwares a partir do código-fonte organizado em árvores de diretórios chamadas
repositórios. Um conjunto definido de repositórios abrange o espaço de trabalho. Os arquivos
de origem em repositórios são organizados em uma hierarquia aninhada de pacotes, em que
cada pacote é um diretório que contém um conjunto de arquivos de origem relacionados e um
arquivo BUILD. O arquivo BUILD especifica quais saídas de software podem ser criadas a partir
da origem.
Repositórios
Os arquivos de origem usados em um build do Bazel são organizados em repositórios (geralmente
encurtados para repos). Um repositório é uma árvore de diretórios com um arquivo de marcador de limites na raiz. Esse arquivo pode ser MODULE.bazel, REPO.bazel ou, em contextos legados, WORKSPACE ou WORKSPACE.bazel.
O repositório em que o comando atual do Bazel está sendo executado é chamado de repositório principal. Outros repositórios (externos) são definidos por regras de repo. Consulte a visão geral de dependências externas para mais informações.
Espaço de trabalho
Um workspace é o ambiente compartilhado por todos os comandos do Bazel executados no mesmo repositório principal. Ela abrange o repositório principal e o conjunto de todos os repositórios externos definidos.
Observe que, historicamente, os conceitos de "repositório" e "espaço de trabalho" foram confundidos. O termo "espaço de trabalho" costuma ser usado para se referir ao repositório principal e, às vezes, até mesmo como sinônimo de "repositório".
Pacotes
A principal unidade de organização de código em um repositório é o pacote (link em inglês). Um pacote é uma coleção de arquivos relacionados e uma especificação de como eles podem ser usados para produzir artefatos de saída.
Um pacote é definido como um diretório que contém um
arquivo BUILD chamado BUILD ou BUILD.bazel. Um
pacote inclui todos os arquivos no diretório dele e todos os subdiretórios abaixo dele,
exceto aqueles que contêm um arquivo BUILD. A partir dessa definição, nenhum
arquivo ou diretório pode fazer parte de dois pacotes diferentes.
Por exemplo, na árvore de diretórios a seguir, há dois pacotes, my/app
e o subpacote my/app/tests. Observe que my/app/data não é um pacote, mas
um diretório pertencente ao pacote my/app.
src/my/app/BUILD
src/my/app/app.cc
src/my/app/data/input.txt
src/my/app/tests/BUILD
src/my/app/tests/test.cc
Destinos
Um pacote é um contêiner de destinos, definidos no arquivo
BUILD do pacote. A maioria dos destinos é um dos dois tipos principais: arquivos e regras.
Os arquivos são divididos em dois tipos. Os arquivos de origem geralmente são gravados pelo esforço das pessoas e colocados no repositório. Os arquivos gerados, às vezes chamados de arquivos derivados ou de saída, não são verificados, mas são gerados a partir de arquivos de origem.
O segundo tipo de destino é declarado com uma regra. Cada instância de regra especifica a relação entre um conjunto de entrada e um conjunto de arquivos de saída. As entradas de uma regra podem ser arquivos de origem, mas também podem ser as saídas de outras regras.
Na maioria dos casos, se a entrada de uma regra é um arquivo de origem ou gerado, isso é irrelevante. O que importa é apenas o conteúdo desse arquivo. Esse fato facilita a substituição de um arquivo de origem complexo por um gerado produzido por uma regra, como acontece quando a carga de manter manualmente um arquivo altamente estruturado se torna muito cansativa e alguém escreve um programa para derivá-lo. Nenhuma alteração é necessária para os consumidores desse arquivo. Por outro lado, um arquivo gerado pode ser facilmente substituído por um arquivo de origem apenas com mudanças locais.
As entradas de uma regra também podem incluir outras regras. O significado preciso dessas relações geralmente é bastante complexo e depende de linguagem ou de regras, mas intuitivamente é simples: uma regra A de biblioteca C++ pode ter outra regra de biblioteca C++ B para uma entrada. O efeito dessa dependência é que os arquivos de cabeçalho de B ficam disponíveis para A durante a compilação, os símbolos de B ficam disponíveis para A durante a vinculação e os dados de tempo de execução de B ficam disponíveis para A durante a execução.
Uma invariante de todas as regras é que os arquivos gerados por uma regra sempre pertencem ao mesmo pacote que a própria regra. Não é possível gerar arquivos em outro pacote. No entanto, não é incomum que as entradas de uma regra venham de outro pacote.
Grupos de pacotes são conjuntos de pacotes com a finalidade de limitar a acessibilidade de
determinadas regras. Os grupos de pacotes são definidos pela função package_group. Eles
têm três propriedades: a lista de pacotes que eles contêm, o nome e outros
grupos de pacotes que incluem. As únicas maneiras permitidas de se referir a eles são no
atributo visibility das regras ou no atributo default_visibility da
função package. Elas não geram nem consomem arquivos. Para mais
informações, consulte a documentação
do package_group.