Zig no Linux — Resolver Problemas Específicos

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

Aspectoglibcmusl
CompatibilidadeCom bibliotecas do sistemaBinário portável
TamanhoMaior (linkagem dinâmica)Menor (estático)
PerformanceLigeiramente mais rápidoMuito bom
DistribuiçãoPrecisa de glibc compatívelRoda em qualquer Linux
DNSSuporte completoFuncionalidade 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

Continue aprendendo Zig

Explore mais tutoriais e artigos em português para dominar a linguagem Zig.