Funções

Nightly · 9.1 · 9.0 · 8.6 · 8.5 · 8.4 · 8.3 · 8.2 · 8.1

Índice

package

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. Ela é usada no máximo uma vez em um pacote (arquivo BUILD).

Para a contraparte que declara metadados aplicáveis a todas as regras em todo o repositório, use a função repo() no REPO.bazel arquivo na raiz do repositório. A função repo() usa exatamente os mesmos argumentos que package().

A função package() precisa ser chamada logo após todas as instruções load() na parte de cima do arquivo, antes de qualquer regra.

Argumentos

Atributo Descrição
default_applicable_licenses

Alias para default_package_metadata.

default_visibility

Lista de rótulos; o padrão é []

A visibilidade padrão dos destinos de regra de nível superior e macros simbólicas nesse pacote, ou seja, os destinos e macros simbólicas que não são declarados dentro de uma macro simbólica. Esse atributo é ignorado se o destino ou a macro especificar um visibility valor.

Para informações detalhadas sobre a sintaxe desse atributo, consulte a documentação de visibility. A visibilidade padrão do pacote não se aplica a exports_files, que é pública por padrão.

default_deprecation

String; o padrão é ""

Define a mensagem deprecation padrão para todas as regras nesse pacote.
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. Esses são normalmente destinos relacionados a declarações de pacotes e licenças de OSS. Consulte rules_license para exemplos.
default_testonly

Booleano; o padrão é False, exceto quando indicado

Define a propriedade testonly padrão para todas as regras nesse pacote.

Em pacotes em javatests, o valor padrão é True.
features

Lista de strings; o padrão é []

Define várias flags que afetam a semântica desse 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 isso, a menos que seja solicitado explicitamente por alguém que trabalhe no sistema de build.

Exemplos

A declaração abaixo declara que as regras nesse pacote são visíveis apenas para participantes do grupo de pacotes //foo:target. As declarações de visibilidade individuais em uma regra, se presentes, 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 ao conjunto. O rótulo pode ser referenciado em atributos visibility.

Os grupos de pacotes são usados principalmente para controle de visibilidade. Um destino visível publicamente pode ser referenciado em todos os pacotes na árvore de origem. Um destino visível de forma particular só pode ser referenciado no próprio pacote (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 de pacotes. Para uma explicação mais detalhada do sistema de visibilidade, consulte o atributo de visibilidade.

Um determinado pacote é considerado no grupo se corresponder ao atributo packages ou se já estiver contido em um dos outros grupos de pacotes mencionados no atributo includes.

Os grupos de pacotes são tecnicamente destinos, mas não são criados por regras e não têm proteção de visibilidade.

Argumentos

Atributo Descrição
name

Nome; obrigatório

Um nome exclusivo para esse 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:

  1. O nome completo de um pacote, sem o repositório, começando com uma barra dupla. Por exemplo, //foo/bar especifica o pacote com esse nome e que reside no mesmo repositório que o grupo de pacotes.
  2. Como acima, mas com um /... no final. Por exemplo, //foo/... especifica o conjunto de //foo e todos os subpacotes dele. //... especifica todos os pacotes no repositório atual. // é usado para indicar o pacote raiz.
  3. As strings public ou private, que especificam, respectivamente, todos os pacotes ou nenhum pacote. Essa forma exige que a flag --incompatible_package_group_has_public_syntax seja definida.

Além disso, os dois primeiros tipos de especificações de pacote também podem ter o prefixo - para indicar que são negados.

O grupo de pacotes contém qualquer pacote que corresponda a pelo menos uma de suas especificações positivas e nenhuma de suas especificações negativas. Por exemplo, o valor [//foo/..., -//foo/tests/...] inclui todos os subpacotes de //foo que também não são subpacotes de //foo/tests. (//foo está incluído, enquanto //foo/tests não está.)

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, que também é o mesmo que defini-lo como uma lista que contém apenas private.

Observação:antes do Bazel 6.0, a especificação //... tinha um comportamento legado de ser igual a public. Esse comportamento é corrigido quando --incompatible_fix_package_group_reporoot_syntax está ativado, que é o padrão após o Bazel 6.0.

Observação: antes do Bazel 6.0, quando esse atributo era serializado como parte de bazel query --output=proto (ou --output=xml), as barras iniciais eram omitidas. Por exemplo, //pkg/foo/... seria gerado como \"pkg/foo/...\". Esse comportamento é corrigido quando --incompatible_package_group_includes_double_slash está ativado, que é o padrão após o Bazel 6.0.
includes

Lista de rótulos; o padrão é []

Outros grupos de pacotes incluídos neste.

Os rótulos nesse atributo precisam se referir a outros grupos de pacotes. Os pacotes em grupos de pacotes referenciados são considerados parte desse grupo de pacotes. Isso é transitivo: se o grupo de pacotes a incluir o grupo de pacotes b, e b incluir o grupo de pacotes c, todos os pacotes em c também serão participantes de a.

Quando usado com especificações de pacote negadas, observe que o conjunto de pacotes para cada grupo é calculado primeiro de forma independente e os resultados são unidos. Isso significa que as especificações negadas em um grupo não têm efeito nas especificações em 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 a seguir 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 esse pacote que são exportados para outros pacotes.

O arquivo BUILD de um pacote só pode se referir diretamente a arquivos de origem pertencentes a outro pacote se eles forem exportados explicitamente com uma exports_files() instrução. Saiba mais sobre a visibilidade dos arquivos.

Como um comportamento legado, os arquivos mencionados como entrada para uma regra também são exportados com a visibilidade padrão até que a flag --incompatible_no_implicit_file_export seja invertida. No entanto, não confie nesse comportamento e migre ativamente dele.

Argumentos

O argumento é uma lista de nomes de arquivos no 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 package função. 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"])

glob

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 dos caminhos. O Glob só pesquisa arquivos no próprio pacote e procura apenas arquivos de origem (não arquivos gerados nem outros destinos).

O rótulo de um arquivo de origem é 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 no padrão são correspondidos aos segmentos do caminho. Os segmentos podem conter o caractere curinga *: ele corresponde a qualquer substring no segmento de caminho (até 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 independente.

Exemplos:
  • foo/bar.txt corresponde exatamente ao arquivo foo/bar.txt nesse pacote (a menos que foo/ seja um subpacote)
  • foo/*.txt corresponde a todos os arquivos no diretório foo/ se o arquivo terminar com .txt (a menos que foo/ seja um subpacote)
  • foo/a*.htm* corresponde a todos os arquivos no diretório foo/ que começam com a, têm uma string arbitrária (pode estar vazia), têm .htm e terminam com outra string arbitrária (a menos que foo/ seja um subpacote), como foo/axx.htm e foo/a.html ou foo/axxx.html
  • foo/* corresponde a todos os arquivos no diretório foo/ (a menos que foo/ seja um subpacote). Ele não corresponde ao diretório foo mesmo que exclude_directories esteja definido como 0
  • foo/** corresponde a todos os arquivos em todos os subdiretórios não subpacotes no primeiro nível de subdiretório foo/ do pacote. Se exclude_directories estiver definido como 0, o diretório foo também vai corresponder ao padrão. Nesse caso, ** é considerado para corresponder a zero segmentos de caminho
  • **/a.txt corresponde a arquivos a.txt no diretório desse pacote e em subdiretórios não subpacotes.
  • **/bar/**/*.txt corresponde a todos os arquivos .txt em todos os subdiretórios não subpacotes desse pacote, se pelo menos um diretório no caminho resultante for chamado bar, como xxx/bar/yyy/zzz/a.txt ou bar/a.txt (lembre-se de que ** também corresponde a zero segmentos) ou bar/zzz/a.txt
  • ** corresponde a todos os arquivos em todos os subdiretórios não subpacotes desse pacote
  • foo**/a.txt é um padrão inválido, porque ** precisa ficar sozinho como um segmento
  • foo/ é um padrão inválido, porque o segundo segmento definido após / é uma string vazia

Se o argumento exclude_directories estiver ativado (definido como 1), os arquivos do tipo diretório serão omitidos dos resultados (padrão 1).

Se o argumento allow_empty estiver definido como False, a função glob vai gerar um erro se o resultado for a lista vazia.

Há várias limitações e ressalvas importantes:

  1. Como glob() é executado durante a avaliação do arquivo BUILD, glob() corresponde a arquivos apenas na árvore de origem, nunca arquivos gerados. Se você estiver criando um destino que exige arquivos de origem e gerados, anexe uma lista explícita de arquivos gerados ao glob. Consulte o exemplo abaixo com :mylib e :gen_java_srcs.

  2. Se uma regra tiver o mesmo nome de um arquivo de origem correspondente, a regra vai "sombrear" o arquivo.

    Para entender isso, lembre-se de que glob() retorna uma lista de caminhos. Portanto, usar glob() em outro atributo de regras (por exemplo, srcs = glob(["*.cc"])) tem o mesmo efeito que listar os caminhos correspondentes explicitamente. Se, por exemplo, glob() gerar ["Foo.java", "bar/Baz.java"] mas também houver uma regra no pacote chamado "Foo.java" (que é permitida, embora o Bazel avise sobre isso), o consumidor do glob() vai usar a regra "Foo.java" (as saídas dela) em vez do arquivo "Foo.java". Consulte o problema 10395 do GitHub (link em inglês) para mais detalhes.

  3. Os globs podem corresponder a arquivos em subdiretórios. E os nomes de subdiretórios podem ser curingas. No entanto...

  4. Os rótulos não podem cruzar o limite do pacote, e o glob não corresponde a arquivos em subpacotes.

    Por exemplo, a expressão glob **/*.cc no pacote x não inclui x/y/z.cc se x/y existir como um pacote (como x/y/BUILD, ou em outro lugar no caminho do pacote). Isso significa que o resultado da expressão glob depende da existência de arquivos BUILD. Ou seja, a mesma expressão glob incluiria x/y/z.cc se não houvesse um pacote chamado x/y ou se ele fosse marcado como excluído usando a --deleted_packages flag.

  5. A restrição acima se aplica a todas as expressões glob, não importa quais caracteres curinga elas usem.
  6. Um arquivo oculto com nome de arquivo começando com . é totalmente correspondido por ambos os caracteres curinga ** e *. Se você quiser corresponder um arquivo oculto com um padrão composto, o padrão precisa começar com um .. Por exemplo, * e .*.txt vão corresponder a .foo.txt, mas *.txt não. Os diretórios ocultos também são correspondidos 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 globados desnecessariamente e o consumo de memória. Para excluir diretórios ocultos, adicione-os ao argumento da lista "exclude".
  7. 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 = False) corresponde a todos os arquivos e diretórios transitivamente estritamente no diretório do pacote atual (mas é claro que 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 é autoexplicativo e garante que você não corresponda acidentalmente a arquivos de backup ou arquivos de salvamento automático do emacs/vi/....

Ao escrever regras de build, é possível enumerar os elementos do glob. Isso permite gerar regras individuais para cada entrada, por exemplo. Consulte a seção de exemplo de glob expandido abaixo.

Exemplos de glob

Crie uma biblioteca Java criada com todos os arquivos Java nesse 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",
    ],
    ...
)

Inclua todos os arquivos txt no diretório testdata, exceto experimental.txt. Os arquivos em subdiretórios de testdata não serão incluídos. Se você quiser incluir esses arquivos, use um glob recursivo (**).

sh_test(
    name = "mytest",
    srcs = ["mytest.sh"],
    data = glob(
        ["testdata/*.txt"],
        exclude = ["testdata/experimental.txt"],
    ),
)

Exemplos de glob recursivo

Faça com que o teste dependa de todos os arquivos txt no diretório testdata e em qualquer um dos subdiretórios dele (e os subdiretórios deles e assim por diante). Os subdiretórios que contêm um arquivo BUILD são ignorados. (Consulte as limitações e ressalvas acima.)

sh_test(
    name = "mytest",
    srcs = ["mytest.sh"],
    data = glob(["testdata/**/*.txt"]),
)

Crie uma biblioteca criada com todos os arquivos Java nesse diretório e todos os subdiretórios, exceto aqueles cujo caminho inclui um diretório chamado testing. Esse padrão precisa ser evitado, se possível, porque pode reduzir a incrementalidade do build e, portanto, aumentar os tempos de build. 

java_library(
    name = "mylib",
    srcs = glob(
        ["**/*.java"],
        exclude = ["**/testing/**"],
    ),
)

Exemplos de glob expandido

Crie uma genrule individual para *_test.cc no diretório atual que conte 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' vai listar todas as regras 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 para que o valor dependa das flags do Bazel da linha de comando. Você pode usar isso, por exemplo, para definir dependências específicas da plataforma ou para incorporar recursos diferentes, dependendo se uma regra é criada no modo "desenvolvedor" ou "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 select que mapeia as condições de configuração para 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 uma especialização das outras, a especialização terá precedência. A condição B é considerada uma especialização da condição A se B tiver todas as mesmas flags e valores de restrição que A, além de algumas flags ou valores de restrição adicionais. Isso também significa que a resolução de especialização não foi projetada para criar uma ordenação, 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 vai falhar com um erro, a menos que todas as condições sejam resolvidas para o mesmo valor.
  • O pseudorótulo especial //conditions:default é considerado uma correspondência se nenhuma outra condição corresponder. Se essa condição for omitida, 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"], ...}) e srcs = select({ ":conditionA": ["a.sh"]}) + select({ ":conditionB": ["b.sh"]}) são expressões válidas.
  • select funciona com a maioria, mas não com todos os atributos. Os atributos incompatíveis são marcados como nonconfigurable na documentação.

    subpackages

    subpackages(include, exclude=[], allow_empty=True)

    subpackages() é uma função auxiliar, semelhante a glob() , que lista subpacotes em vez de arquivos e diretórios. Ela usa os mesmos padrões de caminho que glob() e pode corresponder a qualquer subpacote que seja um descendente direto do arquivo BUILD carregado no momento. 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á em ordem classificada e contém caminhos relativos ao pacote de carregamento atual que correspondem aos padrões fornecidos em include e não àqueles em exclude.

    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/bar/but/bad/BUILD
# foo/sub/BUILD
# foo/sub/deeper/BUILD
#
# In foo/BUILD a call to
subs1 = subpackages(include = ["**"])

# results in subs1 == ["sub", "bar/baz", "bar/but/bad"]
#
# 'sub/deeper' is not included because it is a subpackage of 'foo/sub' not of
# 'foo'

subs2 = subpackages(include = ["bar/*"])
# results in subs2 = ["bar/baz"]
#
# Since 'bar' is not a subpackage itself, this looks for any subpackages under
# all first level subdirectories of 'bar'.

subs3 = subpackages(include = ["bar/**"])
# results in subs3 = ["bar/baz", "bar/but/bad"]
#
# Since bar is not a subpackage itself, this looks for any subpackages which are
# (1) under all subdirectories of 'bar' which can be at any level, (2) not a
# subpackage of another subpackages.

subs4 = subpackages(include = ["sub"])
subs5 = subpackages(include = ["sub/*"])
subs6 = subpackages(include = ["sub/**"])
# results in subs4 and subs6 being ["sub"]
# results in subs5 = [].
#
# In subs4, expression "sub" checks whether 'foo/sub' is a package (i.e. is a
# subpackage of 'foo').
# In subs5, "sub/*" looks for subpackages under directory 'foo/sub'. Since
# 'foo/sub' is already a subpackage itself, the subdirectories will not be
# traversed anymore.
# In subs6, 'foo/sub' is a subpackage itself and matches pattern "sub/**", so it
# is returned. But the subdirectories of 'foo/sub' will not be traversed
# anymore.

    Em geral, é preferível que, em vez de chamar essa função diretamente que os usuários usem o módulo 'subpackages' do skylib.