Como Compilar o Zig do Código-Fonte

Compilar o compilador Zig a partir do código-fonte é um procedimento voltado para usuários avançados, contribuidores do projeto e pessoas que precisam de funcionalidades ainda não lançadas em uma versão estável. Este guia cobre todo o processo, desde a instalação das dependências até a compilação final, em sistemas Linux, macOS e Windows.

Se você busca apenas instalar o Zig para uso cotidiano, os binários pré-compilados são a melhor opção. Consulte o guia completo de instalação para sua plataforma: Ubuntu, Fedora, Arch Linux, macOS ou Windows.

Quando Compilar do Código-Fonte?

Compilar o Zig manualmente faz sentido nos seguintes cenários:

• Contribuir com o projeto — Para enviar patches e pull requests ao repositório oficial do Zig, você precisa de um ambiente de build configurado.
• Acessar a versão mais recente — A branch master do repositório contém as mudanças mais recentes, antes mesmo das releases nightly publicadas.
• Plataformas não suportadas oficialmente — Se sua arquitetura ou sistema operacional não possui binários pré-compilados disponíveis.
• Customizações — Aplicar patches ou modificações locais ao compilador para experimentos ou pesquisa.
• Entender o compilador — Estudar o processo de build é uma excelente forma de compreender a arquitetura interna do Zig.

Requisitos do Sistema

Compilar o Zig exige recursos significativos de hardware e dependências de software específicas.

Hardware Mínimo

• RAM: Mínimo 8 GB (recomendado 16 GB ou mais). A compilação do LLVM e do Zig consome muita memória.
• Disco: Pelo menos 30 GB livres para o código-fonte, artefatos de compilação e cache.
• Processador: Quanto mais núcleos, mais rápida será a compilação. Em máquinas com 4 cores, o processo pode levar de 30 minutos a mais de 1 hora.

Software Necessário

As dependências essenciais são:

• CMake (versão 3.15 ou superior)
• LLVM, Clang e LLD (versão 18 recomendada; deve coincidir com a versão esperada pelo Zig)
• Um compilador C++ com suporte a C++17 (GCC 7+ ou Clang 6+)
• Git para clonar o repositório
• Python 3 (usado por alguns scripts do LLVM)

Instalar Dependências por Plataforma

Ubuntu / Debian

sudo apt update
sudo apt install -y \
    cmake \
    git \
    python3 \
    build-essential \
    llvm-18 \
    llvm-18-dev \
    libclang-18-dev \
    liblld-18-dev \
    libclang-rt-18-dev \
    lld-18

Se a versão 18 do LLVM não estiver disponível nos repositórios padrão, adicione o repositório oficial do LLVM:

# Adicionar repositório LLVM
wget https://apt.llvm.org/llvm.sh
chmod +x llvm.sh
sudo ./llvm.sh 18
sudo apt install -y llvm-18-dev libclang-18-dev liblld-18-dev

Fedora / RHEL

sudo dnf install -y \
    cmake \
    git \
    python3 \
    gcc \
    gcc-c++ \
    llvm18-devel \
    clang18-devel \
    lld-devel \
    lld

Arch Linux

sudo pacman -S --needed \
    cmake \
    git \
    python \
    base-devel \
    llvm \
    clang \
    lld

No Arch Linux, o pacote llvm geralmente já inclui a versão mais recente.

macOS

# Instalar Xcode Command Line Tools (se necessário)
xcode-select --install

# Instalar dependências via Homebrew
brew install cmake llvm lld

No macOS, o LLVM do Homebrew é instalado em um diretório separado do LLVM do sistema. Anote o caminho:

brew --prefix llvm
# Geralmente: /opt/homebrew/opt/llvm (Apple Silicon) ou /usr/local/opt/llvm (Intel)

Você precisará desse caminho na etapa de configuração do CMake.

Windows

No Windows, a compilação é mais complexa. Recomendamos usar o WSL (Windows Subsystem for Linux) e seguir as instruções de Linux. Consulte o guia Instalar Zig no WSL para configurar o WSL.

Se preferir compilar nativamente no Windows, será necessário:

• Visual Studio 2019 ou superior com o componente “Desktop development with C++”
• CMake (incluído no Visual Studio ou instalado separadamente)
• LLVM compilado para Windows (consulte a documentação oficial do LLVM)

Compilar o Zig Passo a Passo

Passo 1: Clonar o Repositório

git clone https://github.com/ziglang/zig.git
cd zig

Para uma versão específica, faça checkout da tag correspondente:

# Para a versão 0.14.0
git checkout 0.14.0

# Para a branch de desenvolvimento
git checkout master

Passo 2: Criar o Diretório de Build

O Zig usa CMake para o sistema de build. Crie um diretório separado para a compilação (out-of-source build):

mkdir build
cd build

Passo 3: Configurar o CMake

No Linux (Ubuntu/Debian/Fedora):

cmake .. \
    -DCMAKE_BUILD_TYPE=Release \
    -DCMAKE_INSTALL_PREFIX=/usr/local

No macOS com LLVM do Homebrew:

cmake .. \
    -DCMAKE_BUILD_TYPE=Release \
    -DCMAKE_PREFIX_PATH="$(brew --prefix llvm)" \
    -DCMAKE_INSTALL_PREFIX=/usr/local

No Arch Linux (onde o LLVM está no caminho padrão):

cmake .. \
    -DCMAKE_BUILD_TYPE=Release \
    -DCMAKE_INSTALL_PREFIX=/usr/local

Opções Úteis do CMake

Passo 4: Compilar

cmake --build . --parallel $(nproc)

O parâmetro --parallel $(nproc) usa todos os núcleos disponíveis do processador. No macOS, substitua $(nproc) por $(sysctl -n hw.ncpu):

cmake --build . --parallel $(sysctl -n hw.ncpu)

Este é o passo mais demorado. Dependendo do hardware, pode levar de 15 minutos a mais de 1 hora. Acompanhe a saída do terminal para verificar o progresso.

Passo 5: Verificar o Build

Após a compilação, o executável estará em ./stage3/bin/zig:

./stage3/bin/zig version

Execute um teste rápido:

./stage3/bin/zig run ../test/standalone/hello_world/main.zig

Passo 6: Instalar no Sistema (Opcional)

Para instalar o Zig compilado no diretório definido em CMAKE_INSTALL_PREFIX:

sudo cmake --install .

Verifique a instalação:

zig version

O Processo de Bootstrap

O Zig tem um processo de bootstrap interessante: o compilador Zig é escrito em Zig. Mas como compilar o Zig sem um compilador Zig? A solução é o bootstrap em três estágios:

1. Stage 1 — Um binário do Zig pré-compilado (baixado automaticamente pelo CMake) é usado como ponto de partida.
2. Stage 2 — O Stage 1 compila o código-fonte do Zig, produzindo um novo compilador.
3. Stage 3 — O Stage 2 recompila o código-fonte novamente, produzindo o compilador final. Este estágio serve para verificar que o compilador é capaz de se compilar a si mesmo de forma determinística.

O CMake gerencia todo esse processo automaticamente. Você não precisa executar cada estágio manualmente.

Build sem LLVM (Experimental)

O projeto Zig está trabalhando em um backend nativo que não depende do LLVM. Para testar essa opção experimental:

cmake .. \
    -DCMAKE_BUILD_TYPE=Release \
    -DZIG_NO_LLVM=ON

Este modo produz um compilador funcional mas sem as otimizações do LLVM. É usado principalmente para acelerar o desenvolvimento do próprio compilador Zig e para targets experimentais.

Executar os Testes

Após compilar, execute a suite de testes para verificar que tudo está funcionando:

# Testes rápidos (recomendado para uma verificação inicial)
./stage3/bin/zig build test -Dskip-non-native

# Suite completa de testes (pode levar bastante tempo)
./stage3/bin/zig build test

Os testes incluem testes unitários do compilador, testes da biblioteca padrão, testes de comportamento e testes de compilação. A suite completa pode levar de 30 minutos a várias horas, dependendo do hardware.

Manter o Build Atualizado

Para acompanhar as mudanças na branch master:

cd /caminho/para/zig
git pull origin master

cd build
cmake --build . --parallel $(nproc)

Se a atualização causar erros de compilação, tente limpar o diretório de build:

cd /caminho/para/zig/build
rm -rf *
cmake .. -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=/usr/local
cmake --build . --parallel $(nproc)

Se você trabalha com múltiplas versões do Zig, consulte o guia sobre gerenciamento de versões para organizar as versões compiladas.

Problemas Comuns

“Could NOT find LLVM”

O CMake não encontrou o LLVM no sistema. Soluções:

# Especificar o caminho manualmente
cmake .. -DCMAKE_PREFIX_PATH=/usr/lib/llvm-18

# No macOS com Homebrew
cmake .. -DCMAKE_PREFIX_PATH=$(brew --prefix llvm)

Compilação termina com erro de memória

O processo de compilação pode consumir mais de 8 GB de RAM. Soluções:

• Reduza o paralelismo: cmake --build . --parallel 2
• Adicione swap ao sistema: sudo fallocate -l 4G /swapfile && sudo mkswap /swapfile && sudo swapon /swapfile
• Use uma máquina com mais memória

Versão do LLVM incompatível

O Zig exige uma versão específica do LLVM. Verifique o arquivo CMakeLists.txt na raiz do repositório para saber qual versão é esperada:

grep -i "find_package(LLVM" CMakeLists.txt

Instale a versão correta usando os repositórios do LLVM ou compile o LLVM do fonte.

Erro “cannot find -lLLVM-18” no Linux

Instale os pacotes de desenvolvimento do LLVM:

# Ubuntu/Debian
sudo apt install llvm-18-dev

# Fedora
sudo dnf install llvm18-devel

Build demora muito

A compilação do Zig (especialmente com LLVM) é um processo intensivo. Algumas dicas para acelerar:

• Use um disco SSD
• Aumente o paralelismo (se a memória permitir)
• Use ccache para cache de compilação C++: sudo apt install ccache e cmake .. -DCMAKE_C_COMPILER_LAUNCHER=ccache -DCMAKE_CXX_COMPILER_LAUNCHER=ccache
• Considere usar a opção -DCMAKE_BUILD_TYPE=Release em vez de Debug, pois produz um compilador mais rápido

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

Contribuindo com o Projeto Zig

Se compilou o Zig do fonte para contribuir com o projeto, aqui estão os próximos passos:

1. Leia o guia de contribuição no repositório oficial
2. Explore os issues marcados como “good first issue” no GitHub
3. Participe da comunidade nos fóruns e canais de discussão do Zig
4. Teste suas mudanças executando a suite de testes completa antes de enviar um pull request

Próximos Passos

Com o Zig compilado do código-fonte:

1. Gerencie versões — Organize builds locais com o guia de gerenciamento de versões
2. Configure seu editor — VS Code ou Neovim
3. Crie um projeto — Primeiro projeto Zig
4. Configure CI/CD — GitHub Actions com Zig
5. Aprenda a linguagem — Introdução ao Zig
6. Veja exemplos — Receitas