---
title: "Cross-Compile Falha em Zig — Resolver Erros de Compilação Cruzada"
url: "https://ziglang.com.br/troubleshooting/cross-compile-falha-em-zig-resolver-erros-de-compila%C3%A7%C3%A3o-cruzada/"
markdown_url: "https://ziglang.com.br/troubleshooting/cross-compile-falha-em-zig-resolver-erros-de-compila%C3%A7%C3%A3o-cruzada.MD"
description: "Guia para resolver erros de cross-compilation em Zig. Targets não encontrados, linkagem falhando, libc, headers faltando e problemas comuns de compilação cruzada."
date: "2026-02-21"
author: "Zig Brasil"
---

# Cross-Compile Falha em Zig — Resolver Erros de Compilação Cruzada

Guia para resolver erros de cross-compilation em Zig. Targets não encontrados, linkagem falhando, libc, headers faltando e problemas comuns de compilação cruzada.


# Cross-Compile Falha em Zig — Resolver Erros de Compilação Cruzada

Uma das grandes vantagens do Zig é a cross-compilation nativa. Quando ela falha, geralmente há uma causa específica e solucionável. Este guia cobre os problemas mais comuns.

## Erro: "unknown target"

**Causa:** O target especificado não é reconhecido pelo Zig.

**Solução:**
```bash
# Listar todos os targets disponíveis
zig targets | head -100

# Formato correto: arch-os-abi
zig build -Dtarget=aarch64-linux-gnu       # Linux ARM64
zig build -Dtarget=x86_64-windows-msvc     # Windows x64
zig build -Dtarget=x86_64-macos-none       # macOS x64
zig build -Dtarget=wasm32-freestanding-none # WASM
```

Verifique a lista completa com `zig targets` e use o formato exato `arch-os-abi`.

## Erro: "unable to find libc"

**Causa:** O target requer libc mas os headers não estão disponíveis.

**Solução:**
```zig
// No build.zig — linkar libc explicitamente
exe.linkLibC();

// Ou usar a libc bundled do Zig
// Zig inclui headers de libc para a maioria dos targets
```

```bash
# Verificar se o target tem libc bundled
zig build -Dtarget=aarch64-linux-gnu
# Zig inclui headers glibc para Linux

# Para targets sem libc bundled, pode ser necessário:
zig build -Dtarget=aarch64-linux-musl  # musl é frequentemente mais fácil
```

## Erro: "missing system library"

**Causa:** Seu código depende de bibliotecas do sistema que não existem no target.

**Solução:**
```zig
// PROBLEMA: biblioteca do sistema não disponível para o target
exe.linkSystemLibrary("openssl");

// SOLUÇÃO 1: Compilar a dependência como parte do build
exe.addCSourceFiles(.{
    .files = &.{ "vendor/openssl/ssl.c" },
});

// SOLUÇÃO 2: Usar alternativa pura Zig
// Exemplo: std.crypto em vez de OpenSSL

// SOLUÇÃO 3: Condicional por target
const target = b.standardTargetOptions(.{});
if (target.result.os.tag == .linux) {
    exe.linkSystemLibrary("rt");
}
```

## Erro: Headers C Não Encontrados

**Causa:** `@cImport` usa headers específicos da plataforma host, não do target.

**Solução:**
```zig
// No build.zig — especificar caminhos de headers
exe.addIncludePath(b.path("include/cross"));

// Ou usar headers específicos por plataforma
const target_os = target.result.os.tag;
if (target_os == .windows) {
    exe.addIncludePath(b.path("include/win32"));
} else if (target_os == .macos) {
    exe.addIncludePath(b.path("include/macos"));
}
```

## Problema: Binário Não Executa no Target

**Causa:** Linkagem dinâmica com bibliotecas que não existem no sistema alvo.

```bash
# Verificar dependências do binário
# No Linux:
ldd ./meu-app

# SOLUÇÃO: Compilar com linkagem estática
```

```zig
// No build.zig — forçar linkagem estática
exe.linkage = .static;

// Ou usar musl para Linux (sempre estático)
// zig build -Dtarget=x86_64-linux-musl
```

## Problema: WASM Cross-Compilation

```bash
# Compilar para WASM
zig build -Dtarget=wasm32-freestanding

# Se usar libc:
zig build -Dtarget=wasm32-wasi  # WASI inclui libc mínima
```

```zig
// No build.zig para WASM
const exe = b.addExecutable(.{
    .name = "app",
    .root_source_file = b.path("src/main.zig"),
    .target = b.resolveTargetQuery(.{
        .cpu_arch = .wasm32,
        .os_tag = .freestanding,
    }),
});

// Exportar funções para JavaScript
exe.export_symbol_names = &.{"processar"};
```

## Problema: macOS Cross-Compilation

```bash
# Compilar PARA macOS a partir de Linux/Windows
zig build -Dtarget=x86_64-macos
zig build -Dtarget=aarch64-macos  # Apple Silicon

# Problemas comuns:
# - Frameworks do sistema (Cocoa, Metal) não estão disponíveis
# - Code signing é necessário para executar em macOS real
```

Para aplicações que usam frameworks Apple, cross-compilation pura não é suficiente. Considere usar CI com runners macOS.

## Problema: Windows Cross-Compilation

```bash
# Compilar PARA Windows a partir de Linux/macOS
zig build -Dtarget=x86_64-windows

# Gerar .exe e .pdb (debug symbols)
zig build -Dtarget=x86_64-windows -Doptimize=ReleaseSafe
```

```zig
// Código condicional por plataforma
const builtin = @import("builtin");

const separador = if (builtin.os.tag == .windows) '\\' else '/';
```

## Diagnóstico de Cross-Compilation

```bash
# Ver detalhes do que o compilador está fazendo
zig build -Dtarget=aarch64-linux --verbose

# Verificar o target que está sendo usado
zig build -Dtarget=aarch64-linux --verbose 2>&1 | grep target

# Listar targets suportados com filtro
zig targets 2>&1 | python3 -c "import sys,json; print('\n'.join(json.load(sys.stdin)['arch']))"
```

## Checklist para Cross-Compilation

1. Verifique se o target está correto: `arch-os-abi`
2. Use `linkLibC()` se precisar de libc
3. Prefira musl sobre glibc para Linux (mais portável)
4. Use linkagem estática quando possível
5. Evite dependências de sistema (`linkSystemLibrary`) em cross-compilation
6. Teste o binário no target real ou em um emulador (QEMU)

## Veja Também

- [FAQ Build System](/faq/faq-build-system/) — Configuração de build e targets
- [Erros no build.zig](/troubleshooting/zig-build-zig-erros/) — Problemas gerais de build
- [Linkar Biblioteca C](/troubleshooting/zig-c-library-link/) — Problemas de linkagem
- [WASM Problemas](/troubleshooting/zig-wasm-problemas/) — WebAssembly específico
- [Instalação](/instalacao/) — Instalar Zig em diferentes plataformas