Esta página aborda os três sistemas de visibilidade do Bazel: visibilidade do destino, visibilidade transitiva e visibilidade de carregamento.
Esses tipos de visibilidade ajudam outros desenvolvedores a distinguir entre a API pública da biblioteca e os detalhes de implementação, além de ajudar a aplicar a estrutura à medida que o espaço de trabalho cresce. Também é possível usar a visibilidade ao descontinuar uma API pública para permitir usuários atuais e negar novos.
Visibilidade desejada
A visibilidade do destino controla quem pode depender do seu destino, ou seja, quem pode
usar o rótulo do destino dentro de um atributo como deps. Um destino não será criado durante a fase de análise se violar a visibilidade de uma das dependências.
Em geral, um destino A fica visível para um destino B se eles estiverem no mesmo
local ou se A conceder visibilidade ao local de B. Na ausência de
macros simbólicas, o termo "local" pode ser simplificado
para apenas "pacote". Consulte abaixo para mais informações sobre macros simbólicas.
A visibilidade é especificada listando os pacotes permitidos. Permitir um pacote não significa necessariamente que os subpacotes dele também sejam permitidos. Para mais detalhes sobre pacotes e subpacotes, consulte Conceitos e terminologia.
Para prototipagem, é possível desativar a aplicação obrigatória da visibilidade de destino definindo a
flag --check_visibility=false. Isso não deve ser feito para uso em produção no
código enviado.
A principal maneira de controlar a visibilidade é com o atributo
visibility de uma regra.
As subseções a seguir descrevem o formato do atributo, como aplicá-lo a
vários tipos de destinos e a interação entre o sistema de visibilidade e
as macros simbólicas.
Especificações de visibilidade
Todos os destinos de regra têm um atributo visibility que usa uma lista de rótulos. Cada
rótulo tem uma das seguintes formas. Com exceção do último formulário, esses
são apenas marcadores de posição sintáticos que não correspondem a nenhum destino real.
"//visibility:public": concede acesso a todos os pacotes."//visibility:private": não concede acesso adicional. Somente os destinos no pacote desse local podem usar esse destino."//foo/bar:__pkg__": concede acesso a//foo/bar(mas não aos subpacotes)."//foo/bar:__subpackages__": concede acesso a//foo/bare a todos os subpacotes diretos e indiretos."//some_pkg:my_package_group": concede acesso a todos os pacotes que fazem parte dopackage_groupfornecido.- Os grupos de pacotes usam uma
sintaxe diferente para
especificar pacotes. Em um grupo de pacotes, os formulários
"//foo/bar:__pkg__"e"//foo/bar:__subpackages__"são substituídos por"//foo/bar"e"//foo/bar/...", respectivamente. Da mesma forma,"//visibility:public"e"//visibility:private"são apenas"public"e"private".
- Os grupos de pacotes usam uma
sintaxe diferente para
especificar pacotes. Em um grupo de pacotes, os formulários
Por exemplo, se //some/package:mytarget tiver visibility definido como
[":__subpackages__", "//tests:__pkg__"], ele poderá ser usado por qualquer destino
que faça parte da árvore de origem //some/package/..., bem como destinos
declarados em //tests/BUILD, mas não por destinos definidos em
//tests/integration/BUILD.
Prática recomendada: para tornar vários destinos visíveis para o mesmo conjunto
de pacotes, use um package_group em vez de repetir a lista no atributo visibility
de cada destino. Isso aumenta a legibilidade e evita que as
listas fiquem dessincronizadas.
Prática recomendada: ao conceder visibilidade ao projeto de outra equipe, prefira
__subpackages__ em vez de __pkg__ para evitar a perda de visibilidade desnecessária à medida que o
projeto evolui e adiciona novos subpacotes.
Visibilidade do destino da regra
A visibilidade de um destino de regra é determinada pelo atributo visibility
ou por um padrão adequado, se não for fornecido, e pela adição do local em que o
destino foi declarado. Para destinos não declarados em uma macro simbólica, se o
pacote especificar um default_visibility,
esse padrão será usado. Para todos os outros pacotes e destinos declarados em uma
macro simbólica, o padrão é apenas ["//visibility:private"].
# //mypkg/BUILD
package(default_visibility = ["//friend:__pkg__"])
cc_library(
name = "t1",
...
# No visibility explicitly specified.
# Effective visibility is ["//friend:__pkg__", "//mypkg:__pkg__"].
# If no default_visibility were given in package(...), the visibility would
# instead default to ["//visibility:private"], and the effective visibility
# would be ["//mypkg:__pkg__"].
)
cc_library(
name = "t2",
...
visibility = [":clients"],
# Effective visibility is ["//mypkg:clients, "//mypkg:__pkg__"], which will
# expand to ["//another_friend:__subpackages__", "//mypkg:__pkg__"].
)
cc_library(
name = "t3",
...
visibility = ["//visibility:private"],
# Effective visibility is ["//mypkg:__pkg__"]
)
package_group(
name = "clients",
packages = ["//another_friend/..."],
)
Prática recomendada: evite definir default_visibility como público. Isso pode ser
conveniente para prototipagem ou em bases de código pequenas, mas o risco de criar
destinos públicos inadvertidamente aumenta à medida que a base de código cresce. É melhor ser
explícito sobre quais destinos fazem parte da interface pública de um pacote.
Visibilidade do destino do arquivo gerado
Um destino de arquivo gerado tem a mesma visibilidade que o destino de regra que o gera.
# //mypkg/BUILD
java_binary(
name = "foo",
...
visibility = ["//friend:__pkg__"],
)
# //friend/BUILD
some_rule(
name = "bar",
deps = [
# Allowed directly by visibility of foo.
"//mypkg:foo",
# Also allowed. The java_binary's "_deploy.jar" implicit output file
# target the same visibility as the rule target itself.
"//mypkg:foo_deploy.jar",
]
...
)
Visibilidade de destino do arquivo de origem
Os destinos de arquivos de origem podem ser declarados explicitamente usando
exports_files ou criados implicitamente
ao se referir ao nome de arquivo em um atributo de rótulo de uma regra (fora de uma
macro simbólica). Assim como nos destinos de regra, o local da chamada para
exports_files ou o arquivo BUILD que se refere ao arquivo de entrada é sempre
anexado automaticamente à visibilidade do arquivo.
Os arquivos declarados por exports_files podem ter a visibilidade definida pelo
parâmetro visibility para essa função. Se esse parâmetro não for fornecido, a visibilidade será pública.
Para arquivos que não aparecem em uma chamada para exports_files, a visibilidade
depende do valor da flag
--incompatible_no_implicit_file_export:
Se a sinalização for verdadeira, a visibilidade será privada.
Caso contrário, o comportamento legado será aplicado: a visibilidade será igual à do
default_visibilitydo arquivoBUILDou privada, se uma visibilidade padrão não for especificada.
Evite depender do comportamento legado. Sempre escreva uma declaração exports_files
quando um destino de arquivo de origem precisar de visibilidade não privada.
Prática recomendada: quando possível, prefira expor um destino de regra em vez de um
arquivo de origem. Por exemplo, em vez de chamar exports_files em um arquivo .java,
envolva o arquivo em um destino java_library não particular. Em geral, os destinos de regra
só devem referenciar diretamente os arquivos de origem que estão no mesmo pacote.
Exemplo
Arquivo //frobber/data/BUILD:
exports_files(["readme.txt"])
Arquivo //frobber/bin/BUILD:
cc_binary(
name = "my-program",
data = ["//frobber/data:readme.txt"],
)
Visibilidade da configuração
Historicamente, o Bazel não aplicava visibilidade para
destinos config_setting que são
referenciados nas chaves de um select(). Há
duas flags para remover esse comportamento legado:
--incompatible_enforce_config_setting_visibilityativa a verificação de visibilidade para esses destinos. Para ajudar na migração, ele também faz com que qualquerconfig_settingque não especifique umvisibilityseja considerado público (independentemente dodefault_visibilityno nível do pacote).--incompatible_config_setting_private_default_visibilityfaz com queconfig_settings que não especificam umvisibilityrespeitem odefault_visibilitydo pacote e usem a visibilidade particular como substituto, assim como qualquer outro destino de regra. Será uma operação sem efeito se--incompatible_enforce_config_setting_visibilitynão estiver definido.
Evite depender do comportamento legado. Qualquer config_setting que se destine a ser usado fora do pacote atual precisa ter um visibility explícito, se o pacote ainda não especificar um default_visibility adequado.
Visibilidade do destino do grupo de pacotes
As metas package_group não têm um atributo visibility. Elas sempre ficam
visíveis publicamente.
Visibilidade de dependências implícitas
Algumas regras têm dependências implícitas,
que não são explicitadas em um arquivo BUILD, mas são inerentes a
todas as instâncias dessa regra. Por exemplo, uma regra cc_library pode criar uma
dependência implícita de cada um dos destinos de regra para um destino executável
que representa um compilador C++.
A visibilidade de uma dependência implícita é verificada em relação ao
pacote que contém o arquivo .bzl em que a regra (ou aspecto) é definida. No
nosso exemplo, o compilador C++ pode ser particular, desde que esteja no mesmo
pacote que a definição da regra cc_library. Como alternativa, se a
dependência implícita não estiver visível na definição, ela será verificada em
relação ao destino cc_library.
Se você quiser restringir o uso de uma regra a determinados pacotes, use a visibilidade de carregamento.
Visibilidade e macros simbólicas
Nesta seção, descrevemos como o sistema de visibilidade interage com macros simbólicas.
Locais em macros simbólicas
Um detalhe importante do sistema de visibilidade é como determinamos o local de uma
declaração. Para destinos que não são declarados em uma macro simbólica, o local
é apenas o pacote em que o destino está, ou seja, o pacote do arquivo BUILD.
No entanto, para destinos criados em uma macro simbólica, o local é o pacote
que contém o arquivo .bzl em que a definição da macro (a
instrução my_macro = macro(...)) aparece. Quando um destino é criado dentro
de vários destinos aninhados, é sempre a definição da macro simbólica mais interna
que é usada.
O mesmo sistema é usado para determinar qual local verificar em relação à visibilidade de uma determinada dependência. Se o destino de consumo foi criado dentro de uma macro, analisamos a definição da macro mais interna, em vez do pacote em que o destino de consumo está.
Isso significa que todas as macros com código definido no mesmo pacote são
automaticamente "amigas" umas das outras. Qualquer destino criado diretamente por uma macro
definida em //lib:defs.bzl pode ser visto em qualquer outra macro definida em //lib,
independentemente dos pacotes em que as macros são instanciadas. Da mesma forma,
eles podem ver e ser vistos por destinos declarados diretamente em //lib/BUILD e
nas macros legadas. Por outro lado, os destinos que estão no mesmo pacote não podem
necessariamente se ver se pelo menos um deles for criado por uma macro
simbólica.
Na função de implementação de uma macro simbólica, o parâmetro visibility
tem o valor efetivo do atributo visibility da macro depois de anexar
o local em que a macro foi chamada. A maneira padrão de uma macro exportar
um dos destinos para o autor da chamada é encaminhar esse valor para a declaração
do destino, como em some_rule(..., visibility = visibility). As metas que omitirem
esse atributo não vão ficar visíveis para o autor da chamada da macro, a menos que ele
esteja no mesmo pacote que a definição da macro. Esse comportamento
é composto, no sentido de que uma cadeia de chamadas aninhadas para submacros pode transmitir
visibility = visibility, reexportando os destinos exportados da macro interna para
o autor da chamada em cada nível, sem expor nenhum dos detalhes de implementação
das macros.
Como delegar privilégios a uma submacro
O modelo de visibilidade tem um recurso especial que permite que uma macro delegue as permissões dela a uma submacro. Isso é importante para fatorar e compor macros.
Suponha que você tenha uma macro my_macro que cria uma borda de dependência usando uma regra
some_library de outro pacote:
# //macro/defs.bzl
load("//lib:defs.bzl", "some_library")
def _impl(name, visibility, ...):
...
native.genrule(
name = name + "_dependency"
...
)
some_library(
name = name + "_consumer",
deps = [name + "_dependency"],
...
)
my_macro = macro(implementation = _impl, ...)
# //pkg/BUILD
load("//macro:defs.bzl", "my_macro")
my_macro(name = "foo", ...)
O destino //pkg:foo_dependency não tem visibility especificado, então ele só é
visível em //macro, o que funciona bem para o destino de consumo. Agora, o que
acontece se o autor de //lib refatorar some_library para que seja
implementado usando uma macro?
# //lib:defs.bzl
def _impl(name, visibility, deps, ...):
some_rule(
# Main target, exported.
name = name,
visibility = visibility,
deps = deps,
...)
some_library = macro(implementation = _impl, ...)
Com essa mudança, o local de //pkg:foo_consumer agora é //lib em vez de
//macro. Portanto, o uso de //pkg:foo_dependency viola a visibilidade
da dependência. Não é esperado que o autor de my_macro transmita
visibility = ["//lib"] para a declaração da dependência apenas para contornar
esse detalhe de implementação.
Por esse motivo, quando uma dependência de um destino também é um valor do atributo da macro que declarou o destino, verificamos a visibilidade da dependência em relação ao local da macro, em vez do local do destino de consumo.
Neste exemplo, para validar se //pkg:foo_consumer pode ver
//pkg:foo_dependency, vemos que //pkg:foo_dependency também foi transmitido como uma
entrada para a chamada para some_library dentro de my_macro e, em vez disso, verificamos a
visibilidade da dependência em relação ao local dessa chamada, //macro.
Esse processo pode se repetir recursivamente, desde que uma declaração de destino ou macro esteja dentro de outra macro simbólica que use o rótulo da dependência em um dos atributos do tipo rótulo.
Finalizadores
As metas declaradas em um finalizador de regra (uma macro simbólica com finalizer = True),
além de ver as metas que seguem as regras de visibilidade de macro simbólica
usuais, também podem ver todas as metas que estão visíveis para o pacote da meta do
finalizador.
Em outras palavras, se você migrar uma macro legada baseada em native.existing_rules() para
um finalizador, os destinos declarados pelo finalizador ainda poderão ver
as dependências antigas.
É possível definir destinos que um finalizador pode analisar usando
native.existing_rules(), mas que não podem ser usados como dependências no
sistema de visibilidade. Por exemplo, se um destino definido por macro não estiver visível para o próprio
pacote ou para a definição da macro de finalização e não for delegado ao
finalizador, o finalizador não poderá ver esse destino. No entanto, uma macro legada baseada em native.existing_rules() também não poderá ver esse destino.
Visibilidade transitiva
A visibilidade transitiva é uma maneira de restringir quem pode depender de um destino, inclusive quando a dependência é apenas indireta. Ele é aplicado separadamente do sistema de visibilidade de destino comum, então é possível que ocorra um erro de visibilidade transitiva mesmo quando todos os links na cadeia de dependência são válidos. Isso permite que o autor do destino o compartilhe com um conjunto confiável de destinos de cliente, evitando que ele seja vazado inadvertidamente para o restante do build.
A visibilidade transitiva é declarada no nível do pacote, usando o
parâmetro transitive_visibility da função
[package][package]. Essa declaração se aplica a todos os destinos no pacote. O parâmetro
usa um único rótulo de um package_group, que especifica os pacotes com
destinos que podem depender de forma transitiva dos destinos desse pacote.
# //third_party/sensitive_dep/BUILD
package(
# This must be explicitly listed
transitive_visibility = ":sensitive_dep_users",
)
package_group(
name = "sensitive_dep_users",
packages = [
"//third_party/sensitive_dep/...", # has to include itself
"//allowed",
],
)
sh_library(
name = "sensitive_dep"
)
# //not_allowed/BUILD
sh_binary(
name = "bad",
deps = ["//third_party/sensitive_dep:sensitive_dep"]
)
A criação de //not_allowed:bad, que depende de
//third_party/sensitive_dep:sensitive_dep, mas não faz parte do
transitive_visibility, resulta no seguinte erro:
Transitive visibility error: //third_party/sensitive_dep:sensitive_dep is not transitively visible from ///not_allowed:bad. //"//third_party/sensitive_dep:sensitive_dep inherits a transitive_visibility declaration from its package or one of its dependencies that does not allow //not_allowed:bad.
Os grupos de pacotes usados em transitive_visibility não podem include outros grupos de pacotes.
Se um destino tiver uma dependência transitiva com uma restrição de visibilidade transitiva, ele vai herdar a restrição e transmiti-la aos destinos que dependem dele. Se um destino tiver várias dependências transitivas com restrições de visibilidade transitiva, ele precisará atender a todas as restrições.
A visibilidade transitiva também se aplica a destinos declarados em macros simbólicas. No entanto, ao contrário da visibilidade de destino comum, ela só considera o pacote em que esses destinos estão, não o pacote que definiu a macro simbólica.
Visibilidade de carga
A visibilidade de carregamento controla se um arquivo .bzl pode ser carregado de outros arquivos BUILD ou .bzl fora do pacote atual.
Da mesma forma que a visibilidade do destino protege o código-fonte encapsulado
por destinos, a visibilidade de carregamento protege a lógica de build encapsulada por arquivos
.bzl. Por exemplo, o autor de um arquivo BUILD pode querer fatorar algumas declarações de destino repetitivas em uma macro em um arquivo .bzl. Sem a proteção da
visibilidade de carregamento, a macro pode ser reutilizada por outros colaboradores no
mesmo espaço de trabalho, de modo que a modificação da macro interrompa os builds de outras equipes.
Um arquivo .bzl pode ou não ter um destino de arquivo de origem correspondente.
Se isso acontecer, não há garantia de que a visibilidade de carregamento e a visibilidade de destino coincidam. Ou seja, o mesmo arquivo BUILD pode carregar o arquivo .bzl, mas não listá-lo no srcs de um filegroup, ou vice-versa. Isso pode causar problemas para regras que consomem arquivos .bzl como código-fonte, como para geração de documentação ou testes.
Para prototipagem, é possível desativar a aplicação da visibilidade de carregamento definindo
--check_bzl_visibility=false. Assim como no --check_visibility=false, isso não deve ser feito para o código enviado.
A visibilidade de carregamento está disponível a partir do Bazel 6.0.
Como declarar a visibilidade de carregamento
Para definir a visibilidade de carregamento de um arquivo .bzl, chame a
função visibility() no arquivo.
O argumento para visibility() é uma lista de especificações de pacote, assim como
o atributo packages de
package_group. No entanto, visibility() não aceita especificações de pacote negativas.
A chamada para visibility() precisa ocorrer apenas uma vez por arquivo, no nível superior (não
dentro de uma função) e, de preferência, logo após as instruções load().
Ao contrário da visibilidade de destino, a visibilidade de carregamento padrão é sempre pública. Os arquivos
que não chamam visibility() sempre podem ser carregados de qualquer lugar no
espaço de trabalho. É uma boa ideia adicionar visibility("private") à parte de cima de qualquer
novo arquivo .bzl que não seja destinado especificamente ao uso fora do pacote.
Exemplo
# //mylib/internal_defs.bzl
# Available to subpackages and to mylib's tests.
visibility(["//mylib/...", "//tests/mylib/..."])
def helper(...):
...
# //mylib/rules.bzl
load(":internal_defs.bzl", "helper")
# Set visibility explicitly, even though public is the default.
# Note the [] can be omitted when there's only one entry.
visibility("public")
myrule = rule(
...
)
# //someclient/BUILD
load("//mylib:rules.bzl", "myrule") # ok
load("//mylib:internal_defs.bzl", "helper") # error
...
Práticas de visibilidade de carga
Nesta seção, descrevemos dicas para gerenciar declarações de visibilidade de carregamento.
Visibilidade de fatoração
Quando vários arquivos .bzl precisam ter a mesma visibilidade, pode ser útil
fatorar as especificações de pacote em uma lista comum. Exemplo:
# //mylib/internal_defs.bzl
visibility("private")
clients = [
"//foo",
"//bar/baz/...",
...
]
# //mylib/feature_A.bzl
load(":internal_defs.bzl", "clients")
visibility(clients)
...
# //mylib/feature_B.bzl
load(":internal_defs.bzl", "clients")
visibility(clients)
...
Isso ajuda a evitar distorções acidentais entre as visibilidades dos vários arquivos .bzl. Ele também é mais legível quando a lista clients é grande.
Como compor visibilidades
Às vezes, um arquivo .bzl precisa estar visível para uma lista de permissões composta por várias listas menores. Isso é semelhante à forma como um
package_group pode incorporar outros package_groups pelo
atributo includes.
Suponha que você esteja descontinuando uma macro amplamente usada. Você quer que ele fique visível apenas para os usuários atuais e para os pacotes que pertencem à sua equipe. Você pode escrever:
# //mylib/macros.bzl
load(":internal_defs.bzl", "our_packages")
load("//some_big_client:defs.bzl", "their_remaining_uses")
# List concatenation. Duplicates are fine.
visibility(our_packages + their_remaining_uses)
Como eliminar duplicações com grupos de pacotes
Ao contrário da visibilidade do destino, não é possível definir uma visibilidade de carregamento em termos de um
package_group. Se você quiser reutilizar a mesma lista de permissões para a visibilidade de destino e de carregamento, é melhor mover a lista de especificações de pacote para um arquivo .bzl, em que os dois tipos de declarações podem se referir a ela. Com base no exemplo em Visibilidades de fatoração
acima, você pode escrever:
# //mylib/BUILD
load(":internal_defs", "clients")
package_group(
name = "my_pkg_grp",
packages = clients,
)
Isso só funciona se a lista não tiver especificações de pacote negativas.
Como proteger símbolos individuais
Qualquer símbolo do Starlark com um nome que comece com um sublinhado não pode ser carregado de
outro arquivo. Isso facilita a criação de símbolos particulares, mas não permite
que você os compartilhe com um conjunto limitado de arquivos confiáveis. Por outro
lado, a visibilidade de carregamento permite controlar quais outros pacotes podem ver seu
.bzl file, mas não permite impedir que qualquer símbolo sem sublinhado seja
carregado.
Felizmente, é possível combinar esses dois recursos para ter um controle detalhado.
# //mylib/internal_defs.bzl
# Can't be public, because internal_helper shouldn't be exposed to the world.
visibility("private")
# Can't be underscore-prefixed, because this is
# needed by other .bzl files in mylib.
def internal_helper(...):
...
def public_util(...):
...
# //mylib/defs.bzl
load(":internal_defs", "internal_helper", _public_util="public_util")
visibility("public")
# internal_helper, as a loaded symbol, is available for use in this file but
# can't be imported by clients who load this file.
...
# Re-export public_util from this file by assigning it to a global variable.
# We needed to import it under a different name ("_public_util") in order for
# this assignment to be legal.
public_util = _public_util
Lint do Buildifier bzl-visibility
Há um lint do Buildifier
que avisa se os usuários carregam um arquivo de um diretório chamado internal
ou private, quando o arquivo do usuário não está abaixo do pai desse
diretório. Esse lint é anterior ao recurso de visibilidade de carregamento e é desnecessário em
espaços de trabalho em que os arquivos .bzl declaram visibilidades.