Migração Zig 0.12 para 0.13

Introdução

A transição de Zig 0.12 para 0.13 traz melhorias significativas no compilador, na biblioteca padrão e no sistema de build. Como Zig ainda está em fase pré-1.0, breaking changes são esperados entre versões. Este guia documenta as mudanças mais impactantes e como adaptar seu código.

Para a migração anterior, veja Migração Zig 0.11 para 0.12. Para entender o roadmap de Zig, consulte O Futuro da Programação de Sistemas com Zig.

Pré-requisitos

• Projeto funcional em Zig 0.12
• Zig 0.13 instalado. Veja Como Instalar Zig

Mudanças no Sistema de Build

Atualização do build.zig.zon

O formato do arquivo build.zig.zon recebeu atualizações. Verifique se seu arquivo está compatível:

// build.zig.zon (formato 0.13)
.{
    .name = "meu-projeto",
    .version = "0.1.0",
    .dependencies = .{},
    .paths = .{
        "build.zig",
        "build.zig.zon",
        "src",
    },
}

Mudanças em addCSourceFiles

A API de addCSourceFiles foi refinada. Verifique a assinatura atualizada:

// 0.12 (antigo)
exe.addCSourceFiles(&.{"src/main.c"}, &.{"-Wall"});

// 0.13 (novo)
exe.addCSourceFiles(.{
    .files = &.{"src/main.c"},
    .flags = &.{"-Wall"},
});

LazyPath e Build.path

O tipo LazyPath foi refinado para melhor manuseio de caminhos:

// 0.12
exe.addIncludePath(.{ .path = "include" });

// 0.13
exe.addIncludePath(b.path("include"));

Mudanças na Linguagem

Atualização de Sintaxe de Structs Anônimas

Verifique o uso de struct literals anônimos que podem ter mudado:

// Verificar a sintaxe de inicialização
const ponto = Ponto{ .x = 1.0, .y = 2.0 };

Melhorias em Comptime

O comptime recebeu melhorias de performance e novas capacidades. Código que era muito lento ou atingia limites em 0.12 pode funcionar melhor em 0.13.

Tratamento de Erros

Verificações de erros foram refinadas. Algumas expressões que silenciosamente ignoravam erros em 0.12 agora geram warnings ou erros de compilação em 0.13:

// Se seu código fazia isso sem tratar o erro:
// 0.12: podia passar silenciosamente
// 0.13: requer tratamento explícito
const resultado = funcaoQuePodeErrar() catch |err| {
    std.log.err("Erro: {}", .{err});
    return err;
};

Mudanças na Biblioteca Padrão

std.mem e std.fmt

Verifique se funções que você usa de std.mem e std.fmt mantiveram a mesma assinatura. Mudanças comuns incluem:

// Verificar assinaturas de funções como:
const resultado = std.fmt.allocPrint(allocator, "Olá {s}", .{nome});

std.fs

Operações com o sistema de arquivos podem ter mudanças sutis na API:

// Verificar uso de openFile, createFile, etc.
const arquivo = try std.fs.cwd().openFile("dados.txt", .{});
defer arquivo.close();

std.json

O parser JSON recebeu melhorias. Se você usa std.json, verifique a API atualizada:

const parsed = try std.json.parseFromSlice(MeuTipo, allocator, json_string, .{});
defer parsed.deinit();
const valor = parsed.value;

Veja nosso tutorial de parsing JSON em Zig.

std.http

O cliente e servidor HTTP podem ter mudanças. Consulte a documentação oficial de 0.13 para detalhes:

var client = std.http.Client{ .allocator = allocator };
defer client.deinit();

Processo de Migração

Passo 1: Atualizar o Zig

# Baixar Zig 0.13
# Verificar a versão
zig version

Passo 2: Tentar Compilar

zig build 2>&1 | head -50

O compilador mostrará erros para código incompatível. Trabalhe nos erros um por um.

Passo 3: Corrigir build.zig

Comece corrigindo o build.zig, pois sem ele nada compila:

1. Atualizar assinaturas de funções de build
2. Atualizar referências a LazyPath
3. Verificar chamadas a addCSourceFiles
4. Verificar build.zig.zon

Passo 4: Corrigir Código Fonte

Depois que o build compila, corrija os erros no código fonte:

1. Verificar imports da stdlib que mudaram
2. Atualizar chamadas de API que mudaram
3. Tratar novos warnings como erros

Passo 5: Executar Testes

zig build test

Verifique se todos os testes passam. Veja Testes Unitários para boas práticas.

Passo 6: Atualizar Dependências

Verifique se suas dependências em build.zig.zon são compatíveis com 0.13:

zig fetch --save https://github.com/dep/repo/archive/v0.13-compat.tar.gz

Dicas de Migração

1. Leia o release notes oficial: A documentação oficial de Zig detalha cada breaking change
2. Migre branch separado: Crie um branch para a migração e só merge quando tudo funcionar
3. Use o compilador como guia: As mensagens de erro de Zig são geralmente claras e sugerem a correção
4. Teste em modo debug primeiro: Modo debug ativa verificações extras que podem revelar problemas
5. Atualize dependências primeiro: Muitas bibliotecas publicam versões compatíveis com a nova release

Compatibilidade com Código C

Se seu projeto usa interop com C (via @cImport), a migração geralmente é transparente — o código C não precisa mudar. O que pode mudar é como Zig traduz tipos C:

const c = @cImport({
    @cInclude("minha_lib.h");
});
// Verificar se os tipos traduzidos mantiveram a mesma estrutura

Veja Interoperabilidade C-Zig.

Conclusão

A migração entre versões de Zig é parte da vida de trabalhar com uma linguagem pré-1.0. Os benefícios — compilador melhor, stdlib mais robusta, bugs corrigidos — geralmente compensam o esforço de migração. O processo é facilitado pelas mensagens de erro claras do compilador.

Para o contexto das mudanças entre versões, veja Zig 2026: Estado Atual e Roadmap. Para decidir se vale a pena manter projetos em Zig pré-1.0, consulte Quando Usar Zig.