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
- Gerenciamento de dependências: Declara pacotes externos de forma reprodutível.
- Verificação de integridade: Cada dependência tem um hash para garantir que o conteúdo é o esperado.
- Sem registro central obrigatório: Dependências podem vir de URLs, Git ou caminhos locais.
- 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
| 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
# 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 buildfalha. Usezig fetchpara 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
.dependenciesdeve corresponder ao usado emb.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