Visão geral da extensão

Informar um problema Ver código-fonte

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:

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 arquivos BUILD 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

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.