Esta página foi traduzida pela API Cloud Translation.

Como implantar regras

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

Regras de nomenclatura e hospedagem

As novas regras devem ser enviadas para o próprio repositório do GitHub na sua organização. Entre em contato com a lista de e-mails bazel-dev 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 as 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 idioma (como Scala) ou por plataforma (como Android).

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. Caso suas regras pertençam à organização bazelbuild, use rules_<lang> (como rules_mockascript). Caso contrário, dê ao seu repositório o nome <org>_rules_<lang> (como build_stack_rules_proto). Entre em contato com a lista de e-mails do bazel-dev 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.

Teste

Configure o Travis conforme descrito nos documentos de introdução. Em seguida, adicione um arquivo .travis.yml ao seu repositório com o seguinte conteúdo:

dist: xenial  # Ubuntu 16.04

# On trusty (or later) images, the Bazel apt repository can be used.
addons:
  apt:
    sources:
    - sourceline: 'deb [arch=amd64] http://storage.googleapis.com/bazel-apt stable jdk1.8'
      key_url: 'https://bazel.build/bazel-release.pub.gpg'
    packages:
    - bazel

script:
  - bazel build //...
  - bazel test //...

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.

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.