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!
See the install zls
tool for editor and binary installation instructions.
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
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. |
Run zig build gen -- --generate-version-data master
to update data files. This command will require an internet connection.
You can replace master
with a specific zig version like 0.10.0
. Which version ZLS uses can be configured by passing the -Ddata_version
parameter when building ZLS.
You can configure zls by editing your zls.json
configuration file.
Running zls --show-config-path
will a path to an already existing zls.json
or a path to the local configuration folder instead.
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 |
true |
Enables snippet completions when the client also supports them |
enable_ast_check_diagnostics |
bool |
true |
Whether to enable ast-check diagnostics |
enable_autofix |
bool |
true |
Whether to automatically fix errors on save. Currently supports adding and removing discards. |
enable_import_embedfile_argument_completions |
bool |
true |
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 |
true |
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) |
record_session |
bool |
false |
When true, zls will record all request is receives and write in into record_session_path , so that they can replayed with zls replay |
record_session_path |
?[]const u8 |
null |
Output file path when record_session is set. The recommended file extension *.zlsreplay |
replay_session_path |
?[]const u8 |
null |
Used when calling zls replay for specifying the replay file. If no extra argument is given record_session_path is used as the default path. |
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 |
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
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
.
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)
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
- Inspiration for
known-folders
by @ziglibs- Provides API to access known folders on Linux, Windows and Mac OS
zls
by @zigtools- Used by many zls developers to more efficently work on zls
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!
MIT