Configurar VS Code para Zig

O Visual Studio Code é o editor mais popular para desenvolvimento com Zig, graças à extensão oficial e ao suporte ao ZLS (Zig Language Server). Este guia mostra como configurar o VS Code para ter a melhor experiência possível de desenvolvimento com Zig, incluindo autocompletar, diagnósticos em tempo real, formatação automática e debug.

Antes de configurar o editor, certifique-se de que o Zig está instalado. Consulte o guia para sua plataforma: Ubuntu, Fedora, Arch, macOS, Windows ou WSL.

Passo 1: Instalar a Extensão Zig

Via Interface do VS Code

1. Abra o VS Code
2. Clique no ícone de Extensões na barra lateral (ou pressione Ctrl+Shift+X)
3. Pesquise por “Zig Language”
4. Instale a extensão Zig Language (identificador: ziglang.vscode-zig)

Via Linha de Comando

code --install-extension ziglang.vscode-zig

O Que a Extensão Oferece

• Syntax highlighting (coloração de sintaxe)
• Integração com o ZLS
• Formatação automática do código
• Snippets para estruturas comuns
• Integração com o sistema de build do Zig

Passo 2: Instalar o ZLS (Zig Language Server)

O ZLS é o servidor de linguagem que fornece funcionalidades avançadas como autocompletar, “ir para definição”, diagnósticos e refatoração.

Instalação Automática via Extensão

A extensão do Zig para VS Code pode instalar o ZLS automaticamente. Na primeira vez que abrir um arquivo .zig, a extensão perguntará se deseja instalar o ZLS. Clique em “Install”.

Instalação Manual

Se preferir instalar manualmente:

Linux

ZLS_VERSION="0.14.0"
ARCH=$(uname -m)
curl -LO "https://github.com/zigtools/zls/releases/download/${ZLS_VERSION}/zls-${ARCH}-linux.tar.xz"
tar -xf "zls-${ARCH}-linux.tar.xz"
sudo mv zls /usr/local/bin/

macOS

brew install zls

Windows

scoop install zls

Verificar a Instalação do ZLS

zls --version

Passo 3: Configurar o VS Code

Abra as configurações do VS Code (Ctrl+, ou Cmd+, no macOS) e ajuste as opções para Zig.

Configuração Recomendada (settings.json)

Abra o settings.json (pressione Ctrl+Shift+P e digite “Preferences: Open User Settings (JSON)”):

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

    "zig.zls.enableSnippets": true,
    "zig.zls.enableAutofix": true,

    "zig.formattingProvider": "zls",

    "editor.formatOnSave": true,

    "[zig]": {
        "editor.defaultFormatter": "ziglang.vscode-zig",
        "editor.tabSize": 4,
        "editor.insertSpaces": true,
        "editor.detectIndentation": false,
        "editor.rulers": [100],
        "editor.wordWrap": "off"
    },

    "files.associations": {
        "*.zig": "zig",
        "*.zon": "zig"
    }
}

Explicação das Configurações

Passo 4: Configurar o Debug

O VS Code suporta debug de programas Zig usando GDB ou LLDB.

Instalar Extensão de Debug

Instale a extensão CodeLLDB para debug com LLDB (recomendado para Zig):

code --install-extension vadimcn.vscode-lldb

Ou C/C++ para debug com GDB:

code --install-extension ms-vscode.cpptools

Criar Configuração de Debug

Crie o arquivo .vscode/launch.json no seu projeto:

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Debug Zig",
            "type": "lldb",
            "request": "launch",
            "program": "${workspaceFolder}/zig-out/bin/${workspaceFolderBasename}",
            "args": [],
            "cwd": "${workspaceFolder}",
            "preLaunchTask": "zig-build-debug"
        },
        {
            "name": "Debug Test",
            "type": "lldb",
            "request": "launch",
            "program": "${workspaceFolder}/zig-out/bin/test",
            "args": [],
            "cwd": "${workspaceFolder}",
            "preLaunchTask": "zig-test-debug"
        }
    ]
}

Criar Tasks de Build

Crie o arquivo .vscode/tasks.json:

{
    "version": "2.0.0",
    "tasks": [
        {
            "label": "zig-build",
            "type": "shell",
            "command": "zig",
            "args": ["build"],
            "group": {
                "kind": "build",
                "isDefault": true
            },
            "problemMatcher": ["$zig"]
        },
        {
            "label": "zig-build-debug",
            "type": "shell",
            "command": "zig",
            "args": ["build"],
            "problemMatcher": ["$zig"]
        },
        {
            "label": "zig-test",
            "type": "shell",
            "command": "zig",
            "args": ["build", "test"],
            "group": {
                "kind": "test",
                "isDefault": true
            },
            "problemMatcher": ["$zig"]
        },
        {
            "label": "zig-test-debug",
            "type": "shell",
            "command": "zig",
            "args": ["test", "src/main.zig"],
            "problemMatcher": ["$zig"]
        },
        {
            "label": "zig-run",
            "type": "shell",
            "command": "zig",
            "args": ["build", "run"],
            "problemMatcher": ["$zig"]
        }
    ]
}

Usar o Debug

1. Compile o projeto com Ctrl+Shift+B (task de build)
2. Coloque breakpoints clicando na margem esquerda do editor
3. Pressione F5 para iniciar o debug
4. Use F10 para step over, F11 para step into

Passo 5: Atalhos Úteis

Atalhos do VS Code para Zig

Atalhos Personalizados

Adicione ao keybindings.json (pressione Ctrl+Shift+P e digite “Preferences: Open Keyboard Shortcuts (JSON)”):

[
    {
        "key": "ctrl+shift+r",
        "command": "workbench.action.tasks.runTask",
        "args": "zig-run"
    },
    {
        "key": "ctrl+shift+t",
        "command": "workbench.action.tasks.runTask",
        "args": "zig-test"
    }
]

Passo 6: Extensões Complementares

Extensões adicionais que melhoram a experiência com Zig:

Error Lens

Mostra erros e avisos diretamente na linha do código:

code --install-extension usernamehw.errorlens

Todo Tree

Rastreia comentários TODO, FIXME e HACK no código:

code --install-extension gruntfuggly.todo-tree

GitLens

Melhor integração com Git, útil para projetos Zig colaborativos:

code --install-extension eamodio.gitlens

Hex Editor

Útil para inspecionar binários compilados com Zig:

code --install-extension ms-vscode.hexeditor

Configuração para WSL

Se você usa o WSL, a configuração é semelhante, mas com algumas diferenças:

1. Instale a extensão WSL no VS Code
2. Abra o VS Code do terminal WSL: code .
3. Instale a extensão Zig Language dentro do contexto WSL
4. Instale o ZLS dentro do WSL (não no Windows)

Veja o guia completo do WSL para mais detalhes.

Exemplo de Projeto Configurado

Estrutura completa de um projeto Zig com configuração do VS Code:

meu-projeto/
├── .vscode/
│   ├── launch.json         # Configuração de debug
│   ├── tasks.json          # Tasks de build e test
│   └── settings.json       # Configurações do workspace
├── src/
│   ├── main.zig            # Ponto de entrada
│   └── lib.zig             # Biblioteca
├── build.zig               # Sistema de build
└── build.zig.zon           # Dependências

O settings.json do workspace (.vscode/settings.json):

{
    "zig.path": "zig",
    "zig.zls.path": "zls",
    "editor.formatOnSave": true,
    "[zig]": {
        "editor.defaultFormatter": "ziglang.vscode-zig"
    }
}

Problemas Comuns

ZLS não inicia

Verifique se o ZLS está instalado e acessível:

which zls
zls --version

Se o ZLS foi instalado mas o VS Code não o encontra, especifique o caminho completo no settings.json:

{
    "zig.zls.path": "/usr/local/bin/zls"
}

Autocompletar não funciona

1. Verifique se a extensão Zig está instalada e habilitada
2. Verifique se o ZLS está rodando (veja o Output panel: View > Output > Zig Language Server)
3. Certifique-se de que as versões do Zig e ZLS são compatíveis

Formatação não funciona ao salvar

Verifique se editor.formatOnSave está habilitado e se o zig.formattingProvider está configurado para "zls" ou "extension".

Para mais soluções, visite nossa página de erros comuns.

Próximos Passos

Com o VS Code configurado para Zig:

1. Crie seu primeiro projeto — Primeiro projeto Zig
2. Aprenda a linguagem — Introdução ao Zig
3. Explore outros editores — Neovim ou Sublime/Emacs
4. Configure CI/CD — GitHub Actions com Zig
5. Veja exemplos — Receitas