/zls

Zig LSP implementation + Zig Language Server

Primary LanguageZigMIT LicenseMIT

Zig Language Server

CI

Need support? Wanna help out? Join our Discord server!

The Zig Language Server (zls) is a tool that implements Microsoft's Language Server Protocol for Zig in Zig. In simpler terms: it'll provide you with completions, go-to definition, etc. when you write Zig code!

Table Of Contents

Installation

See the install zls tool for editor and binary installation instructions.

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

Build Options

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

Updating Data Files

There is a generate-data.py in the src/data folder, run this file to update data files. It writes to stdout and you can redirect output to a zig file like master.zig. By default it generates data file for master, but can be configured to generate for a different version by modifying the zig_version variable. Files generated by this tool contains formatting information.

There is also a generate-data.js in the src/data folder, you'll need to run this inside a Chrome DevTools console and copy the output. Files generated by this tool does not contain formatting information.

Configuration Options

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.

Option Type Default value What it Does
enable_snippets bool false Enables snippet completions when the client also supports them
enable_ast_check_diagnostics bool true Whether to enable ast-check diagnostics
enable_autofix bool false Whether to automatically fix errors on save. Currently supports adding and removing discards.
enable_import_embedfile_argument_completions bool false Whether to enable import/embedFile argument completions
enable_semantic_tokens bool true Enables semantic token support when the client also supports it
enable_inlay_hints bool false Enables inlay hint support when the client also supports it
inlay_hints_show_builtin bool true Enable inlay hints for builtin functions
inlay_hints_exclude_single_argument bool true Don't show inlay hints for single argument calls
inlay_hints_hide_redundant_param_names bool false Hides inlay hints when parameter name matches the identifier (e.g. foo: foo)
inlay_hints_hide_redundant_param_names_last_token bool false Hides inlay hints when parameter name matches the last token of a parameter node (e.g. foo: bar.foo, foo: &foo)
operator_completions bool true Enables * and ? operators in completion lists
warn_style bool false Enables warnings for style guideline mismatches
highlight_global_var_declarations bool false Whether to highlight global var declarations
use_comptime_interpreter bool false Whether to use the comptime interpreter
include_at_in_builtins bool false Whether the @ sign should be part of the completion of builtins
skip_std_references bool false When true, skips searching for references in std. Improves lookup speed for functions in user's code. Renaming and go-to-definition will continue to work as is
max_detail_length usize 1048576 The detail field of completions is truncated to be no longer than this (in bytes)
builtin_path ?[]const u8 null Path to 'builtin;' useful for debugging, automatically set if let null
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
build_runner_path ?[]const u8 null Path to the build_runner.zig file provided by zls. null is equivalent to ${executable_directory}/build_runner.zig
global_cache_path ?[]const u8 null Path to a directroy that will be used as zig's cache. null is equivalent to ${KnownFloders.Cache}/zls

Per-build Configuration Options

The following options can be set on a per-project basis by placing zls.build.json in the project root directory next to build.zig.

Option Type Default value What it Does
relative_builtin_path ?[]const u8 null If present, this path is used to resolve @import("builtin")
build_options ?[]BuildOption null If present, this contains a list of user options to pass to the build. This is useful when options are used to conditionally add packages in build.zig.

BuildOption

BuildOption is defined as follows:

const BuildOption = struct {
    name: []const u8,
    value: ?[]const u8 = null,
};

When value is present, the option will be passed the same as in zig build -Dname=value. When value is null, the option will be passed as a flag instead as in zig build -Dflag.

Features

zls supports most language features, including simple type function support, using namespace, payload capture type resolution, custom packages, cImport and others. Currently there is no support for 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 (implemented by a few clients including VS Code, kak and emacs lsp-mode)
  • Inlay hints (implemented by VS Code)

Related Projects

Quick Thanks :)

We'd like to take a second to thank all our awesome contributors and donators/backers/sponsors; if you have time or money to spare, consider partaking in either of these options - they help keep zls awesome for everyone!

OpenCollective Backers

License

MIT