Nesta página, descrevemos como estender a linguagem BUILD usando macros e regras.
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, primeiro:
Leia sobre a linguagem Starlark, 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 muito complexo, porque permite reutilizar
um 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 macros: se a macro gerar um genrule
, o Bazel se comportará como se você tivesse gravado o genrule
. Como resultado, bazel query
listará apenas o genrule
gerado.
Uma regra é mais eficiente do que uma macro. Ele pode acessar o interno do Bazel e ter controle total sobre o que está acontecendo. Ele pode, por exemplo, transmitir informações para outras regras.
Se você quiser reutilizar uma lógica simples, comece com uma macro. Se uma macro se torna complexa, muitas vezes é uma boa ideia transformá-la em uma regra. O suporte para um novo idioma geralmente é feito com uma regra. As regras são voltadas para usuários avançados, e a maioria deles nunca precisará escrevê-las. Eles só 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
apenas instancia as regras (sempre que uma regra é chamada, ela é adicionada a um gráfico). É nesse momento que as macros são avaliadas.Fase de análise. O código das regras é executado (a função
implementation
delas) e as ações são instanciadas. Uma ação descreve como gerar um conjunto de saídas de um conjunto de entradas, como "run gcc em hello.c e get hello.o". Liste 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ção.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 só é avaliado quando todas as dependências (instruções load()
) são resolvidas. Por padrão, o carregamento de um arquivo .bzl
não tem efeitos colaterais
visíveis, apenas define valores e funções.
O Bazel tenta ser inteligente. Ele usa a análise de dependência 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 de que você não precisa para o build atual, elas não serão executadas.
Criar extensões
Crie sua primeira macro para reutilizar algum código. Em seguida, saiba mais sobre macros e como usá-las para criar "verbos personalizados".
Siga o tutorial para começar a usar as regras. Leia mais sobre os conceitos de regras.
Os dois links abaixo serão muito úteis quando você criar suas próprias extensões. Mantenha-os ao alcance:
Mais informações
Além de macros e regras, escreva aspectos e regras do repositório.
Use o Buildifier de maneira consistente para formatar e inspecionar o código.
Siga o guia de estilo
.bzl
.Teste o código.
Gere documentação para ajudar os usuários.
Otimize o desempenho do código.
Implante as extensões para outras pessoas.