Migração Zig 0.11 para 0.12

Introdução

A migração de Zig 0.11 para 0.12 foi uma das mais significativas na história da linguagem, com mudanças substanciais no sistema de build, compilador self-hosted e biblioteca padrão. Este guia documenta as mudanças mais importantes e como adaptar seu código.

Para a migração seguinte, veja Migração Zig 0.12 para 0.13. Para o roadmap completo, consulte O Futuro da Programação de Sistemas com Zig.

Pré-requisitos

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

Mudança Principal: Compilador Self-Hosted

Zig 0.12 completou a transição para o compilador self-hosted. O compilador anterior (stage1, escrito em C++) foi removido. Isso significa:

• Compilação mais rápida para a maioria dos projetos
• Mensagens de erro melhoradas
• Melhor suporte a comptime
• Alguns comportamentos sutis podem diferir do stage1

Mudanças no Sistema de Build

Introdução do build.zig.zon

Zig 0.12 introduziu build.zig.zon para gerenciamento de dependências, substituindo o sistema anterior:

// build.zig.zon (novo em 0.12)
.{
    .name = "meu-projeto",
    .version = "0.1.0",
    .dependencies = .{
        .minha_dep = .{
            .url = "https://github.com/user/repo/archive/v1.0.0.tar.gz",
            .hash = "1220abc...",
        },
    },
    .paths = .{""},
}

Mudanças em APIs de Build

// 0.11 (antigo)
const exe = b.addExecutable("programa", "src/main.zig");
exe.setBuildMode(b.standardReleaseOptions());

// 0.12 (novo)
const exe = b.addExecutable(.{
    .name = "programa",
    .root_source_file = .{ .path = "src/main.zig" },
    .target = b.standardTargetOptions(.{}),
    .optimize = b.standardOptimizeOption(.{}),
});

addCSourceFiles

A API para adicionar fontes C mudou significativamente:

// 0.11
exe.addCSourceFile("src/lib.c", &.{"-Wall"});

// 0.12
exe.addCSourceFile(.{
    .file = .{ .path = "src/lib.c" },
    .flags = &.{"-Wall"},
});

Veja Migrar de Makefile para build.zig e Migrar de CMake para build.zig para exemplos atualizados.

Mudanças na Linguagem

Remoção de @Type para certas construções

Algumas construções de tipo que funcionavam em 0.11 foram restringidas ou reformuladas em 0.12.

Mudanças em Builtins

Alguns builtins foram renomeados ou tiveram suas assinaturas alteradas:

// Verificar uso de builtins como:
// @intCast, @floatCast, @ptrCast
// As semânticas foram refinadas em 0.12

// 0.11: precisava de dois argumentos
const x = @intCast(u32, valor);

// 0.12: tipo inferido do contexto
const x: u32 = @intCast(valor);

Mudanças em Casting

A forma de fazer casts mudou significativamente:

// 0.11
const ptr = @intToPtr(*u8, endereco);
const num = @ptrToInt(ptr);

// 0.12
const ptr: *u8 = @ptrFromInt(endereco);
const num = @intFromPtr(ptr);

Outros casts renomeados:

Simplificação de @intCast e similares

// 0.11: tipo destino como primeiro argumento
const y = @intCast(u16, x);
const z = @floatCast(f32, valor_f64);

// 0.12: tipo inferido do contexto
const y: u16 = @intCast(x);
const z: f32 = @floatCast(valor_f64);

Mudanças na Biblioteca Padrão

std.mem

Verifique funções de std.mem que podem ter mudado:

// Uso atualizado
const resultado = std.mem.indexOf(u8, haystack, needle);
const igual = std.mem.eql(u8, str1, str2);

std.fs

API de sistema de arquivos refinada:

// 0.12
const dir = try std.fs.cwd().openDir("pasta", .{});
defer dir.close();

std.ArrayList

Verificar se a API de ArrayList mudou para sua versão:

var lista = std.ArrayList(u8).init(allocator);
defer lista.deinit();
try lista.append(42);
try lista.appendSlice("dados");

Processo de Migração Passo a Passo

1. Backup do Projeto

git checkout -b migrar-para-0.12

2. Criar build.zig.zon

Se não existe, crie o arquivo build.zig.zon:

.{
    .name = "meu-projeto",
    .version = "0.1.0",
    .dependencies = .{},
    .paths = .{""},
}

3. Atualizar build.zig

Reescrever usando a nova API de build. Esta é geralmente a mudança mais trabalhosa.

4. Atualizar Casts

Usar search-and-replace para atualizar todos os casts renomeados. A lista na seção anterior serve como referência.

5. Compilar e Corrigir

zig build 2>&1 | head -100

O compilador indica cada problema. Corrija um por um.

6. Executar Testes

zig build test

Veja Testes Unitários para padrões atualizados.

Dicas Importantes

1. Não tente migrar tudo de uma vez: Corrija o build.zig primeiro, depois o código
2. Leia as mensagens de erro: O compilador 0.12 geralmente sugere a correção exata
3. Verifique dependências: Certifique-se de que suas dependências suportam 0.12
4. Teste extensivamente: O compilador self-hosted pode gerar código diferente do stage1
5. Consulte o changelog oficial: O release notes documenta cada mudança em detalhe

Conclusão

A migração de 0.11 para 0.12 é uma das mais impactantes na história de Zig, principalmente pela mudança para o compilador self-hosted e a nova API de build. Apesar do esforço, o resultado é um compilador mais rápido, mais correto, e com melhor suporte a comptime.

O processo é facilitado pelas mensagens de erro claras do compilador Zig. Para continuar atualizando, veja Migração Zig 0.12 para 0.13. Para entender o ciclo de releases, consulte Zig 2026: Estado Atual e Roadmap.