Variáveis "Make"

As variáveis "Make" são uma classe especial de variáveis de string expansíveis disponíveis para atributos marcados como "Sujeito à substituição 'Fazer variável'".

Eles podem ser usados, por exemplo, para injetar caminhos específicos do conjunto de ferramentas em ações de compilação criadas pelo usuário.

O Bazel oferece variáveis predefinidas, que estão disponíveis para todos os destinos, e variáveis personalizadas, que são definidas nos destinos de dependência e disponíveis somente para os destinos que dependem delas.

O motivo do termo "Make" é histórico: a sintaxe e a semântica dessas variáveis originalmente pretendiam corresponder ao GNU Make.

Usar

Atributos marcados como "Sujeito à substituição de 'Fazer variável' podem fazer referência à variável "Make" FOO da seguinte maneira:

my_attr = "prefix $(FOO) suffix"

Em outras palavras, qualquer substring que corresponda a $(FOO) é expandida para o valor de FOO. Se esse valor for "bar", a string final se tornará:

my_attr = "prefix bar suffix"

Se FOO não corresponder a uma variável conhecida pelo destino de consumo, o Bazel falhará com um erro.

Variáveis "Make" com nomes que não são símbolos de letras, como @, também podem ser referenciadas usando apenas um cifrão, sem os parênteses. Exemplo:

my_attr = "prefix $@ suffix"

Para escrever $ como um literal de string (ou seja, para evitar a expansão de variáveis), escreva $$.

Variáveis predefinidas

Variáveis "Make" predefinidas podem ser referenciadas por qualquer atributo marcado como "Subject to 'Make variables' TV" em qualquer destino.

Para conferir a lista dessas variáveis e os valores delas para um determinado conjunto de opções de build, execute

bazel info --show_make_env [build options]

e veja as principais linhas de saída com letras maiúsculas.

Veja um exemplo de variáveis predefinidas.

Variáveis de opção do conjunto de ferramentas

  • COMPILATION_MODE: fastbuild, dbg ou opt. (mais detalhes, link em inglês).

Variáveis de caminho

  • BINDIR: a base da árvore binária gerada para a arquitetura de destino.

    Uma árvore diferente pode ser usada para programas executados durante o build na arquitetura do host para oferecer suporte à compilação cruzada.

    Se você quiser executar uma ferramenta dentro de um genrule, a maneira recomendada de acessar o caminho é $(execpath toolname), em que toolname precisa estar listado no atributo tools do genrule.

  • GENDIR: a base da árvore de código gerada para a arquitetura de destino.

Variáveis de arquitetura de máquina

  • TARGET_CPU: a CPU da arquitetura de destino, por exemplo, k8.

Variáveis de regra de geração predefinidas

Os itens a seguir estão disponíveis especialmente para o atributo cmd de genrule e são geralmente importantes para que esse atributo funcione.

Veja um exemplo de variáveis de geração de regras predefinidas.

  • OUTS: a lista outs do genrule. Se você tiver apenas um arquivo de saída, também poderá usar $@.
  • SRCS: a lista srcs do genrule (ou, mais precisamente, os nomes dos caminhos dos arquivos que correspondem aos rótulos na lista srcs). Se você tiver apenas um arquivo de origem, também poderá usar $<.
  • <: SRCS, se for um único arquivo. Caso contrário, um erro de build será acionado.
  • @: OUTS, se for um único arquivo. Caso contrário, um erro de build será acionado.

  • RULEDIR: o diretório de saída do destino, ou seja, o diretório correspondente ao nome do pacote que contém o destino na árvore genfiles ou bin. Para //my/pkg:my_genrule, isso sempre termina em my/pkg, mesmo que as saídas de //my/pkg:my_genrule estejam em subdiretórios.

  • @D: o diretório de saída. Se outs tiver uma entrada, ele se expandirá para o diretório que contém esse arquivo. Se tiver várias entradas, ele vai se expandir para o diretório raiz do pacote na árvore genfiles, mesmo que todos os arquivos de saída estejam no mesmo subdiretório.

    Observação:use RULEDIR em vez de @D, porque RULEDIR tem semântica mais simples e se comporta da mesma maneira, independente do número de arquivos de saída.

    Se a regra geral precisar gerar arquivos intermediários temporários (talvez como resultado do uso de outra ferramenta, como um compilador), ela precisará tentar gravá-los em @D (embora /tmp também seja gravável) e removê-los antes da conclusão.

    Evite gravar em diretórios que contêm entradas. Eles podem estar em sistemas de arquivos somente leitura. Mesmo se não fizer isso, a árvore de origem será descartada.

Variáveis predefinidas de caminho de origem/saída

As variáveis predefinidas execpath, execpaths, rootpath, rootpaths, location e locations usam os parâmetros de rótulo (por exemplo, $(execpath //foo:bar)) e substituem os caminhos de arquivo indicados por esse rótulo.

Para arquivos de origem, é o caminho relativo à raiz do espaço de trabalho. Para arquivos que são saídas de regras, esse é o caminho de saída do arquivo. Consulte a explicação dos arquivos de saída abaixo.

Veja um exemplo de variáveis de caminho predefinidas.

  • execpath: indica o caminho abaixo do execroot em que o Bazel executa ações de build.

    No exemplo acima, o Bazel executa todas as ações de build no diretório vinculado pelo link simbólico bazel-myproject na raiz do espaço de trabalho. O arquivo de origem empty.source está vinculado ao caminho bazel-myproject/testapp/empty.source. Portanto, o caminho de exec (que é o subcaminho abaixo da raiz) é testapp/empty.source. Essas são as ações de build de caminho que podem ser usadas para encontrar o arquivo.

    Os arquivos de saída são organizados de forma semelhante, mas também têm o prefixo do subcaminho bazel-out/cpu-compilation_mode/bin (ou para as saídas das ferramentas: bazel-out/cpu-opt-exec-hash/bin). No exemplo acima, //testapp:app é uma ferramenta porque aparece no atributo tools de show_app_output. O arquivo de saída app é gravado em bazel-myproject/bazel-out/cpu-opt-exec-hash/bin/testapp/app. Assim, o caminho "exec" é bazel-out/cpu-opt-exec-hash/bin/testapp/app. Esse prefixo extra permite criar o mesmo destino para, por exemplo, duas CPUs diferentes no mesmo build sem que os resultados atrapalhem uma à outra.

    O rótulo transmitido para essa variável precisa representar exatamente um arquivo. Para rótulos que representam arquivos de origem, isso é automaticamente verdadeiro. Para rótulos que representam regras, a regra precisa gerar exatamente uma saída. Se o valor for falso ou o rótulo estiver incorreto, o build falhará com um erro.

  • rootpath: indica o caminho que um binário criado pode usar para encontrar uma dependência no ambiente de execução relativa ao subdiretório do diretório runfiles correspondente ao repositório principal. Observação:isso só vai funcionar se --enable_runfiles estiver ativado, o que não é o caso no Windows por padrão. Use rlocationpath para oferecer suporte multiplataforma.

    Isso é semelhante a execpath, mas remove os prefixos de configuração descritos acima. No exemplo acima, isso significa que empty.source e app usam caminhos puros relativos ao espaço de trabalho: testapp/empty.source e testapp/app.

    O rootpath de um arquivo em um repositório externo repo vai começar com ../repo/, seguido pelo caminho relativo ao repositório.

    Tem os mesmos requisitos de "apenas uma saída" que execpath.

  • rlocationpath: o caminho que um binário criado pode transmitir para a função Rlocation de uma biblioteca runfiles para encontrar uma dependência no momento da execução, seja no diretório runfiles (se disponível) ou usando o manifesto dos arquivos de execução.

    Isso é semelhante a rootpath, porque não contém prefixos de configuração, mas é diferente porque sempre começa com o nome do repositório. No exemplo acima, isso significa que empty.source e app resultam nos seguintes caminhos: myproject/testapp/empty.source e myproject/testapp/app.

    O rlocationpath de um arquivo em um repositório externo repo vai começar com repo/, seguido pelo caminho relativo ao repositório.

    Transmitir esse caminho para um binário e resolvê-lo para um caminho de sistema de arquivos usando as bibliotecas runfiles é a abordagem recomendada para encontrar dependências no ambiente de execução. Comparada a rootpath, ela tem a vantagem de funcionar em todas as plataformas e mesmo quando o diretório runfiles não está disponível.

    Tem os mesmos requisitos de "apenas uma saída" que execpath.

  • location: um sinônimo para execpath ou rootpath, dependendo do atributo que está sendo expandido. Esse é um comportamento legado anterior ao Starlark e não é recomendado, a menos que você saiba o que ele faz em uma regra específica. Para mais detalhes, consulte #2475 (link em inglês).

execpaths, rootpaths, rlocationpaths e locations são as variações no plural de execpath, rootpath, rlocationpaths e location, respectivamente. Elas são compatíveis com rótulos que produzem várias saídas. Nesse caso, cada saída é listada separada por um espaço. Regras de saída zero e rótulos malformados produzem erros de build.

Todos os rótulos referenciados precisam aparecer no srcs, nos arquivos de saída ou no deps do destino de consumo. Caso contrário, o build falhará. Os destinos C++ também podem referenciar rótulos em data.

Os rótulos não precisam estar no formato canônico: foo, :foo e //somepkg:foo são aceitáveis.

Variáveis personalizadas

As variáveis "Make" personalizadas podem ser referenciadas por qualquer atributo marcado como Subject to 'Make variables' replace", mas somente em destinos que dependem de outros que definem essas variáveis.

Como prática recomendada, todas as variáveis precisam ser personalizadas, a menos que haja um bom motivo para incorporá-las ao Bazel principal. Isso evita que o Bazel precise carregar dependências potencialmente caras para fornecer variáveis que consomem tarifas.

Variáveis do conjunto de ferramentas C++

As opções a seguir são definidas nas regras do conjunto de ferramentas C++ e estão disponíveis para qualquer regra que defina toolchains = ["@bazel_tools//tools/cpp:current_cc_toolchain"] (ou "@bazel_tools//tools/cpp:current_cc_host_toolchain" para o equivalente do conjunto de ferramentas do host). Algumas regras, como java_binary, incluem implicitamente o conjunto de ferramentas C++ na definição da regra. Elas herdam essas variáveis automaticamente.

As regras C++ integradas são muito mais sofisticadas do que "executar o compilador nele". Para oferecer suporte a modos de compilação tão diversos quanto *SAN, ThinLTO, com/sem módulos e binários cuidadosamente otimizados, bem como testes de execução rápida em várias plataformas, as regras integradas precisam de grandes distâncias para garantir que as entradas, saídas e flags de linha de comando corretas sejam definidas em cada uma possível várias ações geradas internamente.

Essas variáveis são um mecanismo substituto a ser usado por especialistas em linguagem em casos raros. Se você quiser usá-los, primeiro entre em contato com os desenvolvedores do Bazel.

  • ABI: a versão da ABI C++.
  • AR: o comando "ar" do crosstool.
  • C_COMPILER: o identificador do compilador C/C++, por exemplo, llvm.

  • CC: o comando do compilador C e C++.

    É altamente recomendável usar sempre CC_FLAGS em combinação com CC. Se você não fizer isso, por sua conta e risco.

  • CC_FLAGS: um conjunto mínimo de sinalizações para que o compilador C/C++ possa ser usado por regras gerais. Em particular, ele contém sinalizações para selecionar a arquitetura correta se CC for compatível com várias arquiteturas.
  • NM: o comando "nm" do crosstool.
  • OBJCOPY: o comando objcopy do mesmo pacote que o compilador C/C++.
  • STRIP: o comando de remoção do mesmo pacote que o compilador C/C++.

Variáveis do conjunto de ferramentas Java

Os itens a seguir são definidos nas regras do conjunto de ferramentas Java e estão disponíveis para qualquer regra que defina toolchains = ["@bazel_tools//tools/jdk:current_java_runtime"] (ou "@bazel_tools//tools/jdk:current_host_java_runtime" para o equivalente do conjunto de ferramentas do host).

A maioria das ferramentas no JDK não deve ser usada diretamente. As regras Java integradas usam abordagens muito mais sofisticadas de compilação e empacotamento Java do que ferramentas upstream podem expressar, como JARs de interface, JARs de interface de cabeçalho e implementações de empacotamento e mesclagem Jar altamente otimizadas.

Essas variáveis são um mecanismo substituto a ser usado por especialistas em linguagem em casos raros. Se você quiser usá-los, primeiro entre em contato com os desenvolvedores do Bazel.

  • JAVA: o comando "java" (uma máquina virtual Java). Evite isso e use uma regra java_binary sempre que possível. Pode ser um caminho relativo. Se precisar mudar de diretórios antes de invocar java, capture o diretório de trabalho antes de fazer a mudança.
  • JAVABASE: o diretório base que contém os utilitários do Java. Pode ser um caminho relativo. Ele terá um subdiretório "bin".

Variáveis definidas pelo Starlark

Os gravadores de regras e do conjunto de ferramentas podem definir variáveis totalmente personalizadas retornando um provedor TemplateVariableInfo. Qualquer regra que dependa delas por meio do atributo toolchains pode ler os valores delas:

Veja um exemplo de variáveis definidas pelo Starlark.