---
title: "Como Compilar o Zig do Código-Fonte"
url: "https://ziglang.com.br/instalacao/como-compilar-o-zig-do-c%C3%B3digo-fonte/"
markdown_url: "https://ziglang.com.br/instalacao/como-compilar-o-zig-do-c%C3%B3digo-fonte.MD"
description: "Guia passo a passo para compilar o compilador Zig a partir do código-fonte. Instalação do LLVM e CMake, processo de bootstrap e troubleshooting."
date: "2026-02-21"
author: "Zig Brasil"
---

# Como Compilar o Zig do Código-Fonte

Guia passo a passo para compilar o compilador Zig a partir do código-fonte. Instalação do LLVM e CMake, processo de bootstrap e troubleshooting.


# 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](/instalacao/) para sua plataforma: [Ubuntu](/instalacao/instalar-zig-linux-ubuntu/), [Fedora](/instalacao/instalar-zig-linux-fedora/), [Arch Linux](/instalacao/instalar-zig-linux-arch/), [macOS](/instalacao/instalar-zig-macos/) ou [Windows](/instalacao/instalar-zig-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

```bash
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:

```bash
# 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

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

### Arch Linux

```bash
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

```bash
# 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:

```bash
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](/instalacao/instalar-zig-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

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

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

```bash
# 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):

```bash
mkdir build
cd build
```

### Passo 3: Configurar o CMake

No **Linux** (Ubuntu/Debian/Fedora):

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

No **macOS** com LLVM do Homebrew:

```bash
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):

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

#### Opções Úteis do CMake

| Opção | Descrição |
|---|---|
| `-DCMAKE_BUILD_TYPE=Release` | Compilação otimizada (recomendada) |
| `-DCMAKE_BUILD_TYPE=Debug` | Compilação com símbolos de debug |
| `-DCMAKE_INSTALL_PREFIX=/caminho` | Diretório de instalação |
| `-DZIG_STATIC_LLVM=ON` | Linkar LLVM estaticamente |
| `-DZIG_TARGET_TRIPLE=...` | Cross-compilar para outra plataforma |

### Passo 4: Compilar

```bash
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)`:

```bash
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`:

```bash
./stage3/bin/zig version
```

Execute um teste rápido:

```bash
./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`:

```bash
sudo cmake --install .
```

Verifique a instalação:

```bash
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:

```bash
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:

```bash
# 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`:

```bash
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:

```bash
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](/instalacao/zig-gerenciar-versoes/) para organizar as versões compiladas.

---

## Problemas Comuns

### "Could NOT find LLVM"

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

```bash
# 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:

```bash
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:

```bash
# 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](/erros/).

---

## 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](https://github.com/ziglang/zig/blob/master/CONTRIBUTING.md)
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](/instalacao/zig-gerenciar-versoes/)
2. **Configure seu editor** — [VS Code](/instalacao/configurar-vscode-zig/) ou [Neovim](/instalacao/configurar-neovim-zig/)
3. **Crie um projeto** — [Primeiro projeto Zig](/instalacao/zig-primeiro-projeto/)
4. **Configure CI/CD** — [GitHub Actions com Zig](/instalacao/zig-ci-github-actions/)
5. **Aprenda a linguagem** — [Introdução ao Zig](/tutoriais/introducao-ao-zig/)
6. **Veja exemplos** — [Receitas](/receitas/)