Esta página é destinada a criadores de regras que planejam disponibilizar suas 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 e inclui a geração de documentação da API e configura um pipeline de CI/CD para simplificar a distribuição do conjunto de regras.
Regras de nomenclatura e hospedagem
As novas regras devem ser enviadas para o próprio repositório do GitHub na sua organização. Inicie uma conversa no GitHub se você achar que suas regras pertencem à organização bazelbuild.
Os nomes de repositório para regras do Bazel são padronizados neste formato:
$ORGANIZATION/rules_$NAME
.
Confira exemplos no GitHub (em inglês).
Para consistência, siga esse mesmo formato ao publicar suas regras do Bazel.
Use uma descrição descritiva do repositório do GitHub e o título README.md
, de exemplo:
- Nome do repositório:
bazelbuild/rules_go
- Descrição do repositório: regras de Go para o Bazel
- Tags do repositório:
golang
,bazel
- Cabeçalho
README.md
: regras Go para o Bazel (link em inglês). Observe o link para https://bazel.build, que orienta os usuários que não estão familiarizados com o Bazel para o lugar certo.
As regras podem ser agrupadas por linguagem (como Scala), plataforma de tempo de execução (como Android) ou framework (como Spring).
Conteúdo do repositório
Cada repositório de regras precisa ter um determinado layout para que os usuários possam entender rapidamente as novas regras.
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 fazer referência às regras. Se as regras pertencerem à organização bazelbuild, use rules_<lang>
(como rules_mockascript
). Caso contrário, nomeie seu 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 devem 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 a regra.
Em geral, será um http_archive
que aponta para sua versão do GitHub e
uma chamada de macro que faz o download/configura todas as ferramentas de que a regra precisa. Por exemplo,
para as regras
Go, o
resultado é:
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 dependerem das regras de outro repositório, especifique isso na documentação de 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, várias regras são fornecidas pelo repositório. 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
, além de 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-os em um pacote //<LANG>/constraints
. A
estrutura de diretórios ficará assim:
/
mockascript/
constraints/
BUILD
BUILD
defs.bzl
Leia
github.com/bazelbuild/platforms (link em inglês)
para conhecer as práticas recomendadas e ver quais restrições já estão presentes.
Considere contribuir com suas restrições, caso elas sejam independentes de 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 seleções.
Com restrições personalizadas, você define uma linguagem falada por todo o ecossistema do Bazel.
Biblioteca Runfiles
Se a regra fornecer uma biblioteca padrão para acessar arquivos de execução, ela precisará estar
na forma de um destino de biblioteca localizado em //<LANG>/runfiles
(uma abreviação
de //<LANG>/runfiles:runfiles
). Os destinos de usuários que precisam acessar as dependências de dados
normalmente adicionarão esse destino ao atributo deps
.
Regras de repositório
Dependências
Suas regras podem ter dependências externas. Para simplificar as regras, forneça uma macro WORKSPACE
que vai declarar as dependências
dessas dependências externas. Não declare dependências de testes nele, apenas
as 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 será semelhante a este:
/
mockascript/
constraints/
BUILD
BUILD
defs.bzl
repositories.bzl
Registrar conjuntos de ferramentas
As 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 dependências manualmente, mantendo a permissão para
registrar conjuntos de ferramentas.
Portanto, adicione uma macro WORKSPACE
chamada rules_<LANG>_toolchains
ao
arquivo <LANG>/repositories.bzl
.
Observe que, para resolver conjuntos de ferramentas na fase de análise, o Bazel precisa
analisar todos os destinos toolchain
registrados. O Bazel não vai precisar
analisar todos os destinos referenciados pelo atributo toolchain.toolchain
. Se, para
registrar conjuntos de ferramentas, você precisar executar computação complexa no
repositório, divida o repositório com destinos toolchain
do
repositório com destinos <LANG>_toolchain
. O anterior sempre será buscado, e
o último só será buscado quando o usuário precisar criar o código <LANG>
.
Snippet da versão
No aviso de lançamento, forneça um snippet que os usuários podem copiar e colar
no arquivo WORKSPACE
. Em geral, o snippet fica assim:
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
É preciso haver testes para verificar se as regras estão funcionando conforme o esperado. Ele
pode estar no local padrão do idioma das regras ou 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 ações do GitHub. Veja a configuração usada no repositório rules-template, que é simplificado com um "fluxo de trabalho reutilizável" hospedado na organização bazel-contrib. O ci.yaml
executa testes em cada comit de PR e main
, e o release.yaml
é executado sempre que você envia uma tag ao repositório.
Veja comentários no repositório do modelo de regras para mais informações.
Se o repositório estiver na organização bazelbuild, peça para adicioná-lo a 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/ do modelo de regras
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 das versões do Bazel o máximo possível. Fica mais claro quem é o proprietário das regras individuais, reduzindo a carga para os 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 contribuir para o Bazel, dependendo das regras, incluindo o acesso de envio total ao repositório do GitHub correspondente. O 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 copiar e colar uma regra no arquivo WORKSPACE
, conforme mostrado na
seção README.md
acima.
Costumamos ter todas as regras no repositório do Bazel (em
//tools/build_rules
ou //tools/build_defs
). Ainda temos algumas regras, mas estamos trabalhando para remover as restantes.