Funções

Conteúdo

• pacote
• package_group
• exports_files
• glob
• selecionar
• subpacotes;

pacote

package(default_deprecation, default_testonly, default_visibility, features)

Essa função declara metadados que se aplicam a todas as regras subsequentes no pacote. Ele é usado no máximo uma vez em um pacote (arquivo BUILD).

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

Argumentos

Atributo	Descrição
default_visibility	List of labels; optional A visibilidade padrão das regras neste pacote. Todas as regras neste pacote têm a visibilidade especificada nesse 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 deprecation padrão para todas as regras neste pacote.
default_testonly	Boolean; optional; default is False except as noted Define a propriedade testonly padrão para todas as regras neste 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 algum tipo de tratamento especial. Não use isso a menos que 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. 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 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 de visibilidade particular só pode ser referenciado dentro do próprio pacote (não subpacotes). Entre esses extremos, um destino pode permitir 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 visibilidade.

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

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

Argumentos

Atributo	Descrição
name	Name; required Um nome exclusivo para o destino.
packages	List of strings; optional Uma lista de zero ou mais especificações de pacote. Cada string de especificação de pacote pode ter uma das seguintes formas: 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. Igual ao item acima, mas com uma /... à direita. Por exemplo, //foo/... especifica o conjunto de //foo e todos os respectivos subpacotes. //... especifica todos os pacotes no repositório atual. As strings public ou private, que especificam, respectivamente, cada pacote ou nenhum pacote. Neste formulário, é necessário definir a sinalização --incompatible_package_group_has_public_syntax. Além disso, os dois primeiros tipos de especificações de 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 não são também subpacotes de //foo/tests. //foo é incluído, enquanto //foo/tests não está. Além da visibilidade pública, não há como especificar pacotes diretamente fora do repositório atual. Se esse atributo estiver ausente, é o mesmo que configurá-lo como uma lista vazia, o 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 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 é serializado como parte de bazel query --output=proto (ou --output=xml), as barras iniciais são omitidas. Por exemplo, //pkg/foo/... terá como saída \"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 nesse atributo precisam se referir a outros grupos de pacotes. Os pacotes nos grupos de pacotes referenciados são levados para fazer parte desse grupo. É 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, o conjunto de pacotes para cada grupo é calculado de forma independente, e os resultados são unidos em seguida. Isso significa que as especificações negadas em um grupo não afetam 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"],
)

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ó poderá se referir diretamente aos arquivos de origem pertencentes a outro pacote se eles forem exportados explicitamente 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 sinalização --incompatible_no_implicit_file_export seja invertida. No entanto, esse comportamento não deve ser considerado nem migrado ativamente.

Argumentos

O argumento é uma lista de nomes de arquivos do pacote atual. Também é possível especificar uma declaração de visibilidade. Nesse caso, os arquivos ficam 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 dos testes.

# from //test_data/BUILD

exports_files(["golden.txt"])

Globo

glob(include, exclude=[], exclude_directories=1, allow_empty=True)

O Glob é uma função auxiliar que encontra todos os arquivos que correspondem a determinados padrões de caminho e retorna uma nova lista mutável e ordenada dos caminhos. O Glob só pesquisa arquivos no próprio pacote e arquivos de origem (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 *: isso corresponde a qualquer substring no segmento do 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 autônomo.

Exemplos:

• foo/bar.txt corresponde exatamente ao arquivo foo/bar.txt neste pacote.
• foo/*.txt corresponde a todos os arquivos no diretório foo/ se o arquivo termina com .txt (a menos que foo/ seja um subpacote).
• foo/a*.htm* corresponde a todos os arquivos no diretório foo/ que começa com a, tem uma string arbitrária (pode estar vazia), depois 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 todos os arquivos a.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 chamado bar, como xxx/bar/yyy/zzz/a.txt ou bar/a.txt (lembre-se de que ** também corresponde a segmentos zero ) ou bar/zzz/a.txt
• ** corresponde a todos os arquivos em todos os subdiretórios desse pacote.
• foo**/a.txt é um padrão inválido, porque ** precisa ser um segmento

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

Se o argumento allow_empty for definido como False, a função glob vai apresentar 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() faz a correspondência somente com arquivos na árvore de origem, nunca em arquivos gerados. Se você estiver criando um destino que requer 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 "sombra" o arquivo.

   Para entender isso, lembre-se de que 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. 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 avise sobre isso), o consumidor de glob() vai usar a regra "Foo.java" (as saídas) em vez do arquivo "Foo.java". Consulte o problema 10395 do GitHub (em inglês) para saber mais.

3. Os Globs podem corresponder a arquivos em subdiretórios. Além disso, os nomes de subdiretórios podem receber caracteres curinga. No entanto...

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

   Por exemplo, a expressão glob **/*.cc no pacote x não vai incluir 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 fosse marcada como excluída usando a flag --deleted_packages.

5. A restrição acima se aplica a todas as expressões glob, independentemente dos caracteres curinga que elas usam.
6. Um arquivo oculto com um nome que começa com . é totalmente correspondido pelos caracteres curinga ** e *. Se você quiser corresponder um arquivo oculto com um padrão composto, seu 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. 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".
7. O caractere curinga "**" tem um caso isolado: o padrão "**" não corresponde ao caminho do diretório do pacote. Ou seja, glob(["**"], exclude_directories = 0) faz a correspondência de todos os arquivos e diretórios de forma transitiva estritamente com o diretório do pacote atual (mas é claro que não vai para 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 "*" básico 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 emacs/vi/... salvos automaticamente.

Ao escrever regras de criaçã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 expandido abaixo.

Exemplos da Glob

Crie uma biblioteca Java criada com base em todos os arquivos Java nesse diretório e em 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. Os arquivos em subdiretórios de testdata não serão incluídos. Para incluir esses arquivos, use um glob recursivo (**).

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

Exemplos recursivo de Glob

Fazer o teste depender de todos os arquivos txt no diretório testdata e em qualquer um dos subdiretórios (e seus subdiretórios e assim por diante). Subdiretórios que contêm um arquivo BUILD são ignorados. Consulte as limitações e 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 um caminho que inclui um diretório chamado "testing". Evite esse padrão, se possível, porque pode reduzir a incrementabilidade 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 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 ele 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 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 o valor dependa das sinalizações de linha de comando do Bazel. É possível usar isso, por exemplo, para definir dependências específicas da plataforma ou incorporar recursos diferentes, dependendo se uma regra é criada no modo de "desenvolvedor" ou de "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 marcadores por uma chamada 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 um constraint_value, que "corresponde" se a configuração do destino corresponder a um conjunto de valores esperado. 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 os mesmos valores de sinalização e restrição que A, além de algumas 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 corresponderem e uma não for uma especialização de todas as outras, o Bazel falhará com um erro.
• O pseudorótulo especial //conditions:default é considerado correspondente se nenhuma outra condição corresponde. 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"], ...}) 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. Ela usa os mesmos padrões de caminho que glob() e pode corresponder a qualquer subpacote que seja um descendente direto do arquivo BUILD que está sendo 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á 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 que estão em 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, em vez de chamar essa função diretamente, os usuários usem o módulo "subpackages" de skylib.