Ação
Um comando a ser executado durante o build, por exemplo, uma chamada para um compilador que usa artefatos como entradas e produz outros artefatos como saídas. Inclui metadados como argumentos de linha de comando, chave de ação, variáveis de ambiente e artefatos de entrada/saída declarados.
Consulte também:documentação das regras
Cache de ações
Um cache no disco que armazena um mapeamento de ações executadas para as saídas criadas. A chave de cache é conhecida como chave de ação. Um componente principal do modelo de incrementalidade do Bazel. O cache é armazenado no diretório base de saída e, portanto, sobrevive às reinicializações do servidor do Bazel.
Gráfico de ações
Um gráfico na memória de ações e os artefatos que
essas ações leem e geram. O gráfico pode incluir artefatos que existem como arquivos de origem (por exemplo, no sistema de arquivos), bem como artefatos intermediários/finais gerados que não são mencionados nos arquivos BUILD. Produzido
durante a fase de análise e usado durante a fase de
execução.
Consulta do gráfico de ações (aquery)
Uma ferramenta de consulta que pode consultar ações de build. Isso permite analisar como as regras de build se traduzem no trabalho real que os builds fazem.
Tecla de ação
A chave de cache de uma ação. Calculado com base nos metadados da ação, que podem incluir o comando a ser executado na ação, flags do compilador, locais da biblioteca ou cabeçalhos do sistema, dependendo da ação. Permite que o Bazel armazene em cache ou invalide ações individuais de forma determinística.
Fase de análise
A segunda fase de um build. Processa o gráfico de destino especificado nos arquivos BUILD para produzir um gráfico de ações na memória que determina a ordem das ações a serem executadas durante a fase de execução. Essa é a fase em que as implementações de regras são avaliadas.
Artefato
Um arquivo de origem ou um arquivo gerado. Também pode ser um diretório de arquivos, conhecido como artefatos de árvore.
Um artefato pode ser uma entrada para várias ações, mas só pode ser gerado por no máximo uma ação.
Um artefato que corresponde a um destino de arquivo pode ser abordado por um rótulo.
Aspecto
Um mecanismo para regras criarem ações adicionais nas dependências delas. Por exemplo, se o destino A depender de B, será possível aplicar um aspecto em A que percorre para cima uma aresta de dependência até B e executa ações adicionais em B para gerar e coletar mais arquivos de saída. Essas ações adicionais são armazenadas em cache e reutilizadas entre destinos que exigem o mesmo aspecto. Criado com a função
aspect() da API Starlark Build. Pode ser usado, por exemplo, para gerar
metadados para IDEs e criar ações de linting.
Consulte também:documentação sobre aspectos
Aspecto sobre aspecto
Um mecanismo de composição em que os aspectos podem ser aplicados aos resultados de outros aspectos. Por exemplo, um aspecto que gera informações para uso por
IDEs pode ser aplicado sobre um aspecto que gera arquivos .java de um
proto.
Para que um aspecto A seja aplicado sobre o aspecto B, os provedores que
B anuncia no atributo provides
precisam corresponder ao que A declara querer no atributo required_aspect_providers.
Atributo
Um parâmetro para uma regra, usado para expressar informações de build por destino.
Exemplos incluem srcs, deps e copts, que declaram, respectivamente, os arquivos de origem, as dependências e as opções personalizadas do compilador de um
destino. Os atributos específicos disponíveis para um determinado destino dependem do tipo de regra.
.bazelrc
O arquivo de configuração do Bazel é usado para mudar os valores padrão das flags de inicialização e flags de comando, além de definir grupos comuns de opções que podem ser definidas juntas na linha de comando do Bazel usando uma flag --config. O Bazel pode combinar configurações de vários arquivos bazelrc (em todo o sistema, por espaço de trabalho, por usuário ou de um local personalizado), e um arquivo bazelrc também pode importar configurações de outros arquivos bazelrc.
Blaze
A versão interna do Google do Bazel. O principal sistema de build do Google para o monorepositório.
Arquivo BUILD
Um arquivo BUILD é o principal arquivo de configuração que informa ao Bazel quais saídas de software criar, quais são as dependências e como criá-las. O Bazel usa um arquivo BUILD como entrada e o usa para criar um gráfico de dependências e derivar as ações que precisam ser concluídas para criar saídas de software intermediárias e finais. Um arquivo BUILD marca um diretório e todos os subdiretórios que não contêm um arquivo BUILD como um pacote e pode conter destinos criados por regras. O arquivo também pode ser chamado de
BUILD.bazel.
Arquivo BUILD.bazel
Consulte Arquivo BUILD. Tem precedência sobre um arquivo BUILD no mesmo diretório.
Arquivo .bzl
Um arquivo que define regras, macros e constantes escritas em
Starlark. Em seguida, eles podem ser importados para arquivos
BUILD usando a função load().
Criar gráfico
O gráfico de dependência que o Bazel cria e percorre para realizar um build. Inclui nós como destinos, destinos configurados, ações e artefatos. Um build é considerado concluído quando todos os artefatos de que um conjunto de destinos solicitados depende são verificados como atualizados.
Configuração de build
Uma parte da configuração definida pelo Starlark. As transições podem definir configurações de build para mudar a configuração de um subgrafo. Se exposto ao usuário como uma flag de linha de comando, também conhecida como flag de build.
Build limpo
Um build que não usa os resultados de builds anteriores. Geralmente, esse processo é mais lento do que um build incremental, mas é considerado mais correto. O Bazel garante que builds limpos e incrementais estejam sempre corretos.
Modelo cliente-servidor
O cliente de linha de comando bazel inicia automaticamente um servidor em segundo plano na
máquina local para executar comandos do Bazel. O servidor persiste em todos os
comandos, mas para automaticamente após um período de inatividade (ou explicitamente via
bazel shutdown). Dividir o Bazel em um servidor e um cliente ajuda a amortizar o tempo de inicialização da JVM e oferece suporte a builds incrementais mais rápidos, porque o gráfico de ações permanece na memória em todos os comandos.
Comando
Usado na linha de comando para invocar diferentes funções do Bazel, como bazel
build, bazel test, bazel run e bazel query.
Sinalizações de comando
Um conjunto de flags específicas para um comando. As flags de comando são especificadas depois do comando (bazel build <command flags>) e podem ser aplicáveis a um ou mais comandos. Por exemplo, --configure é uma flag exclusiva do comando
bazel sync, mas --keep_going é aplicável a sync, build,
test e muito mais. As flags são usadas com frequência para fins de configuração. Por isso, mudanças nos valores das flags podem fazer com que o Bazel invalide os gráficos na memória e reinicie a fase de análise.
Configuração
Informações fora das definições de regra que afetam a forma como as regras geram ações. Cada build tem pelo menos uma configuração que especifica a plataforma de destino, as variáveis de ambiente de ação e as flags de build da linha de comando. As transições podem criar configurações adicionais, como para ferramentas de host ou compilação cruzada.
Consulte também:Configurações
Remoção de configurações
O processo de incluir apenas as partes da configuração que
um destino realmente precisa. Por exemplo, se você criar o binário Java //:j com a dependência C++
//:c, será um desperdício incluir o valor de --javacopt na
configuração de //:c, porque mudar --javacopt desnecessariamente interrompe a capacidade de cache de
build do C++.
Consulta configurada (cquery)
Uma ferramenta de consulta que consulta destinos
configurados (depois que a fase de análise
é concluída). Isso significa que select() e flags de build (como
--platforms) são refletidos com precisão nos resultados.
Consulte também:documentação do cquery
Valor desejado configurado
O resultado da avaliação de uma meta com uma configuração. A fase de análise faz isso combinando as opções de build com os destinos que precisam ser criados.
Por exemplo, se //:foo criar para duas arquiteturas diferentes no mesmo
build, ele terá dois destinos configurados: <//:foo, x86> e <//:foo, arm>.
Correção
Um build é correto quando a saída reflete fielmente o estado das entradas transitivas. Para conseguir builds corretos, o Bazel se esforça para ser hermético, reproduzível e para tornar a análise de build e a execução de ações deterministas.
Dependência
Uma aresta direcionada entre dois destinos. Um //:foo de destino tem uma dependência de destino em //:bar se os valores de atributo de //:foo contiverem uma referência a //:bar. //:foo tem uma dependência de ação em //:bar se uma
ação em //:foo depender de um artefato de entrada criado por uma
ação em //:bar.
Depset
Uma estrutura de dados para coletar dados sobre dependências transitivas. Otimizado para que a fusão de depsets seja eficiente em termos de tempo e espaço, porque é comum ter depsets muito grandes (centenas de milhares de arquivos). Implementado para se referir recursivamente a outros depsets por motivos de eficiência de espaço. As implementações de regras não devem "achatar" os depsets convertendo-os em listas, a menos que a regra esteja no nível superior do gráfico de build. Achatamento de depsets grandes causa um consumo enorme de memória. Também conhecidos como conjuntos aninhados na implementação interna do Bazel.
Consulte também:documentação de depset
Cache de disco
Um armazenamento de blob local no disco para o recurso de cache remoto. Pode ser usado em conjunto com um repositório de blobs remotos real.
Distdir
Um diretório somente leitura que contém arquivos que o Bazel buscaria na Internet usando regras de repositório. Permite que os builds sejam executados totalmente off-line.
Execução dinâmica
Uma estratégia de execução que seleciona entre a execução local e remota com base em várias heurísticas e usa os resultados da execução do método mais rápido. Algumas ações são executadas mais rapidamente localmente (por exemplo, vinculação), e outras são mais rápidas remotamente (por exemplo, compilação altamente paralelizável). Uma estratégia de execução dinâmica pode oferecer os melhores tempos de build incremental e limpo possíveis.
Fase de execução
A terceira fase de um build. Executa as ações no gráfico de ações criado durante a fase de análise. Essas ações invocam executáveis (compiladores, scripts) para ler e gravar artefatos. As estratégias de geração controlam como essas ações são executadas: localmente, remotamente, dinamicamente, em sandbox, em Docker etc.
Raiz de execução
Um diretório no diretório base de saída do espaço de trabalho em que as ações locais são executadas em builds não em sandbox. O conteúdo do diretório é principalmente de symlinks
de artefatos de entrada do espaço de trabalho. A raiz de execução também
contém links simbólicos para repositórios externos como outras entradas e o diretório bazel-out
para armazenar saídas. Preparado durante a fase de carregamento
ao criar uma floresta de links simbólicos dos diretórios que representam o fechamento
transitivo de pacotes de que um build depende. Acessível com bazel info
execution_root na linha de comando.
Arquivo
Consulte Artifact.
Hermeticidade
Uma build é hermética se não houver influências externas nas operações de build e teste, o que ajuda a garantir que os resultados sejam deterministas e corretos. Por exemplo, builds herméticos geralmente não permitem acesso à rede para ações, restringem o acesso a entradas declaradas, usam carimbos de data/hora e fusos horários fixos, restringem o acesso a variáveis de ambiente e usam seeds fixas para geradores de números aleatórios.
Build incremental
Um build incremental reutiliza os resultados de builds anteriores para reduzir o tempo de build e o uso de recursos. A verificação e o armazenamento em cache de dependências têm como objetivo produzir resultados corretos para esse tipo de build. Um build incremental é o oposto de um build limpo.
Rótulo
Um identificador de um destino. Um rótulo totalmente qualificado, como
//path/to/package:target, consiste em // para marcar o diretório raiz do espaço de trabalho,
path/to/package como o diretório que contém o arquivoBUILD que declara o destino e :target como o nome do destino
declarado no arquivo BUILD mencionado acima. Também pode ter o prefixo @my_repository//<..> para indicar que o destino foi declarado em um repositório externo chamado my_repository.
Fase de carregamento
A primeira fase de um build em que o Bazel analisa arquivos WORKSPACE, BUILD e .bzl para criar pacotes. As macros e algumas funções, como glob(), são avaliadas nessa fase. Intercalada com a segunda fase do build, a fase de análise, para criar um gráfico de destino.
Macro
Um mecanismo para compor várias declarações de destino de regra em uma única função Starlark. Permite reutilizar padrões comuns de declaração de regra em arquivos BUILD. Expandida para as declarações de destino da regra subjacente durante a fase de carregamento.
Consulte também:documentação de macros
Mnemônico
Uma string curta e legível selecionada por um autor de regra para entender rapidamente
o que uma ação na regra está fazendo. Os mnemônicos podem ser usados como
identificadores para seleções de estratégia de geração. Alguns exemplos de mnemônicos de ação são Javac de regras Java, CppCompile de regras C++ e AndroidManifestMerger de regras Android.
Regras nativas
Regras integradas ao Bazel e implementadas em Java. Essas regras
aparecem em arquivos .bzl como funções no módulo nativo (por
exemplo, native.cc_library ou native.java_library). As regras definidas pelo usuário
(não nativas) são criadas usando Starlark.
Base de saída
Um diretório específico do espaço de trabalho para armazenar arquivos de saída do Bazel. Usado para separar as saídas da árvore de origem do espaço de trabalho. Localizado na saída raiz do usuário.
Grupos de saída
Um grupo de arquivos que devem ser criados quando o Bazel terminar de criar um destino. As regras colocam as saídas normais no "grupo de saída padrão" (por exemplo, o arquivo .jar de um java_library, .a e .so para destinos cc_library). O grupo de saída padrão é aquele cujos artefatos são criados quando um destino é solicitado na linha de comando.
As regras podem definir mais grupos de saída nomeados que podem ser especificados explicitamente em
arquivos BUILD (regra filegroup) ou na linha de comando
(flag --output_groups).
Gerar raiz do usuário
Um diretório específico do usuário para armazenar as saídas do Bazel. O nome do diretório é derivado do nome de usuário do sistema. Evita colisões de arquivos de saída se vários usuários estiverem criando o mesmo projeto no sistema ao mesmo tempo. Contém subdiretórios correspondentes às saídas de build de workspaces individuais, também conhecidos como bases de saída.
Pacote
O conjunto de destinos definidos por um arquivo BUILD. O nome de um
pacote é o caminho do arquivo BUILD relativo à raiz do espaço de trabalho. Um pacote pode conter subpacotes ou subdiretórios com arquivos BUILD, formando uma hierarquia de pacotes.
Grupo de pacotes
Uma meta que representa um conjunto de pacotes. Geralmente usado em valores de atributo visibility.
Plataforma
Um "tipo de máquina" envolvido em um build. Isso inclui a máquina em que o Bazel é executado (a plataforma "host"), as máquinas em que as ferramentas de build são executadas (plataformas "exec") e as máquinas para as quais os destinos são criados (plataformas "de destino").
Provedor
Um esquema que descreve uma unidade de informação a ser transmitida entre destinos de regras ao longo de relações de dependência. Normalmente, ele contém informações como opções do compilador, arquivos de origem ou de saída transitivos e metadados de build. Usado com frequência em conjunto com depsets para armazenar dados transitivos acumulados de maneira eficiente. Um exemplo de provedor integrado é DefaultInfo.
Consulte também:documentação do provedor
Consulta (conceito)
O processo de analisar um gráfico de build para entender as propriedades de destino e as estruturas de dependência. O Bazel é compatível com três variantes de consulta: query, cquery e aquery.
consulta (comando)
Uma ferramenta de consulta que opera no gráfico de destino da fase
de carregamento pós-compilação. Isso é relativamente rápido, mas não pode analisar os efeitos de select(), flags de build, artefatos ou ações de build.
Consulte também:guia de consultas, referência de consultas
Cache do repositório
Um cache de conteúdo endereçável compartilhado de arquivos baixados pelo Bazel para builds,
compartilhável em espaços de trabalho. Permite builds off-line após o
download inicial. Usado geralmente para armazenar em cache arquivos baixados por regras de repositório, como http_archive, e APIs de regras de repositório, como repository_ctx.download. Os arquivos só são armazenados em cache se as somas de verificação SHA-256 forem especificadas para o download.
Reprodutibilidade
A propriedade de um build ou teste em que um conjunto de entradas sempre produzirá o mesmo conjunto de saídas, independentemente do tempo, do método ou do ambiente. Isso não significa necessariamente que as saídas estão corretas ou são as desejadas.
Regra
Um esquema para definir destinos de regra em um arquivo BUILD, como
cc_library. Da perspectiva de um autor de arquivo BUILD, uma regra consiste em
um conjunto de atributos e lógica de caixa preta. A lógica informa ao
destino da regra como produzir artefatos de saída e transmitir informações para
outros destinos de regra. Do ponto de vista dos autores de .bzl, as regras são a principal maneira de estender o Bazel para oferecer suporte a novas linguagens de programação e ambientes.
As regras são instanciadas para produzir destinos de regra na fase de carregamento. Na fase de análise, as regras de destino comunicam informações às dependências downstream na forma de provedores e registram ações que descrevem como gerar os artefatos de saída. Essas ações são executadas na fase de execução.
Consulte também:documentação das regras
Destino da regra
Um destino que é uma instância de uma regra. Contraste com destinos de arquivo e grupos de pacotes. Não confunda com regra.
Runfiles
As dependências de tempo de execução de um destino executável. Normalmente, o executável é a saída executável de uma regra de teste, e os runfiles são dependências de dados de tempo de execução do teste. Antes da invocação do executável (durante bazel test), o Bazel prepara a árvore de runfiles junto com o executável de teste de acordo com a estrutura do diretório de origem.
Consulte também:documentação de runfiles
Sandbox
Uma técnica para isolar uma ação em execução dentro de uma raiz de execução restrita e temporária, ajudando a garantir que ela não leia entradas não declaradas nem grave saídas não declaradas. O isolamento em sandbox melhora muito a hermeticidade, mas geralmente tem um custo de desempenho e exige suporte do sistema operacional. O custo de desempenho depende da plataforma. No Linux, isso não é significativo, mas no macOS pode tornar o sandboxing inutilizável.
Skyframe
O Skyframe é a estrutura principal de avaliação paralela, funcional e incremental do Bazel.
Estampagem
Um recurso para incorporar mais informações em artefatos criados com o Bazel. Por exemplo, isso pode ser usado para controle de origem, tempo de
build e outras informações relacionadas ao ambiente ou ao espaço de trabalho para builds de lançamento.
Ative usando a flag --workspace_status_command e as regras que
aceitam o atributo de carimbo.
Starlark
A linguagem de extensão para escrever regras e macros. Um subconjunto restrito de Python (sintaticamente e gramaticalmente) destinado à configuração e para melhorar o desempenho. Usa a extensão de .bzl
arquivo. Os arquivos BUILD usam uma versão ainda mais
restrita do Starlark (como nenhuma definição de função def), antes
conhecida como Skylark.
Consulte também:documentação da linguagem Starlark
Flags de inicialização
O conjunto de flags especificado entre bazel e o comando,
por exemplo, bazel --host_jvm_debug build. Essas flags modificam a configuração do servidor do Bazel. Portanto, qualquer modificação nas flags de inicialização causa uma reinicialização do servidor. As flags de inicialização não são específicas de nenhum comando.
Destino
Um objeto definido em um arquivo BUILD e identificado por um rótulo. Os destinos representam as unidades criáveis de um espaço de trabalho na perspectiva do usuário final.
Um destino declarado pela instanciação de uma regra é chamado de destino
de regra. Dependendo da regra, eles podem ser executáveis (como cc_binary) ou testáveis (como cc_test). Os destinos de regra geralmente dependem de outros destinos pelos atributos (como deps). Essas dependências formam a base do gráfico de destino.
Além das metas de regra, também há metas de arquivo e de grupo de pacotes. Os destinos de arquivo correspondem a artefatos referenciados
em um arquivo BUILD. Como um caso especial, o arquivo BUILD de qualquer pacote é sempre considerado um destino de arquivo de origem nesse pacote.
Os destinos são descobertos durante a fase de carregamento. Durante a fase de análise, os destinos são associados a configurações de build para formar destinos configurados.
Gráfico de destino
Um gráfico na memória de destinos e as dependências deles. Produzido durante a fase de carregamento e usado como entrada para a fase de análise.
Padrão desejado
Uma maneira de especificar um grupo de destinos na linha de comando. Os padrões usados com frequência são :all (todos os destinos de regra), :* (todos os destinos de regra e arquivo) e ... (o pacote atual e todos os subpacotes de forma recursiva). Pode ser usado em combinação. Por exemplo, //...:* significa todas as regras e destinos de arquivo em todos os pacotes de forma recursiva da raiz do workspace.
Testes
A regra segmenta instanciada de regras de teste e, portanto, contém um executável de teste. Um código de retorno zero da conclusão do executável indica que o teste foi bem-sucedido. O contrato exato entre o Bazel e os testes (como variáveis de ambiente de teste, métodos de coleta de resultados de teste) é especificado na Enciclopédia de testes.
Conjunto de ferramentas
Um conjunto de ferramentas para criar saídas para um idioma. Normalmente, um conjunto de ferramentas inclui compiladores, linkers, intérpretes e/ou linters. Uma cadeia de ferramentas também pode variar de acordo com a plataforma. Por exemplo, os componentes de uma cadeia de ferramentas de compilador Unix podem ser diferentes para a variante do Windows, mesmo que a cadeia de ferramentas seja para o mesmo idioma. Selecionar a cadeia de ferramentas certa para a plataforma é conhecido como resolução de cadeia de ferramentas.
Objetivo de nível superior
Um destino de build é de nível superior se for solicitado na linha de comando do Bazel. Por exemplo, se //:foo depender de //:bar e bazel build //:foo for
chamado, para esse build, //:foo será de nível superior, e //:bar não será
de nível superior, embora ambos os destinos precisem ser criados. Uma diferença importante entre destinos de nível superior e não superior é que as flags de comando definidas na linha de comando do Bazel (ou via .bazelrc) definem a configuração para destinos de nível superior, mas podem ser modificadas por uma transição para destinos de nível não superior.
Transição
Um mapeamento do estado da configuração de um valor para outro. Permite que targets no gráfico de build tenham configurações diferentes, mesmo que tenham sido instanciados da mesma regra. Um uso comum de transições é com transições divididas, em que certas partes do gráfico de destino são ramificadas com configurações distintas para cada ramificação. Por exemplo, é possível criar um APK do Android com binários nativos compilados para ARM e x86 usando transições divididas em uma única build.
Consulte também:Transições definidas pelo usuário
Artefato de árvore
Um artefato que representa uma coleção de arquivos. Como esses arquivos não são artefatos, uma ação que opera neles precisa registrar o artefato de árvore como entrada ou saída.
Visibilidade
Um dos dois mecanismos para evitar dependências indesejadas no sistema de build:
visibilidade de destino para controlar se um destino pode depender
de outros destinos; e visibilidade de carregamento para controlar se um arquivo BUILD
ou .bzl pode carregar um determinado arquivo .bzl. Sem contexto, geralmente "visibilidade" se refere à visibilidade do destino.
Consulte também:documentação sobre visibilidade
Espaço de trabalho
Um diretório que contém um arquivo WORKSPACE e o código-fonte do software que você
quer criar. Os rótulos que começam com // são relativos ao diretório do espaço de trabalho.
Arquivo WORKSPACE
Define um diretório como um espaço de trabalho. O arquivo pode estar vazio, mas geralmente contém declarações de repositório externo para buscar dependências adicionais da rede ou do sistema de arquivos local.