slimsag / zls

Zig LSP implementation + Zig Language Server

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
  • From Source
  • Configuration Options
  • Per-build Configuration Options
    • BuildOption
• Features
• Using as a library
• Related Projects
• Quick Thanks :)
• License

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 https://github.com/zigtools/zls
cd zls
zig build -Doptimize=ReleaseSafe

Configuration Options

You can configure zls by editing your zls.json configuration file. Running zls --show-config-path will show 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_argument_placeholders	bool	true	Whether to enable function argument placeholder completions
enable_build_on_save	bool	false	Whether to enable build-on-save diagnostics
build_on_save_step	[]const u8	"install"	Select which step should be executed on build-on-save
enable_autofix	bool	false	Whether to automatically fix errors on save. Currently supports adding and removing discards.
semantic_tokens	enum	.full	Set level of semantic tokens. Partial only includes information that requires semantic analysis.
enable_inlay_hints	bool	true	Enables inlay hint support when the client also supports it
inlay_hints_show_variable_type_hints	bool	true	Enable inlay hints for variable types
inlay_hints_show_struct_literal_field_type	bool	true	Enable inlay hints for fields in struct and union literals
inlay_hints_show_parameter_name	bool	true	Enable inlay hints for parameter names
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)
warn_style	bool	false	Enables warnings for style guideline mismatches
highlight_global_var_declarations	bool	false	Whether to highlight global var declarations
dangerous_comptime_experiments_do_not_enable	bool	false	Whether to use the comptime interpreter
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
prefer_ast_check_as_child_process	bool	true	Favor using zig ast-check instead of ZLS's fork
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 directory that will be used as zig's cache. null is equivalent to ${KnownFolders.Cache}/zls
build_runner_global_cache_path	?[]const u8	null	Path to a directory that will be used as the global cache path when executing a projects build.zig. null is equivalent to the path shown by zig env
completion_label_details	bool	true	When false, the function signature of completion results is hidden. Improves readability in some editors

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. Support for comptime and semantic analysis is Work-in-Progress.

The following LSP features are supported:

• Completions
• Hover
• Goto definition/declaration
• Document symbols
• Find references
• Rename symbol
• Formatting using zig fmt
• Semantic token highlighting
• Inlay hints
• Code actions
• Selection ranges
• Folding regions

Using as a library

You can use zls as a library! Check out this demo repo for a good reference.

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
• 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 efficiently 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