Pular para o conteúdo
AggregaAggrega
Selecionar língua: Português (Portugal)
Esta página foi traduzida automaticamente. Ler o original em inglês.

aggrega cache

Inspecionar e manter as caches em disco

Sinopse

aggrega cache

Descrição

Inspect and maintain the caches the compiler populates.
status lists cache contents, one element per line, then a summary line.
prune reclaims artifact-cache entries no workspace lockfile references.
evict trims the compiled-module cache to a size cap, oldest first.
clear wipes every cache, including the compiled-module store.

Subcomandos

ComandoDescrição
aggrega cache clearApagar todas as caches, incluindo os módulos compilados
aggrega cache evictReduzir a cache de módulos compilados até um limite de tamanho, começando pelos mais antigos
aggrega cache pruneRemover entradas da cache de artefactos que nenhum lockfile referencia
aggrega cache statusListar o conteúdo da cache e um resumo total

Descrição de aggrega cache clear

Wipe every cache: the workspace artifact cache (entities, source artifacts,
external inputs) and the caches every project on the machine shares (compiled
modules, plugin descriptors, documentation bundles, and the cli plugins added
where no workspace was found). This is the total-wipe verb; unlike prune it
reclaims the compiled-module cache and the documentation bundles as well.
Cleared caches repopulate on the next build, and the documentation bundle on
the next read of the documentation; a cli plugin cleared from the cache is
fetched again by adding it again.
Because the wipe is irreversible, clear asks for confirmation before removing
anything. Pass --yes to skip the prompt for non-interactive use; without --yes
on a non-interactive stdin it refuses rather than blocking on a prompt no one
can answer.

Flags de aggrega cache clear

FlagPredefiniçãoDescrição
--yesfalseignorar o pedido de confirmação (para uso não interativo/em CI)

Descrição de aggrega cache evict

Trim the compiled-module cache to a size cap by removing the
least-recently-compiled modules first, until the cache total is at or below
--max-size. The compiled-module cache is machine-global: every provider guest is
compiled once and reused across every project on the machine, so over time it can
dominate on-disk cache use.
Unlike prune (which reclaims artifact-cache entries no lockfile references) and
clear (which wipes every cache), evict is size-bounded and touches only the
compiled-module cache. Evicted modules recompile on demand on the next build, so
eviction loses no irrecoverable state.
--max-size is required and accepts a binary-unit size in the same vocabulary the
status summary prints — for example 5GiB, "4.5 GiB", or 512MiB — or a bare
integer byte count. The unit suffix is case-insensitive and an optional space
may separate the number from the unit.
This verb is the on-demand trim, at a cap you give it once. The cache is also
held to a standing cap without being asked: every invocation that loads a plugin
applies the `compiled_module_cache.max_bytes` setting (53687091200 bytes, 50 GiB,
by default) before it compiles anything, using this same removal order. Use this
verb to reclaim space now or below the standing cap; change the setting to move
the standing cap itself. When the cache already fits the cap, evict reports a
no-op and removes nothing.

Flags de aggrega cache evict

FlagPredefiniçãoDescrição
--max-size—limite de tamanho da cache de módulos compilados (p. ex., 5GiB, 512MiB ou um número de bytes); obrigatório

Descrição de aggrega cache prune

Remove cache entries whose content digest no workspace lockfile references,
retaining every referenced entry. The reference set is the union of the
digests pinned across every lockfile (*.lock) in the workspace, together with
the digests the configuration's plugins.cli list pins, so a cli plugin you
added keeps the bytes it runs from.
Prune acts on the caches whose entries carry a content digest — the workspace
artifact cache (entities, source artifacts, external inputs), the
plugin-describe cache and the cli-plugin cache, which holds the cli plugins
added where no workspace was found — and on the compiled-module cache by reference: a compiled
plugin module is reclaimed when no lockfile still references the plugin it
belongs to, and the shared runtime module every plugin depends on is reclaimed
once the last plugin referring to it is pruned. A compiled module that cannot be
traced back to a plugin is retained rather than removed on a guess; that
remainder is reclaimed by "aggrega cache evict" or "aggrega cache clear".
Prune needs a pulled workspace: it fails when no lockfile is present.

Descrição de aggrega cache status

List the contents of every cache, one element per line, followed by a
summary line of the form "N elements, <human size>". The listing is
deterministic: identical cache state produces byte-identical output.

O que a cache é e o que não é

A cache de artefactos em artifact_cache_dir (.aggrega/cache por predefinição) contém o que uma obtenção lá colocou: entidades de catálogo e artefactos de origem, cada um guardado sob o seu tipo e a coordenada e a versão em que foi obtido, e garantido por um digest que o lockfile regista. Não é um diretório de catálogo, e uma análise do catálogo passa-lhe ao lado — pelo que o conteúdo que está na cache é lido como uma dependência, através da fixação que o garante, e nunca como uma entidade escrita pelo utilizador.

A consequência que tem mais probabilidade de encontrar. Se a cache contém uma entidade que nenhum lockfile fixa, essa entidade é invisível para uma compilação, e uma compilação que precise dela para, indicando que não foi encontrada. A paragem nomeia a entidade, pelo que a fixação em falta é identificável a partir da mensagem.

Quando a entidade é uma SchemaLibrary alcançada por um $ref:, cada comando que reporta a referência como não resolvida faz seguir o relatório de uma linha remediation: que nomeia cada biblioteca que a cache contém e que nenhuma entrada de lockfile fixa nem nenhum diretório de catálogo fornece, e a ação que resulta para esse comando:

  • aggrega build e aggrega validate --release <release> leem o lockfile da Release, pelo que a linha nomeia aggrega pull --release <release> para resolver a biblioteca e registar a sua entrada.
  • aggrega validate sem argumento, e aggrega validate <entity-path> com ou sem --release, leem bibliotecas apenas dos diretórios de catálogo e não leem nenhum lockfile, pelo que nenhuma entrada registada altera o seu veredicto. A linha di-lo e nomeia aggrega pull --release <release> seguido de aggrega validate --release <release>, que verifica a Release em relação ao que o seu lockfile fixa.
  • aggrega pull, e aggrega build --auto-pull, no modo sem ligação não conseguem obter a biblioteca nem registar uma entrada para ela, pelo que a linha indica que se execute aggrega pull --release <release> onde for possível chegar a um registo. Com ligação, um pull que não encontra a biblioteca em nenhum diretório de catálogo nem em nenhum registo que lê não tem nenhuma entrada a registar.

Cada uma dessas linhas oferece também o outro caminho: escrever a biblioteca num diretório de catálogo.

O que executar. aggrega pull --release <release> resolve a entidade e regista o seu digest, após o que a mesma compilação a encontra. Quando a entidade é sua e não uma dependência, escreva-a antes num diretório listado em workspace.catalog_dirs — uma análise lê esse diretório. aggrega cache prune limpa as entradas que nenhum lockfile referencia, que é a metade de arrumação da mesma regra.

Para a estrutura da cache, o contrato de artifact_cache_dir e o motivo pelo qual um artefacto de resolução não é deliberadamente legível como conteúdo escrito, consulte architecture/13-catalog-and-registry.md.

Que caches pertencem a este projeto e quais pertencem à máquina

Nem todas as caches sobre as quais estes comandos atuam estão circunscritas ao projeto em que o utilizador se encontra, e a diferença decide até onde chega uma recuperação de espaço.

Só suas. A cache de artefactos em artifact_cache_dir — as entidades, os artefactos de origem e as entradas externas fixadas que este projeto resolveu, e os snapshots do catálogo publicado que uma importação que não indica nenhuma pasta de catálogo leu. Recuperar espaço nela afeta este projeto e mais nenhum.

Partilhadas por todos os projetos Aggrega nesta máquina. O armazenamento de módulos compilados, o armazenamento de descrições de plugins, o armazenamento de pacotes de documentação e o armazenamento de plugins cli. Um guest de fornecedor é compilado uma vez e reutilizado por todos os projetos, o que torna rápida a segunda compilação de qualquer coisa, pelo que remover uma entrada significa que a próxima compilação de qualquer projeto na máquina o volta a compilar. O pacote de documentação — as páginas publicadas a partir das quais aggrega explain, as explicações de um editor e os recursos de documentação de um assistente são lidos, e os exemplos executáveis que aggrega scaffold --example escreve — é guardado uma vez por registo e versão, porque o seu conteúdo não depende de mais nada: aquele que o obtiver primeiro obtém-no para todos os projetos, e cada projeto só o recebe depois de a sua própria verificação de assinatura admitir a cópia. Nada se perde definitivamente — um módulo removido é reconstruído quando necessário, e um pacote removido é obtido novamente pela explicação ou pelo exemplo seguinte, ou por um servidor de assistente quando voltar a arrancar — mas o custo recai sobre quem compilar a seguir, que pode não ser o utilizador.

O armazenamento de plugins cli guarda os bytes de cada plugin cli adicionado com aggrega plugin add cli numa pasta que não é um espaço de trabalho, pelo que o seu comando é executado a partir de qualquer pasta; um plugin cli adicionado dentro de um espaço de trabalho guarda, em vez disso, os seus bytes na cache de artefactos desse espaço de trabalho. Ao contrário de um módulo compilado ou de um pacote, um plugin cli cujos bytes são removidos não volta a ser obtido por si só: até que aggrega plugin add cli <name> o volte a adicionar, o seu comando está em falta e todos os comandos avisam que não foi possível adicioná-lo, nomeando o comando aggrega plugin add cli que o volta a adicionar na versão fixada pela configuração.

Os armazenamentos de toda a máquina são guardados onde cada plataforma guarda as caches de um utilizador: no Windows em aggrega\cache dentro do diretório que a variável de ambiente LOCALAPPDATA nomeia, em ~/Library/Caches/aggrega no macOS, e num diretório aggrega dentro daquele que XDG_CACHE_HOME nomeia — ~/.cache/aggrega quando XDG_CACHE_HOME não está definida — no Linux e nos outros sistemas Unix. aggrega config init imprime o diretório na máquina em que é executado. Quando nenhuma dessas variáveis está definida, os plugins compilados são guardados apenas durante a execução e nenhum pacote de documentação é guardado: uma explicação indica então porque falta o seu percurso guiado, os recursos de documentação de um assistente respondem que não foram encontrados, e aggrega scaffold --example recusa, indicando que nenhum diretório de cache é resolvido; aggrega plugin add cli executado numa pasta que não é um espaço de trabalho também recusa, indicando que nenhuma localização de cache de toda a máquina é resolvida.

aggrega cache status indica isto por classe em vez de deixar que seja deduzido a partir do nome: cada classe é reportada como abrangendo o espaço de trabalho ou a máquina, e o mesmo alcance é reportado para cada elemento que prune, evict e clear removem. evict atua apenas sobre o armazenamento partilhado de módulos compilados; prune nunca remove um pacote de documentação nem um snapshot de catálogo que uma importação leu, já que nenhum lockfile referencia nenhum dos dois, e reporta cada uma dessas classes como não elegível para prune; prune mantém os bytes de cada plugin cli que a lista plugins.cli da configuração fixa — tanto no armazenamento de plugins cli como na cache de artefactos do espaço de trabalho, juntamente com a respetiva entrada de descrição de plugin — e remove os que nenhuma fixação nomeia; clear atua sobre tudo, e é por isso que pergunta antes de começar.

Uma raiz de workspace que não pode ser usada. Quando a raiz de workspace indicada ao comando é um ficheiro ou um caminho que não existe, status, evict e clear atuam apenas sobre os armazenamentos de toda a máquina, terminam como terminariam de outro modo e indicam-no na saída de erro padrão, com as mesmas palavras com que qualquer outro comando recusa essa raiz:

note: —workspace-root names the workspace root "<root>", which is not a directory: <root>; only the machine-wide caches are acted on (nota: —workspace-root nomeia uma raiz de workspace que não é um diretório; atua-se apenas sobre as caches de toda a máquina)

Um caminho que não existe apresenta which cannot be used: e o motivo em vez de which is not a directory:. Já prune para, uma vez que precisa dos lockfiles do workspace.

Isto aplica-se seja qual for o local a partir do qual a operação é invocada, não apenas num terminal. As mesmas operações estão acessíveis a partir de uma sessão de editor e da chamada de ferramenta de um assistente, e as suas respostas indicam o mesmo alcance pela mesma razão. Quando um assistente as pode invocar em nome do utilizador, consulte aggrega mcp.

O diretório da cache de artefactos é o único local a partir do qual tudo o que está na cache é lido, escrito e removido — tanto o .aggrega/cache predefinido como um diretório que artifact_cache_dir nomeie saindo da raiz do espaço de trabalho (../shared-cache). Tudo o que nele seja uma ligação simbólica que sai desse diretório — um dos próprios diretórios da cache, como .aggrega/cache/inputs, ou um ficheiro dentro de um deles — não é lido, escrito nem removido através dela, mesmo quando a ligação leva a outro diretório do mesmo espaço de trabalho. O que uma escrita pode alcançar sob o diretório da cache é exatamente o que uma remoção pode alcançar.

  • Um pull, uma compilação e todas as outras operações que escrevem na cache param com E0320, nomeando a ligação e o destino para onde leva, e não escrevem nada.
  • status, prune e clear não listam nada através de uma ligação dessas. Quando um dos próprios diretórios da cache é a ligação, status para com E0321, e um prune ou um clear para com E0320 antes de listar ou remover o que quer que seja — pelo que nada daquilo para que a ligação aponta é removido, e a ligação fica onde está. Quando um ficheiro dentro de um deles é a ligação, os três param com E0321.
  • Uma compilação, um pull e todas as outras operações que leem a cache param com E0321 em vez de lerem bytes guardados noutro local, mesmo quando esses bytes corresponderiam ao digest que o lockfile regista.
  • Uma ligação que permanece dentro do diretório da cache é seguida. Quando um dos próprios diretórios da cache é uma ligação para outro diretório dentro do diretório da cache, esse diretório é da cache: status lista o que lá está, prune remove a partir daí, e clear esvazia-o, mantém a ligação e reporta os bytes que lá removeu.

O próprio diretório da cache. Um artifact_cache_dir escrito dentro da raiz do espaço de trabalho — incluindo o predefinido — pode ser ele próprio uma ligação para outro diretório do espaço de trabalho, e a cache é então guardada para onde a ligação leva. Uma que saia do espaço de trabalho é recusada: qualquer operação que a encontre para com E0321 ou E0320, nomeando a ligação, antes de algo ser lido ou escrito através dela. Um diretório escrito saindo da raiz do espaço de trabalho é respeitado para onde leva, mesmo quando é ele próprio uma ligação.

Remova a ligação e faça novamente pull para preencher a cache no local. Para guardar a cache noutro sítio, defina artifact_cache_dir com esse diretório, escrito em relação à raiz do espaço de trabalho, em vez de criar uma ligação para ele: um diretório nomeado aí é lido e escrito para onde leva. Os armazenamentos de toda a máquina não estão sujeitos a nenhum espaço de trabalho; um que se guarde noutro local através de uma ligação é listado, limpo e esvaziado para onde a ligação leva, e clear mantém a ligação. A fronteira do espaço de trabalho enuncia a regra completa.

Ver também

  • aggrega-pull — resolver as dependências de uma Release para o lockfile e a cache.
  • aggrega-config — onde se escrevem artifact_cache_dir e as outras definições da cache.