--- title: "build.zig.zon em Zig — O que é e Como Usar" url: "https://ziglang.com.br/glossario/build.zig.zon-em-zig-o-que-%C3%A9-e-como-usar/" markdown_url: "https://ziglang.com.br/glossario/build.zig.zon-em-zig-o-que-%C3%A9-e-como-usar.MD" description: "Entenda o build.zig.zon: manifesto de pacote do Zig em formato ZON. Dependências, metadados e gerenciamento de pacotes. Guia pt-BR." date: "2026-02-21" author: "Zig Brasil" --- # build.zig.zon em Zig — O que é e Como Usar Entenda o build.zig.zon: manifesto de pacote do Zig em formato ZON. Dependências, metadados e gerenciamento de pacotes. Guia pt-BR. # 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 ```zig .{ .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) ```zig .{ .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 ```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 | Campo | Descrição | |-------|-----------| | `.name` | Nome do pacote | | `.version` | Versão semântica (ex: "1.2.3") | | `.dependencies` | Mapa de dependências externas | | `.paths` | Arquivos incluídos no pacote quando publicado | | `.minimum_zig_version` | Versão mínima do Zig necessária (opcional) | ## Comandos Úteis ```bash # 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](/glossario/build-zig/) — Arquivo de configuração do sistema de build - [ZON](/glossario/zon/) — Formato Zig Object Notation - [zig fetch](/glossario/zig-fetch/) — Comando para baixar dependências - [zig build](/glossario/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. ```bash # 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 | Ecossistema | Arquivo de Manifesto | Registro Central | |------------|---------------------|-----------------| | Zig | `build.zig.zon` | Não obrigatório | | Rust | `Cargo.toml` | crates.io | | Node.js | `package.json` | npmjs.com | | Go | `go.mod` | pkg.go.dev | | Python | `pyproject.toml` | pypi.org | 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](/tutoriais/zig-packaging/) - [Zig Build System](/tutoriais/zig-build-system/) - [Introdução ao Zig](/tutoriais/introducao-ao-zig/)