Conteúdo
pacote
package(default_deprecation, default_package_metadata, default_testonly, default_visibility, features)
Essa função declara metadados que se aplicam a todas as regras no pacote. Ele é usado no máximo uma vez em um pacote (arquivo BUILD).
Para a contraparte que declara os metadados aplicáveis a todas as regras no repositório inteiro, use a função repo()
no arquivo REPO.bazel
na raiz do repositório.
A função repo()
usa exatamente os mesmos argumentos que package()
.
A função package() deve ser chamada logo após todas as instruções load() na parte superior do arquivo, antes de qualquer regra.
Argumentos
Atributo | Descrição |
---|---|
default_applicable_licenses |
Alias para |
default_visibility |
Lista de rótulos. O padrão é A visibilidade padrão das regras neste pacote. Cada regra neste pacote tem a visibilidade especificada no
atributo, a menos que especificado de outra forma no atributo |
default_deprecation |
String. O padrão é Define a mensagem
|
default_package_metadata |
Lista de rótulos. O padrão é Define uma lista padrão de destinos de metadados que se aplicam a todos os outros destinos no pacote. Normalmente, são destinos relacionados ao pacote OSS e declarações de licença. Consulte exemplos em rules_license. |
default_testonly |
Booleano; o padrão é Define a propriedade
Em pacotes em |
features |
Strings de lista. O padrão é Define várias sinalizações que afetam a semântica deste arquivo BUILD. Esse recurso é usado principalmente pelas pessoas que trabalham no sistema de build para marcar pacotes que precisam de algum tipo de tratamento especial. Não use esse método, a menos que seja explicitamente solicitado por alguém que trabalha no sistema de compilação. |
Exemplos
A declaração abaixo declara que as regras neste pacote são visíveis apenas para os membros do grupo de pacotes//foo:target
. Declarações de visibilidade individuais
em uma regra, se houver, substituem essa especificação.
package(default_visibility = ["//foo:target"])
package_group
package_group(name, packages, includes)
Essa função define um conjunto de pacotes
e associa um rótulo a ele. O rótulo pode ser referenciado nos
atributos visibility
.
Os grupos de pacotes são usados principalmente para controle de visibilidade. Um destino visível publicamente pode ser referenciado de cada pacote na árvore de origem. Um destino visível em particular só pode ser referenciado no próprio pacote, e não em subpacotes. Entre esses extremos, um destino pode permitir o acesso ao próprio pacote e a qualquer um dos pacotes descritos por um ou mais grupos. Para uma explicação mais detalhada sobre o sistema de visibilidade, consulte o atributo visibilidade.
Um determinado pacote será considerado no grupo se corresponder ao
atributo packages
ou se já estiver contido em um dos outros
grupos de pacotes mencionados no atributo includes
.
Tecnicamente, os grupos de pacotes são alvos, mas não são criados por regras e não têm nenhuma proteção de visibilidade.
Argumentos
Atributo | Descrição |
---|---|
name |
Nome, obrigatório Um nome exclusivo para o destino. |
packages |
Lista de strings. O padrão é Uma lista de zero ou mais especificações de pacote. Cada string de especificação de pacote pode ter uma das seguintes formas:
Além disso, os dois primeiros tipos de especificações de pacote também podem ter o prefixo O grupo contém qualquer pacote que corresponda a pelo menos uma das
especificações positivas e a nenhuma das especificações negativas.
Por exemplo, o valor Além da visibilidade pública, não há como especificar diretamente pacotes fora do repositório atual. Se esse atributo estiver ausente, será o mesmo que defini-lo como uma
lista vazia, o que também é o mesmo de defini-lo como uma lista que contém
apenas Observação:antes do Bazel 6.0, a especificação Observação:antes do Bazel 6.0, quando esse atributo é serializado como
parte de |
includes |
Lista de rótulos. O padrão é Outros grupos de pacotes incluídos neste. Os rótulos neste atributo precisam se referir a outros grupos de pacotes.
Os pacotes nos grupos referenciados são considerados parte desse
grupo. Isso é transitivo. Se o grupo de pacotes
Quando usado com especificações de pacote negadas, o conjunto de pacotes de cada grupo é calculado primeiro de maneira independente, e os resultados são unidos. Isso significa que as especificações negadas em um grupo não afetam as especificações de outro grupo. |
Exemplos
A declaração package_group
a seguir especifica um
grupo de pacotes chamado "tropical" que contém frutas tropicais.
package_group( name = "tropical", packages = [ "//fruits/mango", "//fruits/orange", "//fruits/papaya/...", ], )
As declarações abaixo especificam os grupos de pacotes de um aplicativo fictício:
package_group( name = "fooapp", includes = [ ":controller", ":model", ":view", ], ) package_group( name = "model", packages = ["//fooapp/database"], ) package_group( name = "view", packages = [ "//fooapp/swingui", "//fooapp/webui", ], ) package_group( name = "controller", packages = ["//fooapp/algorithm"], )
exports_files
exports_files([label, ...], visibility, licenses)
exports_files()
especifica uma lista de arquivos pertencentes a
este pacote que são exportados para outros pacotes.
O arquivo BUILD de um pacote só poderá se referir diretamente a arquivos de origem pertencentes
a outro pacote se eles forem explicitamente exportados com uma
instrução exports_files()
. Leia mais sobre a visibilidade dos arquivos.
Como um comportamento legado, também os arquivos mencionados como entrada para uma regra são exportados
com a visibilidade padrão até que a flag
--incompatible_no_implicit_file_export
seja invertida. No entanto, esse comportamento não é confiável nem migrado ativamente.
Argumentos
O argumento é uma lista de nomes de arquivos dentro do pacote atual. Uma declaração de visibilidade também pode ser especificada. Nesse caso, os arquivos ficarão visíveis para os destinos especificados. Se nenhuma visibilidade for especificada, os arquivos
ficarão visíveis para todos os pacotes, mesmo que uma visibilidade padrão do pacote tenha sido
especificada na função
package
. As licenças também podem ser especificadas.
Exemplo
O exemplo a seguir exporta golden.txt
, um
arquivo de texto do pacote test_data
, para que outros
pacotes possam usá-lo, por exemplo, no atributo data
de testes.
# from //test_data/BUILD exports_files(["golden.txt"])
massa
glob(include, exclude=[], exclude_directories=1, allow_empty=True)
Glob é uma função auxiliar que encontra todos os arquivos que correspondem a determinados padrões de caminho e retorna uma lista nova, mutável e classificada de caminhos. O Glob só pesquisa arquivos no próprio pacote e procura apenas arquivos de origem, e não arquivos gerados nem outros destinos.
O rótulo de um arquivo de origem será incluído no resultado se o caminho relativo ao pacote
do arquivo corresponder a qualquer um dos padrões include
e a nenhum dos
padrões exclude
.
As listas include
e exclude
contêm padrões de caminho
relativos ao pacote atual. Cada padrão pode consistir em um
ou mais segmentos de caminho. Como de costume com caminhos Unix, esses segmentos são separados por
/
. Os segmentos podem conter o caractere curinga *
, que corresponde a qualquer substring no segmento do caminho (mesmo a substring vazia), excluindo o separador de diretório /
. Esse caractere curinga pode ser usado várias vezes
em um segmento de caminho. Além disso, o caractere curinga **
pode corresponder a zero ou mais segmentos de caminho completos, mas precisa ser declarado como um segmento de caminho autônomo.
foo/bar.txt
corresponde exatamente ao arquivofoo/bar.txt
neste pacotefoo/*.txt
corresponde a todos os arquivos no diretóriofoo/
se o arquivo terminar com.txt
(a menos quefoo/
seja um subpacote)foo/a*.htm*
corresponde a todos os arquivos no diretóriofoo/
que começam coma
, têm uma string arbitrária (pode estar vazia), têm.htm
e terminam com outra string arbitrária, comofoo/axx.htm
efoo/a.html
oufoo/axxx.html
.**/a.txt
corresponde a cada arquivoa.txt
em todos os subdiretórios desse pacote.**/bar/**/*.txt
corresponde a cada arquivo.txt
em todos os subdiretórios desse pacote, se pelo menos um diretório no caminho resultante for chamadobar
, comoxxx/bar/yyy/zzz/a.txt
oubar/a.txt
(lembre-se de que**
também corresponde a zero segmentos) oubar/zzz/a.txt
**
corresponde a todos os arquivos em todos os subdiretórios deste pacote.foo**/a.txt
é um padrão inválido, porque**
precisa ser sozinho como um segmento
Se o argumento exclude_directories
estiver ativado (definido como 1), os arquivos do diretório de tipo serão omitidos dos resultados (padrão 1).
Se o argumento allow_empty
for definido como False
, a função glob
causará um erro se o resultado for a lista vazia.
Há várias limitações e ressalvas importantes:
-
Como
glob()
é executado durante a avaliação do arquivo BUILD,glob()
corresponde apenas a arquivos na árvore de origem, e nunca a arquivos gerados. Se você estiver criando um destino que requer arquivos de origem e gerados, será necessário anexar uma lista explícita de arquivos gerados ao glob. Veja o exemplo abaixo com:mylib
e:gen_java_srcs
. -
Se uma regra tiver o mesmo nome de um arquivo de origem correspondente, ela "sombrará" o arquivo.
Para entender isso, lembre-se de que
glob()
retorna uma lista de caminhos. Portanto, usarglob()
no atributo de outras regras (por exemplo,srcs = glob(["*.cc"])
) tem o mesmo efeito que listar explicitamente os caminhos correspondentes. Se, por exemplo,glob()
gerar["Foo.java", "bar/Baz.java"]
, mas também houver uma regra no pacote chamada "Foo.java" (que é permitida, embora o Bazel tenha avisado sobre isso), o consumidor deglob()
usará a regra "Foo.java" (suas saídas) em vez do arquivo "Foo.java". Consulte o problema 10395 do GitHub para saber mais. - Os Globs podem corresponder a arquivos em subdiretórios. Além disso, os nomes de subdiretórios podem usar caracteres curinga. No entanto...
-
Os rótulos não podem ultrapassar os limites do pacote, e o glob não corresponde a arquivos em subpacotes.
Por exemplo, a expressão glob
**/*.cc
no pacotex
não incluiráx/y/z.cc
sex/y
existir como um pacote (comox/y/BUILD
ou em outro lugar no package-path). Isso significa que o resultado da expressão glob realmente depende da existência de arquivos BUILD, ou seja, a mesma expressão glob incluiriax/y/z.cc
se não houvesse um pacote chamadox/y
ou ele fosse marcado como excluído usando a sinalização --deleted_packages. - A restrição acima se aplica a todas as expressões glob, independentemente dos caracteres curinga que elas usam.
-
Um arquivo oculto com nome de arquivo começando com
.
é totalmente correspondido pelos caracteres curinga**
e*
. Se você quiser corresponder um arquivo oculto a um padrão composto, o padrão precisará começar com.
. Por exemplo,*
e.*.txt
corresponderão a.foo.txt
, mas*.txt
não. A correspondência dos diretórios ocultos é feita da mesma maneira. Os diretórios ocultos podem incluir arquivos que não são necessários como entradas e podem aumentar o número de arquivos globulares desnecessariamente e o consumo de memória. Para excluir diretórios ocultos, adicione-os ao argumento de lista "excluir". -
O caractere curinga "**" tem um caso extremo: o padrão
"**"
não corresponde ao caminho do diretório do pacote. Ou seja,glob(["**"], exclude_directories = 0)
corresponde de forma transitiva a todos os arquivos e diretórios de maneira transitiva no diretório do pacote atual, mas não entra em diretórios de subpacotes. Consulte a observação anterior sobre isso.
Em geral, tente fornecer uma extensão apropriada (por exemplo, *.html) em vez de usar um "*" simples para um padrão glob. O nome mais explícito é autodocumentado e garante que você não corresponda acidentalmente a arquivos de backup ou arquivos de salvamento automático emacs/vi/....
Ao escrever regras de compilação, é possível enumerar os elementos do glob. Isso permite gerar regras individuais para cada entrada, por exemplo. Consulte a seção exemplo de glob expandido abaixo.
Exemplos da Glob
Crie uma biblioteca Java compilada com base em todos os arquivos Java deste diretório e todos os arquivos gerados pela regra :gen_java_srcs
.
java_library( name = "mylib", srcs = glob(["*.java"]) + [":gen_java_srcs"], deps = "...", ) genrule( name = "gen_java_srcs", outs = [ "Foo.java", "Bar.java", ], ... )
Incluir todos os arquivos txt no diretório testdata, exceto experimental.txt. Observe que os arquivos em subdiretórios de testdata não serão incluídos. Se você quiser que esses arquivos sejam incluídos, use um glob recursivo (**).
sh_test( name = "mytest", srcs = ["mytest.sh"], data = glob( ["testdata/*.txt"], exclude = ["testdata/experimental.txt"], ), )
Exemplos de globo recursivo
Faça com que o teste dependa de todos os arquivos txt no diretório testdata e de qualquer dos subdiretórios (e dos subdiretórios deles e assim por diante). Os subdiretórios que contêm um arquivo BUILD são ignorados. Consulte as limitações e as advertências acima.
sh_test( name = "mytest", srcs = ["mytest.sh"], data = glob(["testdata/**/*.txt"]), )
Crie uma biblioteca compilada com base em todos os arquivos Java nesse diretório e em todos os subdiretórios, exceto aqueles com caminhos que incluem um diretório chamado "testing". Evite esse padrão, se possível, porque ele pode reduzir a incrementabilidade e aumentar os tempos de build.
java_library( name = "mylib", srcs = glob( ["**/*.java"], exclude = ["**/testing/**"], ), )
Exemplos de Glob expandido
Crie uma regra geral individual para *_test.cc no diretório atual que conta o número de linhas no arquivo.
# Conveniently, the build language supports list comprehensions. [genrule( name = "count_lines_" + f[:-3], # strip ".cc" srcs = [f], outs = ["%s-linecount.txt" % f[:-3]], cmd = "wc -l $< >$@", ) for f in glob(["*_test.cc"])]
Se o arquivo BUILD acima estiver no pacote //foo e o pacote contiver três
arquivos correspondentes, a_test.cc, b_test.cc e c_test.cc, a execução de
bazel query '//foo:all'
listará todas as regras que foram geradas:
$ bazel query '//foo:all' | sort //foo:count_lines_a_test //foo:count_lines_b_test //foo:count_lines_c_test
select
select( {conditionA: valuesA, conditionB: valuesB, ...}, no_match_error = "custom message" )
select()
é a função auxiliar que torna um atributo de regra configurável.
Ele pode substituir o lado direito de
quase
qualquer atribuição de atributo, então o valor depende das flags da linha de comando do Bazel.
Isso pode ser usado, por exemplo, para definir dependências específicas da plataforma ou incorporar recursos diferentes, dependendo se uma regra é criada no modo "desenvolvedor" ou no modo "lançamento".
O uso básico é o seguinte:
sh_binary( name = "mytarget", srcs = select({ ":conditionA": ["mytarget_a.sh"], ":conditionB": ["mytarget_b.sh"], "//conditions:default": ["mytarget_default.sh"] }) )
Isso torna o atributo srcs
de um sh_binary
configurável substituindo a atribuição normal da lista de rótulos por uma chamada de select
que mapeia as condições de configuração para os valores correspondentes. Cada condição é uma referência de rótulo a um config_setting
ou constraint_value
, que "corresponde" se a configuração do destino corresponder a um conjunto esperado de valores. O valor de mytarget#srcs
se torna a lista de rótulos que corresponde à invocação atual.
Observações:
- Exatamente uma condição é selecionada em qualquer invocação.
- Se várias condições corresponderem e uma for especialização da outra, a especialização terá precedência. A condição B será considerada uma especialização da condição A se B tiver as mesmas flags e valores de restrição que A, além de algumas outras flags ou valores de restrição. Isso também significa que a resolução da especialização não foi projetada para criar uma ordem, conforme demonstrado no Exemplo 2 abaixo.
- Se várias condições corresponderem e uma não for uma especialização de todas as outras, o Bazel falhará com um erro, a menos que todas as condições sejam resolvidas para o mesmo valor.
- O pseudorótulo especial
//conditions:default
será considerado correspondente se nenhuma outra condição corresponder. Se essa condição for deixada de fora, alguma outra regra precisará corresponder para evitar um erro. select
pode ser incorporado dentro de uma atribuição de atributo maior. Portanto,srcs = ["common.sh"] + select({ ":conditionA": ["myrule_a.sh"], ...})
esrcs = select({ ":conditionA": ["a.sh"]}) + select({ ":conditionB": ["b.sh"]})
são expressões válidas.select
funciona com a maioria dos atributos, mas não com todos. Atributos incompatíveis são marcados comononconfigurable
na documentação.subpacotes
subpackages(include, exclude=[], allow_empty=True)
subpackages()
é uma função auxiliar, semelhante aglob()
, que lista subpacotes em vez de arquivos e diretórios. Ele usa os mesmos padrões de caminho queglob()
e pode corresponder a qualquer subpacote que seja descendente direto do arquivo BUILD que está sendo carregado. Consulte glob para uma explicação detalhada e exemplos de padrões de inclusão e exclusão.A lista resultante de subpacotes retornados está na ordem de classificação e contém caminhos relativos ao pacote de carregamento atual que correspondem aos padrões fornecidos em
include
, e não aos deexclude
.Exemplo
O exemplo a seguir lista todos os subpacotes diretos do pacote
foo/BUILD
# The following BUILD files exist: # foo/BUILD # foo/bar/baz/BUILD # foo/sub/BUILD # foo/sub/deeper/BUILD # # In foo/BUILD a call to subs = subpackages(include = ["**"]) # results in subs == ["sub", "bar/baz"] # # 'sub/deeper' is not included because it is a subpackage of 'foo/sub' not of # 'foo'
Em geral, é preferível que, em vez de chamar essa função diretamente, os usuários usem o módulo "subpackages" do skylib.