FAQ Build System do Zig — Compilação e Configuração
O build system integrado é uma das grandes vantagens do Zig. Aqui estão as perguntas mais frequentes sobre compilação, configuração e build.
1. O que é o build.zig?
build.zig é o arquivo de configuração do build system do Zig, escrito na própria linguagem Zig. Diferente de Makefiles, CMake ou Cargo.toml, o build.zig é código Zig real que configura como o projeto é compilado:
const std = @import("std");
pub fn build(b: *std.Build) void {
const target = b.standardTargetOptions(.{});
const optimize = b.standardOptimizeOption(.{});
const exe = b.addExecutable(.{
.name = "meu-app",
.root_source_file = b.path("src/main.zig"),
.target = target,
.optimize = optimize,
});
b.installArtifact(exe);
}
2. Como inicio um novo projeto?
# Criar um novo projeto executável
mkdir meu-projeto && cd meu-projeto
zig init
# Isso cria:
# build.zig — configuração do build
# build.zig.zon — manifesto de dependências
# src/main.zig — ponto de entrada
# src/root.zig — biblioteca raiz
3. Como adiciono dependências externas?
Zig usa o Zig Package Manager com o arquivo build.zig.zon:
// build.zig.zon
.{
.name = "meu-projeto",
.version = "0.1.0",
.dependencies = .{
.zap = .{
.url = "https://github.com/zigzap/zap/archive/v0.1.0.tar.gz",
.hash = "...", // hash de integridade
},
},
}
Depois, no build.zig:
const zap = b.dependency("zap", .{
.target = target,
.optimize = optimize,
});
exe.root_module.addImport("zap", zap.module("zap"));
4. Como faço cross-compilation?
Uma das maiores vantagens do Zig: cross-compilation sem configuração especial:
# Compilar para Linux ARM (ex: Raspberry Pi)
zig build -Dtarget=aarch64-linux
# Compilar para Windows a partir de Linux
zig build -Dtarget=x86_64-windows
# Compilar para macOS a partir de Linux
zig build -Dtarget=x86_64-macos
# Compilar para WebAssembly
zig build -Dtarget=wasm32-freestanding
Não é necessário instalar toolchains adicionais. Zig inclui tudo que precisa.
5. Quais são os modos de compilação e quando usar cada um?
# Debug (padrão) — para desenvolvimento
zig build
# ReleaseSafe — para produção com segurança
zig build -Doptimize=ReleaseSafe
# ReleaseFast — para máxima performance
zig build -Doptimize=ReleaseFast
# ReleaseSmall — para menor tamanho de binário
zig build -Doptimize=ReleaseSmall
- Debug: Compilação rápida, runtime lento, todas as verificações de segurança ativas
- ReleaseSafe: Compilação lenta, runtime rápido, mantém verificações de segurança
- ReleaseFast: Compilação lenta, runtime máximo, remove verificações de segurança
- ReleaseSmall: Compilação lenta, binário mínimo, ideal para embarcados e WASM
6. Como compilo código C junto com Zig?
// No build.zig
const exe = b.addExecutable(.{
.name = "meu-app",
.root_source_file = b.path("src/main.zig"),
.target = target,
.optimize = optimize,
});
// Adicionar arquivos C
exe.addCSourceFiles(.{
.files = &.{ "src/lib.c", "src/utils.c" },
.flags = &.{ "-Wall", "-O2" },
});
// Incluir diretórios de headers
exe.addIncludePath(b.path("include"));
// Linkar com biblioteca do sistema
exe.linkSystemLibrary("pthread");
exe.linkLibC();
7. Como adiciono testes ao build?
// No build.zig
const unit_tests = b.addTest(.{
.root_source_file = b.path("src/main.zig"),
.target = target,
.optimize = optimize,
});
const run_unit_tests = b.addRunArtifact(unit_tests);
const test_step = b.step("test", "Rodar testes unitários");
test_step.dependOn(&run_unit_tests.step);
Execute com zig build test.
8. O que é zig build vs zig build-exe vs zig run?
| Comando | Descrição |
|---|---|
zig build | Usa build.zig para compilar o projeto |
zig build-exe arquivo.zig | Compila um arquivo direto sem build.zig |
zig run arquivo.zig | Compila e executa imediatamente |
zig test arquivo.zig | Compila e roda testes de um arquivo |
Para projetos reais, use sempre zig build com um build.zig.
9. Como uso Zig como compilador C?
Zig pode ser usado como drop-in replacement para gcc ou clang:
# Compilar código C com Zig
zig cc -o programa main.c -lm
# Compilar C++ com Zig
zig c++ -o programa main.cpp -lstdc++
# Cross-compile C para outra plataforma
zig cc -target aarch64-linux-gnu -o programa main.c
Muitos projetos C usam Zig apenas como compilador para aproveitar a cross-compilation fácil.
10. Como limpo o cache de compilação?
# Limpar cache e saída do projeto
rm -rf zig-cache .zig-cache zig-out
# Limpar cache global do Zig
rm -rf ~/.cache/zig
O cache do Zig é seguro para deletar. Ele será recriado automaticamente na próxima compilação.
11. Como crio um step customizado no build?
pub fn build(b: *std.Build) void {
// Step customizado que roda um comando
const gerar_docs = b.addSystemCommand(&.{
"python3", "scripts/gerar_docs.py",
});
const docs_step = b.step("docs", "Gerar documentação");
docs_step.dependOn(&gerar_docs.step);
// Agora: zig build docs
}
12. Como publico um pacote Zig?
Para tornar seu código disponível como dependência:
- Crie um
build.zig.zoncom nome e versão - Exporte módulos no
build.zig - Publique no GitHub ou outro host
- Outros projetos referenciam pela URL e hash
// build.zig — exportar módulo
const modulo = b.addModule("minha-lib", .{
.root_source_file = b.path("src/lib.zig"),
});
_ = modulo;
Veja Também
- Erros no build.zig — Resolver erros do build system
- Compilação Lenta — Otimizar tempo de compilação
- Cross-Compile Falha — Resolver erros de cross-compilation
- Falha em Dependências — Problemas com packages
- Instalação — Instalar e configurar o Zig