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 entrar no próprio repositório do GitHub na 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
.
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 um título README.md
, 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 do Go para o Bazel (link em inglês) (confira o link https://bazel.build, que vai orientar os usuários que não conhecem o Bazel sobre o local correto)
As regras podem ser agrupadas por linguagem (como Scala), plataforma de ambiente 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 as novas regras rapidamente.
Por exemplo, ao escrever novas regras para a linguagem mockascript
(make-believe), o repositório de regras teria a seguinte estrutura:
/
LICENSE
README
WORKSPACE
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
ESPAÇO DE TRABALHO
No WORKSPACE
do projeto, defina o nome que os usuários usarão para se referir às suas regras. Se as regras pertencem à organização
bazelbuild, use
rules_<lang>
(por exemplo, rules_mockascript
). Caso contrário, nomeie o
repositório como <org>_rules_<lang>
(como build_stack_rules_proto
). Inicie
uma linha de execução no GitHub
se você achar que suas regras precisam seguir a convenção de regras na organização
bazelbuild.
Nas seções a seguir, suponha que o repositório pertença à organização bazelbuild.
workspace(name = "rules_mockascript")
README
No nível superior, deve haver um README
que contenha (pelo menos) o que os usuários precisarão copiar e colar no arquivo WORKSPACE
para usar sua regra.
Em geral, será um http_archive
apontando para a versão do GitHub e
uma chamada de macro que faz o download/configura as ferramentas necessárias para a regra. Por exemplo,
para as regras
do Go, a aparência
ficará assim:
load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
http_archive(
name = "rules_go",
urls = ["https://github.com/bazelbuild/rules_go/releases/download/0.18.5/rules_go-0.18.5.tar.gz"],
sha256 = "a82a352bffae6bee4e95f68a8d80a70e87f42c4741e6a448bec11998fcc82329",
)
load("@rules_go//go:deps.bzl", "go_rules_dependencies", "go_register_toolchains")
go_rules_dependencies()
go_register_toolchains()
Se suas regras dependem das regras de outro repositório, especifique isso na documentação das regras (por exemplo, consulte as regras do Skydoc, que dependem das regras do Sass) e forneça uma macro WORKSPACE
que fará o download de todas as dependências (consulte rules_go
acima).
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 arquivo defs.bzl
dentro:
/
mockascript/
BUILD
defs.bzl
Restrições
Se a regra definir regras do conjunto de ferramentas, talvez seja necessário definir constraint_setting
s e/ou constraint_value
s personalizados. Coloque-as em um pacote //<LANG>/constraints
. Sua estrutura de diretórios será semelhante a esta:
/
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.
Não se esqueça de introduzir restrições personalizadas. Todos os usuários das suas regras as
usarão 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
vai falar.
Biblioteca Runfiles
Se a regra fornece uma biblioteca padrão para acessar arquivos de execução, ela precisa estar
na forma de um destino de biblioteca localizado em //<LANG>/runfiles
(abreviação
de //<LANG>/runfiles:runfiles
). Os destinos de usuários que precisam acessar as dependências
de dados geralmente adicionam esse destino ao atributo deps
.
Regras do repositório
Dependências
Suas regras podem ter dependências externas. Para tornar a dependência de suas regras
mais simples, forneça uma macro WORKSPACE
que declare as dependências
nessas dependências externas. Não declare dependências de testes lá, apenas
dependências que as regras exigem para funcionar. Coloque as dependências de desenvolvimento no
arquivo WORKSPACE
.
Crie um arquivo chamado <LANG>/repositories.bzl
e forneça uma única macro de ponto de entrada chamada rules_<LANG>_dependencies
. Nosso diretório vai ficar assim:
/
mockascript/
constraints/
BUILD
BUILD
defs.bzl
repositories.bzl
Como registrar conjuntos de ferramentas
Suas regras também podem registrar conjuntos de ferramentas. Forneça uma macro WORKSPACE
separada que registre esses conjuntos de ferramentas. Dessa forma, os usuários podem decidir omitir a
macro anterior e controlar as dependências manualmente, mantendo o registro dos conjuntos de ferramentas.
Portanto, adicione uma macro WORKSPACE
chamada rules_<LANG>_toolchains
ao
arquivo <LANG>/repositories.bzl
.
Para resolver os 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 os conjuntos de ferramentas, você precisar executar cálculos complexos no
repositório, divida o repositório com destinos toolchain
do
repositório com destinos <LANG>_toolchain
. A classe anterior vai ser sempre buscada, e
a segunda apenas 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 WORKSPACE
. Em geral, esse snippet será semelhante a este:
load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
http_archive(
name = "rules_<LANG>",
urls = ["<url_to_the_release.zip"],
sha256 = "4242424242",
)
load("@rules_<LANG>//<LANG>:repositories.bzl", "rules_<LANG>_dependencies", "rules_<LANG>_toolchains")
rules_<LANG>_dependencies()
rules_<LANG>_toolchains()
Testes
Deve haver testes para verificar 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 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 por meio de um "fluxo de trabalho reutilizável" hospedado na organização bazel-contrib. 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 adicioná-lo a ci.bazel.build.
Documentação
Consulte a documentação do Stardoc (em inglês) para instruções sobre como comentar suas regras para que a documentação seja gerada automaticamente.
A rules-template docs/ folder
mostra uma maneira simples de garantir que o conteú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 Bazel no GitHub?
Queremos dissociar as regras das versões do Bazel o máximo possível. Ficou mais claro quem é o proprietário das regras individuais, reduzindo a carga para desenvolvedores do Bazel. Para nossos usuários, a dissociação facilita a modificação, o upgrade, o downgrade e a substituição de regras. Contribuir com regras pode ser mais leve do que com o Bazel, dependendo das regras, incluindo acesso total de envio ao repositório correspondente do GitHub. Conseguir acesso de envio ao próprio Bazel é um processo muito mais envolvido.
A desvantagem é um processo de instalação única mais complicado para nossos usuários: eles precisam copiar e colar uma regra no arquivo WORKSPACE
, conforme mostrado na seção README.md
acima.
Costumávamos ter 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 demais.