Funções

Informar um problema Ver código

Índice

pacote

package(default_deprecation, default_package_metadata, default_testonly, default_visibility, features)

Essa função declara metadados que se aplicam a cada regra subsequente no pacote. Ele é usado no máximo uma vez dentro de um pacote (arquivo BUILD).

A função package() precisa 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_package_metadata.

default_visibility

List of labels; optional

A visibilidade padrão das regras neste pacote.

Todas as regras deste pacote têm a visibilidade especificada neste atributo, a menos que especificado de outra forma no atributo visibility da regra. Para informações detalhadas sobre a sintaxe desse atributo, consulte a documentação de visibilidade. A visibilidade padrão do pacote não se aplica a exports_files, que é público por padrão.
default_deprecation

String; optional

Define a mensagem padrão deprecation para todas as regras do pacote.
default_package_metadata

List of labels; optional

Define uma lista padrão de destinos de metadados que se aplicam a todos os outros destinos no pacote. Normalmente, são alvos relacionados a declarações de licença e pacote OSS. Consulte rules_license para exemplos.
default_testonly

Boolean; optional; default is False except as noted

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

Em pacotes abaixo de javatests, o valor padrão é 1.
features

List strings; optional

Define várias sinalizações que afetam a semântica desse arquivo BUILD.

Esse recurso é usado principalmente pelas pessoas que trabalham no sistema de compilação para marcar pacotes que precisam de um tratamento especial. Não use isso a menos que solicitado explicitamente por alguém que trabalha no sistema de compilação.

Exemplos

A declaração abaixo declara que as regras neste pacote estão visíveis apenas para membros do grupo de pacotes //foo:target. As declarações de visibilidade individuais em uma regra, se houver, modificam esta especificação. 
package(default_visibility = ["//foo:target"])

grupo_do_pacote

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 nos 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 particularmente só pode ser referenciado dentro do próprio pacote (não dos subpacotes). Entre esses extremos, uma meta pode permitir acesso ao próprio pacote mais 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 visibility.

Um determinado pacote será considerado no grupo se corresponder ao atributo packages ou 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

Name; required

Um nome exclusivo para este destino.
packages

List of strings; optional

Uma lista de zero ou mais especificações de pacote.

Cada string de especificação do 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 que tem esse nome e que reside no mesmo repositório que o grupo de pacotes.
  2. Conforme acima, mas com um /... à direita. Por exemplo, //foo/... especifica o conjunto de //foo e todos os respectivos subpacotes. //... especifica todos os pacotes no repositório atual.
  3. As strings public ou private, que respectivamente especificam todos os pacotes ou nenhum pacote. Esse formulário requer a definição da sinalização --incompatible_package_group_has_public_syntax.

Além disso, os dois primeiros tipos de especificações do pacote também podem ser prefixados com - para indicar que foram negados.

O grupo de pacotes contém qualquer pacote que corresponda a pelo menos uma das especificações positivas e nenhuma das 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 é incluído, mas //foo/tests propriamente dito não é.

Além da visibilidade pública, não é possível especificar pacotes diretamente fora do repositório atual.

Se esse atributo estiver ausente, será o mesmo que configurá-lo para uma lista vazia, que também é o mesmo que configurá-lo para uma lista contendo 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, o que é o padrão após o Bazel 6.0.

Observação: antes do Bazel 6.0, quando esse atributo é serializado como parte de bazel query --output=proto (ou --output=xml), as barras iniciais são omitidas. Por exemplo, //pkg/foo/... será exibido 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

List of labels; optional

Outros grupos de pacotes incluídos neste.

Os rótulos neste atributo precisam se referir a outros grupos de pacotes. Os pacotes em grupos de pacotes referenciados são considerados parte deste grupo. Isso é transitivo. Se o grupo de pacotes a incluir o grupo b e b incluir o grupo c, todos os pacotes em c também serão membros 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 sobre as 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"],
)

export_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ó pode se referir diretamente aos arquivos de origem pertencentes a outro pacote se eles forem explicitamente exportados com uma instrução exports_files(). Leia mais sobre a visibilidade de arquivos.

Como comportamento legado, os arquivos mencionados como entrada para uma regra são exportados com a visibilidade padrão até que a sinalização --incompatible_no_implicit_file_export seja invertida. No entanto, esse comportamento não deve ser descontado e 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 serã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"])

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 nova lista ordenada, mutável e de caminhos. O Glob pesquisa apenas arquivos no próprio pacote e procura apenas arquivos de origem (arquivos não 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 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 *: ele corresponde a qualquer substring no segmento de caminho (até mesmo com a substring vazia), exceto 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 neste pacote
  • foo/*.txt corresponderá 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 cada arquivo no diretório foo/ que começa com a, tem uma string arbitrária (pode estar vazia), tem .htm e termina com outra string arbitrária, como foo/axx.htm e foo/a.html ou foo/axxx.html
  • **/a.txt corresponde a cada arquivo a.txt em cada subdiretório desse pacote
  • **/bar/**/*.txt corresponde a cada arquivo .txt em cada subdiretório 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 cada subdiretório desse pacote.
  • foo**/a.txt é um padrão inválido, porque ** precisa permanecer 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 estiver definido como False, a função glob 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 de arquivos BUILD, glob() corresponde a arquivos somente na árvore de origem, nunca a arquivos gerados. Se estiver criando um destino que exija arquivos de origem e gerados, anexe uma lista explícita de arquivos gerados ao glob. Veja 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 será "shadow" para o arquivo.

    Para entender isso, glob() retorna uma lista de caminhos. Portanto, usar glob() no atributo de outras regras (por exemplo, srcs = glob(["*.cc"])) tem o mesmo efeito que listar explicitamente os caminhos correspondentes. Por exemplo, se glob() gerar ["Foo.java", "bar/Baz.java"], mas também houver uma regra no pacote chamada "Foo.java" (o que é permitido, embora Bazel tenha cuidado), o consumidor de glob() usará a regra "Foo.java" (as saídas) em vez do arquivo "Foo.java". Consulte o problema 10395 do GitHub para ver mais detalhes.

  3. Os globos podem corresponder aos arquivos em subdiretórios. E os nomes de subdiretórios podem ter um caractere curinga. 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 incluirá x/y/z.cc se x/y existir como um pacote (como x/y/BUILD ou em algum 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 estivesse marcada usando a sinalização --deleted_packages.

  5. A restrição acima se aplica a todas as expressões glob, independentemente dos caracteres curinga utilizados.
  6. Um arquivo oculto com nome de arquivo que começa com . é totalmente correspondido pelos caracteres curinga ** e *. Se você quiser corresponder um arquivo oculto a um padrão composto, seu padrão precisa começar com .. Por exemplo, * e .*.txt corresponderão 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 globed desnecessariamente e o consumo de memória. Para excluir diretórios ocultos, adicione-os ao argumento de lista "excluir".
  7. O caractere curinga "**" tem um caso único: o padrão "**" não corresponde ao caminho do diretório do pacote. Ou seja, glob(["**"], exclude_directories = 0) corresponde de modo temporário a todos os arquivos e diretórios estritamente sob o diretório do pacote atual, mas, obviamente, não entra nos 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 "*" para um padrão glob. O nome mais explícito é auto-documentar e garantir que você não corresponda acidentalmente a arquivos de backup ou arquivos emacs/vi/... de salvamento automático.

Ao gravar regras de compilação, você pode enumerar os elementos do glob. Isso permite gerar regras individuais para cada entrada, por exemplo. Consulte a seção exemplo de glob expandida abaixo.

Exemplos de globo

Crie uma biblioteca Java criada a partir de todos os arquivos Java neste 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 nos diretórios testtest, exceto experimental.txt. Observe que os arquivos nos 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 o teste depender de todos os arquivos txt do diretório testdata e de qualquer um dos subdiretórios (e dos subdiretórios etc.). Os subdiretórios que contêm um arquivo BUILD são ignorados. Veja as limitações e ressalvas acima.

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

Crie uma biblioteca criada a partir de todos os arquivos Java neste 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 incrementabilidade da compilação e, portanto, aumentar os tempos de compilação. 

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

Exemplos de globo expandido

Crie uma regra geral 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, executar bazel query '//foo:all' 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, de modo que seu valor dependa das sinalizações do Bazel de linha de comando. Você pode usar isso, por exemplo, para definir dependências específicas da plataforma ou incorporar recursos diferentes, dependendo de a regra ser criada no modo "desenvolvedor" ou "versão".

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 de 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 para 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 torna-se 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 forem correspondentes 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 sinalizações e valores de restrição que A, além de outras sinalizações 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 forem correspondentes 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 com o mesmo valor.
  • O pseudorótulo especial //conditions:default será considerado correspondente se nenhuma outra condição corresponder. Se essa condição for ignorada, 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 dos atributos, mas não todos. Os atributos incompatíveis são marcados como nonconfigurable na documentação.

    subpacotes

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

    subpackages() é uma função auxiliar, semelhante a glob(), que lista subpacotes em vez de arquivos e diretórios. Ele usa os mesmos padrões de caminho que glob() e pode corresponder a qualquer subpacote que seja descendente direto do arquivo BUILD em carregamento 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á 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 nos exclude.

    Exemplo

    O exemplo a seguir lista todos os subpacotes diretos para o 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 os usuários usem o módulo "subpackages" de skylib em vez de chamar essa função diretamente.