Nesta página, descrevemos como estender a linguagem BUILD usando macros e regras.
As extensões do Bazel são arquivos que terminam em .bzl
. Use uma instrução de carregamento para importar um símbolo de uma extensão.
Antes de aprender os conceitos mais avançados, faça o seguinte:
Leia sobre a linguagem Starlark (link em inglês), usada nos arquivos
BUILD
e.bzl
.Saiba como compartilhar variáveis entre dois arquivos
BUILD
.
Macros e regras
Uma macro é uma função que instancia regras. Ela é útil quando um arquivo BUILD
está ficando muito repetitivo ou complexo, porque permite reutilizar algum código. A função é avaliada assim que o arquivo BUILD
é lido. Após
a avaliação do arquivo BUILD
, o Bazel tem poucas informações sobre as macros.
Se a macro gerar um genrule
, o Bazel vai se comportar como se você tivesse criado a
genrule
. Como resultado, bazel query
listará apenas o genrule
gerado.
Uma regra é mais eficiente do que uma macro. Ele pode acessar os componentes internos do Bazel e ter controle total sobre o que está acontecendo. Ela pode, por exemplo, transmitir informações para outras regras.
Se você quiser reutilizar a lógica simples, comece com uma macro. Se uma macro se tornar complexa, é recomendável transformá-la em uma regra. O suporte a uma nova linguagem normalmente é feito com uma regra. As regras são para usuários avançados, e a maioria deles nunca terá que escrever uma regra. Elas apenas carregarão e chamarão as regras existentes.
Modelo de avaliação
Um build consiste em três fases.
Fase de carregamento: Primeiro, carregue e avalie todas as extensões e todos os arquivos
BUILD
necessários para o build. A execução dos arquivosBUILD
simplesmente instancia as regras (sempre que uma regra é chamada, ela é adicionada a um gráfico). É aqui que as macros são avaliadas.Fase de análise. O código das regras é executado (a função
implementation
) e as ações são instanciadas. Uma ação descreve como gerar um conjunto de saídas com base em um conjunto de entradas, por exemplo, "executar gcc em hello.c e receber hello.o". É necessário listar explicitamente quais arquivos serão gerados antes de executar os comandos reais. Em outras palavras, a fase de análise usa o gráfico gerado pela fase de carregamento e gera um gráfico de ações.Fase de execução: As ações são executadas quando pelo menos uma das saídas é necessária. Se um arquivo estiver ausente ou se um comando não gerar uma saída, o build falhará. Os testes também são executados durante essa fase.
O Bazel usa o paralelismo para ler, analisar e avaliar os arquivos .bzl
e BUILD
. Um arquivo é lido no máximo uma vez por build e o resultado da avaliação é
armazenado em cache e reutilizado. Um arquivo é avaliado somente depois que todas as dependências (instruções load()
) são resolvidas. Por padrão, o carregamento de um arquivo .bzl
não tem efeito colateral visível, ele define apenas valores e funções.
Ele tenta ser inteligente: usa a análise de dependências para saber quais arquivos precisam ser carregados, quais regras precisam ser analisadas e quais ações precisam ser executadas. Por exemplo, se uma regra gerar ações desnecessárias para a versão atual, elas não serão executadas.
Criar extensões
Crie sua primeira macro para reutilizar código. Em seguida, saiba mais sobre macros e como usá-las para criar "verbos personalizados".
Siga o tutorial de regras para começar a usá-las. A seguir, leia mais sobre os conceitos de regras.
Os dois links abaixo serão muito úteis para criar suas próprias extensões. Mantenha-os ao seu alcance:
Indo mais longe
Além de macros e regras, você pode escrever aspectos e regras de repositório.
Use o Buildifier de maneira consistente para formatar e inspecionar o código.
Siga o guia de estilo do
.bzl
.Teste o código.
Gere documentação para ajudar seus usuários.
Otimize o desempenho do seu código.
Implante suas extensões para outras pessoas.