Clean Build Folder ou excluir o DerivedData no Xcode?

A diferença é o alcance, não a profundidade

Product > Clean Build Folder (Shift-Command-K) age dentro do projeto e do scheme abertos no momento. Ele descarta os produtos compilados e os arquivos intermediários desse contexto, para que o próximo build comece do código-fonte. O alcance é um único projeto, e ele mantém de propósito o que é caro de reconstruir.

O DerivedData é a pasta principal compartilhada por todos os projetos que usam o local padrão — ~/Library/Developer/Xcode/DerivedData, com uma subpasta para cada projeto ou workspace que você já abriu. Excluir uma subpasta zera exatamente aquele projeto. Excluir a pasta inteira faz todos os seus projetos serem recompilados e reindexados na próxima vez que forem abertos.

Por isso, a forma honesta de descrever os dois não é “limpeza leve” versus “limpeza profunda”. O Clean Build Folder tem alcance estreito e custa pouco; excluir o DerivedData tem alcance amplo e custa o índice. Qual é o certo depende só de onde está o problema: dentro dos produtos de build ou fora deles.

Quando o build quebrar, comece pelo mais restrito

Se a falha surgiu logo depois de você trocar de branch, mudar uma configuração de build ou editar arquivos de recursos, encerre o app em execução e use primeiro o Clean Build Folder. É o reset mais barato que existe, preserva o índice e faz você voltar ao trabalho depois de um build — e não de um build mais vários minutos de indexação.

Passe a excluir a pasta do DerivedData daquele projeto quando os sintomas não tiverem a ver com produtos de build: o Xcode mostrando erros em código que você já corrigiu, o Jump to Definition levando ao lugar errado, o autocompletar que deixou de reconhecer os seus próprios tipos. Esses são sintomas do índice, e o Clean Build Folder não mexe no índice.

Há um caso específico que vale conhecer, porque é o motivo mais comum para “limpei e não adiantou” virar “excluí o DerivedData e resolveu”: o cache de módulos pré-compilados (ModuleCache.noindex) fica na raiz do DerivedData, e não dentro da subpasta de algum projeto. O Clean Build Folder nunca chega até ele. Quando esse cache fica desatualizado depois de uma mudança de SDK ou de toolchain, só removê-lo elimina o erro.

Nenhum dos dois comandos corrige um bug real no seu código ou nas suas dependências. Se exatamente o mesmo erro sobreviver a um build limpo, pare de limpar e leia a mensagem do compilador — a causa está nas configurações do projeto, no Package.resolved, no SDK selecionado ou no próprio código.

Nenhum dos dois é uma estratégia de limpeza de disco

O Clean Build Folder é uma ferramenta de diagnóstico que, de quebra, libera alguns bytes. Ele pode devolver o espaço do projeto atual, mas os produtos de build de todos os outros projetos, todos os índices e o cache de módulos continuam exatamente onde estavam. Usá-lo para recuperar espaço em disco é medir a coisa errada.

Se o objetivo é mesmo espaço, faça o caminho inverso: meça primeiro as subpastas do DerivedData e depois exclua as dos projetos que você não abre há meses. É ali que costumam estar as dezenas de gigabytes — clones avulsos que você compilou uma vez e nunca mais abriu.

Não comece pelo rm -rf. O Finder permite mover as pastas selecionadas para o Lixo, de onde ainda dá para recuperá-las até você esvaziá-lo — e essa diferença importa na primeira vez que você exclui a pasta de um projeto que, na verdade, estava sendo compilado naquele momento. O Terminal vale a pena para automatizar, mas só depois de confirmar o caminho exato.

Confira o resultado em vez de confiar num número

Anote o tamanho do DerivedData antes de fazer qualquer coisa, aplique só uma das duas opções e meça de novo. Depois do Clean Build Folder, compile o scheme atual. Depois de excluir uma pasta do DerivedData, abra o Xcode e espere terminar o primeiro build e a indexação.

Seguir essa ordem separa o espaço que você recuperou do preço que pagou por ele. Não existe um número universal a esperar: o resultado depende de quantos projetos, configurações e arquiteturas já foram compilados naquele Mac.

Qual usar em cada situação

Esta tabela descreve o alcance de cada opção, não uma quantidade prometida de gigabytes. Meça o seu Mac antes e depois.

Perguntas frequentes