Práticas recomendadas

Informar um problema Ver código-fonte

Nesta página, presumimos que você conhece o Bazel e fornece orientações e conselhos sobre como estruturar seus projetos para aproveitar ao máximo os recursos do Bazel.

Os objetivos gerais são os seguintes:

  • Usar dependências detalhadas para permitir o paralelismo e a incrementabilidade.
  • Para manter as dependências bem encapsuladas.
  • Para deixar o código bem estruturado e testável.
  • Para criar uma configuração de build que seja fácil de entender e manter.

Essas diretrizes não são requisitos: alguns projetos poderão aderir a todas elas. Como diz a página do manual do lint, "Uma recompensa especial será apresentada à primeira pessoa para produzir um programa real que não produz erros com verificação rigorosa". No entanto, incorporar o máximo possível desses princípios pode deixar o projeto mais legível, menos propenso a erros e mais rápido.

Nesta página, usamos os níveis de requisito descritos nesta RFC.

Como executar builds e testes

Um projeto sempre pode executar bazel build //... e bazel test //... na ramificação estável dele. Os destinos que são necessários, mas não são criados sob determinadas circunstâncias (como, por exemplo, exigem sinalizações de compilação específicas, não criam em uma determinada plataforma, exigem contratos de licença) precisam ser marcados da maneira mais específica possível (por exemplo, "requires-osx"). Essa tag permite que os destinos sejam filtrados em um nível mais refinado 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-as como repositórios remotos no arquivo WORKSPACE.
  • Se preferir, coloque-os em um diretório chamado third_party/ no seu diretório do espaço de trabalho.

Dependendo dos binários

Tudo precisa ser criado da origem sempre que possível. Geralmente, isso 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 e, em seguida, precisaria depender desse destino.

A criação de origem sempre garante que um build não esteja usando uma biblioteca que tenha sido criada 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 só funcionam na origem.

Controle de versões

Prefira criar todo o código da cabeça sempre que possível. Quando as versões precisarem 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 losangos: 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 vão ser enganosos.

Como usar o arquivo .bazelrc

Para ver opções específicas do projeto, use o arquivo de configuração do workspace/.bazelrc (consulte o formato bazelrc).

Se você quiser oferecer compatibilidade com 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) no workspace/.bazelrc e adicione user.bazelrc ao .gitignore.

Entrega de pacotes

Todo diretório que contém arquivos que podem ser compilados precisa ser um pacote. Se um arquivo BUILD se referir 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 longa essa estrutura existir, mais prováveis dependências circulares serão criadas acidentalmente, o escopo do destino aumentará e um número crescente de dependências inversas precisará ser atualizado.