As seções anteriores descreveram pacotes, destinos e rótulos, além do gráfico de dependências de build de forma abstrata. Esta seção descreve a sintaxe concreta usada para definir um pacote.
Por definição, cada pacote contém um arquivo BUILD, que é um programa
curto. Os arquivos BUILD são avaliados usando uma linguagem imperativa,
Starlark.
Elas são interpretadas como uma lista sequencial de instruções.
Em geral, a ordem importa: as variáveis precisam ser definidas antes de serem
usadas, por exemplo. No entanto, a maioria dos arquivos BUILD consiste apenas em declarações de
regras de build, e a ordem relativa dessas instruções é irrelevante. O que
importa é quais regras foram declaradas e com quais valores, até
que a avaliação do pacote seja concluída.
Quando uma função de regra de build, como cc_library, é executada, ela cria um
novo destino no gráfico. Esse destino pode ser referenciado posteriormente usando um rótulo.
Em arquivos BUILD simples, as declarações de regras podem ser reordenadas livremente sem
mudar o comportamento.
Para incentivar uma separação limpa entre código e dados, os arquivos BUILD não podem
conter definições de função, instruções for ou if. No entanto, as compreensões
de lista e as expressões if são permitidas. As funções podem ser declaradas em
arquivos .bzl. Além disso, os argumentos *args e **kwargs não são
permitidos em arquivos BUILD. Em vez disso, liste todos os argumentos explicitamente.
Os programas em Starlark não podem realizar E/S arbitrárias. Essa invariância
faz com que a interpretação de arquivos BUILD seja hermética, dependendo apenas de um conjunto
conhecido de entradas, o que é essencial para garantir que os builds sejam reproduzíveis.
Para mais detalhes, consulte Hermeticity.
Os arquivos BUILD precisam ser escritos usando apenas caracteres ASCII, embora
tecnicamente sejam interpretados usando o conjunto de caracteres Latin-1.
Como os arquivos BUILD precisam ser atualizados sempre que as dependências do
código subjacente mudam, eles geralmente são mantidos por várias pessoas em uma
equipe. Os autores de arquivos BUILD precisam comentar bastante para documentar o papel
de cada destino de build, seja para uso público ou não, e
documentar o papel do próprio pacote.
Como carregar uma extensão
As extensões do Bazel são arquivos que terminam em .bzl. Use a instrução load para importar
um símbolo de uma extensão.
load("//foo/bar:file.bzl", "some_library")
Esse código carrega o arquivo foo/bar/file.bzl e adiciona o símbolo some_library
ao ambiente. Ele pode ser usado para carregar novas regras, funções ou constantes, por exemplo, uma string ou uma lista. Vários símbolos podem ser importados usando
argumentos adicionais para a chamada para load. Os argumentos precisam ser literais de string
(sem variável) e as instruções load precisam aparecer no nível superior. Elas não podem estar
no corpo de uma função.
O primeiro argumento de load é um rótulo que identifica um
arquivo .bzl. Se for um rótulo relativo, ele será resolvido em relação ao
pacote (não ao diretório) que contém o arquivo bzl atual. Os rótulos relativos em
instruções load precisam usar um : inicial.
load também oferece suporte a aliases. Portanto, é possível atribuir nomes diferentes aos
símbolos importados.
load("//foo/bar:file.bzl", library_alias = "some_library")
É possível definir vários aliases em uma instrução load. Além disso, a
lista de argumentos pode conter aliases e nomes de símbolos regulares. O exemplo
a seguir é perfeitamente legal (observe quando usar aspas).
load(":my_rules.bzl", "some_rule", nice_alias = "some_other_rule")
Em um arquivo .bzl, os símbolos que começam com _ não são exportados e não podem ser
carregados de outro arquivo.
É possível usar a visibilidade de carregamento para restringir
quem pode carregar um arquivo .bzl.
Tipos de regras de build
A maioria das regras de build vem em famílias, agrupadas por
língua. Por exemplo, cc_binary, cc_library
e cc_test são as regras de build para binários C++,
bibliotecas e testes, respectivamente. Outras linguagens usam o mesmo
esquema de nomenclatura, com um prefixo diferente, como java_* para
Java. Algumas dessas funções são documentadas na
Enciclopédia do Build, mas qualquer pessoa pode
criar novas regras.
As regras
*_binarycriam programas executáveis em uma determinada linguagem. Após um build, o executável vai residir na árvore de saída binária da ferramenta de build com o nome correspondente ao rótulo da regra, então//my:programvai aparecer em (por exemplo)$(BINDIR)/my/program.Em alguns idiomas, essas regras também criam um diretório de arquivos de execução que contém todos os arquivos mencionados em um atributo
datapertencente à regra ou qualquer regra no fechamento transitivo de dependências. Esse conjunto de arquivos é reunido em um só lugar para facilitar a implantação na produção.As regras
*_testsão uma especialização de uma regra*_binary, usada para testes automatizados. Os testes são simplesmente programas que retornam zero em caso de sucesso.Assim como os binários, os testes também têm árvores de arquivos de execução, e os arquivos abaixo delas são os únicos que um teste pode abrir legitimamente no momento da execução. Por exemplo, um programa
cc_test(name='x', data=['//foo:bar'])pode abrir e ler$TEST_SRCDIR/workspace/foo/bardurante a execução. Cada linguagem de programação tem sua própria função de utilitário para acessar o valor de$TEST_SRCDIR, mas todas são equivalentes ao uso direto da variável de ambiente. Se a regra não for observada, o teste vai falhar quando for executado em um host de teste remoto.As regras
*_libraryespecificam módulos compilados separadamente na linguagem de programação especificada. As bibliotecas podem depender de outras bibliotecas, e os binários e testes podem depender de bibliotecas, com o comportamento esperado de compilação separada.
| Rótulos | Dependências |