Document per-build configuration options

This commit is contained in:
J.C. Moyer 2022-09-28 04:26:20 -04:00
parent 0b0e6a7cb9
commit 340290a406

View File

@ -18,6 +18,8 @@ Zig Language Server, or `zls`, is a language server for Zig. The Zig wiki states
- [Build Options](#build-options) - [Build Options](#build-options)
- [Updating Data Files](#updating-data-files) - [Updating Data Files](#updating-data-files)
- [Configuration Options](#configuration-options) - [Configuration Options](#configuration-options)
- [Per-build Configuration Options](#per-build-configuration-options)
- [`BuildOption`](#buildoption)
- [Features](#features) - [Features](#features)
- [VS Code](#vs-code) - [VS Code](#vs-code)
- [Sublime Text](#sublime-text) - [Sublime Text](#sublime-text)
@ -117,6 +119,28 @@ The following options are currently available.
|`max_detail_length`|`usize`|`1024 * 1024`| The detail field of completions is truncated to be no longer than this (in bytes). |`max_detail_length`|`usize`|`1024 * 1024`| The detail field of completions is truncated to be no longer than this (in bytes).
| `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. | `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.
### Per-build Configuration Options
The following options can be set on a per-project basis by placing `zls.user.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 ## Features
`zls` supports most language features, including simple type function support, using namespace, payload capture type resolution, custom packages, `cImport` and others. `zls` supports most language features, including simple type function support, using namespace, payload capture type resolution, custom packages, `cImport` and others.