f6c15ac10c
Fixes #842 |
||
---|---|---|
.github | ||
src | ||
tests | ||
.gitattributes | ||
.gitignore | ||
.gitmodules | ||
build.zig | ||
default.nix | ||
flake.lock | ||
flake.nix | ||
LICENSE | ||
README.md | ||
schema.json |
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
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
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!
License
MIT