build.zig.zon em Zig — O que é e Como Usar

Definição

build.zig.zon é o arquivo de manifesto de pacote do Zig, escrito em formato ZON (Zig Object Notation). Ele declara os metadados do projeto (nome, versão) e suas dependências externas. O gerenciador de pacotes do Zig lê este arquivo para baixar, verificar e disponibilizar dependências durante o build.

É equivalente ao Cargo.toml do Rust, package.json do Node.js ou go.mod do Go.

Por que build.zig.zon Importa

1. Gerenciamento de dependências: Declara pacotes externos de forma reprodutível.
2. Verificação de integridade: Cada dependência tem um hash para garantir que o conteúdo é o esperado.
3. Sem registro central obrigatório: Dependências podem vir de URLs, Git ou caminhos locais.
4. Versionamento: Metadados do pacote ficam separados da lógica de build.

Exemplo Prático

build.zig.zon Básico

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

    .dependencies = .{
        .zap = .{
            .url = "https://github.com/zigzap/zap/archive/refs/tags/v0.5.0.tar.gz",
            .hash = "12209a42f03620ba6a12345678901234567890abcdef1234567890abcdef12345678",
        },
        .zig_clap = .{
            .url = "https://github.com/Hejsil/zig-clap/archive/refs/tags/0.9.1.tar.gz",
            .hash = "1220abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890ab",
        },
    },

    .paths = .{
        "build.zig",
        "build.zig.zon",
        "src",
        "LICENSE",
        "README.md",
    },
}

Dependência Local (para desenvolvimento)

.{
    .name = "app-principal",
    .version = "0.1.0",

    .dependencies = .{
        // Dependência de um diretório local
        .minha_lib = .{
            .path = "../minha-biblioteca",
        },
    },

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

Usando Dependências no 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 .zon
    const clap_dep = b.dependency("zig_clap", .{
        .target = target,
        .optimize = optimize,
    });

    const exe = b.addExecutable(.{
        .name = "meu-cli",
        .root_source_file = b.path("src/main.zig"),
        .target = target,
        .optimize = optimize,
    });

    // Disponibilizar para @import("clap") no código-fonte
    exe.root_module.addImport("clap", clap_dep.module("clap"));

    b.installArtifact(exe);
}

Campos do build.zig.zon

Comandos Úteis

# Baixar dependências e mostrar o hash
zig fetch https://github.com/user/repo/archive/v1.0.tar.gz

# Build busca dependências automaticamente
zig build

Armadilhas Comuns

• Hash incorreto: Se o hash não bater, zig build falha. Use zig fetch para obter o hash correto.
• Formato ZON, não JSON: ZON usa .campo = em vez de "campo":. Sem vírgulas antes de }.
• Nome da dependência: O nome usado em .dependencies deve corresponder ao usado em b.dependency() no build.zig.
• Caminhos em .paths: Devem listar os arquivos que fazem parte do pacote. Esquecer arquivos pode quebrar dependentes.

Termos Relacionados

• build.zig — Arquivo de configuração do sistema de build
• ZON — Formato Zig Object Notation
• zig fetch — Comando para baixar dependências
• zig build — Comando para compilar o projeto

Ciclo de Vida de uma Dependência

Quando você executa zig build, o sistema lê o build.zig.zon, baixa as dependências ausentes do cache global, verifica o hash de cada uma e as torna disponíveis para o build.zig. O cache global do Zig (~/.cache/zig/ no Linux/macOS) evita downloads repetidos — se dois projetos distintos usam a mesma dependência com o mesmo hash, ela é baixada apenas uma vez.

# Fluxo típico ao adicionar uma nova dependência:

# 1. Obter o hash da dependência
zig fetch --save=nome_dep https://github.com/user/repo/archive/v1.0.tar.gz

# 2. Verificar que build.zig.zon foi atualizado corretamente
cat build.zig.zon

# 3. Usar a dependência no build.zig (b.dependency + addImport)
# 4. Confirmar que o build funciona
zig build

Comparação com Outros Ecossistemas

A ausência de um registro central obrigatório no Zig significa mais flexibilidade — você pode hospedar pacotes em qualquer URL pública — mas também exige que os consumidores confiem na URL de origem.

Boas Práticas

• Commite o build.zig.zon junto com o build.zig: Ambos fazem parte da definição do projeto e devem estar no controle de versão.
• Use releases com tag: Prefira URLs que apontem para tags de release em vez de commits arbitrários. Tags são mais estáveis e o hash não muda.
• Campo .paths completo: Ao publicar sua própria biblioteca, certifique-se de listar todos os arquivos necessários em .paths. Esquecer um arquivo fará com que dependentes do seu pacote falhem.
• minimum_zig_version: Declare a versão mínima do Zig se sua biblioteca usa APIs específicas de uma versão. Isso melhora a experiência do usuário ao tentar compilar com uma versão incompatível.

Tutoriais Relacionados

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