Dependency Fetch Failed — Como Resolver em Zig
O Que Este Erro Significa
O erro de falha ao buscar dependências ocorre quando o sistema de build do Zig não consegue baixar ou validar uma dependência declarada no build.zig.zon. Isso pode acontecer por problemas de rede, URL incorreta, hash de integridade inválido ou formato incorreto do manifesto.
Mensagens típicas:
error: unable to fetch dependency
error: hash mismatch
error: unable to resolve dependency
O sistema de pacotes do Zig usa hashes de integridade para garantir reprodutibilidade — cada dependência é identificada por um hash exato do seu conteúdo.
Causas Comuns
1. URL Incorreta no build.zig.zon
// build.zig.zon
.{
.name = "meu-projeto",
.version = "0.1.0",
.dependencies = .{
.minha_lib = .{
.url = "https://github.com/usuario/repo/archive/refs/tags/v1.0.0.tar.gz",
// URL pode estar errada ou o repositório foi removido
.hash = "12209876543210abcdef...",
},
},
}
2. Hash Incorreto ou Desatualizado
// build.zig.zon
.{
.name = "meu-projeto",
.version = "0.1.0",
.dependencies = .{
.zap = .{
.url = "https://github.com/zigtools/zap/archive/v0.1.0.tar.gz",
.hash = "1220aaaabbbbccccdddd...", // Hash antigo ou errado
// ERRO: hash mismatch — conteúdo não bate
},
},
}
3. Sem Conexão de Rede
$ zig build
# ERRO: unable to connect to github.com — sem internet
4. Manifesto build.zig.zon Malformado
// build.zig.zon — ERRO DE SINTAXE
.{
.name = "meu-projeto",
.version = "0.1.0",
.dependencies = .{
.lib = .{
.url = "https://example.com/lib.tar.gz"
// Falta vírgula e hash!
},
},
}
5. Versão do Zig Incompatível com a Dependência
# A dependência requer Zig 0.12.0, mas você tem 0.11.0
$ zig build
# ERRO: dependency requires newer Zig version
Como Corrigir
Solucao 1: Usar zig fetch para Obter o Hash Correto
# O Zig calcula o hash automaticamente
$ zig fetch https://github.com/usuario/repo/archive/refs/tags/v1.0.0.tar.gz
# Saída: 1220abcdef1234567890...
# Copie este hash para o build.zig.zon
Solucao 2: Remover Hash e Deixar Zig Calcular
// build.zig.zon — remova o hash temporariamente
.{
.name = "meu-projeto",
.version = "0.1.0",
.dependencies = .{
.minha_lib = .{
.url = "https://github.com/usuario/repo/archive/refs/tags/v1.0.0.tar.gz",
// Sem hash — zig build mostrará o hash correto no erro
},
},
}
$ zig build
# error: hash not provided; expected: 1220abcdef...
# Copie o hash sugerido e cole no build.zig.zon
Solucao 3: Verificar e Corrigir a URL
// build.zig.zon
.{
.name = "meu-projeto",
.version = "0.1.0",
.dependencies = .{
.minha_lib = .{
// Use a URL do archive do GitHub (não do repositório)
.url = "https://github.com/usuario/repo/archive/refs/tags/v1.0.0.tar.gz",
.hash = "1220...",
},
},
}
URLs válidas para dependências:
# GitHub release
https://github.com/user/repo/archive/refs/tags/v1.0.0.tar.gz
# GitHub commit específico
https://github.com/user/repo/archive/abc123def.tar.gz
# Tarball direto
https://example.com/lib-1.0.0.tar.gz
Solucao 4: Usar Dependência Local (Desenvolvimento)
// build.zig.zon — para desenvolvimento local
.{
.name = "meu-projeto",
.version = "0.1.0",
.dependencies = .{
.minha_lib = .{
.path = "../minha-lib", // Caminho local — sem download
},
},
}
Solucao 5: Configurar Proxy ou Cache
# Se estiver atrás de proxy
$ export HTTPS_PROXY=http://proxy:8080
$ zig build
# Limpar cache de pacotes
$ rm -rf ~/.cache/zig
$ zig build
Solucao 6: Usar a Dependência no build.zig
Após declarar no build.zig.zon, use no build.zig:
// build.zig
const std = @import("std");
pub fn build(b: *std.Build) void {
const target = b.standardTargetOptions(.{});
const optimize = b.standardOptimizeOption(.{});
// Buscar dependência declarada no build.zig.zon
const dep = b.dependency("minha_lib", .{
.target = target,
.optimize = optimize,
});
const exe = b.addExecutable(.{
.name = "meu-projeto",
.root_source_file = b.path("src/main.zig"),
.target = target,
.optimize = optimize,
});
// Adicionar módulo da dependência
exe.root_module.addImport("minha_lib", dep.module("minha_lib"));
b.installArtifact(exe);
}
build.zig.zon Completo de Exemplo
.{
.name = "meu-projeto",
.version = "0.1.0",
.minimum_zig_version = "0.13.0",
.dependencies = .{
.zap = .{
.url = "https://github.com/zigtools/zap/archive/refs/tags/v0.2.0.tar.gz",
.hash = "1220abcdef1234567890abcdef1234567890abcdef1234567890abcdef12345678",
},
.minha_lib_local = .{
.path = "../minha-lib",
},
},
.paths = .{
"build.zig",
"build.zig.zon",
"src",
},
}
Diagnóstico
# Verificar versão do Zig
$ zig version
# Testar download manual
$ curl -L -o test.tar.gz "URL_DA_DEPENDENCIA"
$ sha256sum test.tar.gz
# Verificar cache
$ ls ~/.cache/zig/
# Rebuild limpo
$ rm -rf zig-out .zig-cache
$ zig build
Erros Relacionados
- build.zig not found — Arquivo de build não encontrado
- Linker error — Erro de linker
- Target not supported — Alvo não suportado