Erros no build.zig — Resolver Problemas do Build System
O build.zig é código Zig que configura o processo de compilação. Quando ele falha, o projeto inteiro não compila. Este guia cobre os erros mais comuns e suas soluções.
Erro: “build.zig has errors”
Causa: Erro de sintaxe ou lógica no build.zig.
# Ver o erro exato
zig build 2>&1
# Exemplo de saída:
# build.zig:15:5: error: expected expression, found '}'
Solução: Trate build.zig como qualquer outro arquivo Zig — leia a mensagem de erro, verifique a linha indicada e corrija o problema.
Erro: “unable to find build.zig”
# Verificar se está no diretório correto
ls build.zig
# Se não existe, criar um:
zig init
# Ou especificar o caminho:
zig build --build-file /caminho/para/build.zig
Erro: “unable to resolve dependency”
Causa: Dependência declarada no build.zig.zon não foi encontrada.
# Baixar/atualizar dependências
zig fetch --save https://github.com/user/lib/archive/v1.0.tar.gz
# Se o hash está errado:
# O erro mostrará o hash esperado — copie e atualize no build.zig.zon
// build.zig.zon — verificar formato
.{
.name = "meu-projeto",
.version = "0.1.0",
.dependencies = .{
.minha_dep = .{
.url = "https://github.com/user/lib/archive/v1.0.tar.gz",
.hash = "1220abc...", // Hash correto fornecido pelo erro
},
},
.paths = .{"."},
}
Erro: “module not found”
Causa: Tentando importar um módulo que não foi registrado no build.zig.
// No build.zig — registrar o módulo corretamente
const dep = b.dependency("minha_dep", .{
.target = target,
.optimize = optimize,
});
// Adicionar o módulo ao executável
exe.root_module.addImport("minha_dep", dep.module("minha_dep"));
Verifique se o nome do módulo no addImport corresponde ao que a dependência exporta.
Erro: “step has no dependencies”
Causa: Step declarado mas não conectado ao grafo de build.
// PROBLEMA: step não conectado
const meu_step = b.step("deploy", "Deploy");
// Faltou: meu_step.dependOn(...)
// SOLUÇÃO:
const meu_step = b.step("deploy", "Deploy");
const run = b.addRunArtifact(exe);
meu_step.dependOn(&run.step);
Erro: API Mudou entre Versões
As mudanças mais comuns ao atualizar o Zig:
0.11 para 0.12+
// ANTIGO (0.11):
// exe.addPackagePath("modulo", "src/modulo.zig");
// NOVO (0.12+):
exe.root_module.addImport("modulo", b.addModule(.{
.name = "modulo",
.root_source_file = b.path("src/modulo.zig"),
}));
Mudanças de path
// ANTIGO:
// .root_source_file = .{ .path = "src/main.zig" },
// NOVO:
.root_source_file = b.path("src/main.zig"),
Consulte o changelog da versão para todas as mudanças de API.
Erro: “duplicate module”
Causa: O mesmo módulo foi adicionado duas vezes.
// PROBLEMA: duplicata
exe.root_module.addImport("utils", modulo_utils);
exe.root_module.addImport("utils", modulo_utils); // ERRO!
// SOLUÇÃO: adicionar apenas uma vez
exe.root_module.addImport("utils", modulo_utils);
Problema: Testes Não São Encontrados
// Verificar se o step de teste está configurado
const unit_tests = b.addTest(.{
.root_source_file = b.path("src/main.zig"),
.target = target,
.optimize = optimize,
});
const run_tests = b.addRunArtifact(unit_tests);
const test_step = b.step("test", "Rodar testes");
test_step.dependOn(&run_tests.step);
# Rodar testes
zig build test
# Ver quais steps estão disponíveis
zig build --help
Problema: Custom Steps com Erros
// Step customizado que roda comando externo
const cmd = b.addSystemCommand(&.{ "echo", "Hello" });
// Adicionar dependência a outro step
cmd.step.dependOn(&exe.step);
// Criar step nomeado
const custom_step = b.step("custom", "Meu step");
custom_step.dependOn(&cmd.step);
Problema: Variáveis de Build
// Adicionar opções customizadas ao build
const porta = b.option(u16, "porta", "Porta do servidor") orelse 8080;
// Passar opção para o código Zig via @import("config")
const options = b.addOptions();
options.addOption(u16, "porta", porta);
exe.root_module.addOptions("config", options);
// No código Zig:
const config = @import("config");
const porta: u16 = config.porta;
# Usar a opção
zig build -Dporta=3000
Diagnóstico
# Ver todos os steps disponíveis
zig build --help
# Compilação verbose
zig build --verbose
# Limpar cache e tentar novamente
rm -rf zig-cache .zig-cache zig-out && zig build
# Verificar a versão do Zig (APIs mudam entre versões)
zig version
Checklist de Resolução
- Leia a mensagem de erro completa — build.zig é código Zig normal
- Verifique se
build.zig.zontem hashes corretos - Limpe o cache:
rm -rf zig-cache .zig-cache zig-out - Verifique se a versão do Zig é compatível com o projeto
- Consulte o changelog ao atualizar versões
- Use
zig build --verbosepara mais detalhes
Veja Também
- FAQ Build System — Perguntas sobre o build system
- Compilação Lenta — Otimizar compilação
- Falha em Dependências — Problemas com packages
- Zig Não Compila — Erros de compilação
- Atualizar Versão — Migrar entre versões