Nesta página, presumimos que você já conhece o Bazel e fornecemos diretrizes e orientações sobre como estruturar seus projetos para aproveitar ao máximo os recursos do Bazel.
Os objetivos gerais são:
- Usar dependências detalhadas para permitir paralelismo e incrementalidade.
- Para manter as dependências bem encapsuladas.
- Para tornar o código bem estruturado e testável.
- Criar uma configuração de build fácil de entender e manter.
Essas diretrizes não são requisitos: poucos projetos vão conseguir aderir a todas elas. Como diz a página de manual do lint, "Uma recompensa especial será apresentada à primeira pessoa a produzir um programa real que não produz erros com verificação estrita". 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.
Esta página usa os níveis de requisito descritos em este RFC.
Como executar builds e testes
Um projeto precisa sempre ser capaz de executar bazel build //... e
bazel test //... com sucesso na ramificação estável. Os destinos que são necessários,mas não são criados em determinadas circunstâncias (como exigir flags de build
específicas, não criar em uma determinada plataforma, exigir contratos de licença) precisam ser
marcados da forma mais específica possível (por exemplo, "requires-osx"). Essa
marcação permite que os destinos sejam filtrados em um nível mais detalhado do que a
tag "manual" e permite que alguém que inspecione o arquivo BUILD entenda quais
são as restrições de um destino.
Dependências de terceiros
Você pode 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 espaço de trabalho.
Dependendo de binários
Sempre que possível, tudo deve ser criado a partir da fonte. Isso geralmente significa
que, em vez de depender de uma biblioteca some-library.so, você criaria um
arquivo BUILD e criaria some-library.so a partir das fontes, depois dependeria desse
alvo.
Sempre criar a partir da 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
Sempre que possível, prefira criar todo o código da cabeça. Quando as versões precisam ser
usadas, evite incluir a versão no nome de destino (por exemplo, //guava,
não //guava-20.0). Essa nomenclatura facilita a atualização da biblioteca, já que apenas um
destino precisa ser atualizado. Ele também é mais resistente 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
workspace/.bazelrc (consulte formato bazelrc).
Se você quiser oferecer suporte a opções por usuário para seu projeto que não queiram fazer o check-in no controle de origem, inclua a linha:
try-import %workspace%/user.bazelrc
(ou qualquer outro nome de arquivo) no workspace/.bazelrc
e adicione user.bazelrc ao .gitignore.
Pacotes
Cada diretório que contém arquivos buildáveis precisa ser um pacote. Se um arquivo BUILD
se refere a arquivos em subdiretórios (como srcs = ["a/b/C.java"]), é
um sinal de que um arquivo BUILD precisa ser adicionado a esse subdiretório. Quanto mais
tempo essa estrutura existir, maior será a probabilidade de que dependências circulares sejam
criadas acidentalmente, o escopo de um destino vai aumentar e um número cada vez maior
de dependências reversas terá que ser atualizado.