---
title: "Cross-Compilation em Zig — O que é e Como Usar"
url: "https://ziglang.com.br/glossario/cross-compilation-em-zig-o-que-%C3%A9-e-como-usar/"
markdown_url: "https://ziglang.com.br/glossario/cross-compilation-em-zig-o-que-%C3%A9-e-como-usar.MD"
description: "Entenda cross-compilation em Zig: compilar código para plataformas diferentes da máquina host. Suporte nativo para 30+ arquiteturas. Guia pt-BR."
date: "2026-02-21"
author: "Zig Brasil"
---

# Cross-Compilation em Zig — O que é e Como Usar

Entenda cross-compilation em Zig: compilar código para plataformas diferentes da máquina host. Suporte nativo para 30+ arquiteturas. Guia pt-BR.


# Cross-Compilation em Zig — O que é e Como Usar

## Definição

**Cross-compilation** (compilação cruzada) é a capacidade de compilar código em uma máquina (host) para ser executado em uma plataforma diferente (target). Zig foi projetado desde o início para suportar cross-compilation de forma nativa, sem necessidade de instalar toolchains adicionais. Basta passar o flag `-target` para compilar para mais de 30 arquiteturas e sistemas operacionais.

Isso contrasta com C/C++, onde cross-compilation tipicamente exige instalar cross-toolchains específicas, configurar sysroots e lidar com incompatibilidades entre versões.

## Por que Cross-Compilation Importa

1. **Desenvolvimento embarcado**: Compilar para ARM, RISC-V ou MIPS diretamente do seu PC x86.
2. **Distribuição multiplataforma**: Gerar binários para Linux, macOS e Windows a partir de uma única máquina.
3. **CI/CD simplificado**: Build pipelines podem gerar todos os artefatos em uma única plataforma.
4. **Sem toolchains extras**: O Zig já inclui tudo necessário para cross-compilation.

## Exemplo Prático

### Cross-Compilation Básica

```bash
# Compilar para Linux x86_64 (a partir de qualquer plataforma)
zig build-exe src/main.zig -target x86_64-linux-gnu

# Compilar para macOS ARM (Apple Silicon)
zig build-exe src/main.zig -target aarch64-macos

# Compilar para Windows x86_64
zig build-exe src/main.zig -target x86_64-windows-gnu

# Compilar para ARM embarcado (bare metal)
zig build-exe src/main.zig -target arm-freestanding-none

# Compilar para WebAssembly
zig build-exe src/main.zig -target wasm32-freestanding
```

### Via build.zig

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

pub fn build(b: *std.Build) void {
    // standardTargetOptions permite -Dtarget= na linha de comando
    const target = b.standardTargetOptions(.{});
    const optimize = b.standardOptimizeOption(.{});

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

// Uso:
// zig build -Dtarget=aarch64-linux-gnu
// zig build -Dtarget=x86_64-windows-gnu -Doptimize=ReleaseFast
```

### Código Condicional por Plataforma

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

pub fn main() void {
    const os_nome = switch (builtin.os.tag) {
        .linux => "Linux",
        .macos => "macOS",
        .windows => "Windows",
        .freestanding => "Bare Metal",
        else => "Outro",
    };

    const arch_nome = switch (builtin.cpu.arch) {
        .x86_64 => "x86_64",
        .aarch64 => "AArch64",
        .arm => "ARM",
        .riscv64 => "RISC-V 64",
        .wasm32 => "WebAssembly",
        else => "Outra",
    };

    std.debug.print("Plataforma: {s} / {s}\n", .{ os_nome, arch_nome });
}
```

## Targets Suportados (Principais)

| Arquitetura | Sistemas |
|------------|---------|
| `x86_64` | Linux, macOS, Windows, FreeBSD |
| `aarch64` | Linux, macOS (Apple Silicon) |
| `arm` | Linux, freestanding (embarcado) |
| `riscv64` | Linux, freestanding |
| `wasm32` | freestanding, wasi |
| `mips` | Linux |
| `powerpc64` | Linux |

## Boas Práticas

- **Use `-musl` para portabilidade máxima no Linux**: O `musl libc` gera binários estáticos que funcionam em qualquer distribuição Linux sem dependências externas.
- **Defina o target no `build.zig`**: Usar `b.standardTargetOptions` permite que o usuário passe `-Dtarget=` na linha de comando, tornando o processo reproduzível.
- **Teste no hardware real ou em QEMU**: Compilar para ARM num x86_64 não garante que o binário funcionará — teste com QEMU user-mode emulation ou no hardware real.
- **Evite caminhos absolutos em comptime**: Se você usa `@embedFile` com caminhos absolutos do host, eles não existirão no target.
- **Separe código específico de plataforma**: Use `comptime` e `builtin` para isolar código específico de SO/arquitetura em blocos bem definidos.

## Comparação com Outras Linguagens

| Ferramenta | Facilidade de cross-compile | Toolchain extra? | Targets suportados |
|-----------|----------------------------|------------------|--------------------|
| Zig | Muito fácil (nativo) | Não | 30+ |
| GCC/Clang | Médio a difícil | Sim | Muitos |
| Go | Fácil (`GOOS`/`GOARCH`) | Não | ~20 |
| Rust | Médio (`cross` tool) | Sim (linker) | Muitos |

A principal vantagem do Zig é que ele embute um compilador C (baseado em Clang/LLVM) e pode inclusive ser usado como cross-compiler para projetos C puros, com o comando `zig cc`.

## Armadilhas Comuns

- **ABI do sistema**: `-gnu` e `-musl` produzem binários diferentes. Use `-musl` para binários estáticos portáveis no Linux.
- **Bibliotecas do sistema**: Cross-compilation com `linkSystemLibrary` pode falhar se a biblioteca não estiver disponível para o target.
- **Paths do host**: Cuidado ao usar caminhos absolutos em comptime — eles são do host, não do target.
- **Endianness**: Algumas arquiteturas são big-endian. Código que assume little-endian pode ter bugs.
- **Testar no target**: Compilar é metade do trabalho — teste o binário na plataforma-alvo.

## Termos Relacionados

- [Target Triple](/glossario/target-triple/) — Formato de especificação de plataforma
- [build.zig](/glossario/build-zig/) — Configuração de cross-compilation no build
- [Release Modes](/glossario/release-modes/) — Otimizações por modo de build
- [LLVM](/glossario/llvm/) — Backend que gera código para múltiplas arquiteturas

## Tutoriais Relacionados

- [Cross-Compilation com Zig](/tutoriais/cross-compilation-zig/)
- [Zig Build System](/tutoriais/zig-build-system/)
- [Zig para Embarcados](/tutoriais/zig-embarcados/)