Zig no Windows — Resolver Problemas Específicos
O Zig funciona nativamente no Windows, mas existem peculiaridades da plataforma que podem causar problemas. Este guia cobre as situações mais comuns.
Zig Não Encontrado no PATH
Sintoma: 'zig' is not recognized as an internal or external command
Solução:
# Verificar se Zig está no PATH
where zig
# Adicionar ao PATH temporariamente
$env:PATH += ";C:\zig"
# Adicionar ao PATH permanentemente (PowerShell como Admin)
[Environment]::SetEnvironmentVariable("PATH",
"$([Environment]::GetEnvironmentVariable('PATH', 'User'));C:\zig",
"User")
# Ou via Configurações do Sistema:
# Painel de Controle > Sistema > Variáveis de Ambiente > Path > Editar
Se instalou via Scoop ou Chocolatey, o PATH já deveria estar configurado:
scoop install zig
# ou
choco install zig
Antivírus Bloqueando o Zig
Sintoma: Compilação muito lenta ou arquivos sendo deletados.
Causa: Windows Defender e outros antivírus escaneiam cada arquivo gerado durante a compilação.
Solução:
- Abra Segurança do Windows
- Vá em Proteção contra vírus e ameaças
- Clique em Gerenciar configurações
- Em Exclusões, adicione:
- A pasta do projeto (
C:\projetos\meu-app) - A pasta de cache (
C:\projetos\meu-app\zig-cache) - O executável do Zig (
C:\zig\zig.exe) - A pasta do Zig (
C:\zig)
- A pasta do projeto (
# Via PowerShell (Admin)
Add-MpExclusion -Path "C:\zig"
Add-MpExclusion -Path "C:\projetos"
Add-MpExclusion -Process "zig.exe"
Erro: “unable to find MSVC”
Causa: Zig precisa do Windows SDK ou MSVC para linkar com certas bibliotecas do sistema.
Soluções:
# Opção 1: Instalar Visual Studio Build Tools (recomendado)
# Baixe de https://visualstudio.microsoft.com/downloads/
# Selecione "Desktop development with C++"
# Opção 2: Instalar apenas o Windows SDK
# Via winget:
winget install Microsoft.WindowsSDK
# Opção 3: Usar MinGW target para evitar dependência de MSVC
zig build -Dtarget=x86_64-windows-gnu
Problema: Caminhos de Arquivo com Espaços
// Zig lida bem com caminhos, mas scripts e shells podem ter problemas
const caminho = "C:\\Users\\Meu Usuário\\Documentos\\projeto";
// No build.zig — usar paths corretamente
exe.addIncludePath(.{ .cwd_relative = "C:\\libs\\include" });
# No terminal, use aspas para caminhos com espaços
zig build-exe "C:\Meu Projeto\src\main.zig"
Problema: Quebras de Linha (CRLF vs LF)
Sintoma: Zig pode ter problemas com arquivos com terminação de linha Windows (CRLF).
# Configurar Git para checkout LF
git config core.autocrlf input
# .gitattributes para projeto Zig
# *.zig text eol=lf
# *.zon text eol=lf
zig fmt normaliza automaticamente para LF.
Problema: Unicode em Nomes de Arquivo
// Zig suporta Unicode em paths via std.fs
const arquivo = try std.fs.cwd().openFile("dados_café.txt", .{});
defer arquivo.close();
// Para APIs do Windows que precisam de wide strings:
const wide = try std.unicode.utf8ToUtf16LeAlloc(allocator, "café.txt");
defer allocator.free(wide);
Problema: Linkagem com DLLs
// No build.zig
exe.linkSystemLibrary("ws2_32"); // Winsock
exe.linkSystemLibrary("kernel32");
exe.linkSystemLibrary("user32");
// Para DLL customizada
exe.addLibraryPath(.{ .cwd_relative = "C:\\libs" });
exe.linkSystemLibrary("minha_lib");
Problema: Executável Não Roda
Causa: Faltam DLLs de runtime.
# Verificar dependências
# Usar Dependency Walker ou dumpbin
dumpbin /dependents zig-out\bin\meu-app.exe
# Compilar estaticamente para evitar problemas de DLL
# No build.zig:
# exe.linkage = .static;
Console e Cores
// Habilitar cores ANSI no terminal Windows
const std = @import("std");
pub fn main() !void {
const stderr = std.io.getStdErr();
// Em Windows, pode ser necessário habilitar modo ANSI
if (@import("builtin").os.tag == .windows) {
const handle = stderr.handle;
_ = std.os.windows.kernel32.SetConsoleMode(
handle,
std.os.windows.ENABLE_VIRTUAL_TERMINAL_PROCESSING |
std.os.windows.ENABLE_PROCESSED_OUTPUT,
);
}
}
Compilar para Windows a partir de Outro SO
# De Linux/macOS para Windows
zig build -Dtarget=x86_64-windows
# O .exe gerado roda diretamente no Windows
# Sem necessidade de instalar toolchains especiais
Diagnóstico
# Verificar versão do Zig
zig version
# Verificar se Visual Studio Build Tools está instalado
where cl
# Verificar Windows SDK
dir "C:\Program Files (x86)\Windows Kits\10\Include"
# Ver informações do sistema
systeminfo | findstr /B /C:"OS"
Veja Também
- Instalação — Instalar Zig no Windows
- FAQ Build System — Configuração de build
- Cross-Compile Falha — Cross-compilation
- Linkar Biblioteca C — Linkagem com DLLs
- VS Code e ZLS — Editor no Windows