Visão geral da extensão

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, 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 fica muito repetitivo ou complexo, porque permite reutilizar parte do 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 uma genrule, o Bazel vai se comportar como se você tivesse escrito a genrule. Como resultado, bazel query vai listar apenas a genrule gerada.

Uma regra é mais poderosa do que uma macro. Ela pode acessar os elementos internos do Bazel e ter controle total sobre o que está acontecendo. Por exemplo, ela pode transmitir informações para outras regras.

Se você quiser reutilizar uma lógica simples, comece com uma macro. Se uma macro se tornar complexa, geralmente é uma boa ideia transformá-la em uma regra. O suporte para uma nova linguagem geralmente é feito com uma regra. As regras são para usuários avançados, e a maioria dos usuários nunca precisará escrever uma. Eles só vão carregar e chamar regras atuais.

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 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 de um conjunto de entradas, como "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 dele (instruções load()) forem resolvidas. Por design, o carregamento de um arquivo .bzl não tem efeito colateral visível. Ele apenas define valores e funções.

O Bazel tenta ser inteligente: ele 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 que não são necessárias para o build atual, elas não serão executadas.

Como criar extensões

• Crie sua primeira macro para reutilizar parte do 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 usar as regras. Em seguida, leia mais sobre os conceitos de regras.

Os dois links abaixo serão muito úteis ao escrever suas próprias extensões. Mantenha-os ao alcance:

• A referência da API

• Exemplos

Avançar

Além de macros e regras, talvez você queira escrever aspectos e regras de repositório.

• Use Buildifier de forma consistente para formatar e fazer a lintagem do código.

• Siga o .bzl guia de estilo.

• Teste seu código.

• Gere documentação para ajudar seus usuários.

• Otimize o desempenho do código.

• Implante suas extensões para outras pessoas.