Como implantar regras

Esta página é destinada a criadores de regras que planejam disponibilizar as regras para outras pessoas.

Recomendamos que você inicie um novo conjunto de regras no 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 estar em um repositório do GitHub próprio na sua organização. Inicie uma conversa no GitHub se você achar que suas regras pertencem à organização bazelbuild.

Os nomes de repositórios para regras do Bazel são padronizados no seguinte formato: $ORGANIZATION/rules_$NAME. Confira exemplos no GitHub. Para manter a consistência, siga o mesmo formato ao publicar suas regras do Bazel.

Use uma descrição descritiva do repositório do GitHub e um título README.md. Por 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 Bazel (observe o link para https://bazel.build, que vai direcionar os usuários que não conhecem o Bazel para o lugar certo)

As regras podem ser agrupadas por linguagem (como Scala), plataforma de execução (como Android) ou framework (como Spring).

Conteúdo do repositório

Todo repositório de regras precisa ter um layout específico para que os usuários possam entender rapidamente novas regras.

Por exemplo, ao escrever novas regras para a linguagem (fictícia) 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

WORKSPACE

No WORKSPACE do projeto, defina o nome que os usuários vão usar para se referir às suas regras. Se as suas 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 conversa no GitHub se você achar que suas regras devem seguir a convenção da 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 que aponta para sua versão do GitHub e uma chamada de macro que faz o download/configura todas as ferramentas necessárias para sua regra. Por exemplo, para as regras do Go, isso seria 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 as regras dependerem 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 faça o download de todas as dependências (consulte rules_go acima).

Regras

Muitas vezes, o repositório fornece várias regras. Crie um diretório com o nome do idioma e forneça um ponto de entrada: um arquivo defs.bzl que exporte 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 dele:

/
  mockascript/
    BUILD
    defs.bzl

Restrições

Se a regra definir regras de cadeia de ferramentas, talvez seja necessário definir constraint_settings e/ou constraint_values personalizados. Coloque-os em um pacote //<LANG>/constraints. Sua estrutura de diretórios vai ficar assim:

/
  mockascript/
    constraints/
      BUILD
    BUILD
    defs.bzl

Leia github.com/bazelbuild/platforms para conferir as práticas recomendadas e as restrições já presentes, e considere contribuir com suas restrições se elas forem independentes de linguagem. Tenha cuidado ao introduzir restrições personalizadas. Todos os usuários das suas regras vão usá-las para realizar uma lógica específica da plataforma nos arquivos BUILD (por exemplo, usando seletores). Com as restrições personalizadas, você define uma linguagem que todo o ecossistema do Bazel vai usar.

Biblioteca de arquivos de execução

Se a regra fornecer uma biblioteca padrão para acessar runfiles, ela deverá estar na forma de um destino de biblioteca localizado em //<LANG>/runfiles (uma abreviação de //<LANG>/runfiles:runfiles). Os destinos do usuário 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 simplificar a dependência das suas regras, forneça uma macro WORKSPACE que declare dependências dessas dependências externas. Não declare dependências de testes ali, 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 toolchains. Forneça uma macro WORKSPACE separada que registre essas cadeias de ferramentas. Assim, os usuários podem omitir a macro anterior e controlar as dependências manualmente, sem deixar de registrar toolchains.

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

Para resolver toolchains na fase de análise, o Bazel precisa analisar todos os destinos toolchain registrados. O Bazel não precisará analisar todos os destinos referenciados pelo atributo toolchain.toolchain. Se você precisar realizar cálculos complexos no repositório para registrar toolchains, divida o repositório com destinos toolchain do repositório com destinos <LANG>_toolchain. O primeiro sempre será buscado, e o segundo só será buscado quando o usuário precisar criar código <LANG>.

Snippet de lançamento

No anúncio do lançamento, forneça um snippet que os usuários possam copiar e colar no arquivo WORKSPACE. Em geral, o snippet vai ter esta aparência:

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 que verifiquem se as regras estão funcionando conforme o esperado. Isso pode estar no local padrão do idioma das regras 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 usando um "fluxo de trabalho reutilizável" hospedado na organização bazel-contrib. O ci.yaml executa testes em cada solicitação de pull e commit main, e o release.yaml é executado sempre que você envia uma tag para o repositório. Consulte os comentários no repositório rules-template para mais informações.

Se o repositório estiver na organização bazelbuild, você pode pedir para adicionar 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/ rules-template 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 Bazel no GitHub?

Queremos desacoplar as regras dos lançamentos do Bazel o máximo possível. Fica mais claro quem é o proprietário das regras individuais, reduzindo 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. Contribuir com regras pode ser mais leve do que contribuir com o Bazel, dependendo das regras, incluindo acesso total de envio ao repositório do GitHub correspondente. Receber acesso de envio ao próprio Bazel é um processo muito mais complexo.

A desvantagem é um processo de instalação única mais complicado para os usuários: eles precisam copiar e colar uma regra no arquivo WORKSPACE, conforme mostrado na seção README.md acima.

Antes, tínhamos 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 restantes.