Nesta página, pressupomos que você já conhece o Bazel e fornecemos diretrizes e conselhos sobre como estruturar seus projetos para aproveitar ao máximo os recursos do Bazel.
Os objetivos gerais são:
- Usar dependências refinadas para permitir paralelismo e incrementalidade.
- Para manter as dependências bem encapsuladas.
- Para deixar o código bem estruturado e testável.
- Para criar uma configuração de build fácil de entender e manter.
Essas diretrizes não são requisitos: poucos projetos conseguem aderir a todas elas. Como diz a página de manual do lint, "Uma recompensa especial será apresentada à primeira pessoa que produzir um programa real sem erros com verificação estrita". No entanto, incorporar o máximo possível desses princípios torna um projeto mais legível, menos propenso a erros e mais rápido de criar.
Esta página usa os níveis de requisitos descritos nesta RFC.
Executar builds e testes
Um projeto precisa sempre conseguir executar bazel build //... e
bazel test //... com sucesso na ramificação estável. As metas necessárias, mas que não são criadas em determinadas circunstâncias (por exemplo, exigem flags de build específicas, não são criadas em uma determinada plataforma, exigem contratos de licença), precisam ser marcadas da forma mais específica possível (por exemplo, "requires-osx"). Essa marcação permite que as metas sejam filtradas em um nível mais refinado do que a tag "manual" e permite que alguém que inspecione o arquivo BUILD entenda quais são as restrições de uma meta.
Dependências de terceiros
Você pode declarar dependências de terceiros:
- Declare-os como repositórios remotos no arquivo
MODULE.bazel. - Ou coloque-os em um diretório chamado
third_party/no diretório do espaço de trabalho.
Dependendo de binários
Sempre que possível, tudo deve ser criado com base na fonte. Em geral, isso significa que, em vez de depender de uma biblioteca some-library.so, você criaria um arquivo BUILD e criaria some-library.so com base nas fontes dele, dependendo desse destino.
Sempre criar da origem garante que uma build não esteja usando uma biblioteca que foi criada com flags incompatíveis ou uma arquitetura diferente. Há também alguns recursos, como cobertura, análise estática ou análise dinâmica, que só funcionam na origem.
Controle de versões
Sempre que possível, prefira criar todo o código do cabeçalho. Quando for necessário usar versões, evite incluir a versão no nome do destino (por exemplo, //guava, não //guava-20.0). Isso facilita a atualização da biblioteca, já que apenas um destino precisa ser atualizado. Ele também é mais resiliente a problemas de dependência de diamante: se uma biblioteca depende de guava-19.0 e outra depende de guava-20.0, você pode acabar com uma biblioteca que tenta depender de duas versões diferentes.
Se você criou um alias enganoso para apontar os dois destinos para uma biblioteca guava,
os arquivos BUILD são enganosos.
Como usar o arquivo .bazelrc
Para opções específicas do projeto, use o arquivo de configuração do seu
workspace/.bazelrc (consulte formato bazelrc).
Se você quiser oferecer suporte a opções por usuário para seu projeto que não quer verificar no controle de origem, inclua a linha:
try-import %workspace%/user.bazelrc
(ou qualquer outro nome de arquivo) em workspace/.bazelrc
e adicione user.bazelrc a .gitignore.
Pacotes
Todo diretório que contém arquivos passíveis de build precisa ser um pacote. Se um arquivo BUILD
se referir a arquivos em subdiretórios (como srcs = ["a/b/C.java"]), isso
indica que um arquivo BUILD precisa ser adicionado a esse subdiretório. Quanto mais tempo essa estrutura existir, maior será a probabilidade de criar dependências circulares inadvertidamente, o escopo de uma meta vai aumentar e um número crescente de dependências inversas terá que ser atualizado.