---
title: "Migração Zig 0.11 para 0.12"
url: "https://ziglang.com.br/tutoriais/migra%C3%A7%C3%A3o-zig-0.11-para-0.12/"
markdown_url: "https://ziglang.com.br/tutoriais/migra%C3%A7%C3%A3o-zig-0.11-para-0.12.MD"
description: "Guia de migração de Zig 0.11 para 0.12. Mudanças no build system, remoção de recursos deprecated, atualizações na stdlib, nova sintaxe e breaking changes documentados."
date: "2026-02-21"
author: "Zig Brasil"
---

# Migração Zig 0.11 para 0.12

Guia de migração de Zig 0.11 para 0.12. Mudanças no build system, remoção de recursos deprecated, atualizações na stdlib, nova sintaxe e breaking changes documentados.


## 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](/tutoriais/zig-0-12-para-0-13/). Para o roadmap completo, consulte [O Futuro da Programação de Sistemas com Zig](/artigos/zig-futuro-sistemas/).

## Pré-requisitos

- Projeto funcional em Zig 0.11
- Zig 0.12 instalado. Veja [Como Instalar Zig](/tutoriais/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:

```zig
// 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

```zig
// 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:

```zig
// 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](/tutoriais/migrar-makefile-para-build-zig/) e [Migrar de CMake para build.zig](/tutoriais/migrar-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:

```zig
// 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:

```zig
// 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:

| 0.11 | 0.12 |
|------|------|
| `@intToPtr` | `@ptrFromInt` |
| `@ptrToInt` | `@intFromPtr` |
| `@intToFloat` | `@floatFromInt` |
| `@floatToInt` | `@intFromFloat` |
| `@intToEnum` | `@enumFromInt` |
| `@enumToInt` | `@intFromEnum` |
| `@boolToInt` | `@intFromBool` |
| `@errSetCast` | `@errorCast` |

### Simplificação de @intCast e similares

```zig
// 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:

```zig
// 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:

```zig
// 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:

```zig
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

```bash
git checkout -b migrar-para-0.12
```

### 2. Criar build.zig.zon

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

```zig
.{
    .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

```bash
zig build 2>&1 | head -100
```

O compilador indica cada problema. Corrija um por um.

### 6. Executar Testes

```bash
zig build test
```

Veja [Testes Unitários](/receitas/zig-teste-unitario-basico/) 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](/tutoriais/zig-0-12-para-0-13/). Para entender o ciclo de releases, consulte [Zig 2026: Estado Atual e Roadmap](/artigos/zig-2026-estado-atual-roadmap/).