Esta página é destinada a criadores de regras que planejam disponibilizar regras para outras pessoas.
Recomendamos que você inicie um novo conjunto de regras a partir do repositório de modelos: https://github.com/bazel-contrib/rules-template Esse modelo segue as recomendações abaixo, 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 ser colocadas no repositório do GitHub da sua organização. Inicie uma linha de execução no GitHub se você achar que suas regras pertencem à organização bazelbuild.
Os nomes de repositório para regras do Bazel são padronizados com o seguinte formato:
$ORGANIZATION/rules_$NAME.
Consulte exemplos no GitHub.
Para manter a consistência, siga esse mesmo formato ao publicar suas regras do Bazel.
Use uma descrição descritiva do repositório do GitHub e um título README.md, por exemplo:
- Nome do repositório:
bazelbuild/rules_go - Descrição do repositório: Regras Go para o Bazel
- Tags do repositório:
golang,bazel - Cabeçalho
README.md: Regras do Go para Bazel (observe o link para https://bazel.build, que vai orientar os usuários que não estão familiarizados com o Bazel para o lugar certo)
As regras podem ser agrupadas por idioma (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 mockascript
(ficção), 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 usarão para se referir às suas regras. Se as regras pertencerem à
organização bazelbuild, use
rules_<lang> (como rules_mockascript). Caso contrário, nomeie o
repositório como <org>_rules_<lang> (como build_stack_rules_proto).
Inicie uma conversa no GitHub
se você achar que suas regras devem seguir a convenção de regras na
organização bazelbuild.
Nas seções a seguir, suponha que o repositório pertence à organização bazelbuild.
module(name = "rules_mockascript")
README
No nível superior, deve haver um README que contenha uma breve descrição
da regra e o que os usuários da API podem esperar.
Regras
Muitas vezes, o repositório vai fornecer várias regras. Crie um diretório nomeado de acordo com a linguagem e forneça um ponto de entrada: o arquivo defs.bzl exportando 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 e um arquivo BUILD e um defs.bzl dentro:
/
mockascript/
BUILD
defs.bzl
Restrições
Se a regra definir regras do
conjunto de ferramentas,
talvez seja necessário definir constraint_settings e/ou
constraint_values personalizados. Coloque-as em um pacote //<LANG>/constraints. A
estrutura de diretórios vai ficar assim:
/
mockascript/
constraints/
BUILD
BUILD
defs.bzl
Leia
github.com/bazelbuild/platforms
para ver as práticas recomendadas, ver quais restrições já estão presentes e
considerar contribuir com suas restrições se elas não dependem da linguagem.
Tenha cuidado ao introduzir restrições personalizadas. Todos os usuários das suas regras vão
usá-las para executar a lógica específica da plataforma nos arquivos BUILD (por exemplo,
usando seleções).
Com as restrições personalizadas, você define um idioma que todo o ecossistema do Bazel
vai usar.
Biblioteca de runfiles
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 geralmente adicionam esse destino ao atributo deps.
Regras do repositório
Dependências
As regras podem ter dependências externas, que você precisa especificar no arquivo MODULE.bazel.
Como registrar toolchains
As regras também podem registrar toolchains, que também podem ser especificadas no arquivo MODULE.bazel.
Para resolver as cadeias 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 toolchains, você precisar realizar cálculos complexos no
repositório, considere dividir o repositório com destinos toolchain do
repositório com destinos <LANG>_toolchain. O primeiro será sempre buscado, e
o segundo só será buscado quando o usuário precisar criar o 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 em geral vai ficar assim:
bazel_dep(name = "rules_<LANG>", version = "<VERSION>")
Testes
Deve haver testes que verifiquem se as regras estão funcionando conforme o esperado. Ele
pode estar no local padrão do idioma para o qual as regras são ou em um
diretório tests/ no nível superior.
Exemplos (opcional)
É útil que os usuários tenham 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 no bazel-contrib
org. O ci.yaml executa testes em cada comit PR e main, e o release.yaml é executado sempre que você envia uma tag ao repositório.
Consulte os comentários no repositório rules-template para mais informações.
Se o repositório estiver na organização bazelbuild, é possível pedir para adicioná-lo ao ci.bazel.build.
Documentação
Consulte a documentação do Stardoc para instruções sobre como comentar suas regras para que a documentação possa ser gerada automaticamente.
A pasta docs/rules-template
mostra uma maneira simples de garantir que o conteúdo do Markdown na pasta docs/ esteja sempre atualizado
à medida que os arquivos do Starlark são atualizados.
Perguntas frequentes
Por que não podemos adicionar nossa regra ao repositório principal do Bazel no GitHub?
Queremos desvincular as regras dos lançamentos do Bazel o máximo possível. Fica mais claro quem é o proprietário das regras individuais, reduzindo a carga sobre os desenvolvedores do Bazel. Para nossos usuários, a separação facilita a modificação, o upgrade, o downgrade e a substituição de regras. Contribuir com regras pode ser mais leve do que contribuir com o Bazel, dependendo das regras, incluindo o acesso de envio total ao repositório do GitHub correspondente. O processo de envio de acesso ao Bazel é muito mais envolvente.
A desvantagem é um processo de instalação única mais complicado para nossos usuários:
eles precisam adicionar uma dependência à regra no arquivo MODULE.bazel.
Antes, todas as regras estavam no repositório do Bazel (em
//tools/build_rules ou //tools/build_defs). Ainda temos algumas regras
lá, mas estamos trabalhando para removê-las.