ZLS em Zig — O que é e Como Usar

Definição

ZLS (Zig Language Server) é a implementação do Language Server Protocol (LSP) para a linguagem Zig. Ele fornece funcionalidades como autocomplete, diagnósticos em tempo real, “go to definition”, hover com documentação e renomeação de símbolos para qualquer editor que suporte LSP — incluindo VS Code, Neovim, Emacs, Sublime Text e outros.

O ZLS é um projeto de código aberto mantido pela comunidade com apoio da Zig Software Foundation.

Por que ZLS Importa

1. Produtividade: Autocomplete e diagnósticos instantâneos aceleram o desenvolvimento.
2. Navegação: “Go to definition” e “find references” em qualquer código Zig.
3. Documentação inline: Hover sobre funções mostra documentação e assinaturas.
4. Qualquer editor: Funciona com qualquer editor que suporte LSP.

Instalação

Via zigup

# Instalar zigup (gerenciador de versões do Zig)
# Depois instalar o ZLS compatível com sua versão do Zig
zigup fetch zls

Manual

# Baixar release do GitHub
# https://github.com/zigtools/zls/releases

# Ou compilar do fonte
git clone https://github.com/zigtools/zls.git
cd zls
zig build -Doptimize=ReleaseSafe

Configuração no VS Code

{
    "zig.path": "zig",
    "zig.zls.path": "zls"
}

Configuração no Neovim (com nvim-lspconfig)

require('lspconfig').zls.setup{
    cmd = { "zls" },
    settings = {
        zls = {
            enable_snippets = true,
            enable_autofix = true,
        },
    },
}

Funcionalidades

Exemplo de Uso

const std = @import("std");

// O ZLS fornece:
// 1. Autocomplete ao digitar "std."
// 2. Hover sobre "ArrayList" mostra documentação
// 3. Go to definition em "append" navega para a std lib
// 4. Diagnóstico se você esquecer defer para deinit

pub fn main() !void {
    var gpa = std.heap.GeneralPurposeAllocator(.{}){};
    defer _ = gpa.deinit();

    var lista = std.ArrayList(u32).init(gpa.allocator());
    defer lista.deinit();

    try lista.append(42);
    try lista.append(100);

    for (lista.items) |item| {
        std.debug.print("{}\n", .{item});
    }
}

Armadilhas Comuns

• Versão compatível: O ZLS deve ser da mesma versão major que o compilador Zig. ZLS 0.13.x com Zig 0.13.x.
• build.zig necessário: O ZLS funciona melhor em projetos com build.zig. Sem ele, a resolução de imports pode falhar.
• Cache: Se o ZLS parecer desatualizado, reinicie o servidor no editor.
• Performance em projetos grandes: O ZLS pode consumir memória significativa em projetos muito grandes.

Termos Relacionados

• Zig Software Foundation — Organização que apoia o ZLS
• build.zig — ZLS usa o build.zig para entender o projeto
• zigup — Gerenciador que facilita instalar o ZLS
• Comptime — ZLS analisa código comptime para autocomplete

Configuração no Helix e Emacs

O ZLS funciona com qualquer editor compatível com LSP. Para Helix, basta ter o binário zls no PATH — o Helix detecta automaticamente. Para Emacs com lsp-mode:

;; Emacs com lsp-mode
(with-eval-after-load 'lsp-mode
  (add-to-list 'lsp-language-id-configuration '(zig-mode . "zig"))
  (lsp-register-client
   (make-lsp-client
    :new-connection (lsp-stdio-connection "zls")
    :major-modes '(zig-mode)
    :server-id 'zls)))

Para Sublime Text com o pacote LSP, basta adicionar zls como servidor para arquivos .zig.

O que o ZLS Analisa

O ZLS usa o próprio compilador do Zig internamente para analisar o código. Ele executa análise semântica completa, o que significa que o autocomplete entende comptime — se você chamar uma função genérica com um tipo específico, o ZLS mostrará os campos e métodos corretos para aquele tipo instanciado.

// O ZLS entende que ArrayList(u32) tem método .append que recebe u32
var lista = std.ArrayList(u32).init(allocator);
try lista.append(  // ZLS sugere: u32

Isso é significativamente mais sofisticado do que ferramentas baseadas em análise estática simples, pois requer avaliação do código comptime.

Inlay Hints

Uma das funcionalidades mais úteis do ZLS são os inlay hints — anotações de tipo exibidas inline no editor sem modificar o código:

// Com inlay hints habilitados, o editor exibe:
const x = calcular();     // ← u32
const nome = buscar(id);  // ← []const u8
for (lista.items) |item| { // item: Produto
    _ = item;
}

Isso é especialmente útil em código com muita inferência de tipos, onde o tipo de uma variável não é óbvio apenas pela leitura do código.

Boas Práticas

• Mantenha o ZLS atualizado junto com o Zig: A cada nova versão do Zig, baixe a versão correspondente do ZLS. Versões incompatíveis causam falsos positivos nos diagnósticos.
• Reinicie o servidor periodicamente: Em sessões longas, o ZLS pode acumular estado desatualizado. A maioria dos editores tem um comando “Restart LSP Server”.
• build.zig ajuda o ZLS: Com um build.zig bem configurado, o ZLS consegue resolver imports e dependências corretamente, fornecendo autocomplete para bibliotecas externas.

Tutoriais Relacionados

• Configurando o Ambiente Zig
• Introdução ao Zig
• Zig para Iniciantes