ZLS
Go to file
2021-01-04 17:51:26 +00:00
.assets Added screenshots for ZLS for VSCode extension 2020-11-22 14:30:54 -06:00
.github/workflows add: run tests on linux 2020-11-04 17:15:57 -06:00
src Fixed string printing with {s} format specifier 2021-01-04 17:51:26 +00:00
tests Fixed string printing with {s} format specifier 2021-01-04 17:51:26 +00:00
.gitattributes Always use LF line endings in .zig files 2020-06-24 17:07:33 +03:00
.gitignore Fixed string printing with {s} format specifier 2021-01-04 17:51:26 +00:00
.gitmodules zig build config is here! 2020-05-25 17:12:08 -04:00
build.zig Fixed string printing with {s} format specifier 2021-01-04 17:51:26 +00:00
default.nix Fix Nix derivation 2020-10-31 17:36:37 -03:00
LICENSE.md Added Alexandros Naskos to LICENSE 2020-11-15 20:37:46 +02:00
README.md Update README.md 2020-12-24 01:04:45 +01:00

Zig Language Server

CI Zig Tools

Zig Language Server, or zls, is a language server for Zig. The Zig wiki states that "The Zig community is decentralized" and "There is no concept of 'official' or 'unofficial'", so instead of calling zls unofficial, and I'm going to call it a cool option, one of many.

Table Of Contents

Installation

Installation starts with downloading an official release from the Releases page.

See Downloading and Building ZLS on the Wiki, or the page about using ZLS with Visual Studio Code for a guide to help get zls running in your editor.

From Source

Building zls is very easy. You will need a build of Zig master to build zls.

git clone --recurse-submodules https://github.com/zigtools/zls
cd zls
zig build -Drelease-safe
zig build config # Configure ZLS

For detailed building instructions, see the Wiki page about Cloning With Git.

Build Options

Option Type Default Value What it Does
-Ddata_version string (master or 0.7.0) master The data file version. This selects the files in the src/data folder that correspond to the Zig version being served.

Configuration Options

You can configure zls by providing a zls.json file.
zls will look for a zls.json configuration file in multiple locations with the following priority:

  • In the local configuration folder of your OS (as provided by known-folders)
  • In the same directory as the executable

The following options are currently available.

Option Type Default value What it Does
enable_snippets bool false Enables snippet completions when the client also supports them.
zig_lib_path ?[]const u8 null zig library path, e.g. /path/to/zig/lib/zig, used to analyze std library imports.
zig_exe_path ?[]const u8 null zig executable path, e.g. /path/to/zig/zig, used to run the custom build runner. If null, zig is looked up in PATH. Will be used to infer the zig standard library path if none is provided.
warn_style bool false Enables warnings for style guideline mismatches
build_runner_path ?[]const u8 null Path to the build_runner.zig file provided by zls. This option must be present in one of the global configuration files to have any effect. null is equivalent to ${executable_directory}/build_runner.zig
enable_semantic_tokens bool true Enables semantic token support when the client also supports it.
operator_completions bool true Enables * and ? operators in completion lists.

Features

zls supports most language features, including simple type function support, usingnamespace, payload capture type resolution, custom packages and others. Notable language features that are not currently implemented include @cImport as well as most forms of compile time evaluation.

The following LSP features are supported:

  • Completions
  • Hover
  • Goto definition/declaration
  • Document symbols
  • Find references
  • Rename symbol
  • Formatting using zig fmt
  • Semantic token highlighting (LSP 3.16 proposed feature, implemented by a few clients including VSCode, kak and emacs lsp-mode)

You can install zls using the instuctions for your text editor below:

VSCode

Install the zls-vscode extension from here and provide a path to the build zls executable.

Sublime Text 3

  • Install the LSP package from here or via Package Control.
  • Add this snippet to LSP's user settings:
{
    "clients": {
        "zig":{
            "command": ["zls"],
            "enabled": true,
            "languageId": "zig",
            "scopes": ["source.zig"],
            "syntaxes": ["Packages/Zig Language/Syntaxes/Zig.tmLanguage"]
        }
    }
}

Kate

  • Enable LSP client plugin in Kate settings.
  • Add this snippet to LSP client's user settings (e.g. /$HOME/.config/kate/lspclient) (or paste it in LSP client's GUI settings)
{
    "servers": {
        "zig": {
            "command": ["zls"],
            "url": "https://github.com/zigtools/zls",
            "highlightingModeRegex": "^Zig$"
        }
    }
}

Neovim/Vim8

CoC

  • Install the CoC engine from here.
  • Issue :CocConfig from within your Vim editor, and the following snippet:
{
   "languageserver": {
       "zls" : {
           "command": "command_or_path_to_zls",
           "filetypes": ["zig"]
       }
   }
}

nvim-lspconfig

Requires Nvim 0.5 (HEAD)!

  • Install nvim-lspconfig from here.
  • Install zig.vim from here.

nvim-lspconfig already ships a configuration for zls. A simple init.vim might look like this:

call plug#begin('~/.config/nvim/plugged')
Plug 'neovim/nvim-lspconfig'
Plug 'nvim-lua/completion-nvim'
Plug 'ziglang/zig.vim'
call plug#end()

:lua << EOF
    local lspconfig = require('lspconfig')

    local on_attach = function(_, bufnr)
        vim.api.nvim_buf_set_option(bufnr, 'omnifunc', 'v:lua.vim.lsp.omnifunc')
        require('completion').on_attach()
    end

    local servers = {'zls'}
    for _, lsp in ipairs(servers) do 
        lspconfig[lsp].setup {
            on_attach = on_attach,
        }
    end
EOF

" Set completeopt to have a better completion experience
set completeopt=menuone,noinsert,noselect

" Enable completions as you type
let g:completion_enable_auto_popup = 1

Emacs

(require 'lsp)
(add-to-list 'lsp-language-id-configuration '(zig-mode . "zig"))
(lsp-register-client
  (make-lsp-client
    :new-connection (lsp-stdio-connection "<path to zls>")
    :major-modes '(zig-mode)
    :server-id 'zls))

License

MIT