Como implantar regras

Informar um problema Acessar a origem

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_settings e/ou constraint_values 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.