Um rótulo é um identificador de um destino. Um rótulo típico em sua versão canônica completa formulário é semelhante a:
@@myrepo//my/app/main:app_binary
A primeira parte do rótulo é o nome do repositório, @@myrepo. O duplo @
sintaxe significa que este é um repositório canônico
nome, que é exclusivo no
espaço de trabalho. Rótulos com nomes de repositórios canônicos identificam um destino de forma clara
independentemente do contexto.
Muitas vezes, o nome do repositório canônico é uma string misteriosa que parece
@@rules_java++toolchains+local_jdk: O que é muito mais comumente visto é
rótulos com um nome de repositório aparente;
que tem esta aparência:
@myrepo//my/app/main:app_binary
A única diferença é que o nome do repositório é prefixado com um @ em vez de dois.
Isso se refere a um repositório com o nome aparente myrepo, que pode ser diferente
com base no contexto em que o marcador aparece.
No caso típico de um rótulo se referir ao mesmo repositório do qual
for usado, a parte do nome do repositório pode ser omitida. Dentro de @@myrepo, o primeiro
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.
em relação à raiz do repositório. Juntos, o nome do repositório
o nome do pacote não qualificado forma o nome do pacote totalmente qualificado
@@myrepo//my/app/main: Quando o rótulo se refere ao mesmo
o pacote em que ele é usado, o nome do pacote (e, opcionalmente, os dois pontos)
podem ser omitidos. Então, em @@myrepo//my/app/main,
o rótulo pode ser gravado das seguintes maneiras:
app_binary
:app_binary
É uma questão de convenção que os dois pontos sejam omitidos para arquivos, mas retido para regras, mas não é significativo de outra forma.
A parte do rótulo após os dois-pontos, app_binary é o destino não qualificado
nome. Quando ele corresponder ao último componente do caminho do pacote, ele e o
dois pontos, pode ser omitido. 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). Então,
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 da
no contexto em que são usados: quando o Bazel espera um rótulo, eles significam
//my/app:app e @@some_repo//my/app:app, respectivamente. Mas, quando o Bazel
espera um pacote (por exemplo, em especificações package_group), ele faz referência ao
que contém o 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, mas isso não acontece. Lembre-se, é
equivalente a //my/app:app, então ele nomeia o destino app no objeto my/app
do repositório atual.
No entanto, o uso de //my/app para se referir a um pacote é incentivado na
especificação de um package_group ou em arquivos .bzl, porque claramente
informa que o nome do pacote é absoluto e tem como enraizado no nível superior
do espaço de trabalho.
Rótulos relativos não podem ser usados para se referir a destinos em outros pacotes. as
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 os
pacote my/app/testdata (cada um desses dois diretórios tem o próprio
BUILD), o último pacote contém um arquivo chamado testdepot.zip. Aqui
há duas maneiras (uma errada, uma correta) de se referir a esse arquivo em
//my/app:BUILD:
Incorreto: testdata é um pacote diferente, então não é possível usar um caminho relativo.
testdata/testdepot.zip
Correto: consulte testdata com o caminho completo
//my/app/testdata:testdepot.zip
Os marcadores que começam com @@// são referências aos principais
que vai funcionar mesmo em repositórios externos.
Portanto, @@//a/b/c é diferente
//a/b/c quando referenciados em um repositório externo.
O primeiro se refere ao repositório principal, enquanto o segundo se refere
procura //a/b/c no próprio repositório externo.
Isso é especialmente relevante ao escrever regras na entrada
que se referem a destinos no repositório principal e serão
de repositórios externos.
Para informações sobre as diferentes maneiras de se referir a destinos, consulte padrões de segmentação.
Especificação léxica de um rótulo
A sintaxe do rótulo desencoraja o uso de metacaracteres que tenham um significado especial para o casco Isso ajuda a evitar problemas de citação acidentais e facilita construir ferramentas e scripts que manipulam rótulos, como o Linguagem de consulta do Bazel.
Confira abaixo os detalhes exatos dos nomes de destino 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 BUILD
file; o nome de um arquivo é o nome do caminho em relação ao diretório que contém
no arquivo BUILD.
Os nomes de destino precisam ser compostos inteiramente de caracteres retirados do conjunto de a a z.
A–Z, 0–9 e os símbolos de pontuação !%-@^_"#$&'()*-+,;<=>?[]{|}~/..
Os nomes de arquivo devem ser nomes de caminho relativos no formato normal, o que significa que eles devem
não começam nem terminam com uma barra (por exemplo, /foo e foo/ são
proibido) 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 do diretório atual (./) são proibidas.
Errado: não use .. para se referir a arquivos em outros pacotes.
Correto: uso
//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 é
usado, pode confundir o leitor. O rótulo //foo/bar/wiz é sempre uma abreviação
para //foo/bar/wiz:wiz, mesmo que não haja esse pacote foo/bar/wiz;
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 até mesmo necessário. Por exemplo, o nome de certas regras precisa ser igual seu 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.
Em um nível técnico, o Bazel aplica o seguinte:
- Os caracteres permitidos em nomes de pacotes são as letras minúsculas de
aazas letras maiúsculasAaZ, os dígitos de0a9, os caracteres! \"#$%&'()*+,-.;<=>?@[]^_`{|}(sim, há um caractere de espaço lá!) e, claro, a barra/(já que é o diretório separador). - Os nomes dos pacotes não podem começar ou terminar com uma barra
/. - Os nomes dos pacotes não podem conter a substring
//. Isso não daria sentido: qual seria o caminho do diretório correspondente? - Os nomes dos pacotes não podem conter a substring
/./,/../,/.../etc. Essa aplicação é feita para evitar confusão ao traduzir entre uma lógica nome de pacote e um nome de diretório físico, dado o significado semântico do ponto nas strings de caminho.
Em termos práticos:
- Para uma linguagem com uma estrutura de diretórios significativa para seu módulo por exemplo, Java), é importante escolher nomes de diretórios que sejam identificadores válidos no idioma. Por exemplo, não comece com um e evite caracteres especiais, especialmente sublinhados e hifens.
- Embora o Bazel aceite destinos no pacote raiz do espaço de trabalho (por exemplo,
//:foo), recomendamos deixar o pacote em branco para que todos os pacotes significativos tenham nomes descritivos.
Regras
Uma regra especifica a relação entre entradas e saídas, e a etapas para criar as saídas. As regras podem ser de uma das várias (às vezes chamada de classe de regra), que produzem dados compilados executáveis e bibliotecas, executáveis de teste e outros saídas, conforme descrito na Enciclopédia de builds.
Arquivos BUILD declaram destinos invocando regras.
No exemplo abaixo, vemos a declaração do destino my_app.
usando a regra cc_binary.
cc_binary(
name = "my_app",
srcs = ["my_app.cc"],
deps = [
"//absl/base",
"//absl/strings",
],
)
Toda invocação de regra tem um atributo name, que precisa ser um atributo válido
target name), que declara um destino dentro do pacote
do arquivo BUILD.
Cada regra tem um conjunto de atributos. os atributos aplicáveis a um determinado e a importância e a semântica de cada atributo são uma função o tipo da regra. consulte a Build Encyclopedia lista de regras e seus atributos correspondentes. Cada atributo tem um nome, um tipo. Alguns dos tipos comuns que um atributo pode ter são número inteiro, rótulo, lista de rótulos, string, lista de strings, rótulo de saída, lista de rótulos de saída. Não todos os atributos precisam ser especificados em cada regra. Assim, os atributos formam de chaves (nomes) a valores tipados opcionais.
O atributo srcs, presente em muitas regras, tem o tipo "lista de rótulos". dela
valor, se presente, é uma lista de rótulos, sendo cada um o nome de um destino que é
uma entrada para essa 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 é verdadeiro das regras gerais. Para mais informações, consulte Regras gerais: genrule.
Em outros casos, o nome é significativo: para as regras *_binary e *_test,
por exemplo, o nome da regra determina o nome do executável produzido pelo
o build.
Esse gráfico acíclico direcionado sobre os alvos é chamado de gráfico de destino ou gráfico de dependências de build, que é o domínio sobre o qual o A ferramenta Bazel Query funciona.
| Metas | Arquivos BUILD |