@embedFile em Zig

O @embedFile incorpora o conteúdo de um arquivo diretamente no binário compilado, em tempo de compilação. Retorna um ponteiro para um array de bytes constante. Ideal para incluir recursos como arquivos de texto, SQL, HTML, imagens ou certificados sem dependências externas em runtime.

Sintaxe

@embedFile(comptime path: []const u8) *const [N]u8

Parâmetros

• path ([]const u8, comptime): Caminho do arquivo relativo ao diretório do arquivo-fonte atual, ou relativo a um caminho de include configurado no build.zig.

Valor de retorno

Retorna *const [N]u8 — ponteiro para array de bytes constante, onde N é o tamanho do arquivo em bytes. O compilador determina N automaticamente.

Exemplos práticos

Exemplo 1: Incorporar arquivo de texto

const std = @import("std");

// Incorpora o conteúdo de "versao.txt" no binário
const versao = @embedFile("versao.txt");

pub fn main() void {
    std.debug.print("Versão: {s}\n", .{versao});
    std.debug.print("Tamanho: {} bytes\n", .{versao.len});
}

Exemplo 2: SQL embutido

const std = @import("std");

const sql_criar_tabela = @embedFile("sql/criar_tabela.sql");
const sql_inserir = @embedFile("sql/inserir.sql");

fn executarSQL(conexao: anytype, query: []const u8) !void {
    try conexao.exec(query);
}

pub fn main() !void {
    // As queries SQL são compiladas no binário
    // Não precisa carregar arquivos em runtime
    std.debug.print("Query de criação ({} bytes):\n{s}\n", .{
        sql_criar_tabela.len,
        sql_criar_tabela,
    });
}

Exemplo 3: Dados binários (certificado, imagem)

const std = @import("std");

const certificado_raiz = @embedFile("certs/ca-bundle.crt");
const icone = @embedFile("assets/icone.png");

pub fn main() void {
    std.debug.print("Certificado: {} bytes\n", .{certificado_raiz.len});
    std.debug.print("Ícone: {} bytes\n", .{icone.len});

    // Os dados estão disponíveis como slices de bytes
    // Prontos para uso sem I/O de arquivo
    if (std.mem.startsWith(u8, icone, &[_]u8{ 0x89, 'P', 'N', 'G' })) {
        std.debug.print("Formato: PNG confirmado\n", .{});
    }
}

Casos de uso comuns

1. Queries SQL: Incorporar arquivos .sql para executar sem carregar do disco.
2. Templates HTML: Incluir templates de página no binário do servidor.
3. Certificados TLS: Embutir certificados raiz sem dependência do sistema.
4. Shaders: Incluir shaders GLSL/HLSL compilados no binário.
5. Dados de teste: Incorporar fixtures de teste diretamente no binário de testes.
6. Assets: Imagens, ícones e fontes para aplicações self-contained.

Builtins relacionados

• @import — Importa módulos Zig (não dados binários)
• @compileError — Gera erro se arquivo não existir
• @src — Informações de localização no código-fonte

Tutoriais relacionados

• Zig Build System
• Comptime em Zig
• Introdução ao Zig