Como implantar regras

Esta página é destinada a autores de regras que planejam disponibilizar as regras para outras pessoas.

Recomendamos que você inicie um novo conjunto de regras no repositório de modelos: https://github.com/bazel-contrib/rules-template Esse modelo segue as recomendações abaixo e inclui a geração de documentação da API e configura um pipeline de CI/CD para facilitar a distribuição do conjunto de regras.

Regras de hospedagem e nomenclatura

As novas regras precisam estar no próprio repositório do GitHub na sua organização. Inicie uma conversa no GitHub se achar que suas regras pertencem à organização bazelbuild.

Os nomes dos repositórios para regras do Bazel são padronizados no seguinte formato: $ORGANIZATION/rules_$NAME. Confira exemplos no GitHub. Para manter a consistência, siga o mesmo formato ao publicar as regras do Bazel.

Use uma descrição do repositório do GitHub e um README.md título descritivos. Exemplo:

• Nome do repositório: bazelbuild/rules_go
• Descrição do repositório: Regras do Go para o Bazel
• Tags do repositório: golang, bazel
• README.md cabeçalho: Regras do Go para o Bazel (observe o link para https://bazel.build, que orienta os usuários que não conhecem o Bazel ao lugar certo)

As regras podem ser agrupadas por linguagem (como Scala), plataforma de execução (como Android) ou framework (como Spring).

Conteúdo do repositório

Cada repositório de regras precisa ter um layout específico para que os usuários possam entender rapidamente as novas regras.

Por exemplo, ao escrever novas regras para a linguagem (fictícia) mockascript, o repositório de regras teria a seguinte estrutura:

/
  LICENSE
  README
  MODULE.bazel
  mockascript/
    constraints/
      BUILD
    runfiles/
      BUILD
      runfiles.mocs
    BUILD
    defs.bzl
  tests/
    BUILD
    some_test.sh
    another_test.py
  examples/
    BUILD
    bin.mocs
    lib.mocs
    test.mocs

MODULE.bazel

No MODULE.bazel do projeto, defina o nome que os usuários vão usar para referenciar suas regras. Se as regras pertencerem à bazelbuild organização, use rules_<lang> (como rules_mockascript). Caso contrário, nomeie seu repositório <org>_rules_<lang> (como build_stack_rules_proto). Por favor, inicie uma conversa no GitHub se achar que suas regras devem seguir a convenção para regras na bazelbuild organização.

Nas seções a seguir, suponha que o repositório pertença à bazelbuild organização.

module(name = "rules_mockascript")

README

No nível superior, precisa haver um README que contenha uma breve descrição do conjunto de regras e da API que os usuários precisam esperar.

Regras

Muitas vezes, o repositório vai fornecer várias regras. Crie um diretório nomeado pela linguagem e forneça um ponto de entrada: defs.bzl arquivo que exporta todas as regras. Inclua também um arquivo BUILD para que o diretório seja um pacote. Para rules_mockascript, isso significa que haverá um diretório chamado mockascript, um arquivo BUILD e um arquivo defs.bzl dentro dele:

/
  mockascript/
    BUILD
    defs.bzl

Restrições

Se a regra definir regras de conjunto de ferramentas, talvez seja necessário definir constraint_settings e/ou constraint_values personalizados. Coloque-os em um pacote //<LANG>/constraints. A estrutura do diretório será assim:

/
  mockascript/
    constraints/
      BUILD
    BUILD
    defs.bzl

Leia github.com/bazelbuild/platforms para conferir as práticas recomendadas e as restrições já presentes. Considere contribuir com suas restrições se elas forem independentes da linguagem. Tenha cuidado ao introduzir restrições personalizadas. Todos os usuários das suas regras vão usá-las para realizar uma lógica específica da plataforma nos arquivos BUILD (por exemplo, usando seleções). Com restrições personalizadas, você define uma linguagem que todo o ecossistema do Bazel vai usar.

Biblioteca de arquivos de execução

Se a regra fornecer uma biblioteca padrão para acessar arquivos de execução, ela precisa estar na forma de um destino de biblioteca localizado em //<LANG>/runfiles (uma abreviação de //<LANG>/runfiles:runfiles). Os destinos do usuário que precisam acessar as dependências de dados normalmente adicionam esse destino ao atributo deps.

Regras do repositório

Dependências

As regras podem ter dependências externas, que precisam ser especificadas em seu arquivo MODULE.bazel.

Como registrar conjuntos de ferramentas

As regras também podem registrar conjuntos de ferramentas, que também podem ser especificados no arquivo MODULE.bazel.

Para resolver conjuntos de ferramentas na fase de análise, o Bazel precisa analisar todos os destinos toolchain registrados. O Bazel não precisa analisar todos os destinos referenciados pelo atributo toolchain.toolchain. Se, para registrar conjuntos de ferramentas, você precisar realizar cálculos complexos no repositório, considere dividir o repositório com toolchain destinos do repositório com <LANG>_toolchain destinos. O primeiro será sempre buscado, e o segundo só será buscado quando o usuário precisar criar um código <LANG>.

Snippet de lançamento

No anúncio de lançamento, forneça um snippet que os usuários possam copiar e colar no arquivo MODULE.bazel. Esse snippet geralmente será assim:

bazel_dep(name = "rules_<LANG>", version = "<VERSION>")

Testes

É necessário que haja testes que verifiquem se as regras estão funcionando conforme o esperado. Isto pode estar no local padrão da linguagem para a qual as regras são ou em um tests/ diretório no nível superior.

Exemplos (opcional)

É útil para os usuários ter um diretório examples/ que mostre algumas maneiras básicas de usar as regras.

CI/CD

Muitos conjuntos de regras usam o GitHub Actions. Consulte a configuração usada no repositório rules-template, que é simplificada usando um "fluxo de trabalho reutilizável" hospedado na organização bazel-contrib. ci.yaml executa testes em cada solicitação de envio e confirmação main, e release.yaml é executado sempre que você envia uma tag para o repositório. Consulte os comentários no repositório rules-template para mais informações.

Se o repositório estiver na organização bazelbuild, você pode pedir para adicionar a ci.bazel.build.

Documentação

Consulte a documentação do Stardoc para instruções sobre como comentar as regras para que a documentação possa ser gerada automaticamente.

A pasta docs/ do rules-template mostra uma maneira simples de garantir que o conteúdo do Markdown na pasta docs/ esteja sempre atualizado à medida que os arquivos Starlark são atualizados.

Perguntas frequentes

Por que não podemos adicionar nossa regra ao repositório principal do GitHub do Bazel?

Queremos separar as regras dos lançamentos do Bazel o máximo possível. É mais claro quem é o proprietário das regras individuais, reduzindo a carga dos desenvolvedores do Bazel. Para nossos usuários, a separação facilita a modificação, o upgrade, o downgrade e a substituição de regras. A contribuição para regras pode ser mais leve do que a contribuição para o Bazel - dependendo das regras -, incluindo acesso total ao repositório do GitHub correspondente. Obter acesso de envio ao próprio Bazel é um processo muito mais complexo.

A desvantagem é um processo de instalação única mais complicado para nossos usuários: eles precisam adicionar uma dependência ao conjunto de regras no arquivo MODULE.bazel.

Antes, tínhamos todas as regras no repositório do Bazel (em //tools/build_rules ou //tools/build_defs). Ainda temos algumas regras lá, mas estamos trabalhando para remover as regras restantes.