Cheatsheet: Comandos CLI do Zig
O compilador Zig é uma ferramenta multifuncional que serve como compilador, linker, test runner, formatador de código e até compilador C/C++. Este guia cobre todos os comandos que você precisa conhecer para trabalhar eficientemente com Zig no terminal.
Comandos Principais
zig build — Compilar projeto via build.zig
# Compilar o projeto (modo debug padrão)
zig build
# Compilar e executar
zig build run
# Executar testes
zig build test
# Compilar com otimização
zig build -Doptimize=ReleaseSafe
zig build -Doptimize=ReleaseFast
zig build -Doptimize=ReleaseSmall
# Cross-compile
zig build -Dtarget=x86_64-linux-gnu
zig build -Dtarget=aarch64-macos-none
zig build -Dtarget=x86_64-windows-msvc
# Passar argumentos para o executável
zig build run -- arg1 arg2 arg3
# Ver todos os steps e opções disponíveis
zig build --help
# Modo verbose — ver comandos executados
zig build --verbose
# Especificar diretório de saída
zig build --prefix ./minha-saida
# Limpar artefatos
zig build --prefix-override ./zig-out && rm -rf zig-out
zig build-exe — Compilar executável diretamente
# Compilar arquivo único
zig build-exe main.zig
# Com otimização
zig build-exe main.zig -OReleaseFast
# Cross-compile
zig build-exe main.zig -target x86_64-linux-gnu
# Nome de saída customizado
zig build-exe main.zig --name meu-programa
# Linkar com libc
zig build-exe main.zig -lc
# Linkar com biblioteca
zig build-exe main.zig -lSDL2 -lc
# Adicionar caminho de include
zig build-exe main.zig -I/usr/local/include
# Strip de símbolos (binário menor)
zig build-exe main.zig -OReleaseSafe --strip
# Compilar e rodar
zig run main.zig
# Com argumentos
zig run main.zig -- arg1 arg2
# Com otimização
zig run main.zig -OReleaseFast
zig test — Executar testes
# Rodar todos os testes de um arquivo
zig test arquivo.zig
# Filtrar testes por nome
zig test arquivo.zig --test-filter "somar"
# Modo release
zig test arquivo.zig -OReleaseSafe
# Verbose — ver quais testes executaram
zig test arquivo.zig --verbose
# Com libc
zig test arquivo.zig -lc
# Formatar arquivo
zig fmt main.zig
# Formatar diretório recursivamente
zig fmt src/
# Verificar formatação sem alterar (CI)
zig fmt --check main.zig
zig fmt --check src/
# Ler de stdin
cat main.zig | zig fmt --stdin
Compilação de Bibliotecas
# Biblioteca estática
zig build-lib lib.zig
# Biblioteca dinâmica (shared)
zig build-lib lib.zig -dynamic
# Gerar header C
zig build-lib lib.zig -femit-h
# Biblioteca com otimização
zig build-lib lib.zig -OReleaseFast
# Objeto (sem linkar)
zig build-obj modulo.zig
Ferramentas de Tradução e Análise
zig translate-c — Traduzir C para Zig
# Traduzir header C para Zig
zig translate-c header.h
# Com defines
zig translate-c -D_GNU_SOURCE header.h
# Com include paths
zig translate-c -I/usr/include header.h
# Salvar saída
zig translate-c header.h > header.zig
zig cc / zig c++ — Compilador C/C++ drop-in
# Zig como compilador C (drop-in replacement para gcc/clang)
zig cc -o programa main.c
zig cc -O2 -o programa main.c util.c -lm
# Zig como compilador C++
zig c++ -o programa main.cpp -lstdc++
# Cross-compile com zig cc
zig cc -target x86_64-linux-gnu -o programa main.c
zig cc -target aarch64-linux-musl -o programa main.c
# Usar com projetos existentes (substituir CC)
CC="zig cc" make
CC="zig cc" cmake ..
Gerenciamento de Dependências
# Buscar hash de uma dependência
zig fetch https://github.com/autor/lib/archive/v1.0.tar.gz
# Buscar hash e salvar no cache
zig fetch --save https://github.com/autor/lib/archive/v1.0.tar.gz
# Limpar cache de dependências
rm -rf ~/.cache/zig
# Versão do compilador
zig version
# Informações do ambiente
zig env
# Listar todos os targets suportados
zig targets
# Listar bibliotecas disponíveis no sistema
zig libc
# Zen do Zig (filosofia)
zig zen
Opções de Compilação
Tabela de flags comuns
| Flag | Descrição |
|---|
-ODebug | Sem otimização, com verificações (padrão) |
-OReleaseSafe | Otimizado com verificações de segurança |
-OReleaseFast | Máxima performance |
-OReleaseSmall | Menor binário possível |
-target X | Cross-compile para target X |
-lc | Linkar com libc |
-lNOME | Linkar com biblioteca NOME |
-I PATH | Adicionar caminho de include |
-L PATH | Adicionar caminho de biblioteca |
--strip | Remover símbolos de debug |
--name NOME | Nome do artefato de saída |
-femit-h | Gerar header C |
--verbose | Saída detalhada |
Targets comuns
# Linux
zig build -Dtarget=x86_64-linux-gnu
zig build -Dtarget=x86_64-linux-musl # estático com musl
zig build -Dtarget=aarch64-linux-gnu # ARM 64-bit
# macOS
zig build -Dtarget=x86_64-macos
zig build -Dtarget=aarch64-macos # Apple Silicon
# Windows
zig build -Dtarget=x86_64-windows-msvc
zig build -Dtarget=x86_64-windows-gnu # MinGW
# WebAssembly
zig build -Dtarget=wasm32-freestanding
zig build -Dtarget=wasm32-wasi
# Embedded
zig build -Dtarget=thumb-freestanding # ARM Cortex-M
zig build -Dtarget=riscv32-freestanding # RISC-V
Cache e Limpeza
# Localização do cache global
ls ~/.cache/zig/
# Cache do projeto (local)
ls zig-cache/ 2>/dev/null || ls .zig-cache/ 2>/dev/null
# Limpar cache do projeto
rm -rf zig-cache .zig-cache
# Limpar artefatos de build
rm -rf zig-out
Variáveis de Ambiente
| Variável | Descrição |
|---|
ZIG_LOCAL_CACHE_DIR | Diretório do cache local |
ZIG_GLOBAL_CACHE_DIR | Diretório do cache global |
ZIG_LIB_DIR | Diretório da biblioteca padrão |
CC | Compilador C (para zig cc) |
Dicas e Atalhos
# Compilar e rodar rápido (modo script)
zig run solucao.zig
# Ver AST de um arquivo
zig ast-check arquivo.zig
# Ver assembly gerado
zig build-exe main.zig -femit-asm
# Ver LLVM IR
zig build-exe main.zig -femit-llvm-ir
# Compilação paralela (padrão, usa todos os cores)
# Limitar threads:
zig build -j4 # usar 4 threads
Veja Também