Ação
Um comando para ser executado durante a criação, por exemplo, uma chamada para um compilador que usa artefatos como entradas e produz outros artefatos como saídas. Inclui metadados como os argumentos de linha de comando, a chave de ação, as variáveis de ambiente e os artefatos de entrada/saída declarados.
Confira também: documentação sobre regras
Cache de ação
Um cache no disco que armazena um mapeamento de ações executadas para as saídas criadas por eles. Essa chave é conhecida como chave de ação. Um componente principal para o modelo de incrementabilidade 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 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/final gerados que não são mencionados em arquivos BUILD
. Criada
durante a fase de análise e usada durante a fase
de execução.
Consulta do gráfico de ação (aquery)
Uma ferramenta de consulta que pode consultar ações de criação. Isso permite analisar como as regras de build se traduzem no trabalho real dos builds.
Tecla de ação
A chave de cache de uma ação. São computados com base em metadados de ação, que podem incluir o comando a ser executado, sinalizações 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 maneira determinista.
Fase de análise
A segunda fase de uma criação. 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 uma ação.
Um artefato correspondente a um destino de arquivo pode ser resolvido por um rótulo.
Aspecto
Um mecanismo para que as regras criem ações adicionais nas próprias dependências. Por exemplo, se o destino A depende de B, é possível aplicar um aspecto em
A que passa para cima de uma borda de dependência até B e executa outras ações em B
para gerar e coletar outros arquivos de saída. Essas outras ações são
armazenadas em cache e reutilizadas entre destinos que exigem o mesmo aspecto. Criada com a
função aspect()
da API Starlark Build. Pode ser usada, por exemplo, para gerar
metadados para ambientes de desenvolvimento integrado e criar ações para inspeção.
Consulte também: Documentação sobre aspectos
Aspecto sobre aspecto
Mecanismo de composição em que 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
com base em um
proto.
Para que um A
seja aplicado sobre o aspecto B
, os provedores que
B
anuncia no atributo provides
precisam corresponder ao que o A
declara que quer no
atributo required_aspect_providers
.
Atributo
Um parâmetro para uma regra, usado para expressar informações de compilação por destino.
Exemplos incluem srcs
, deps
e copts
, que, respectivamente, declaram os
arquivos de origem, as dependências e as opções de compilador personalizadas 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 alterar os valores padrão das sinalizações de inicialização e das sinalizações de comando e para definir grupos comuns de opções que podem ser configurados juntos na linha de comando do Bazel usando uma sinalização --config
. O Bazel pode combinar configurações de vários arquivos bazelrc
(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 compilação do Google para seu monorepositório.
Arquivo BUILD
BUILD
é o principal arquivo de configuração que informa ao Bazel quais saídas
de software criar, quais são as dependências delas e como criá-las. Ele
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 qualquer subdiretório que
não contenha um arquivo BUILD
como um pacote e pode conter
destinos criados por regras. O arquivo também pode ser nomeado como
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. Eles podem ser importados para arquivos BUILD
usando a função load()
.
Criar gráfico
O gráfico de dependência que o Bazel constrói e percorre para executar uma compilação. 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 do build
Uma parte da configuração definida pelo Starlark. Transições podem definir configurações de build para mudar a configuração de um subgráfico. Se exposto ao usuário como uma sinalização de linha de comando, também conhecida como sinalização de build.
Criação limpa
Um build que não usa os resultados de builds anteriores. Isso geralmente é mais lento que um build incremental, mas normalmente é considerado mais correto. Ele garante que os 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 entre os comandos, mas é interrompido automaticamente após um período de inatividade (ou explicitamente via desligamento do Bazel). 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 entre 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 sinalizações específicas de um comando. As sinalizações de comando são especificadas após o comando (bazel build <command flags>
). Elas podem ser aplicáveis a um ou mais comandos. Por exemplo, --configure
é uma sinalização exclusivamente para o
comando bazel sync
, mas --keep_going
é aplicável a sync
, build
,
test
e outros. As flags geralmente são usadas para fins de configuração.
Portanto, mudanças nos valores delas podem fazer com que o Bazel invalide gráficos na
memória e reinicie a fase de análise.
Configuração
Informações fora das definições de regra que afetam 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 sinalizações de build de linha de comando. As transições podem criar outras configurações, como para ferramentas de host ou compilação cruzada.
Consulte também: Configurações
Corte de configuração
Processo de incluir apenas as partes de configuração que um destino realmente precisa. Por exemplo, se você criar o //:j
binário Java com a dependência
C++ //:c
, não vai ser útil incluir o valor de --javacopt
na
configuração de //:c
, já que a mudança de --javacopt
interrompe desnecessariamente a capacidade de armazenamento
em cache do build do C++.
Consulta configurada (cquery)
uma ferramenta de consulta que consulta destinos configurados (após a conclusão da fase de análise). Isso significa que select()
e flags de build (como
--platforms
) são refletidas com precisão nos resultados.
Consulte também: documentação sobre subconsulta
Destino configurado
O resultado da avaliação de um destino com uma configuração. A fase de análise produz
isso combinando as opções da versão 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 está correto quando a saída reflete fielmente o estado das entradas transitivas. Para conseguir os builds corretos, o Bazel se esforça para ser hermético, reproduzível e fazer a análise de build e a execução de ações deterministas.
Dependência
Uma borda direcionada entre dois destinos. Um //:foo
de destino tem uma dependência
de destino no //:bar
de destino se os valores do atributo de //:foo
contêm 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
.
Desativado
Uma estrutura de dados para coletar dados sobre dependências transitivas. Otimizada para que a mesclagem de dependências seja eficiente em termos de tempo e espaço, porque é comum ter depsets muito grandes (centenas de milhares de arquivos). Implementado para se referir de forma recursiva a outros depsets por motivos de eficiência de espaço. As implementações de Rule não podem "nivelar" os conjuntos de dados ao convertê-los em listas, a menos que a regra esteja no nível superior do gráfico de criação. Nivelar grandes conjuntos de dados incorre em um grande consumo de memória. Também conhecidos como conjuntos aninhados na implementação interna do Bazel.
Consulte também: Documentação do Depset
Cache de disco
Um repositório de blobs no disco para o recurso de armazenamento em cache remoto. Pode ser usado em conjunto com um repositório de blob remoto real.
Distdir
Um diretório somente leitura contendo 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 que seleciona entre a execução local e remota com base em várias heurísticas e usa os resultados do método bem-sucedido mais rápido. Certas 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 carregável em paralelo). Uma estratégia de execução dinâmica pode fornecer os melhores tempos de compilação incrementais e limpos 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, de forma dinâmica, no sandbox, no Docker e assim por diante.
Raiz de execução
Um diretório no diretório da base de saída do workspace em que as ações locais são executadas em builds que não estão no sandbox. O conteúdo do diretório são principalmente links simbólicos
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
criando uma floresta de links simbólicos dos diretórios que representam o fechamento
transitivo de pacotes dos quais um build depende. Acessível com bazel info
execution_root
na linha de comando.
Arquivo
Consulte Artefato.
Hermética
Um build é hermético quando não há influências externas nas operações de build e teste, o que ajuda a garantir que os resultados sejam determinísticos e corretos. Por exemplo, as versões herméticas normalmente proíbem o acesso à rede a ações, restringem o acesso às entradas declaradas, usam carimbos de data/hora e fusos horários fixos, restringem o acesso a variáveis de ambiente e usam sementes 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 de dependências e o armazenamento em cache têm como objetivo produzir resultados corretos para esse tipo de build. Um build incremental é o oposto de um build limpo.
Rótulo
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 arquivo
BUILD
declarando o destino e :target
como o nome do destino
declarado no arquivo BUILD
mencionado acima. Também pode ser prefixado com
@my_repository//<..>
para indicar que o destino é declarado em um ]repositório
externo] chamado my_repository
.
Carregando fase
A primeira fase de um build em que o Bazel analisa os arquivos WORKSPACE
, BUILD
e .bzl
para criar pacotes (links em inglês). Macros e determinadas
funções, como glob()
, são avaliadas nessa fase. Intercalado 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 regras juntas em
uma única função Starlark. Permite a reutilização de padrões de declaração
de regras comuns em arquivos BUILD
. Expansão para as declarações de segmentação de regra subjacentes
durante a fase de carregamento.
Consulte também: documentação de macros
Mnemônico
Uma string curta e legível selecionada por um autor da regra para entender rapidamente
o que uma action na regra está fazendo. As mneumônicas podem ser usadas como
identificadores para seleções de estratégias de geração. Alguns exemplos de mnemônicas de ação
são Javac
das regras Java, CppCompile
das regras C++ e
AndroidManifestMerger
das regras do 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
). Regras definidas pelo usuário
(não nativas) são criadas usando o Starlark.
Base de saída
Um diretório específico do workspace para armazenar arquivos de saída do Bazel. Usado para separar saídas da árvore de origem do workspace. Localizados na raiz do usuário de saída.
Grupos de saída
Um grupo de arquivos que precisa ser criado quando o Bazel terminar a criação de um
destino. As regras colocam as saídas habituais no "grupo de saída padrão" (por exemplo, o arquivo .jar
de java_library
, .a
e .so
para destinos cc_library
). O grupo de saída padrão é aquele em que os
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
(sinalização --output_groups
).
Raiz do usuário de saída
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 no sistema do usuário. 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 que correspondem a saídas de compilação de espaços de trabalho individuais, também conhecidos como bases de saída.
Pacote
O conjunto de destinos definido 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 que contêm arquivos BUILD
,
formando uma hierarquia de pacotes.
Grupo de pacotes
Um destino 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 que o Bazel é executado (a plataforma "host"), as ferramentas de build de máquinas executadas em ("plataformas" "exec") e os destinos de máquina são criados para ("plataformas de destino").
Provedor
Um esquema que descreve uma unidade de informações a ser transmitida entre destinos de regra ao longo de relações de dependência. Normalmente, ele
contém informações como opções do compilador, arquivos de origem ou saída transitivos e
metadados de build. Usado frequentemente em conjunto com depsets para armazenar com eficiência dados transitivos acumulados. Um exemplo de provedor integrado
é o DefaultInfo
.
Consulte também: Documentação do provedor
Consulta (conceito)
O processo de análise de um gráfico de build para entender propriedades de destino e estruturas de dependência. O Bazel é compatível com três variantes de consulta: query, cquery e aquery.
query (comando)
Uma ferramenta de consulta que opera na fase de pós-fase
de carregamento do gráfico de destino do build. Esse método é relativamente rápido,
mas não pode analisar os efeitos de select()
, flags de build,
artefatos ou ações de build.
Consulte também: Instruções de consulta, Referência de consulta
Cache do repositório
Um cache de conteúdo endereçável compartilhado de arquivos transferidos por download pelo Bazel para builds,
que pode ser compartilhado entre espaços de trabalho. Permite builds off-line após o
download inicial. Normalmente usado para armazenar em cache arquivos transferidos por download por meio de regras
de repositório, como http_archive
, e APIs de regras de repositório, como
repository_ctx.download
. Os arquivos serão armazenados em cache somente 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 para a versão ou o teste sempre vai produzir o mesmo conjunto de saídas todas as vezes, independentemente do horário, método ou ambiente. Isso não implica necessariamente que as saídas estejam corretas ou que sejam 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. Da perspectiva dos autores de .bzl
, as regras são a principal maneira de estender o Bazel para oferecer suporte a novas linguagens e ambientes de programação.
As regras são instanciadas para produzir destinos de regras na fase de carregamento. Na fase de análise, os destinos de regra comunicam informações para as dependências downstream na forma de provedores e registram ações que descrevem como gerar os artefatos de saída deles. Essas ações são executadas na fase de execução.
Confira também: documentação sobre regras
Destino da regra
Um destino que é uma instância de uma regra. Contrasta com destinos de arquivos e grupos de pacotes. Não confunda com rule.
Arquivos de execução
As dependências de ambiente de execução de um destino executável. Geralmente, o executável é a saída executável de uma regra de teste, e os runfiles são dependências de dados do ambiente de execução do teste. Antes da invocação do executável (durante o teste do Bazel), o Bazel prepara a árvore de arquivos de execução com o executável de teste, de acordo com a estrutura de diretório de origem.
Consulte também: Documentação dos arquivos de execução
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 sandbox melhora muito a hermeticidade, mas geralmente tem um custo de desempenho e exige suporte do sistema operacional. O custo de performance depende da plataforma. No Linux, ela não é significativa, mas no macOS pode tornar o sandbox inutilizável.
Estrutura do arranha-céu
O Skyframe é o framework principal de avaliação paralela, funcional e incremental do Bazel.
Estampagem
Um recurso para incorporar mais informações a artefatos
criados pelo Bazel. Por exemplo, isso pode ser usado para controle de origem, tempo
de build e outras informações de espaço de trabalho ou de ambiente para builds de lançamento.
Ative por meio da sinalização --workspace_status_command
e das regras que
oferecem suporte ao atributo carimbo.
Starlark
A linguagem da extensão para escrever regras e macros. Um
subconjunto restrito de Python (sintática e gramaticalmente) destinado para
fins de configuração e para melhor desempenho. Usa a extensão do arquivo
.bzl
. Arquivos BUILD
usam uma versão ainda mais
restrita do Starlark (como definições de função sem def
), anteriormente
conhecida como Skylark.
Veja também: Documentação da linguagem Starlark
Sinalizações de inicialização
O conjunto de sinalizações especificadas entre bazel
e o comando,
por exemplo, o build --host_jvm_debug
do bazel. Essas sinalizações modificam a configuração do servidor do Bazel. Portanto, qualquer modificação nas sinalizações de inicialização causa uma reinicialização do servidor. As sinalizações de inicialização não são específicas de nenhum
comando.
Objetivo
Um objeto definido em um arquivo BUILD
e identificado por um rótulo. Os destinos representam as unidades edificáveis de um espaço de trabalho
da perspectiva do usuário final.
Um destino declarado ao instanciar uma regra é chamado de destino
da regra. Dependendo da regra, elas podem ser executadas (como
cc_binary
) ou testáveis (como cc_test
). As segmentações de regras normalmente dependem de
outras metas por meio dos atributos delas (como deps
). Essas
dependências formam a base do gráfico de destino.
Além dos destinos de regra, há também destinos de arquivo e de grupo de pacotes. Os destinos de arquivo correspondem aos artefatos que são referenciados
em um arquivo BUILD
. Como um caso especial, o arquivo BUILD
de qualquer pacote é
sempre considerado um arquivo de origem de destino 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 do build para formar destinos configurados.
Gráfico de destino
Um gráfico na memória de destinos e suas dependências. Ele é 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
mais usados são :all
(todos os destinos de regra), :*
(todos os destinos de regra + arquivo),
...
(pacote atual e todos os subpacotes recursivamente). Pode ser usado
em combinação, por exemplo, //...:*
significa todos os destinos de regras e arquivos em todos
os pacotes recursivamente a partir da raiz do espaço de trabalho.
Testes
Os destinos da regra são instanciados das 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 o sucesso do teste. O contrato exato entre o Bazel e os testes (como variáveis de ambiente de teste e métodos de coleta de resultados de teste) é especificado na Enciclopédia de teste.
Conjunto de ferramentas
Um conjunto de ferramentas para criar saídas para uma linguagem. Normalmente, um conjunto de ferramentas inclui compiladores, vinculadores, intérpretes e/e lints. Um conjunto de ferramentas também pode variar por plataforma, ou seja, os componentes de um conjunto de ferramentas do compilador Unix podem ser diferentes para a variante do Windows, mesmo que o conjunto seja para a mesma linguagem. A seleção do conjunto de ferramentas correto para a plataforma é conhecido como resolução do conjunto de ferramentas.
Meta de nível superior
Um destino de compilação é de nível superior se solicitado na linha de comando do Bazel. Por exemplo, se //:foo
depender de //:bar
e bazel build //:foo
for
chamado, para esse build, //:foo
vai ser de nível superior e //:bar
não vai ser
de nível superior, embora seja necessário criar os dois destinos. Uma diferença importante
entre destinos de nível superior e que não são de nível superior é que as sinalizações
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 superior.
Transição
Um mapeamento do estado da configuração de um valor para outro. Permite que os destinos no gráfico do build tenham configurações diferentes, mesmo que sejam instanciados a partir da mesma regra. Um uso comum de transições é com as transições, em que determinadas partes do gráfico de destino são bifurcadas com configurações distintas para cada bifurcação. Por exemplo, é possível criar um APK do Android com binários nativos compilados para ARM e x86 usando transições divididas em um único 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 operando 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 do destino, para controlar se um destino pode ser depender
de outros destinos, e visibilidade do carregamento, para controlar se um arquivo BUILD
ou .bzl
pode carregar um determinado arquivo .bzl
. Sem contexto, geralmente
"visibilidade" se refere à visibilidade do público-alvo.
Consulte também: Documentação de visibilidade
Workspace
Um diretório contendo um arquivo WORKSPACE
e um 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, mesmo que ele geralmente contenha declarações de repositório externo para buscar outras dependências da rede ou do sistema de arquivos local.