zigup — Gerenciador de Versões do Zig: Instalação e Uso

Trabalhar com Zig frequentemente exige lidar com múltiplas versões do compilador. Projetos diferentes podem depender de versões específicas, você pode querer testar o nightly build mais recente sem comprometer seu ambiente estável, ou precisa manter compatibilidade com versões anteriores. O zigup resolve todos esses problemas de forma elegante, funcionando como o nvm do Node.js ou o rustup do Rust, mas para o ecossistema Zig.

O Que É o zigup

O zigup é um gerenciador de versões do compilador Zig que permite instalar, remover e alternar entre diferentes versões com comandos simples. Escrito em Zig, ele é rápido, leve e não possui dependências externas. O zigup baixa binários oficiais diretamente dos servidores de distribuição do Zig, garantindo integridade e autenticidade.

Instalação do zigup

Download Direto

A forma mais simples é baixar o binário pré-compilado:

# Linux x86_64
curl -L https://github.com/marler8997/zigup/releases/latest/download/zigup-x86_64-linux.tar.xz | tar -xJ
sudo mv zigup /usr/local/bin/

# macOS x86_64
curl -L https://github.com/marler8997/zigup/releases/latest/download/zigup-x86_64-macos.tar.xz | tar -xJ
sudo mv zigup /usr/local/bin/

# macOS ARM64 (Apple Silicon)
curl -L https://github.com/marler8997/zigup/releases/latest/download/zigup-aarch64-macos.tar.xz | tar -xJ
sudo mv zigup /usr/local/bin/

# Windows (PowerShell)
Invoke-WebRequest -Uri "https://github.com/marler8997/zigup/releases/latest/download/zigup-x86_64-windows.zip" -OutFile zigup.zip
Expand-Archive zigup.zip

Compilação a Partir do Fonte

Se você já tem uma versão do Zig instalada:

git clone https://github.com/marler8997/zigup
cd zigup
zig build -Doptimize=ReleaseSafe
sudo cp zig-out/bin/zigup /usr/local/bin/

Via Gerenciadores de Pacotes

# Homebrew (macOS e Linux)
brew install zigup

# Nix
nix-env -iA nixpkgs.zigup

Configuração Inicial

Após instalar o zigup, configure o diretório onde as versões do Zig serão armazenadas:

# O zigup usa ~/.local/share/zigup por padrão no Linux
# e ~/Library/zigup no macOS

# Verifique a configuração
zigup --help

Certifique-se de que o diretório de binários do zigup está no seu PATH. Adicione ao seu .bashrc, .zshrc ou equivalente:

export PATH="$HOME/.local/share/zigup:$PATH"

Comandos Essenciais

Instalar uma Versão

# Instalar versão específica
zigup install 0.13.0

# Instalar o nightly mais recente
zigup install master

# Instalar e definir como padrão
zigup default 0.13.0

Listar Versões Instaladas

zigup list
# Saída:
# 0.12.0
# 0.13.0
# 0.14.0-dev.1234+abcdef
# master (default)

Alternar Entre Versões

# Definir versão padrão
zigup default 0.13.0

# Verificar versão ativa
zig version
# 0.13.0

Remover uma Versão

zigup remove 0.12.0

Atualizar o Nightly

# Baixar a build master mais recente
zigup install master

# Isso substitui a versão master anterior

Fluxo de Trabalho com Múltiplos Projetos

Um cenário comum é ter projetos que dependem de versões diferentes do Zig. O zigup facilita essa gestão:

# Projeto A usa Zig 0.13.0
cd ~/projetos/projeto-a
zigup default 0.13.0
zig build

# Projeto B usa a versão de desenvolvimento
cd ~/projetos/projeto-b
zigup default master
zig build

# Voltar para o projeto A
cd ~/projetos/projeto-a
zigup default 0.13.0

Dica: Scripts de Projeto

Crie um script setup.sh na raiz de cada projeto para automatizar a seleção de versão:

#!/bin/bash
# setup.sh
REQUIRED_ZIG="0.13.0"
zigup default $REQUIRED_ZIG
echo "Zig $REQUIRED_ZIG ativado para este projeto"

Integração com ZLS

O ZLS (Zig Language Server) precisa corresponder à versão do compilador Zig em uso. O zigup pode gerenciar o ZLS em conjunto:

# Instalar ZLS correspondente à versão do Zig
zigup fetch-zls 0.13.0

# O ZLS será automaticamente selecionado junto com a versão do Zig
zigup default 0.13.0
# Agora tanto zig quanto zls apontam para a versão 0.13.0

Essa integração é essencial para garantir que o autocompletar e os diagnósticos do editor estejam sincronizados com o compilador.

Integração com CI/CD

O zigup é útil em pipelines de CI/CD para garantir versões reproduzíveis:

# GitHub Actions
- name: Instalar zigup
  run: |
    curl -L https://github.com/marler8997/zigup/releases/latest/download/zigup-x86_64-linux.tar.xz | tar -xJ
    sudo mv zigup /usr/local/bin/

- name: Instalar Zig
  run: |
    zigup install 0.13.0
    zigup default 0.13.0

- name: Build
  run: zig build

- name: Testes
  run: zig build test

# GitLab CI
build:
  script:
    - curl -L https://github.com/marler8997/zigup/releases/latest/download/zigup-x86_64-linux.tar.xz | tar -xJ
    - mv zigup /usr/local/bin/
    - zigup install 0.13.0
    - zigup default 0.13.0
    - zig build
    - zig build test

Comparação com Alternativas

Download Manual

Sem o zigup, gerenciar versões requer download manual, extração e manipulação de PATH. Isso é tedioso e propenso a erros, especialmente quando se precisa alternar frequentemente.

Docker

Usar containers Docker com diferentes versões do Zig é uma alternativa, mas adiciona overhead e complexidade. O zigup é mais leve e rápido para desenvolvimento local.

asdf

O gerenciador de versões genérico asdf tem um plugin para Zig, mas o zigup oferece melhor integração com o ecossistema (como o gerenciamento conjunto do ZLS) e é mantido por membros ativos da comunidade Zig.

Resolução de Problemas

Versão Não Encontrada

Se o zigup não encontra uma versão, verifique se ela existe nos releases oficiais. Versões de desenvolvimento seguem o formato 0.14.0-dev.NNNN+hash.

Conflito de PATH

Se zig version mostra uma versão diferente da esperada, verifique se não há outra instalação do Zig no PATH com prioridade maior:

which -a zig
# Deve mostrar apenas o caminho gerenciado pelo zigup

Permissões

Em Linux, o zigup armazena binários em ~/.local/share/zigup/. Certifique-se de que esse diretório tem permissões corretas:

chmod -R u+rwx ~/.local/share/zigup/

Boas Práticas

1. Documente a versão do Zig necessária no README de cada projeto
2. Use versões estáveis para projetos em produção; reserve o master para experimentação
3. Atualize o ZLS sempre que mudar a versão do compilador
4. Automatize no CI usando zigup para garantir reprodutibilidade
5. Limpe versões antigas periodicamente com zigup remove para economizar espaço em disco

Próximos Passos

Com o zigup configurado, explore o sistema de build e o gerenciador de pacotes para montar seu ambiente de desenvolvimento completo. Consulte nossos tutoriais para projetos práticos e a seção de carreira para oportunidades profissionais com Zig.