zig fetch em Zig — O que é e Como Usar

Definição

zig fetch é o comando da toolchain do Zig usado para baixar pacotes de uma URL e calcular o hash de integridade necessário para o arquivo build.zig.zon. Quando você adiciona uma nova dependência ao seu projeto, zig fetch baixa o arquivo, verifica o conteúdo e exibe o hash que deve ser incluído na configuração.

Por que zig fetch Importa

1. Obter hashes: Calcula o hash exato para garantir integridade das dependências.
2. Cache local: Dependências são armazenadas em cache e reutilizadas entre builds.
3. Verificação: Garante que o conteúdo baixado é exatamente o esperado.
4. Simplicidade: Um único comando para adicionar dependências ao projeto.

Exemplo Prático

Baixar Dependência e Obter Hash

# Baixar pacote e exibir o hash
zig fetch https://github.com/zigzap/zap/archive/refs/tags/v0.5.0.tar.gz

# Saída: hash como 1220abcdef...
# Copie este hash para o build.zig.zon

Adicionar ao build.zig.zon

.{
    .name = "meu-projeto",
    .version = "0.1.0",

    .dependencies = .{
        .zap = .{
            .url = "https://github.com/zigzap/zap/archive/refs/tags/v0.5.0.tar.gz",
            // Cole o hash obtido pelo zig fetch
            .hash = "1220abcdef1234567890abcdef1234567890abcdef1234567890abcdef12345678",
        },
    },

    .paths = .{
        "build.zig",
        "build.zig.zon",
        "src",
    },
}

Salvar Diretamente no build.zig.zon

# Com --save, adiciona diretamente ao build.zig.zon
zig fetch --save https://github.com/user/repo/archive/refs/tags/v1.0.tar.gz

# Com --save=nome, especifica o nome da dependência
zig fetch --save=minha_lib https://github.com/user/lib/archive/v2.0.tar.gz

Opções do Comando

Armadilhas Comuns

• URL do arquivo, não do repositório: Use a URL do arquivo .tar.gz, não a URL da página do GitHub.
• Hash muda com o conteúdo: Se o mantenedor recriar a tag/release, o hash pode mudar. Prefira releases estáveis.
• Rede necessária: O primeiro fetch requer internet. Após isso, o cache local é usado.
• Formato do hash: O hash começa com 1220 seguido de caracteres hexadecimais. É um hash multihash (SHA-256).

Termos Relacionados

• build.zig.zon — Manifesto onde o hash é declarado
• build.zig — Onde a dependência é usada
• ZON — Formato do manifesto
• zig build — Comando que resolve dependências automaticamente

Fontes de Dependências Suportadas

O zig fetch suporta diferentes fontes de dependências. Além de arquivos .tar.gz hospedados no GitHub ou em qualquer servidor HTTP, é possível usar arquivos .tar.xz e .tar.zst. A URL pode apontar para qualquer servidor público — não há dependência de um registro central como crates.io ou npmjs.com. Isso significa que você pode hospedar suas próprias bibliotecas em qualquer infraestrutura.

Como o Hash Funciona

O hash gerado pelo zig fetch usa o formato multihash com SHA-256. O prefixo 1220 indica que o algoritmo é SHA-256 (0x12) com comprimento de 32 bytes (0x20). O restante é o digest hexadecimal do conteúdo do arquivo comprimido.

Essa abordagem garante que qualquer alteração no arquivo — mesmo de um único byte — produza um hash completamente diferente. O sistema de build usa esse hash para verificar a integridade antes de extrair e usar a dependência, prevenindo ataques de substituição ou corrupção de arquivos em trânsito.

Fluxo Completo de Adição de Dependência

# 1. Encontrar a URL do release desejado (GitHub, GitLab, etc.)
# 2. Rodar zig fetch para obter o hash
zig fetch --save=zig_clap https://github.com/Hejsil/zig-clap/archive/refs/tags/0.9.1.tar.gz

# 3. O arquivo build.zig.zon é atualizado automaticamente com --save
# 4. Usar a dependência no build.zig

// No build.zig, referenciar a dependência pelo nome declarado no .zon
const clap_dep = b.dependency("zig_clap", .{
    .target = target,
    .optimize = optimize,
});
const exe = b.addExecutable(.{
    .name = "meu-app",
    .root_source_file = b.path("src/main.zig"),
    .target = target,
    .optimize = optimize,
});
exe.root_module.addImport("clap", clap_dep.module("clap"));
b.installArtifact(exe);

Comparação com Outros Gerenciadores

Em Rust, cargo add atualiza o Cargo.toml com a versão desejada. Em Go, go get baixa o módulo e atualiza go.sum. O zig fetch é conceitualmente similar, mas opera com URLs diretas em vez de um registro central como crates.io ou pkg.go.dev. Isso dá mais controle sobre a origem das dependências, mas exige que você conheça a URL exata do release.

Cache de Dependências

Após o primeiro zig fetch, o conteúdo é armazenado no cache global do Zig (geralmente ~/.cache/zig/ no Linux/macOS ou %LOCALAPPDATA%\zig\ no Windows). Builds subsequentes — inclusive em outros projetos que usam a mesma dependência com o mesmo hash — reutilizam o cache sem fazer download novamente.

Tutoriais Relacionados

• Zig Packaging
• Zig Build System
• Introdução ao Zig