From 340290a4068134ff4b5a3c7f8f9b2edc5e613ad7 Mon Sep 17 00:00:00 2001
From: "J.C. Moyer" <jcmoyer32@gmail.com>
Date: Wed, 28 Sep 2022 04:26:20 -0400
Subject: [PATCH] Document per-build configuration options

---
 README.md | 24 ++++++++++++++++++++++++
 1 file changed, 24 insertions(+)

diff --git a/README.md b/README.md
index 7dd57eb..4b42a77 100644
--- a/README.md
+++ b/README.md
@@ -18,6 +18,8 @@ Zig Language Server, or `zls`, is a language server for Zig. The Zig wiki states
     - [Build Options](#build-options)
     - [Updating Data Files](#updating-data-files)
   - [Configuration Options](#configuration-options)
+  - [Per-build Configuration Options](#per-build-configuration-options)
+    - [`BuildOption`](#buildoption)
 - [Features](#features)
   - [VS Code](#vs-code)
   - [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).
 | `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
 
 `zls` supports most language features, including simple type function support, using namespace, payload capture type resolution, custom packages, `cImport` and others.