-
-
Notifications
You must be signed in to change notification settings - Fork 3
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- split documentation into separate pages - update editor configuration (every single one, no exceptions) - add documentation for zls.json JSON Schema - add documentation for Zed - add documentation for Code Actions - add "Build-On-Save" Guide - add "View Logs" Guide - add table of contents as a sidebar - clearly document support for in-editor configuration for each Editor - mark Emacs Documentation as incomplete #1 - minor styling changes fixes #6
- Loading branch information
Showing
30 changed files
with
1,467 additions
and
650 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,34 @@ | ||
| --- | ||
| { | ||
| .title = "In-Editor Config", | ||
| .date = @date("2020-03-02T00:00:00"), | ||
| .author = "Sample Author", | ||
| .layout = "zls-docs.shtml", | ||
| } | ||
| --- | ||
|
|
||
| In-Editor Config (or Workspace Config) will integrate with the config system of you editor to configure ZLS on a per-editor basis. | ||
|
|
||
| Some editors (like VS Code) also allow workspace-specific configuration. If you want to share the same configuration across multiple editors, please refer to the [zls.json]($link.page('zls/configure/zls-json')) alternative. | ||
|
|
||
| ## Supported Editors | ||
|
|
||
| | Editor | in-editor config support | | ||
| | ------------------------------------------------------------- | ------------------------- | | ||
| | [VS Code](/zls/editors/vscode) | Yes | | ||
| | [Sublime Text](/zls/editors/sublime-text) | Yes | | ||
| | [ZigBrains for JetBrains](/zls/editors/jetbrains) | Limited\* | | ||
| | [Helix](/zls/editors/helix) | Yes | | ||
| | [Zed](/zls/editors/zed) | Yes\*\* | | ||
| | [Neovim with nvim-lspconfig](/zls/editors/vim/nvim-lspconfig) | Yes | | ||
| | [Vim/Neovim with CoC](/zls/editors/vim/coc) | Yes | | ||
| | [Vim/Neovim with YCM](/zls/editors/vim/ycm) | Yes\*\*\* | | ||
| | [Emacs with eglot](/zls/editors/emacs) | Yes | | ||
| | [Emacs with lsp-mode](/zls/editors/emacs) | Yes | | ||
| | [Kate](/zls/editors/kate) | Yes\*\* | | ||
|
|
||
| \* Only a subset of config options are available. | ||
|
|
||
| \*\* In-Editor configuration for these editors requires at least ZLS `0.14.0-dev.22+a263b8dc6`. | ||
|
|
||
| \*\*\* In-Editor configuration is somewhat tedious to setup for this Editor. You may favor the [zls.json]($link.page('zls/configure/zls-json')) alternative. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,12 @@ | ||
| --- | ||
| { | ||
| .title = "Configuration", | ||
| .date = @date("2020-03-01T00:00:00"), | ||
| .author = "Sample Author", | ||
| .layout = "zls-docs.shtml", | ||
| } | ||
| --- | ||
|
|
||
| - [In-Editor Configuration](./in-editor) (recommended) | ||
| - [zls.json](./zls-json) | ||
| - [Per-build Configuration](./per-build) (advanced) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,28 @@ | ||
| --- | ||
| { | ||
| .title = "Per-Build Config", | ||
| .date = @date("2020-03-04T00:00:00"), | ||
| .author = "Sample Author", | ||
| .layout = "zls-docs.shtml", | ||
| } | ||
| --- | ||
|
|
||
| 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`. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,85 @@ | ||
| --- | ||
| { | ||
| .title = "zls.json Config", | ||
| .date = @date("2020-03-03T00:00:00"), | ||
| .author = "Sample Author", | ||
| .layout = "zls-docs.shtml", | ||
| } | ||
| --- | ||
|
|
||
| You can configure ZLS by creating a `zls.json` configuration file. This config will apply to **all** editors that use ZLS. | ||
|
|
||
| Here is an example of how a `zls.json` _could_ look like: | ||
|
|
||
| ```json | ||
| { | ||
| "zig_exe_path": "/path/to/zig_executable", | ||
| "semantic_tokens": "partial", | ||
| "enable_build_on_save": true | ||
| } | ||
| ``` | ||
|
|
||
| The file must be valid JSON which cannot contain comments or trailing commas. | ||
|
|
||
| ## Where should the zls.json be created? | ||
|
|
||
| ### ZLS since 0.14.0-dev.50+3354fdcb | ||
|
|
||
| Running `zls env` will show you where ZLS will look for the `zls.json` file: | ||
|
|
||
| ```json | ||
| { | ||
| "version": "0.14.0-dev.50+3354fdcb", | ||
| "global_cache_dir": "/home/anon/.cache/zls", | ||
| "global_config_dir": "/etc/xdg", | ||
| "local_config_dir": "/home/anon/.config", | ||
| "config_file": null, | ||
| "log_file": "/home/anon/.cache/zls/zls.log" | ||
| } | ||
| ``` | ||
|
|
||
| ZLS will look for a `zls.json` in the `local_config_dir` directory and then fallback to `global_config_dir`. | ||
|
|
||
| After creating the configuration file at `$local_config_dir/zls.json`, `zls env` should output the following: | ||
|
|
||
| ```json | ||
| { | ||
| "version": "0.14.0-dev.50+3354fdcb", | ||
| "global_cache_dir": "/home/anon/.cache/zls", | ||
| "global_config_dir": "/etc/xdg", | ||
| "local_config_dir": "/home/anon/.config", | ||
| "config_file": "/home/anon/.config/zls.json", | ||
| "log_file": "/home/anon/.cache/zls/zls.log" | ||
| } | ||
| ``` | ||
|
|
||
| ### ZLS before 0.14.0-dev.50+3354fdcb (like ZLS 0.13.0) | ||
|
|
||
| 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 --show-config-path | ||
| info ( main ): No config file zls.json found. | ||
| info ( main ): A path to the local configuration folder will be printed instead. | ||
| /home/anon/.config/zls.json | ||
| ``` | ||
|
|
||
| ## JSON Schema | ||
|
|
||
| ZLS provides a [JSON Schema](https://github.com/zigtools/zls/blob/master/schema.json) to validate the configuration file. It can be used to validate the configuration file and provide IntelliSense features to editors. Further information about JSON Schemas can be found at https://json-schema.org. | ||
|
|
||
| You can add a mapping to `zls.json` that can be used by *some* editors: | ||
|
|
||
| ```json | ||
| { | ||
| "$schema": "https://raw.githubusercontent.com/zigtools/zls/refs/heads/master/schema.json", | ||
| "zig_exe_path": "/path/to/zig_executable", | ||
| "semantic_tokens": "partial", | ||
| "enable_build_on_save": true | ||
| } | ||
| ``` | ||
|
|
||
| Please refer to your Editor's Documentation to find out if and how they support JSON Schemas. | ||
|
|
||
| Be aware that configuration options change over time. The example above assumes that you are using ZLS nightly/master. If you use a tagged release of ZLS, you will need to the JSON Schema of the respective version: | ||
| `https://raw.githubusercontent.com/zigtools/zls/refs/tags/<ZLS_VERSION_HERE>/schema.json`. |
Oops, something went wrong.