Nesta página, consideramos que você já conhece o Bazel e fornece diretrizes e conselhos sobre como estruturar seus projetos para aproveitar ao máximo os recursos dele.
Os objetivos gerais são:
- Usar dependências refinadas para permitir paralelismo e incrementabilidade.
- Para manter as dependências bem encapsuladas.
- Para tornar o código bem estruturado e testável.
- Para criar uma configuração do build que seja fácil de entender e manter.
Essas diretrizes não são requisitos: poucos projetos poderão seguir todas elas. Como diz a página do manual do lint, "Uma recompensa especial será apresentada à primeira pessoa que produzir um programa real que não produza erros com verificação rigorosa". No entanto, incorporar o maior número possível desses princípios deve tornar um projeto mais legível, menos propenso a erros e mais rápido de criar.
Nesta página, são usados os níveis de requisitos descritos nesta RFC.
Como executar builds e testes
Um projeto precisa sempre conseguir executar bazel build //... e
bazel test //... na ramificação estável. Os destinos necessários,mas não criados em determinadas circunstâncias (como exigem sinalizações de build
específicas, não criam em uma determinada plataforma, exigem contratos de licença) precisam ser
marcados o mais especificamente possível (por exemplo, "requires-osx"). Essa
tag permite que os destinos sejam filtrados em um nível mais detalhado do que a
tag "manual" e permite que alguém inspecione o arquivo BUILD para entender quais
são as restrições de um destino.
Dependências de terceiros
É possível declarar dependências de terceiros:
- Declare-os como repositórios remotos no arquivo
WORKSPACE. - Ou coloque-os em um diretório chamado
third_party/no diretório do seu espaço de trabalho.
Depende de binários
Tudo deve ser criado da fonte sempre que possível. Geralmente, isso significa
que, em vez de depender de uma biblioteca some-library.so, você criaria um
arquivo BUILD e um some-library.so usando as origens. Depois, dependeria desse
destino.
Sempre criar com base na origem garante que um build não use uma biblioteca 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
Prefira criar todo o código a partir do cabeçalho sempre que possível. Quando as versões precisam ser
usadas, evite incluir a versão no nome do destino (por exemplo, //guava,
não //guava-20.0). Essa nomenclatura facilita a atualização da biblioteca (apenas um
destino precisa ser atualizado). Ela 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 estarão enganosos.
Como usar o arquivo .bazelrc
Para opções específicas do projeto, use o arquivo de configuração
workspace/.bazelrc (consulte formato bazelrc).
Se você quiser oferecer suporte a opções por usuário no 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 edificáveis precisa ser um pacote. Se um arquivo BUILD
se referir a arquivos em subdiretórios (como srcs = ["a/b/C.java"]), isso
é um sinal de que um arquivo BUILD precisa ser adicionado a esse subdiretório. Quanto maior
essa estrutura, mais prováveis dependências circulares serão
criadas por acidente, o escopo de um destino vai aumentar e um número
cada vez maior de dependências reversas precisará ser atualizado.