Falha em Dependências Zig — Resolver Problemas com Packages
O gerenciador de pacotes do Zig é integrado ao build system. Quando dependências falham, geralmente é por problemas de rede, hash incorreto ou versões incompatíveis. Este guia resolve os problemas mais comuns.
Erro: “hash mismatch”
Causa: O hash no build.zig.zon não corresponde ao conteúdo baixado.
error: hash mismatch: expected 1220abc..., found 1220def...
Solução:
# Opção 1: Usar o hash correto da mensagem de erro
# Copie o hash "found" e substitua no build.zig.zon
# Opção 2: Usar zig fetch para calcular o hash correto
zig fetch https://github.com/user/lib/archive/v1.0.tar.gz
# Saída: 1220def...
# Opção 3: Fetch e salvar automaticamente
zig fetch --save https://github.com/user/lib/archive/v1.0.tar.gz
Atualize o hash no build.zig.zon:
.minha_dep = .{
.url = "https://github.com/user/lib/archive/v1.0.tar.gz",
.hash = "1220def...", // Hash corrigido
},
Erro: “unable to fetch”
Causa: Problema de rede ou URL inválida.
# Verificar se a URL é acessível
curl -I https://github.com/user/lib/archive/v1.0.tar.gz
# Verificar conectividade
ping github.com
# Se atrás de proxy:
export HTTP_PROXY=http://proxy:8080
export HTTPS_PROXY=http://proxy:8080
zig build
URLs comuns que mudam:
// GitHub — usar formato de archive correto
.url = "https://github.com/USER/REPO/archive/refs/tags/v1.0.tar.gz",
// ou
.url = "https://github.com/USER/REPO/archive/COMMIT_HASH.tar.gz",
Erro: “dependency build failure”
Causa: A dependência baixou corretamente mas falha ao compilar.
# Ver o erro detalhado
zig build 2>&1
# Causas comuns:
# 1. Versão do Zig incompatível com a dependência
# 2. Target não suportado pela dependência
# 3. Dependência transitiva faltando
Soluções:
// Verificar se a dependência suporta sua versão do Zig
// No build.zig.zon da dependência, veja .minimum_zig_version
// Usar uma versão específica da dependência compatível com seu Zig
.minha_dep = .{
.url = "https://github.com/user/lib/archive/v0.5.0.tar.gz", // versão compatível
.hash = "...",
},
Erro: “module not found in dependency”
Causa: O nome do módulo no addImport não corresponde ao que a dependência exporta.
// Verificar o build.zig da dependência para saber o nome do módulo
const dep = b.dependency("httpz", .{
.target = target,
.optimize = optimize,
});
// O nome aqui deve corresponder ao que a dep exporta
exe.root_module.addImport("httpz", dep.module("httpz"));
// Se o erro diz "module 'httpz' not found", tente:
// dep.module("http") — pode ter outro nome
Consulte a documentação ou o build.zig da dependência para ver os nomes corretos dos módulos exportados.
Problema: Cache de Dependências Corrompido
# Limpar cache global de pacotes
rm -rf ~/.cache/zig
# Limpar cache local
rm -rf zig-cache .zig-cache
# Recompilar
zig build
Problema: Dependência com Subdependências
// Se a dependência tem suas próprias dependências,
// elas são resolvidas automaticamente.
// Mas se houver conflitos:
// No build.zig.zon — sobrescrever dependência transitiva
.{
.name = "meu-projeto",
.version = "0.1.0",
.dependencies = .{
.minha_dep = .{
.url = "...",
.hash = "...",
},
// Sobrescrever subdependência se necessário
.sub_dep = .{
.url = "...",
.hash = "...",
},
},
.paths = .{"."},
}
Problema: Dependência Local (durante desenvolvimento)
// build.zig.zon — usar caminho local durante desenvolvimento
.{
.dependencies = .{
.minha_dep = .{
.path = "../minha-lib", // Caminho local
},
},
}
Caminhos locais são úteis durante desenvolvimento mas não devem ser commitados para produção. Use URLs para distribuição.
Problema: Versão do Zig Incompatível
# Verificar versão do Zig
zig version
# Verificar versão mínima exigida pela dependência
# Geralmente documentada no README ou build.zig.zon
Se a dependência requer uma versão mais nova do Zig:
- Atualize o Zig para a versão requerida
- Ou use uma versão anterior da dependência compatível com seu Zig
Diagnóstico
# Ver o que zig build está fazendo
zig build --verbose
# Testar apenas o fetch das dependências
zig fetch https://url/do/pacote.tar.gz
# Verificar build.zig.zon (deve ser JSON-like válido)
cat build.zig.zon
# Listar dependências resolvidas
zig build --verbose 2>&1 | grep -i "fetch\|depend"
Checklist de Resolução
- Verifique se a URL da dependência é acessível
- Atualize o hash com
zig fetch --save URL - Limpe o cache:
rm -rf zig-cache .zig-cache ~/.cache/zig - Verifique compatibilidade de versão do Zig
- Confira o nome correto do módulo no build.zig da dependência
- Para cross-compilation, verifique se a dependência suporta o target
Veja Também
- FAQ Build System — Gerenciar dependências
- Erros no build.zig — Problemas do build system
- FAQ Ecossistema — Onde encontrar pacotes
- Atualizar Versão — Migrar entre versões
- Receitas — Exemplos com dependências externas