Nesta página, consideramos que você já conhece o Bazel e apresenta diretrizes e 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.
- Para criar uma configuração do build que seja 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 do manual do lint, "Uma recompensa especial será oferecida à primeira pessoa a produzir um programa real que não produz 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.
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. Metas necessárias
mas não sob certas circunstâncias (como exigem um build específico
sinalizações, não são desenvolvidas em uma determinada plataforma, exigem contratos de licença) devem ser
seja marcada da forma mais específica possível (por exemplo, "requires-osx"). Isso
a inclusão de tag permite que os destinos sejam filtrados em um nível mais detalhado do que o
"manual" e permite que alguém que inspecione o arquivo BUILD entenda qual
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
Tudo deve ser criado da fonte sempre que possível. 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
destino.
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 apenas trabalham 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
usado, evite incluir a versão no nome de destino (por exemplo, //guava,
e não //guava-20.0). Essa nomenclatura facilita a atualização da biblioteca (apenas um
o destino precisa ser atualizado). Ele também é mais resiliente à dependência de diamantes
problemas: se uma biblioteca depende de guava-19.0 e outra depende de guava-20.0,
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 do
workspace/.bazelrc (consulte formato bazelrc).
Se você quiser oferecer suporte para opções por usuário para seu projeto que você não deseja verificar o 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 seu .gitignore.
Pacotes
Todo diretório que contém arquivos edificá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
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.