arnodel / zls Goto Github PK

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.

• Installation
  • Build Options
  • Configuration Options
• Usage
  • VSCode
  • Sublime Text 3
  • Kate
  • Neovim/Vim8
  • Emacs
  • Doom Emacs
• Related Projects
• License

Installation starts with downloading an official release from the Releases page. Up to date builds from master branch are also available in the latest successful CI run, contained in the builds artifact.

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.

You can install the latest release into $HOME/zls using e.g.:

brew install xz
mkdir $HOME/zls && cd $HOME/zls && curl -L https://github.com/zigtools/zls/releases/download/0.1.0/x86_64-macos.tar.xz | tar -xJ --strip-components=1 -C .

You can install the latest release into $HOME/zls using e.g.:

sudo apt install xz-utils
mkdir $HOME/zls && cd $HOME/zls && curl -L https://github.com/zigtools/zls/releases/download/0.1.0/x86_64-linux.tar.xz | tar -xJ --strip-components=1 -C .

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-out/bin/zls config # Configure ZLS

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

You can configure zls by running zls config or manually creating your own zls.json configuration 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 global configuration folder of your OS (as provided by known-folders)

The following options are currently available.

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:

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

• 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"]
        }
    }
}

• 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$"
        }
    }
}

• 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"]
       }
   }
}

• Install YouCompleteMeFrom here.
• Add these lines to your vimrc:

"ensure zig is a recognized filetype
autocmd BufNewFile,BufRead *.zig set filetype=zig

let g:ycm_language_server =
  \ [
  \{
  \     'name': 'zls',
  \     'filetypes': [ 'zig' ],
  \     'cmdline': [ '/path/to/zls_executable' ]
  \    }
  \ ]

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

• Install the LanguageClient-neovim from here
• Edit your neovim configuration and add zls for zig filetypes:

let g:LanguageClient_serverCommands = {
       \ 'zig': ['~/code/zls/zig-out/bin/zls'],
       \ }

• Install lsp-mode from melpa
• zig mode is also useful

;; Setup lsp-mode as desired.
;; See https://emacs-lsp.github.io/lsp-mode/page/installation/ for more information.
(require 'lsp-mode)

;; Either place zls in your PATH or add the following:
(setq lsp-zig-zls-executable "<path to zls>")

• Enable the lsp module
• Install the zig-mode package (add (package! zig-mode) to your packages.el file

(use-package! zig-mode
  :hook ((zig-mode . lsp-deferred))
  :custom (zig-format-on-save nil)
  :config
  (after! lsp-mode
    (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))))

• sublime-zig-language by @prime31
  • Supports basic language features
  • Uses data provided by src/data to perform builtin autocompletion
• zig-lsp by @xackus
  • Inspiration for zls
• known-folders by @ziglibs
  • Provides API to access known folders on Linux, Windows and Mac OS

MIT