--- title: "Linker Error — Como Resolver em Zig" url: "https://ziglang.com.br/erros/linker-error-como-resolver-em-zig/" markdown_url: "https://ziglang.com.br/erros/linker-error-como-resolver-em-zig.MD" description: "Entenda os erros de linker em Zig, que ocorrem ao vincular código objeto com bibliotecas externas ou C. Veja como diagnosticar e corrigir." date: "2026-02-21" author: "Zig Brasil" --- # Linker Error — Como Resolver em Zig Entenda os erros de linker em Zig, que ocorrem ao vincular código objeto com bibliotecas externas ou C. Veja como diagnosticar e corrigir. # Linker Error — Como Resolver em Zig ## O Que Este Erro Significa Erros de linker em Zig ocorrem na etapa final da compilação, quando o linker tenta combinar o código objeto compilado com bibliotecas externas para gerar o executável ou biblioteca final. O linker precisa resolver todos os símbolos (funções, variáveis) referenciados pelo código — se algum símbolo não é encontrado ou há conflito, o processo falha. Mensagens típicas: ``` error: undefined symbol: funcao_externa ``` ``` error: library not found: -lssl ``` ``` error: relocation overflow ``` Estes erros são mais comuns ao usar interoperabilidade com C (`@cImport`), bibliotecas externas ou cross-compilation. ## Causas Comuns ### 1. Biblioteca C Não Instalada ```zig const c = @cImport({ @cInclude("openssl/ssl.h"); }); // ERRO DE LINKER: library not found: -lssl ``` ### 2. Símbolo Externo Não Definido ```zig // Declaração de função externa que não existe extern fn funcao_que_nao_existe() void; pub fn main() void { funcao_que_nao_existe(); // ERRO: undefined symbol } ``` ### 3. Falta Vincular Biblioteca no build.zig ```zig // build.zig — SEM linkagem da biblioteca const exe = b.addExecutable(.{ .name = "meu-projeto", .root_source_file = b.path("src/main.zig"), .target = target, .optimize = optimize, }); // Falta: exe.linkSystemLibrary("ssl"); ``` ### 4. Biblioteca Estática Não Encontrada ```bash $ zig build # error: unable to find library: -lminha_lib # library search paths: /usr/lib, /usr/local/lib ``` ### 5. Conflito de Símbolos Duplicados ```zig // Dois módulos exportam a mesma função export fn processar() void {} // Módulo A export fn processar() void {} // Módulo B // ERRO: duplicate symbol: processar ``` ## Como Corrigir ### Solucao 1: Instalar Bibliotecas de Desenvolvimento ```bash # Ubuntu/Debian $ sudo apt install libssl-dev libz-dev # Fedora/RHEL $ sudo dnf install openssl-devel zlib-devel # macOS $ brew install openssl zlib # Após instalar, rebuild $ zig build ``` ### Solucao 2: Vincular Biblioteca no build.zig ```zig // build.zig const std = @import("std"); pub fn build(b: *std.Build) void { const target = b.standardTargetOptions(.{}); const optimize = b.standardOptimizeOption(.{}); const exe = b.addExecutable(.{ .name = "meu-projeto", .root_source_file = b.path("src/main.zig"), .target = target, .optimize = optimize, }); // Vincular bibliotecas do sistema exe.linkSystemLibrary("ssl"); exe.linkSystemLibrary("crypto"); exe.linkSystemLibrary("z"); // Vincular libc (necessário para muitas bibliotecas C) exe.linkLibC(); b.installArtifact(exe); } ``` ### Solucao 3: Adicionar Caminhos de Busca de Bibliotecas ```zig // build.zig const exe = b.addExecutable(.{ .name = "meu-projeto", .root_source_file = b.path("src/main.zig"), .target = target, .optimize = optimize, }); // Adicionar caminhos de busca exe.addLibraryPath(.{ .cwd_relative = "/usr/local/lib" }); exe.addIncludePath(.{ .cwd_relative = "/usr/local/include" }); exe.linkSystemLibrary("minha_lib"); exe.linkLibC(); ``` ### Solucao 4: Vincular Biblioteca Estática Diretamente ```zig // build.zig const exe = b.addExecutable(.{ .name = "meu-projeto", .root_source_file = b.path("src/main.zig"), .target = target, .optimize = optimize, }); // Vincular arquivo .a ou .lib diretamente exe.addObjectFile(.{ .cwd_relative = "libs/libminha_lib.a" }); exe.linkLibC(); ``` ### Solucao 5: Compilar Código C junto com Zig ```zig // build.zig const exe = b.addExecutable(.{ .name = "meu-projeto", .root_source_file = b.path("src/main.zig"), .target = target, .optimize = optimize, }); // Compilar arquivo C como parte do projeto exe.addCSourceFile(.{ .file = b.path("src/utils.c"), .flags = &.{ "-Wall", "-O2" }, }); exe.linkLibC(); ``` ### Solucao 6: Cross-Compilation com Bibliotecas Bundled ```zig // build.zig — para cross-compilation const exe = b.addExecutable(.{ .name = "meu-projeto", .root_source_file = b.path("src/main.zig"), .target = target, .optimize = optimize, }); // Use bibliotecas que Zig traz embutidas exe.linkLibC(); // libc do target // Zig inclui implementações de muitas bibliotecas comuns ``` ## Diagnóstico ### Verificar Bibliotecas Disponíveis ```bash # Linux — listar bibliotecas instaladas $ ldconfig -p | grep ssl # macOS $ brew list openssl --prefix # Verificar se pkg-config encontra a biblioteca $ pkg-config --libs openssl ``` ### Ver Símbolos em uma Biblioteca ```bash # Listar símbolos de uma biblioteca estática $ nm /usr/lib/libssl.a | grep SSL_connect # Listar símbolos de uma biblioteca compartilhada $ nm -D /usr/lib/libssl.so | grep SSL_connect ``` ### Verbose Mode do Linker ```bash # Zig com output verbose do linker $ zig build -verbose ``` ## Cross-Compilation e Linker Ao compilar para outro sistema, o linker precisa das bibliotecas do alvo: ```zig // build.zig — cross-compilation const target = b.resolveTargetQuery(.{ .cpu_arch = .x86_64, .os_tag = .linux, .abi = .musl, // musl é estático — evita problemas de linking }); const exe = b.addExecutable(.{ .name = "meu-projeto", .root_source_file = b.path("src/main.zig"), .target = target, .optimize = optimize, }); // musl libc é bundled com Zig — funciona em cross-compilation exe.linkLibC(); ``` ## Erros Relacionados - [build.zig not found](/erros/erro-build-zig-not-found/) — Arquivo de build não encontrado - [@cImport failed](/erros/erro-c-import-failed/) — Falha ao importar cabeçalho C - [Target not supported](/erros/erro-target-not-supported/) — Alvo não suportado - [Dependency fetch failed](/erros/erro-dependency-fetch-failed/) — Falha ao buscar dependência ## Links Úteis - [Documentação oficial do Zig — Build System](https://ziglang.org/documentation/master/#Zig-Build-System) - [Documentação oficial do Zig — C Interop](https://ziglang.org/documentation/master/#C-Interop) - [Receitas de interoperabilidade com C](/receitas/) - [Tutorial sobre build system](/tutoriais/)