--- title: "Zig Package Manager: Guia Completo do build.zig.zon" url: "https://ziglang.com.br/artigos/zig-package-manager-guia-build-zig-zon/" markdown_url: "https://ziglang.com.br/artigos/zig-package-manager-guia-build-zig-zon.MD" description: "Aprenda a gerenciar dependências em Zig com build.zig.zon: adicionar pacotes, cache, zig-pkg no 0.16 e publicar bibliotecas. Guia prático em português." date: "2026-04-23" author: "" --- # Zig Package Manager: Guia Completo do build.zig.zon Aprenda a gerenciar dependências em Zig com build.zig.zon: adicionar pacotes, cache, zig-pkg no 0.16 e publicar bibliotecas. Guia prático em português. # Zig Package Manager: Guia Completo do build.zig.zon Gerenciar dependências é uma das tarefas mais importantes em qualquer projeto de software. O Zig adota uma abordagem única com o **build.zig.zon** — um manifesto declarativo que funciona em conjunto com o [build.zig](/glossario/build-zig/) para resolver, baixar e compilar pacotes automaticamente. Com as novidades do [Zig 0.16.0](/artigos/zig-0-16-juicy-main-novidades/), o sistema de pacotes ganhou melhorias significativas como o diretório local `zig-pkg` e cache comprimido global. Neste guia completo, você vai aprender desde o básico do formato `.zon` até técnicas avançadas de publicação de bibliotecas. ## O que é o build.zig.zon? O arquivo `build.zig.zon` é o **manifesto de metadados** do seu projeto Zig. Ele descreve o nome do pacote, a versão, os caminhos expostos e, principalmente, as **dependências externas**. O formato [ZON](/glossario/zon/) (Zig Object Notation) é uma sintaxe nativa do Zig — similar a JSON, mas com tipagem e avaliada pelo compilador. ```zig // build.zig.zon .{ .name = .meu_projeto, .version = "0.1.0", .minimum_zig_version = "0.16.0", .paths = .{ "src", "build.zig", "build.zig.zon", "LICENSE", "README.md", }, .dependencies = .{}, } ``` Cada campo tem uma função específica: - **`.name`**: identificador do pacote (usado em imports) - **`.version`**: versão semântica do seu projeto - **`.minimum_zig_version`**: versão mínima do compilador necessária - **`.paths`**: arquivos incluídos quando o pacote é consumido por terceiros - **`.dependencies`**: mapa de dependências externas ## Adicionando Dependências Para adicionar uma dependência, você pode usar o comando `zig fetch` ou declarar manualmente no `.zon`. Vamos usar o exemplo da biblioteca **zap** (servidor HTTP): ### Usando zig fetch O comando [`zig fetch`](/glossario/zig-fetch/) baixa o pacote e calcula o hash automaticamente: ```bash zig fetch --save https://github.com/zigzap/zap/archive/refs/tags/v0.2.0.tar.gz ``` Isso adiciona a entrada em `.dependencies` automaticamente: ```zig .dependencies = .{ .zap = .{ .url = "https://github.com/zigzap/zap/archive/refs/tags/v0.2.0.tar.gz", .hash = "122054b0f5518a64b1769b1eb6475f44faa8da66120d14a1db0e0a60a0e6ca0c6e13", }, }, ``` ### Declaração manual Você também pode declarar dependências apontando para repositórios Git: ```zig .dependencies = .{ .ziglyph = .{ .url = "git+https://github.com/kubkon/ziglyph#v0.4.0", .hash = "1220a1b...", }, }, ``` O campo `.hash` é um **hash de conteúdo** que garante integridade — se o conteúdo mudar, o build falha. Para obter o hash correto, rode `zig fetch` com a URL e copie o valor gerado. ## Consumindo Dependências no build.zig Depois de declarar a dependência no `.zon`, você precisa **expô-la** no [build.zig](/glossario/build-zig/). Veja como conectar a dependência `zap` ao seu executável: ```zig const std = @import("std"); pub fn build(b: *std.Build) void { const target = b.standardTargetOptions(.{}); const optimize = b.standardOptimizeOption(.{}); // Obtém a dependência declarada no build.zig.zon const zap_dep = b.dependency("zap", .{ .target = target, .optimize = optimize, }); const exe = b.addExecutable(.{ .name = "meu-servidor", .root_source_file = b.path("src/main.zig"), .target = target, .optimize = optimize, }); // Adiciona o módulo da dependência exe.root_module.addImport("zap", zap_dep.module("zap")); b.installArtifact(exe); } ``` A função `b.dependency()` resolve o pacote usando o nome declarado no `.zon`. Depois, `addImport()` expõe o módulo para uso com `@import("zap")` no seu código-fonte. ## Dependências Locais para Desenvolvimento Durante o desenvolvimento, é comum trabalhar com pacotes locais — por exemplo, ao contribuir para uma biblioteca. O Zig permite apontar para caminhos no sistema de arquivos: ```zig .dependencies = .{ .minha_lib = .{ .path = "../minha-lib", }, }, ``` Isso é útil para: - **Desenvolvimento simultâneo** de biblioteca + aplicação - **Testes locais** antes de publicar uma versão - **Monorepos** com múltiplos pacotes interdependentes Quando estiver pronto para publicar, substitua `.path` por `.url` + `.hash`. ## Novidades do Zig 0.16: zig-pkg e Cache Comprimido O [Zig 0.16.0](/artigos/zig-0-16-juicy-main-novidades/) trouxe melhorias importantes no gerenciamento de pacotes: ### Diretório zig-pkg As dependências agora residem em um diretório local `zig-pkg` no projeto, em vez de ficarem apenas no cache global. Isso traz vantagens: ```bash meu-projeto/ ├── build.zig ├── build.zig.zon ├── zig-pkg/ # ← Novo no 0.16 │ ├── zap/ │ └── ziglyph/ └── src/ └── main.zig ``` - **Reprodutibilidade**: cada projeto tem suas dependências isoladas - **Offline builds**: após o primeiro fetch, tudo funciona offline - **Transparência**: você pode inspecionar o código das dependências diretamente ### Cache comprimido global O Zig mantém um cache global comprimido que economiza espaço significativo. Por exemplo, o pacote `freetype` ocupa 13MB no `zig-pkg` local mas apenas 2.4MB no cache comprimido. Pacotes menores como `opus` vão de 707KB para apenas 4KB. ### Flag --fork para debug A nova flag `--fork` permite depurar o processo de resolução de dependências: ```bash zig build --fork ``` Isso é especialmente útil quando você precisa diagnosticar problemas de resolução ou [loops de dependência](/artigos/zig-0-16-juicy-main-novidades/). ## Criando uma Biblioteca Publicável Para transformar seu código em uma biblioteca que outros possam consumir, você precisa configurar o `build.zig.zon` corretamente e expor módulos no `build.zig`. ### Estrutura do projeto ```bash minha-lib-zig/ ├── build.zig ├── build.zig.zon ├── src/ │ ├── lib.zig # Ponto de entrada da biblioteca │ └── internal.zig # Módulos internos ├── tests/ │ └── test_lib.zig ├── LICENSE └── README.md ``` ### Configurando o build.zig.zon O campo `.paths` é crucial — ele define quais arquivos são incluídos quando alguém consome sua biblioteca. O Zig **remove tudo que não está listado** antes de comprimir: ```zig .{ .name = .minha_lib, .version = "1.0.0", .minimum_zig_version = "0.16.0", .paths = .{ "src", "build.zig", "build.zig.zon", "LICENSE", }, .dependencies = .{}, } ``` ### Expondo módulos no build.zig ```zig const std = @import("std"); pub fn build(b: *std.Build) void { const target = b.standardTargetOptions(.{}); const optimize = b.standardOptimizeOption(.{}); // Módulo que será exposto para consumidores const lib_module = b.addModule("minha_lib", .{ .root_source_file = b.path("src/lib.zig"), .target = target, .optimize = optimize, }); // Testes unitários const tests = b.addTest(.{ .root_source_file = b.path("tests/test_lib.zig"), .target = target, .optimize = optimize, }); tests.root_module.addImport("minha_lib", lib_module); const run_tests = b.addRunArtifact(tests); const test_step = b.step("test", "Roda os testes unitários"); test_step.dependOn(&run_tests.step); } ``` ### Publicando via tag Git Para que outros consumam sua lib, basta criar uma tag no repositório: ```bash git tag v1.0.0 git push origin v1.0.0 ``` Os consumidores usam a URL do tarball da tag: ```zig .minha_lib = .{ .url = "https://github.com/seu-user/minha-lib-zig/archive/refs/tags/v1.0.0.tar.gz", .hash = "1220...", }, ``` ## Encontrando Pacotes na Comunidade O ecossistema Zig está crescendo rapidamente. Alguns recursos para encontrar pacotes: - **[Zigistry](https://zigistry.dev/)** — registro de pacotes e programas Zig - **[awesome-zig](https://github.com/catdevnull/awesome-zig)** — lista curada de projetos - **GitHub Topics** — busque por `zig-package` ou `zig-library` Antes de adicionar uma dependência, verifique: 1. **Compatibilidade de versão** com seu `minimum_zig_version` 2. **Atividade do repositório** — commits recentes indicam manutenção ativa 3. **Testes** — bibliotecas com CI configurado são mais confiáveis 4. **Licença** — compatível com seu projeto ## Boas Práticas Após trabalhar com o sistema de pacotes do Zig em vários projetos, estas são as práticas recomendadas: 1. **Sempre use `zig fetch --save`** em vez de copiar hashes manualmente — evita erros de digitação 2. **Fixe versões com tags** — nunca aponte para branches como `main` em produção 3. **Liste apenas arquivos necessários em `.paths`** — reduz o tamanho do pacote drasticamente 4. **Teste com `zig build`** após adicionar dependências — garante que tudo resolve corretamente 5. **Use dependências locais durante desenvolvimento** e mude para URLs antes de fazer merge 6. **Verifique hashes após atualizar** — um hash diferente do esperado pode indicar problemas ## Conclusão O sistema de pacotes do Zig com `build.zig.zon` oferece uma solução elegante e reprodutível para gerenciamento de dependências. Com as melhorias do [0.16.0](/artigos/zig-0-16-juicy-main-novidades/) — diretório `zig-pkg`, cache comprimido e melhor detecção de loops — o fluxo de trabalho ficou ainda mais robusto. Se você está começando com Zig, recomendo seguir nosso [tutorial de introdução](/tutoriais/introducao-ao-zig/) e explorar o [glossário sobre ZON](/glossario/zon/) para entender melhor a sintaxe. Para projetos mais avançados, confira nosso [guia do build system](/artigos/zig-build-system-guia/) que complementa este artigo. O gerenciamento de pacotes é essencial tanto para quem está começando quanto para quem desenvolve em Rust ou Go e quer comparar abordagens. Cada linguagem de sistemas tem sua filosofia — e o Zig aposta na simplicidade e transparência.