Zig no Linux — Resolver Problemas Específicos
Zig roda nativamente no Linux e é a plataforma principal de desenvolvimento. Mesmo assim, existem problemas específicos que podem ocorrer dependendo da distribuição e configuração.
Zig Não Encontrado após Instalação
Sintoma: zig: command not found
# Verificar se está no PATH
which zig
echo $PATH
# Adicionar ao PATH (bash)
echo 'export PATH=$PATH:/caminho/para/zig' >> ~/.bashrc
source ~/.bashrc
# Ou para zsh
echo 'export PATH=$PATH:/caminho/para/zig' >> ~/.zshrc
source ~/.zshrc
# Verificar se o binário tem permissão de execução
ls -la /caminho/para/zig
chmod +x /caminho/para/zig
Erro: “GLIBC_X.XX not found”
Causa: O binário do Zig (ou de programa compilado) requer uma versão de glibc mais nova que a do sistema.
# Verificar versão do glibc
ldd --version
# Soluções:
# 1. Usar musl em vez de glibc (recomendado)
zig build -Dtarget=x86_64-linux-musl
# 2. Compilar com linkagem estática
# No build.zig:
# exe.linkage = .static;
# 3. Atualizar o sistema (se possível)
sudo apt update && sudo apt upgrade
Para distribuição de binários, musl é recomendado pois gera binários completamente estáticos que rodam em qualquer distribuição Linux.
Erro: Faltam Pacotes de Desenvolvimento
Sintoma: Headers não encontrados ao usar @cImport.
# Ubuntu/Debian — instalar headers de desenvolvimento
sudo apt install build-essential
sudo apt install libssl-dev # OpenSSL
sudo apt install libsqlite3-dev # SQLite
sudo apt install libz-dev # zlib
sudo apt install pkg-config # Para encontrar bibliotecas
# Fedora/RHEL
sudo dnf groupinstall "Development Tools"
sudo dnf install openssl-devel
sudo dnf install sqlite-devel
sudo dnf install zlib-devel
sudo dnf install pkg-config
# Arch Linux
sudo pacman -S base-devel
sudo pacman -S openssl
sudo pacman -S sqlite
sudo pacman -S pkg-config
Problema: Permissões de Execução
# Binário compilado não executa
chmod +x ./zig-out/bin/meu-app
# Verificar se o sistema permite execução no diretório
# Partições montadas com 'noexec' bloqueiam execução
mount | grep $(df . --output=source | tail -1)
# Se estiver em /tmp com noexec:
# Mova para outro diretório ou remonte
Problema: libc Linking
// No build.zig — escolher entre glibc e musl
const target = b.standardTargetOptions(.{});
// Para binário que roda em qualquer Linux:
// zig build -Dtarget=x86_64-linux-musl
// Para usar bibliotecas do sistema que dependem de glibc:
// zig build -Dtarget=x86_64-linux-gnu
exe.linkLibC();
glibc vs musl
| Aspecto | glibc | musl |
|---|---|---|
| Compatibilidade | Com bibliotecas do sistema | Binário portável |
| Tamanho | Maior (linkagem dinâmica) | Menor (estático) |
| Performance | Ligeiramente mais rápido | Muito bom |
| Distribuição | Precisa de glibc compatível | Roda em qualquer Linux |
| DNS | Suporte completo | Funcionalidade limitada |
Problema: Distro Antiga com Kernel Antigo
# Verificar versão do kernel
uname -r
# Zig requer kernel relativamente recente para algumas features
# Se o kernel é muito antigo:
# Opção 1: Atualizar o kernel
sudo apt install linux-generic-hwe-22.04 # Ubuntu
# Opção 2: Compilar com musl para maior compatibilidade
zig build -Dtarget=x86_64-linux-musl
Problema: perf e Profiling
# Instalar perf
# Ubuntu/Debian
sudo apt install linux-tools-common linux-tools-$(uname -r)
# Fedora
sudo dnf install perf
# Rodar com perf
perf record ./zig-out/bin/meu-app
perf report
# Se perf diz "access denied":
# Temporário:
sudo sysctl kernel.perf_event_paranoid=-1
# Permanente:
echo 'kernel.perf_event_paranoid=-1' | sudo tee /etc/sysctl.d/99-perf.conf
sudo sysctl -p
Problema: Systemd Service
Para rodar um binário Zig como serviço:
# /etc/systemd/system/meu-app.service
[Unit]
Description=Meu App Zig
After=network.target
[Service]
Type=simple
ExecStart=/opt/meu-app/meu-app
Restart=on-failure
RestartSec=5
User=meu-app
Group=meu-app
WorkingDirectory=/opt/meu-app
# Limites de memória e CPU (opcional)
MemoryMax=512M
CPUQuota=200%
[Install]
WantedBy=multi-user.target
sudo systemctl daemon-reload
sudo systemctl enable --now meu-app
sudo systemctl status meu-app
sudo journalctl -u meu-app -f # Ver logs
Problema: Docker
# Dockerfile mínimo para app Zig
FROM alpine:latest AS runner
# Alpine usa musl — compile com -Dtarget=x86_64-linux-musl
COPY zig-out/bin/meu-app /usr/local/bin/meu-app
CMD ["meu-app"]
# Ou binário estático com scratch (menor imagem possível)
FROM scratch
COPY zig-out/bin/meu-app /app
ENTRYPOINT ["/app"]
# Compilar para Docker (musl para imagem Alpine/scratch)
zig build -Dtarget=x86_64-linux-musl -Doptimize=ReleaseSafe
# Build e rodar
docker build -t meu-app .
docker run meu-app
Problema: Valgrind e Sanitizers
# Instalar Valgrind
sudo apt install valgrind # Ubuntu/Debian
sudo dnf install valgrind # Fedora
# Rodar com Valgrind
valgrind --leak-check=full --show-leak-kinds=all ./zig-out/bin/meu-app
# Usar AddressSanitizer do Zig
zig build-exe src/main.zig -fsanitize=address
./main
Veja Também
- Instalação — Instalar Zig no Linux
- Cross-Compile Falha — Compilação cruzada
- Linkar Biblioteca C — Problemas de linkagem
- CI Falha — Zig em pipelines CI
- FAQ Build System — Configuração de build