Como Gerenciar Múltiplas Versões do Zig

7 min de leitura
zig zigup versões gerenciamento instalação versionamento

Como Gerenciar Múltiplas Versões do Zig

Conforme você trabalha com o Zig em diferentes projetos, inevitavelmente surge a necessidade de manter múltiplas versões do compilador no mesmo sistema. Um projeto legado pode depender do Zig 0.13.0, enquanto outro exige a versão estável mais recente, e talvez você ainda queira testar funcionalidades experimentais da versão nightly. Este guia apresenta as ferramentas e técnicas para gerenciar essas versões de forma organizada e eficiente.

Se você ainda não instalou o Zig pela primeira vez, comece pelo guia completo de instalação e escolha a plataforma adequada: Ubuntu, Fedora, Arch Linux, macOS ou Windows.

Por Que Gerenciar Múltiplas Versões?

Existem diversos cenários em que manter mais de uma versão do Zig instalada é essencial:

  • Compatibilidade de projetos — Projetos diferentes podem exigir versões diferentes do compilador. O build.zig e as APIs da biblioteca padrão mudam entre versões, e código escrito para uma versão pode não compilar em outra.
  • Testar versões nightly — A versão de desenvolvimento (master/nightly) do Zig traz as funcionalidades mais recentes, mas pode conter mudanças que quebram compatibilidade. Ter acesso a ela sem afetar seu ambiente estável é fundamental.
  • Contribuir com o ecossistema — Se você mantém bibliotecas ou contribui para projetos open-source, precisa testar contra múltiplas versões para garantir compatibilidade.
  • Migração gradual — Ao atualizar um projeto grande para uma nova versão do Zig, é útil manter a versão antiga disponível para comparação e rollback.

Método 1: zigup (Recomendado)

O zigup é um gerenciador de versões dedicado ao Zig, similar ao rustup para Rust ou ao nvm para Node.js. Ele simplifica o download, a instalação e a alternância entre versões.

Instalar o zigup

No Linux e macOS, baixe o binário pré-compilado:

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

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

# macOS (Intel)
curl -LO https://github.com/marler8997/zigup/releases/latest/download/zigup-x86_64-macos.tar.xz
tar -xf zigup-x86_64-macos.tar.xz
sudo mv zigup /usr/local/bin/

No Windows, baixe o executável da página de releases do zigup e adicione o diretório ao PATH.

Verifique a instalação:

zigup --help

Instalar Versões do Zig com zigup

# Instalar a versão estável mais recente
zigup 0.14.0

# Instalar uma versão específica mais antiga
zigup 0.13.0

# Instalar a versão nightly (master)
zigup master

O zigup baixa o compilador e o configura automaticamente no PATH. Cada versão é armazenada em um diretório separado, sem sobrescrever as outras.

Alternar Entre Versões

# Mudar para a versão 0.13.0
zigup default 0.13.0

# Mudar para a versão 0.14.0
zigup default 0.14.0

# Mudar para a nightly
zigup default master

Após trocar, confirme:

zig version

Listar Versões Instaladas

zigup list

Saída esperada:

0.13.0
0.14.0 (default)
master

Remover uma Versão

zigup remove 0.13.0

Atualizar a Versão Nightly

A versão master é atualizada com frequência. Para obter a compilação mais recente:

zigup master

O zigup detecta automaticamente se já existe uma versão master instalada e a substitui pela nova.

Se você prefere não instalar ferramentas adicionais, é possível gerenciar versões manualmente usando diretórios separados e links simbólicos. Esse método funciona em qualquer sistema Linux ou macOS.

Estrutura de Diretórios

Crie um diretório base para armazenar todas as versões:

sudo mkdir -p /opt/zig-versions

Baixe e extraia cada versão em seu próprio subdiretório:

# Versão 0.14.0
curl -LO https://ziglang.org/download/0.14.0/zig-linux-x86_64-0.14.0.tar.xz
tar -xf zig-linux-x86_64-0.14.0.tar.xz
sudo mv zig-linux-x86_64-0.14.0 /opt/zig-versions/0.14.0

# Versão 0.13.0
curl -LO https://ziglang.org/download/0.13.0/zig-linux-x86_64-0.13.0.tar.xz
tar -xf zig-linux-x86_64-0.13.0.tar.xz
sudo mv zig-linux-x86_64-0.13.0 /opt/zig-versions/0.13.0

Use um link simbólico em /usr/local/bin para apontar para a versão ativa:

sudo ln -sf /opt/zig-versions/0.14.0/zig /usr/local/bin/zig

Para alternar para outra versão, basta atualizar o link:

sudo ln -sf /opt/zig-versions/0.13.0/zig /usr/local/bin/zig

Verifique:

zig version

Script de Alternância

Para facilitar a troca, crie um script zigswitch:

#!/bin/bash
set -euo pipefail

ZIG_BASE="/opt/zig-versions"
ZIG_LINK="/usr/local/bin/zig"

if [ $# -eq 0 ]; then
    echo "Versões disponíveis:"
    for dir in "$ZIG_BASE"/*/; do
        version=$(basename "$dir")
        current=""
        if [ "$(readlink -f "$ZIG_LINK")" = "$ZIG_BASE/$version/zig" ]; then
            current=" (ativa)"
        fi
        echo "  $version$current"
    done
    echo ""
    echo "Uso: zigswitch <versão>"
    exit 0
fi

VERSION="$1"

if [ ! -d "$ZIG_BASE/$VERSION" ]; then
    echo "Erro: versão $VERSION não encontrada em $ZIG_BASE"
    echo "Versões disponíveis:"
    ls "$ZIG_BASE"
    exit 1
fi

sudo ln -sf "$ZIG_BASE/$VERSION/zig" "$ZIG_LINK"
echo "Zig alterado para versão $VERSION"
zig version

Salve como /usr/local/bin/zigswitch, torne executável e use:

sudo chmod +x /usr/local/bin/zigswitch

# Listar versões disponíveis
zigswitch

# Alternar para uma versão específica
zigswitch 0.14.0

Método 3: Nix com Ambientes por Projeto

O gerenciador de pacotes Nix oferece uma abordagem declarativa para fixar a versão do Zig por projeto, usando flakes e devshells. Cada projeto pode ter seu próprio flake.nix especificando a versão exata do compilador.

Para um guia completo desse método, consulte a página Instalar Zig com Nix, que cobre flakes, o zig-overlay e a integração com direnv para ativação automática do ambiente.

Exemplo Rápido com Zig Overlay

{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    zig-overlay.url = "github:mitchellh/zig-overlay";
    flake-utils.url = "github:numtide/flake-utils";
  };

  outputs = { self, nixpkgs, zig-overlay, flake-utils }:
    flake-utils.lib.eachDefaultSystem (system:
      let
        pkgs = nixpkgs.legacyPackages.${system};
        zigpkg = zig-overlay.packages.${system};
      in {
        devShells.default = pkgs.mkShell {
          buildInputs = [
            zigpkg."0.13.0"   # Fixar versão específica
            pkgs.zls
          ];
        };
      }
    );
}

Entre no ambiente com nix develop e o Zig 0.13.0 estará disponível automaticamente, sem afetar a instalação global.

Método 4: Docker para Isolamento Total

Outra alternativa é usar containers Docker com versões específicas do Zig. Esse método garante isolamento completo e é especialmente útil em ambientes de CI/CD.

Consulte o guia Usar Zig com Docker para instruções detalhadas sobre como criar imagens com versões específicas do compilador.

Exemplo rápido:

# Executar com Zig 0.14.0
docker run --rm -v $(pwd):/app -w /app minha-imagem-zig:0.14.0 zig build

# Executar com Zig 0.13.0
docker run --rm -v $(pwd):/app -w /app minha-imagem-zig:0.13.0 zig build

Boas Práticas para Gerenciamento de Versões

Documentar a versão exigida pelo projeto

Adicione a versão mínima e máxima suportada do Zig na documentação do projeto. O arquivo build.zig.zon é o local adequado para indicar a versão mínima:

.{
    .name = "meu-projeto",
    .version = "1.0.0",
    .minimum_zig_version = "0.14.0",
    .dependencies = .{},
    .paths = .{
        "build.zig",
        "build.zig.zon",
        "src",
    },
}

Verificar a versão no build.zig

Adicione uma verificação automática no início do build.zig para alertar sobre incompatibilidades:

const std = @import("std");
const builtin = @import("builtin");

pub fn build(b: *std.Build) void {
    // Verificar versão mínima do Zig
    const min_version = std.SemanticVersion.parse("0.14.0") catch unreachable;
    if (builtin.zig_version.order(min_version) == .lt) {
        @compileError("Este projeto requer Zig >= 0.14.0. Versão atual: " ++ builtin.zig_version_string);
    }

    // ... resto do build
    const target = b.standardTargetOptions(.{});
    const optimize = b.standardOptimizeOption(.{});

    const exe = b.addExecutable(.{
        .name = "meu-projeto",
        .root_source_file = b.path("src/main.zig"),
        .target = target,
        .optimize = optimize,
    });

    b.installArtifact(exe);
}

Manter o ZLS compatível

O ZLS (Zig Language Server) precisa ser compatível com a versão do Zig que você está usando. Ao trocar de versão do Zig, certifique-se de usar a versão correspondente do ZLS. Consulte os guias de configuração do VS Code ou do Neovim para saber como configurar o ZLS por projeto.

Testar contra múltiplas versões no CI

Se você mantém uma biblioteca Zig, configure o CI para testar contra todas as versões que deseja suportar. Consulte nosso guia de Zig no GitHub Actions para ver como criar uma matrix de versões no pipeline.

Comparação dos Métodos

MétodoFacilidadeIsolamentoAutomatizaçãoIdeal para
zigupAltaMédioAltaDesenvolvedores individuais
Manual (links simbólicos)MédiaMédioBaixaQuem prefere controle total
Nix (flakes)MédiaAltoAltaEquipes, reprodutibilidade
DockerMédiaMuito altoAltaCI/CD, ambientes descartáveis

Problemas Comuns

“zig version” mostra versão errada após troca

Isso pode acontecer se houver múltiplas entradas do Zig no PATH. Verifique qual binário está sendo executado:

which zig

Se o caminho não for o esperado, revise a ordem das entradas no PATH do seu ~/.bashrc ou ~/.zshrc.

zigup não encontra a versão solicitada

Verifique se a versão existe na página oficial de downloads. Versões muito antigas podem ter sido removidas dos servidores de distribuição.

Conflito entre instalação do sistema e zigup

Se você instalou o Zig via gerenciador de pacotes do sistema (apt, brew, pacman), ele pode ter prioridade sobre o zigup no PATH. Remova a instalação do sistema ou ajuste a ordem do PATH para priorizar o zigup.

Para mais soluções, visite nossa página de erros comuns.

Próximos Passos

Com o gerenciamento de versões configurado:

  1. Compile o Zig do fonte — Se quiser a versão mais recente possível, veja como compilar o Zig do código-fonte
  2. Configure CI/CD — Teste múltiplas versões com GitHub Actions
  3. Crie seu primeiro projeto — Primeiro projeto Zig
  4. Configure seu editor — VS Code ou Neovim
  5. Aprenda a linguagem — Introdução ao Zig
  6. Veja exemplos práticos — Receitas

Explore Mais

🚀 Primeiros Passos 🔧 Build System 📋 Receitas Prontas 💼 Vagas e Carreira ❓ FAQ (50 Perguntas) 🔄 Migrar de Outra Linguagem

Artigos relacionados

Continue aprendendo Zig

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

📚 Ver Todos os Tutoriais 💬 Junte-se à Comunidade