Todos os destinos pertencem exatamente a um pacote. O nome de um destino é chamado de rótulo. Cada rótulo identifica um destino de forma exclusiva. Um rótulo típico em formato canônico é semelhante a:
@myrepo//my/app/main:app_binary
A primeira parte do rótulo é o nome do repositório, @myrepo//
.
No caso típico de um rótulo se referir ao mesmo repositório em que
é usado, o identificador do repositório pode ser abreviado como //
.
Então, dentro de @myrepo
, esse rótulo geralmente é escrito como
//my/app/main:app_binary
A segunda parte do rótulo é o nome do pacote não qualificado
my/app/main
, o caminho para o pacote
relativo à raiz do repositório. Juntos, o nome do repositório e o
nome do pacote não qualificado formam o nome do pacote totalmente qualificado
@myrepo//my/app/main
. Quando o rótulo se refere ao mesmo
pacote em que é usado, o nome dele e, opcionalmente, os dois pontos
podem ser omitidos. Portanto, dentro de @myrepo//my/app/main
,
esse rótulo pode ser escrito de uma das seguintes maneiras:
app_binary
:app_binary
É uma questão de convenção que os dois pontos sejam omitidos para arquivos, mas retidos para regras, mas não são significativos.
A parte do rótulo após os dois-pontos, app_binary
, é o nome do destino
não qualificado. Quando corresponde ao último componente do caminho do pacote, ele e os
dois pontos podem ser omitidos. Portanto, esses dois rótulos são equivalentes:
//my/app/lib
//my/app/lib:lib
O nome de um destino de arquivo em um subdiretório do pacote é o caminho do arquivo
em relação à raiz do pacote (o diretório que contém o arquivo BUILD
). Portanto,
esse arquivo está no subdiretório my/app/main/testdata
do repositório:
//my/app/main:testdata/input.txt
Strings como //my/app
e @some_repo//my/app
têm dois significados, dependendo do
contexto em que são usadas: quando o Bazel espera um rótulo, elas significam
//my/app:app
e @some_repo//my/app:app
, respectivamente. No entanto, quando o Bazel
espera um pacote (por exemplo, nas especificações package_group
), ele faz referência ao
pacote que contém esse rótulo.
Um erro comum em arquivos BUILD
é usar //my/app
para se referir a um pacote ou
a todos os destinos em um pacote. Isso não acontece. Lembre-se de que ele é
equivalente a //my/app:app
, então ele nomeia o destino app
no pacote my/app
do repositório atual.
No entanto, o uso de //my/app
para se referir a um pacote é recomendado na especificação de um package_group
ou em arquivos .bzl
, porque comunica claramente que o nome do pacote é absoluto e tem acesso root no diretório de nível superior do espaço de trabalho.
Rótulos relativos não podem ser usados para se referir a destinos em outros pacotes.
Nesse caso, o identificador do repositório e o nome do pacote precisam ser sempre especificados.
Por exemplo, se a árvore de origem contiver os pacotes my/app
e
my/app/testdata
(cada um desses dois diretórios tiver o próprio arquivo
BUILD
), o último pacote conterá um arquivo chamado testdepot.zip
. Veja
duas maneiras (uma errada e outra correta) para se referir a esse arquivo em
//my/app:BUILD
:
Incorreto: testdata
é um pacote diferente, portanto não é possível usar um caminho relativo.
testdata/testdepot.zip
Correto: consulte testdata
com o caminho completo.
//my/app/testdata:testdepot.zip
Os rótulos que começam com @//
são referências ao repositório
principal, que ainda funciona até mesmo em repositórios externos.
Portanto, @//a/b/c
é diferente de
//a/b/c
quando referenciado de um repositório externo.
O primeiro se refere ao repositório principal, enquanto o último
procura //a/b/c
no próprio repositório externo.
Isso é especialmente relevante ao escrever regras no repositório
principal que se referem a destinos no repositório principal e será
usada em repositórios externos.
Para informações sobre as diferentes maneiras de se referir aos destinos, consulte padrões de destino.
Especificação léxica de um rótulo
A sintaxe do rótulo desencoraja o uso de metacaracteres que têm um significado especial para o shell. Isso ajuda a evitar problemas de cotações acidentais e facilita a construção de ferramentas e scripts que manipulam rótulos, como a Linguagem de Consulta do Bazel.
Veja abaixo os detalhes precisos dos nomes de destinos permitidos.
Nomes de destino: package-name:target-name
target-name
é o nome do destino no pacote. O nome de uma regra
é o valor do atributo name
na declaração da regra em um arquivo
BUILD
. O nome de um arquivo é o nome do caminho relacionado ao diretório que contém
o arquivo BUILD
.
Os nomes dos destinos precisam ser compostos inteiramente de caracteres do conjunto a
–z
,
A
–Z
, 0
–9
e os símbolos de pontuação !%-@^_"#$&'()*-+,;<=>?[]{|}~/.
.
Os nomes de arquivos precisam ser nomes de caminho relativos em formato normal, ou seja, eles
não podem começar nem terminar com uma barra (por exemplo, /foo
e foo/
são
proibidas) nem conter várias barras consecutivas como separadores de caminho
(por exemplo, foo//bar
). Da mesma forma, referências de nível superior (..
) e
referências de diretórios atuais (./
) são proibidas.
Incorreto: não use ".." para se referir a arquivos em outros pacotes.
Correto: use "//package-name:filename".
Embora seja comum usar /
no nome de um destino de arquivo, evite o uso de
/
nos nomes das regras. Especialmente quando a forma abreviada de um rótulo é
usada, isso pode confundir o leitor. O rótulo //foo/bar/wiz
é sempre uma abreviação
de //foo/bar/wiz:wiz
, mesmo que não exista esse pacote foo/bar/wiz
. Ele
nunca se refere a //foo:bar/wiz
, mesmo que esse destino exista.
No entanto, há algumas situações em que o uso de uma barra é conveniente ou, às vezes, necessário. Por exemplo, o nome de determinadas regras precisa corresponder ao arquivo de origem principal, que pode residir em um subdiretório do pacote.
Nomes de pacote: //package-name:target-name
O nome de um pacote é o nome do diretório que contém o arquivo BUILD
,
em relação ao diretório de nível superior do repositório que o contém.
Por exemplo, my/app
.
Os nomes de pacote precisam ser compostos inteiramente de caracteres do conjunto
A
-Z
, a
–z
, 0
–9
, "/
", "-
", ".
", "@
" e "_
" e não podem
começar com uma barra.
Para uma linguagem com uma estrutura de diretórios importante para o sistema de módulos (por exemplo, Java), é importante escolher nomes de diretórios que sejam identificadores válidos na linguagem.
Embora o Bazel ofereça suporte a destinos no pacote raiz do espaço de trabalho (por exemplo,
//:foo
), é melhor deixar esse pacote vazio para que todos os pacotes significativos
tenham nomes descritivos.
Os nomes dos pacotes não podem conter a substring //
nem terminar com uma barra.
Regras
Uma regra especifica a relação entre entradas e saídas e as etapas para criar as saídas. As regras podem ser de vários tipos diferentes (às vezes chamadas de classe de regra), que produzem executáveis e bibliotecas compilados, executáveis de teste e outras saídas compatíveis, conforme descrito na Enciclopédia de build.
Os arquivos BUILD
declaram destinos invocando regras.
No exemplo abaixo, vemos a declaração do my_app
de destino usando a regra cc_binary
.
cc_binary(
name = "my_app",
srcs = ["my_app.cc"],
deps = [
"//absl/base",
"//absl/strings",
],
)
Cada invocação de regra tem um atributo name
, que precisa ser um
nome de destino válido, que declara um destino no pacote
do arquivo BUILD
.
Cada regra tem um conjunto de atributos. Os atributos aplicáveis a uma determinada regra, e o significado e a semântica de cada atributo são uma função do tipo da regra. Consulte a Enciclopédia de builds para ver uma lista de regras e os atributos correspondentes. Cada atributo tem um nome e um tipo. Alguns dos tipos comuns que um atributo pode ter são inteiro, rótulo, lista de rótulos, string, lista de strings, rótulo de saída e lista de rótulos de saída. Nem todos os atributos precisam ser especificados em todas as regras. Assim, os atributos formam um dicionário que vai de chaves (nomes) a valores digitados opcionais.
O atributo srcs
presente em muitas regras tem o tipo "lista de rótulos".
O valor, se presente, é uma lista de rótulos, e cada um é o nome de um destino
que é uma entrada dessa regra.
Em alguns casos, o nome do tipo da regra é um pouco arbitrário, e mais interessantes são os nomes dos arquivos gerados pela regra, e isso é verdade para as regras gerais. Para mais informações, consulte Regras gerais: genrule.
Em outros casos, o nome é significativo: para regras *_binary
e *_test
,
por exemplo, o nome da regra determina o nome do executável produzido
pelo build.
Esse gráfico acíclico direcionado sobre destinos é chamado de gráfico de destino ou gráfico de dependência de build e é o domínio sobre o qual a ferramenta de consulta Bazel opera.
Destinos | Arquivos BUILD |