ZLS — Zig Language Server: Configuração e Uso Completo

O ZLS (Zig Language Server) é a ferramenta essencial para qualquer desenvolvedor Zig que deseja produtividade no dia a dia. Implementando o protocolo LSP (Language Server Protocol), o ZLS traz funcionalidades avançadas de IDE para praticamente qualquer editor de texto moderno: autocompletar inteligente, diagnósticos em tempo real, navegação de código, informações de hover, formatação automática e muito mais.

O Que É o ZLS

O ZLS é um servidor de linguagem escrito inteiramente em Zig que analisa seu código em tempo real enquanto você digita. Ele se comunica com seu editor através do protocolo LSP, o mesmo padrão utilizado por ferramentas como rust-analyzer (Rust), gopls (Go) e typescript-language-server (TypeScript). Isso significa que qualquer editor com suporte a LSP pode se beneficiar do ZLS.

O projeto é mantido pela comunidade com contribuições frequentes e possui forte alinhamento com as atualizações do compilador Zig. Cada nova versão do compilador geralmente é acompanhada por uma atualização correspondente do ZLS.

Recursos Principais

Autocompletar Inteligente

O ZLS oferece autocompletar contextual que entende os tipos, funções, campos de structs e módulos do seu projeto. Ele analisa não apenas o arquivo atual, mas toda a árvore de dependências, incluindo pacotes importados via build.zig.zon.

const std = @import("std");

pub fn main() void {
    var list = std.ArrayList(u8).init(std.heap.page_allocator);
    list.  // ZLS mostra: append, appendSlice, items, deinit, etc.
}

Diagnósticos em Tempo Real

Sem precisar compilar manualmente, o ZLS destaca erros de sintaxe, tipos incompatíveis, variáveis não utilizadas e outros problemas diretamente no editor. Isso acelera enormemente o ciclo de desenvolvimento.

Go to Definition e Find References

Navegue instantaneamente para a definição de qualquer símbolo com um clique ou atalho de teclado. Encontre todas as referências a uma função, tipo ou variável em todo o projeto.

Hover Information

Passe o cursor sobre qualquer identificador para ver sua assinatura de tipo, documentação inline e informações de módulo. Essa funcionalidade é especialmente útil quando se trabalha com APIs complexas da biblioteca padrão.

Inlay Hints

O ZLS pode exibir hints inline que mostram os tipos inferidos de variáveis, nomes de parâmetros em chamadas de função e tipos de retorno, tudo sem poluir o código fonte.

Formatação Automática

Integra o zig fmt diretamente no editor, permitindo formatação automática ao salvar ou sob demanda. Isso garante que todo o código do projeto siga o estilo oficial do Zig.

Instalação

Via Gerenciador de Pacotes do Sistema

No Linux, você pode instalar o ZLS através de gerenciadores de pacotes:

# Arch Linux
sudo pacman -S zls

# Nix
nix-env -iA nixpkgs.zls

# Homebrew (macOS e Linux)
brew install zls

Compilação a Partir do Fonte

Para a versão mais recente ou para corresponder exatamente à versão do seu compilador:

git clone https://github.com/zigtools/zls
cd zls
zig build -Doptimize=ReleaseSafe

O binário será gerado em zig-out/bin/zls. Adicione-o ao seu PATH ou copie para /usr/local/bin/.

Via zigup

Se você usa o zigup como gerenciador de versões, ele pode gerenciar o ZLS automaticamente:

zigup fetch-zls 0.13.0

Configuração por Editor

VS Code

Instale a extensão oficial “Zig Language” do marketplace do VS Code. A extensão detecta automaticamente o ZLS se estiver no PATH. Para configurar manualmente:

{
    "zig.path": "/caminho/para/zig",
    "zig.zls.path": "/caminho/para/zls",
    "zig.zls.enableAutofix": true,
    "zig.formattingProvider": "zls"
}

A extensão também oferece suporte a snippets, syntax highlighting avançado e integração com o sistema de build.

Neovim

Com o nvim-lspconfig, a configuração é direta:

-- init.lua
require('lspconfig').zls.setup{
    cmd = { "zls" },
    settings = {
        zls = {
            enable_snippets = true,
            enable_ast_check_diagnostics = true,
            enable_autofix = true,
            enable_import_detection = true,
            skip_std_references = false,
            enable_inlay_hints = true,
            inlay_hints_exclude_single_argument = true,
            operator_completions = true,
        }
    }
}

Para uma experiência ainda mais completa no Neovim, considere usar plugins como telescope.nvim para navegação de símbolos e trouble.nvim para uma lista de diagnósticos organizada.

Emacs

Com o lsp-mode ou eglot:

;; Com lsp-mode
(use-package zig-mode
  :hook (zig-mode . lsp-deferred))

;; Com eglot (Emacs 29+)
(add-to-list 'eglot-server-programs '(zig-mode . ("zls")))
(add-hook 'zig-mode-hook 'eglot-ensure)

Sublime Text

Instale o pacote “LSP” e “LSP-zig” via Package Control. A configuração é automática se o ZLS estiver no PATH.

Helix

O Helix já inclui configuração padrão para ZLS. Basta ter o binário no PATH e abrir um arquivo .zig.

Configuração Avançada do ZLS

O ZLS pode ser configurado globalmente através de um arquivo zls.json no diretório de configuração do usuário:

{
    "zig_exe_path": "/usr/local/bin/zig",
    "warn_style": true,
    "enable_snippets": true,
    "enable_ast_check_diagnostics": true,
    "enable_autofix": true,
    "enable_import_detection": true,
    "enable_inlay_hints": true,
    "inlay_hints_show_builtin": true,
    "operator_completions": true,
    "include_at_in_builtins": false,
    "skip_std_references": false,
    "builtin_path": null,
    "highlight_global_var_declarations": true
}

Opções Importantes

• enable_ast_check_diagnostics: Ativa análise AST para diagnósticos mais profundos. Recomendado manter ativado.
• skip_std_references: Pule referências na biblioteca padrão ao buscar referências. Útil em projetos grandes para melhorar performance.
• enable_import_detection: Detecta automaticamente imports não utilizados e sugere remoção.
• enable_autofix: Aplica correções automáticas quando possível (como remover imports não utilizados).

Dicas de Produtividade

Workspace Symbols

Use a busca de símbolos do workspace (geralmente Ctrl+T ou :Telescope lsp_workspace_symbols no Neovim) para navegar rapidamente entre funções, structs e constantes de todo o projeto.

Code Actions

O ZLS oferece code actions contextuais como:

• Remover imports não utilizados
• Adicionar try faltante
• Converter entre notações de ponteiro
• Organizar imports

Integração com Build System

O ZLS analisa automaticamente seu build.zig e build.zig.zon para entender as dependências do projeto. Isso significa que pacotes baixados pelo gerenciador de pacotes são automaticamente reconhecidos pelo autocompletar.

Resolução de Problemas

ZLS Não Encontra o Compilador

Verifique se o zig está no PATH ou configure zig_exe_path no zls.json. A versão do ZLS deve corresponder à versão do compilador.

Performance Lenta em Projetos Grandes

Ative skip_std_references e considere fechar arquivos não utilizados. O ZLS mantém em memória a análise de todos os arquivos abertos.

Diagnósticos Não Aparecem

Verifique se enable_ast_check_diagnostics está ativado. Alguns editores podem desativar diagnósticos por padrão para servidores LSP desconhecidos.

Relação com Outras Ferramentas

O ZLS complementa outras ferramentas do ecossistema. Use-o em conjunto com as ferramentas de debug para depuração, ferramentas de profiling para otimização e os frameworks de teste para garantir qualidade do código. Para conhecer todos os plugins disponíveis para editores, consulte nosso guia de plugins para IDEs.

Contribuindo para o ZLS

O ZLS é um projeto open source e aceita contribuições. Se você encontrou um bug ou quer implementar uma feature, visite o repositório no GitHub. A comunidade é acolhedora e há issues marcadas como “good first issue” para iniciantes.

Para mais informações sobre como começar com Zig, consulte nossos tutoriais e receitas práticas.