---
title: "FAQ Build System do Zig — Compilação e Configuração"
url: "https://ziglang.com.br/faq/faq-build-system-do-zig-compila%C3%A7%C3%A3o-e-configura%C3%A7%C3%A3o/"
markdown_url: "https://ziglang.com.br/faq/faq-build-system-do-zig-compila%C3%A7%C3%A3o-e-configura%C3%A7%C3%A3o.MD"
description: "Perguntas frequentes sobre o build system do Zig. Como funciona build.zig, cross-compilation, dependências, modos de compilação e integração com C."
date: "2026-02-21"
author: "Zig Brasil"
---

# FAQ Build System do Zig — Compilação e Configuração

Perguntas frequentes sobre o build system do Zig. Como funciona build.zig, cross-compilation, dependências, modos de compilação e integração com C.


# FAQ Build System do Zig — Compilação e Configuração

O build system integrado é uma das grandes vantagens do Zig. Aqui estão as perguntas mais frequentes sobre compilação, configuração e build.

## 1. O que é o build.zig?

`build.zig` é o arquivo de configuração do build system do Zig, escrito **na própria linguagem Zig**. Diferente de Makefiles, CMake ou Cargo.toml, o build.zig é código Zig real que configura como o projeto é compilado:

```zig
const std = @import("std");

pub fn build(b: *std.Build) void {
    const target = b.standardTargetOptions(.{});
    const optimize = b.standardOptimizeOption(.{});

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

    b.installArtifact(exe);
}
```

## 2. Como inicio um novo projeto?

```bash
# Criar um novo projeto executável
mkdir meu-projeto && cd meu-projeto
zig init

# Isso cria:
# build.zig        — configuração do build
# build.zig.zon    — manifesto de dependências
# src/main.zig     — ponto de entrada
# src/root.zig     — biblioteca raiz
```

## 3. Como adiciono dependências externas?

Zig usa o **Zig Package Manager** com o arquivo `build.zig.zon`:

```zig
// build.zig.zon
.{
    .name = "meu-projeto",
    .version = "0.1.0",
    .dependencies = .{
        .zap = .{
            .url = "https://github.com/zigzap/zap/archive/v0.1.0.tar.gz",
            .hash = "...", // hash de integridade
        },
    },
}
```

Depois, no `build.zig`:

```zig
const zap = b.dependency("zap", .{
    .target = target,
    .optimize = optimize,
});
exe.root_module.addImport("zap", zap.module("zap"));
```

## 4. Como faço cross-compilation?

Uma das maiores vantagens do Zig: **cross-compilation sem configuração especial**:

```bash
# Compilar para Linux ARM (ex: Raspberry Pi)
zig build -Dtarget=aarch64-linux

# Compilar para Windows a partir de Linux
zig build -Dtarget=x86_64-windows

# Compilar para macOS a partir de Linux
zig build -Dtarget=x86_64-macos

# Compilar para WebAssembly
zig build -Dtarget=wasm32-freestanding
```

Não é necessário instalar toolchains adicionais. Zig inclui tudo que precisa.

## 5. Quais são os modos de compilação e quando usar cada um?

```bash
# Debug (padrão) — para desenvolvimento
zig build

# ReleaseSafe — para produção com segurança
zig build -Doptimize=ReleaseSafe

# ReleaseFast — para máxima performance
zig build -Doptimize=ReleaseFast

# ReleaseSmall — para menor tamanho de binário
zig build -Doptimize=ReleaseSmall
```

- **Debug:** Compilação rápida, runtime lento, todas as verificações de segurança ativas
- **ReleaseSafe:** Compilação lenta, runtime rápido, mantém verificações de segurança
- **ReleaseFast:** Compilação lenta, runtime máximo, remove verificações de segurança
- **ReleaseSmall:** Compilação lenta, binário mínimo, ideal para embarcados e WASM

## 6. Como compilo código C junto com Zig?

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

// Adicionar arquivos C
exe.addCSourceFiles(.{
    .files = &.{ "src/lib.c", "src/utils.c" },
    .flags = &.{ "-Wall", "-O2" },
});

// Incluir diretórios de headers
exe.addIncludePath(b.path("include"));

// Linkar com biblioteca do sistema
exe.linkSystemLibrary("pthread");
exe.linkLibC();
```

## 7. Como adiciono testes ao build?

```zig
// No build.zig
const unit_tests = b.addTest(.{
    .root_source_file = b.path("src/main.zig"),
    .target = target,
    .optimize = optimize,
});

const run_unit_tests = b.addRunArtifact(unit_tests);

const test_step = b.step("test", "Rodar testes unitários");
test_step.dependOn(&run_unit_tests.step);
```

Execute com `zig build test`.

## 8. O que é `zig build` vs `zig build-exe` vs `zig run`?

| Comando | Descrição |
|---------|-----------|
| `zig build` | Usa `build.zig` para compilar o projeto |
| `zig build-exe arquivo.zig` | Compila um arquivo direto sem build.zig |
| `zig run arquivo.zig` | Compila e executa imediatamente |
| `zig test arquivo.zig` | Compila e roda testes de um arquivo |

Para projetos reais, use sempre `zig build` com um `build.zig`.

## 9. Como uso Zig como compilador C?

Zig pode ser usado como **drop-in replacement** para `gcc` ou `clang`:

```bash
# Compilar código C com Zig
zig cc -o programa main.c -lm

# Compilar C++ com Zig
zig c++ -o programa main.cpp -lstdc++

# Cross-compile C para outra plataforma
zig cc -target aarch64-linux-gnu -o programa main.c
```

Muitos projetos C usam Zig apenas como compilador para aproveitar a cross-compilation fácil.

## 10. Como limpo o cache de compilação?

```bash
# Limpar cache e saída do projeto
rm -rf zig-cache .zig-cache zig-out

# Limpar cache global do Zig
rm -rf ~/.cache/zig
```

O cache do Zig é seguro para deletar. Ele será recriado automaticamente na próxima compilação.

## 11. Como crio um step customizado no build?

```zig
pub fn build(b: *std.Build) void {
    // Step customizado que roda um comando
    const gerar_docs = b.addSystemCommand(&.{
        "python3", "scripts/gerar_docs.py",
    });

    const docs_step = b.step("docs", "Gerar documentação");
    docs_step.dependOn(&gerar_docs.step);

    // Agora: zig build docs
}
```

## 12. Como publico um pacote Zig?

Para tornar seu código disponível como dependência:

1. Crie um `build.zig.zon` com nome e versão
2. Exporte módulos no `build.zig`
3. Publique no GitHub ou outro host
4. Outros projetos referenciam pela URL e hash

```zig
// build.zig — exportar módulo
const modulo = b.addModule("minha-lib", .{
    .root_source_file = b.path("src/lib.zig"),
});
_ = modulo;
```

## Veja Também

- [Erros no build.zig](/troubleshooting/zig-build-zig-erros/) — Resolver erros do build system
- [Compilação Lenta](/troubleshooting/zig-lento-compilar/) — Otimizar tempo de compilação
- [Cross-Compile Falha](/troubleshooting/zig-cross-compile-falha/) — Resolver erros de cross-compilation
- [Falha em Dependências](/troubleshooting/zig-dependencia-falha/) — Problemas com packages
- [Instalação](/instalacao/) — Instalar e configurar o Zig