Como implantar regras

Informar um problema Mostrar fonte Por noite · 7,3 · 7,2 · 7,1 · 7,0 · 6,5

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
  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 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.

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 todas as ferramentas necessárias para a regra. Por exemplo: para o Go regras, esse é semelhante a:

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 no de regras de firewall (por exemplo, consulte a Regras do Skydoc, que dependem das regras do Sass) e fornecem um WORKSPACE que fará o download de todas as dependências (veja 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 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. Fazer com que dependendo das suas regras mais simples, forneça uma macro WORKSPACE que declarará dependências no essas dependências externas. Não declare dependências de testes nesse arquivo, somente dependências que as regras exigem para funcionar. Coloque as dependências de desenvolvimento no WORKSPACE.

Crie um arquivo chamado <LANG>/repositories.bzl e forneça um único 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 um WORKSPACE separado que registra esses conjuntos de ferramentas. Dessa forma, os usuários podem decidir omitir a macro anterior e controlar as dependências manualmente, enquanto ainda pode registrar conjuntos de ferramentas.

Portanto, adicione uma macro WORKSPACE chamada rules_<LANG>_toolchains arquivo <LANG>/repositories.bzl.

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 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. 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 copiar e colar uma regra no arquivo WORKSPACE, conforme mostrado 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 no site, mas estamos trabalhando para remover as demais.