zls/README.md

158 lines
9.1 KiB
Markdown
Raw Normal View History

<img src="https://raw.githubusercontent.com/zigtools/install-zls/main/img/zls-opt.svg" alt="Zig Language Server" width=200>
[![CI](https://github.com/zigtools/zls/workflows/CI/badge.svg)](https://github.com/zigtools/zls/actions)
**Need support? Wanna help out? Join our [Discord server](https://discord.gg/5m5U3qpUhk)!**
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.](#features) when you write Zig code!
<!-- omit in toc -->
## Table Of Contents
- [Installation](#installation)
2022-07-08 09:13:46 +01:00
- [From Source](#from-source)
- [Build Options](#build-options)
- [Updating Data Files](#updating-data-files)
- [Configuration Options](#configuration-options)
- [Per-build Configuration Options](#per-build-configuration-options)
- [`BuildOption`](#buildoption)
2022-07-08 09:13:46 +01:00
- [Features](#features)
- [Related Projects](#related-projects)
2022-11-15 20:00:05 +00:00
- [Quick Thanks :)](#quick-thanks-)
- [License](#license)
## Installation
<!-- omit in toc -->
### [See the `install zls` tool](https://zigtools.github.io/install-zls/) for editor and binary installation instructions.
### From Source
Building `zls` is very easy. You will need [a build of Zig master](https://ziglang.org/download/) to build zls.
```bash
git clone --recurse-submodules https://github.com/zigtools/zls
cd zls
zig build -Drelease-safe
2022-08-22 16:06:36 +01:00
./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.
On Powershell 5.1 (the default Powershell on Windows 10 & 11), the following will update `master.zig`.
```pwsh
New-Item -Force .\src\data\master.zig -Value ((python .\src\data\generate-data.py) -split "`r?`n" -join "`n")
```
This unweidly command is necesary in order to guarantee Unix-style line endings and UTF-8 text encoding.
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
2022-08-22 16:06:36 +01:00
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:
2021-06-24 06:59:03 +01:00
- In the local configuration folder of your OS (as provided by [known-folders](https://github.com/ziglibs/known-folders/blob/master/RESOURCES.md#folder-list))
- In the global configuration folder of your OS (as provided by [known-folders](https://github.com/ziglibs/known-folders/blob/master/RESOURCES.md#folder-list))
The following options are currently available.
<!-- DO NOT EDIT | THIS SECTION IS AUTO-GENERATED | DO NOT EDIT -->
| 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. |
2022-09-03 18:00:12 +01:00
| `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 |
2022-10-01 18:41:55 +01:00
| `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` |
<!-- DO NOT EDIT -->
### Per-build Configuration Options
2022-09-28 13:31:00 +01:00
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:
```zig
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
2022-08-22 16:06:36 +01:00
`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](https://github.com/prime31/sublime-zig-language)
- Supports basic language features
- Uses data provided by `src/data` to perform builtin autocompletion
- [`zig-lsp` by @xackus](https://github.com/xackus/zig-lsp)
- Inspiration for `zls`
- [`known-folders` by @ziglibs](https://github.com/ziglibs/known-folders)
- Provides API to access known folders on Linux, Windows and Mac OS
- [`zls` by @zigtools](https://github.com/zigtools/zls)
- Used by many zls developers to more efficently work on zls
2022-11-15 20:00:05 +00:00
## Quick Thanks :)
We'd like to take a second to thank all our awesome [contributors](https://github.com/zigtools/zls/graphs/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](https://opencollective.com/zigtools/backers.svg?width=890&limit=1000)](https://opencollective.com/zigtools#category-CONTRIBUTE)
## License
MIT