Práticas recomendadas

Relatar um problema Conferir código-fonte Por noite · 7,3 · 7,2 · 7,1 · 7,0 · 6,5

Nesta página, consideramos que você já conhece o Bazel e apresenta diretrizes e conselhos sobre como estruturar projetos para aproveitar ao máximo os recursos do Bazel.

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. todos eles. 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.

Nesta página, usamos os níveis de requisitos descritos em deste RFC.

Como executar builds e testes

É necessário que um projeto sempre possa 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

É 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 uma arquivo BUILD e criar some-library.so a partir das origens, depois dependa disso. alvo.

Sempre criar a partir da origem garante que um build não use uma biblioteca que foi criado com sinalizações 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 workspace/.bazelrc (consulte o 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 BUILD refere-se 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 esta estrutura existir, as dependências circulares mais prováveis serão criadas acidentalmente, o escopo de um destino se infiltra e um número de dependências reversas precisarão ser atualizadas.