---
title: "Zig Lento para Compilar — Como Acelerar a Compilação"
url: "https://ziglang.com.br/troubleshooting/zig-lento-para-compilar-como-acelerar-a-compila%C3%A7%C3%A3o/"
markdown_url: "https://ziglang.com.br/troubleshooting/zig-lento-para-compilar-como-acelerar-a-compila%C3%A7%C3%A3o.MD"
description: "Soluções para compilação lenta em Zig: otimizar build.zig, reduzir tempo de compilação, cache, compilação incremental e diagnóstico. Em português."
date: "2026-02-21"
author: "Zig Brasil"
---

# Zig Lento para Compilar — Como Acelerar a Compilação

Soluções para compilação lenta em Zig: otimizar build.zig, reduzir tempo de compilação, cache, compilação incremental e diagnóstico. Em português.


# Zig Lento para Compilar — Como Acelerar a Compilação

Se a compilação do seu projeto Zig está demorando mais do que o esperado, existem várias estratégias para identificar e resolver o gargalo. Zig é geralmente rápido para compilar, então compilação lenta geralmente indica um problema específico.

## Causas Comuns e Soluções

### 1. Compilando em modo Release desnecessariamente

**Problema:** Usar `-OReleaseFast` durante desenvolvimento é muito mais lento que Debug.

**Solução:**
```bash
# Desenvolvimento — rápido
zig build

# Apenas para deploy — lento mas otimizado
zig build -Doptimize=ReleaseFast
```

A compilação Debug é significativamente mais rápida porque pula todas as otimizações LLVM.

### 2. Muitos @cImport ou arquivos C

**Problema:** Cada `@cImport` precisa parsear headers C, que podem incluir milhares de linhas.

**Solução:**
```zig
// LENTO: importar headers grandes repetidamente
// const c = @cImport(@cInclude("gtk/gtk.h")); // em cada arquivo

// RÁPIDO: importar uma vez e reexportar
// Em c_bindings.zig:
pub const c = @cImport({
    @cInclude("gtk/gtk.h");
});

// Em outros arquivos:
const bindings = @import("c_bindings.zig");
const c = bindings.c;
```

### 3. Cache corrompido ou desatualizado

**Solução:**
```bash
# Limpar cache local do projeto
rm -rf zig-cache .zig-cache zig-out

# Limpar cache global
rm -rf ~/.cache/zig

# Recompilar
zig build
```

### 4. Uso excessivo de comptime

**Problema:** Cálculos comptime complexos são executados a cada compilação.

**Solução:**
- Mover cálculos pesados para runtime quando possível
- Usar `@embedFile` para dados grandes pré-calculados
- Limitar a profundidade de recursão comptime

### 5. Compilação paralela insuficiente

**Solução:**
```bash
# Zig usa todos os cores por padrão
# Verificar se o sistema tem recursos disponíveis
nproc  # Linux
sysctl -n hw.ncpu  # macOS

# Limitar se a máquina estiver sobrecarregada
zig build -j4
```

### 6. Antivírus interferindo (Windows)

**Problema:** Antivírus escaneiam cada arquivo gerado durante compilação.

**Solução:**
- Adicionar diretório do projeto às exclusões do antivírus
- Adicionar `zig.exe` e `zig-cache/` às exclusões
- Windows Defender: Configurações > Proteção contra vírus > Exclusões

### 7. Muitas dependências externas

**Solução:**
```bash
# Verificar quanto tempo cada dependência leva
zig build --verbose 2>&1 | head -50

# Considerar pré-compilar dependências como bibliotecas estáticas
```

## Diagnóstico

```bash
# Medir tempo total de compilação
time zig build

# Ver o que o compilador está fazendo
zig build --verbose

# Verificar tamanho do cache
du -sh zig-cache/ .zig-cache/ 2>/dev/null
```

## Benchmarks de Referência

Em hardware moderno, tempos esperados para compilação Debug:

| Tamanho do Projeto | Tempo Esperado |
|---------------------|---------------|
| Arquivo único simples | < 1s |
| Projeto pequeno (~10 arquivos) | 1-3s |
| Projeto médio (~50 arquivos) | 3-10s |
| Projeto grande (~200+ arquivos) | 10-30s |
| Com muitos @cImport | +5-15s por header complexo |

Se seus tempos são significativamente maiores, provavelmente um dos problemas acima é a causa.

## Veja Também

- [Build System](/cheatsheets/build-system/) — Configuração otimizada do build.zig
- [CLI do Zig](/cheatsheets/cli-comandos-zig/) — Flags de compilação
- [Erros no build.zig](/troubleshooting/zig-build-zig-erros/) — Problemas no sistema de build
- [Performance Lenta](/troubleshooting/zig-performance-lenta/) — Otimização de runtime
- [FAQ Build System](/faq/faq-build-system/) — Perguntas sobre compilação