Esta página é destinada aos criadores de regras que planejam disponibilizar suas regras a 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 e inclui a geração da documentação da API e configura um pipeline de CI/CD para facilitar a distribuição do seu conjunto de regras.
Regras de hospedagem e nomenclatura
As novas regras precisam entrar no próprio repositório do GitHub na sua organização. Iniciar uma conversa no GitHub se você achar que suas regras pertencem ao bazelbuild organização.
Os nomes de repositório para as regras do Bazel são padronizados no seguinte formato:
$ORGANIZATION/rules_$NAME:
Confira exemplos no GitHub (em inglês).
Para manter a consistência, siga este mesmo formato ao publicar regras do Bazel.
Use uma descrição descritiva do repositório do GitHub e README.md
título, exemplo:
- Nome do repositório:
bazelbuild/rules_go - Descrição do repositório: Regras do Go para Bazel
- Tags do repositório:
golang,bazel - Cabeçalho
README.md: regras Go para o Bazel (confira o link https://bazel.build para orientar os usuários que não conhecem com o Bazel ao lugar certo).
As regras podem ser agrupadas por linguagem (como Scala), plataforma de ambiente de execução (como o Android) ou framework (como Spring).
Conteúdo do repositório
Cada repositório de regras deve ter um layout específico para que os usuários possam entender novas regras.
Por exemplo, ao escrever novas regras para o (make-believe)
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 fazer referência às suas regras. Se suas regras pertencem ao
bazelbuild, é preciso usar
rules_<lang> (como rules_mockascript). Caso contrário, você deve nomear
repositório <org>_rules_<lang> (como build_stack_rules_proto). Não se esqueça
iniciar uma conversa no GitHub
se você acha que suas regras devem seguir a convenção de regras na
bazelbuild.
Nas seções a seguir, suponha que o repositório pertença ao bazelbuild.
module(name = "rules_mockascript")
README
No nível superior, deve haver uma README com uma breve descrição
do seu conjunto de regras e a API que os usuários devem esperar.
Regras
Muitas vezes, o repositório vai fornecer várias regras. Crie um
diretório nomeado de acordo com a linguagem e fornece um arquivo defs.bzl de ponto de entrada.
exportar 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 arquivo defs.bzl dentro:
/
mockascript/
BUILD
defs.bzl
Restrições
Se a regra define
regras do conjunto de ferramentas.
talvez seja necessário definir constraint_settings personalizadas e/ou
constraint_value Coloque-as em um pacote //<LANG>/constraints. Seu
será semelhante a esta:
/
mockascript/
constraints/
BUILD
BUILD
defs.bzl
Leia
github.com/bazelbuild/platforms
para conhecer as práticas recomendadas e ver quais restrições já estão presentes, e
considere contribuir com suas restrições se elas não dependem da linguagem.
Esteja atento à introdução de restrições personalizadas, pois todos os usuários de suas regras
Use-as para executar a lógica específica da plataforma nos arquivos BUILD (por exemplo,
usando selects).
Com restrições personalizadas, você define uma linguagem que todo o ecossistema do Bazel
falará.
Biblioteca Runfiles
Se sua regra oferece uma biblioteca padrão para acessar arquivos de execução, ela deve ser
na forma de uma biblioteca de destino localizada em //<LANG>/runfiles (uma abreviação
de //<LANG>/runfiles:runfiles). Segmentações de usuários que precisam acessar os dados
dependências normalmente adicionam esse destino ao atributo deps.
Regras do repositório
Dependências
Suas regras podem ter dependências externas, que você precisará especificar em arquivo MODULE.bazel.
Como registrar conjuntos de ferramentas
Suas regras também podem registrar conjuntos de ferramentas, que você também pode especificar no arquivo MODULE.bazel.
Para resolver os conjuntos de ferramentas na fase de análise, o Bazel precisa fazer o seguinte:
analisar todos os toolchain destinos registrados. O Bazel não precisa
analisar todos os destinos referenciados pelo atributo toolchain.toolchain; Se em ordem
para registrar conjuntos de ferramentas, você precisa realizar cálculos complexos no
repositório, considere dividi-lo com destinos toolchain do
repositório com <LANG>_toolchain destinos. A classe antiga será sempre buscada, 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. Em geral, esse snippet será semelhante a este:
bazel_dep(name = "rules_<LANG>", version = "<VERSION>")
Testes
Deve haver testes para verificar se as regras estão funcionando conforme o esperado. Isso
pode estar no local padrão para o idioma das regras ou em um
tests/ 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. Veja a configuração usada no repositório rules-template, que é simplificada com um "fluxo de trabalho reutilizável". hospedados no cluster 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.
Veja os comentários no repositório de modelos de regras para mais informações.
Se o repositório estiver na organização bazelbuild, você pode pedir para adicionar para 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.
rules-template docs/ folder
mostra uma maneira simples de garantir que o conteúdo Markdown na pasta docs/ esteja sempre atualizado
conforme 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 dissociar as regras das versões do Bazel o máximo possível. É mais clara proprietário de regras individuais, o que reduz a carga dos desenvolvedores do Bazel. Para nossos usuários, o desacoplamento facilita a modificação, o upgrade, o downgrade e a substituição de regras. A contribuição para as regras pode ser mais leve do que a do Bazel. dependendo das regras, incluindo acesso total ao envio repositório do GitHub. Ter acesso de envio ao Bazel é muito mais complicado de desenvolvimento de software.
A desvantagem é um processo de instalação única mais complicado para nossos usuários:
É necessário adicionar uma dependência ao conjunto de regras no arquivo MODULE.bazel.
Costumávamos ter todas as regras no repositório do Bazel (em
//tools/build_rules ou //tools/build_defs). Ainda temos algumas regras
no site, mas estamos trabalhando para remover as demais.