As seções anteriores descreveram pacotes, destinos e rótulos, e as 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, todo pacote contém um arquivo BUILD, que é uma versão curta
neste programa. Os arquivos BUILD são avaliados com uma linguagem imperativa,
Starlark.
Elas são interpretadas como uma lista sequencial de instruções.
Em geral, a ordem é importante: as variáveis devem ser definidas antes de serem
usada, por exemplo. No entanto, a maioria dos arquivos BUILD consiste apenas de declarações de
regras de criação, e a ordem relativa dessas declarações não importa. todos
o que importa é quais regras foram declaradas e com quais valores, pelos
quando a avaliação do pacote é concluída.
Quando uma função de regra de build, como cc_library, é executada, ela cria uma
um novo destino no gráfico. Mais tarde, é possível referenciar esse destino usando um rótulo.
Em arquivos BUILD simples, as declarações de regras podem ser reordenadas livremente, sem
mudando o comportamento.
Para incentivar uma separação limpa entre código e dados, os arquivos BUILD não podem
contêm definições de função, instruções for ou instruções if, mas listam
compreensões e expressões if são permitidas). As funções podem ser declaradas em
.bzl. Além disso, os argumentos *args e **kwargs não são
permitido em arquivos BUILD em vez disso, liste todos os argumentos explicitamente.
É importante destacar que os programas no Starlark não podem realizar E/S arbitrárias. Essa invariante
torna a interpretação dos arquivos BUILD hermética, dependente apenas de um
conjunto de entradas, o que é essencial para garantir que os builds sejam reproduzíveis.
Para mais detalhes, consulte Hermeticity.
Arquivos BUILD devem ser gravados usando somente caracteres ASCII, embora
tecnicamente, eles são interpretados usando o conjunto de caracteres Latin-1.
Como os arquivos BUILD precisam ser atualizados sempre que as dependências do
alterações de código subjacentes, elas normalmente são mantidas por várias pessoas em uma
equipe. Os autores do arquivo BUILD precisam fazer comentários livres para documentar o papel
de cada destino de versão, seja para uso público ou não, e para
documentar o papel do próprio pacote.
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.
para o meio ambiente. Pode ser usado para carregar novas regras, funções ou constantes
(por exemplo, uma string ou uma lista). É possível importar vários símbolos usando
mais argumentos para a chamada para load. Os argumentos precisam ser literais de string
(sem variável) e instruções load precisam aparecer no nível superior. Elas não podem ser
no corpo de uma função.
O primeiro argumento de load é um rótulo que identifica uma
.bzl. Se for um rótulo relativo, ele é resolvido em relação ao
pacote (não diretório) que contém o arquivo bzl atual. Rótulos relativos em
As instruções load precisam usar um : no início.
O load também aceita aliases, então é possível atribuir nomes diferentes aos
símbolos importados.
load("//foo/bar:file.bzl", library_alias = "some_library")
Você pode definir vários aliases em uma instrução load. Além disso, o
lista de argumentos pode conter aliases e nomes de símbolos regulares. O seguinte
exemplo é 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
carregado de outro arquivo.
Use a visibilidade da carga para restringir
que podem carregar um arquivo .bzl.
Tipos de regras de build
A maioria das regras de build vem em famílias, agrupadas por
idioma de destino. Por exemplo, cc_binary e cc_library.
e cc_test são as regras de build para binários C++,
bibliotecas e testes, respectivamente. Outros idiomas usam a mesma
esquema de nomenclatura, com um prefixo diferente, como java_* para
Java. Algumas dessas funções estão documentadas na
Build Encyclopedia, mas é possível
para que qualquer pessoa possa criar novas regras.
As regras
*_binarycriam programas executáveis em uma determinada linguagem. Após um o executável ficará no sistema binário da ferramenta de build, no nome correspondente do rótulo da regra, então//my:programapareceria em (por exemplo)$(BINDIR)/my/program.Em algumas linguagens, essas regras também criam um diretório runfiles que contêm todos os arquivos mencionados em uma
dataatributo que pertence à regra ou qualquer regra na encerramento de dependências esse conjunto de arquivos é reunido em para facilitar a implantação na produção.*_testregra é uma especialização de uma regra do*_binary, usada para testes. Testes são simplesmente programas que retornam zero em caso de sucesso.Como os binários, os testes também têm árvores de runfiles, e os arquivos abaixo dele, há os únicos arquivos que um teste pode abrir legitimamente durante a 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 utilitária para acessando o valor de$TEST_SRCDIR, mas todos são equivale a usar a variável de ambiente diretamente. A não observação da regra fará com que o teste falhe quando for em um host de teste remoto.As regras
*_libraryespecificam módulos compilados separadamente nos de programação centrada no usuário. As bibliotecas podem depender de outras, e binários e testes podem depender de bibliotecas, com a extensão comportamento de compilação separada.
| Rótulos | Dependências |