From 2dbec4c933c7a0856ccf338f96dfb831ea771fb8 Mon Sep 17 00:00:00 2001
From: Michael Davis <mcarsondavis@gmail.com>
Date: Mon, 12 Dec 2022 21:38:30 -0600
Subject: [PATCH] Add a document for the runtime directory

This help topic should otherwise belong under `runtime/help/topics`
but it should be accessible if the runtime directory is not correctly
installed.

This article shows up under `:help topics` because of the symlink
but can also be accessed by `:help runtime` if necessary.
---
 runtime/README.md              | 57 ++++++++++++++++++++++++++++++++++
 runtime/help/topics/Runtime.md |  1 +
 2 files changed, 58 insertions(+)
 create mode 100644 runtime/README.md
 create mode 120000 runtime/help/topics/Runtime.md

diff --git a/runtime/README.md b/runtime/README.md
new file mode 100644
index 000000000..bdc9cbda8
--- /dev/null
+++ b/runtime/README.md
@@ -0,0 +1,57 @@
+Runtime
+
+Helix looks for some additional files on startup to provide features
+like the tutorial (`:tutor`) or syntax highlighting.
+
+The directory that contains these files is called the _runtime
+directory_. Check the "Runtime directory" line from `hx --health` to
+find where Helix looks for the runtime directory on your machine.
+
+When installed correctly, the runtime directory should have a shape
+like this:
+
+```
+$ tree $HELIX_RUNTIME
+runtime
+├── tutor            The tutorial file.
+├── grammars         Compiled tree-sitter parsers.
+│   ├── rust.so
+│   ├── awk.so
+│   ├── bash.so
+│   └── sources      (Optional) source files for tree-sitter parsers.
+│       └── ...      Used in 'hx --grammar build'.
+├── help             Documentation for the :help command.
+│   └── ...
+└── queries          Tree-sitter queries.
+    ├── rust
+    │   ├── highlights.scm
+    │   ├── injections.scm
+    │   └── textobjects.scm
+    └── ...
+```
+
+When looking up the runtime directory, Helix checks these places in
+order and returns the first value that exists:
+
+* The `HELIX_RUNTIME` environment variable. If that variable is set,
+  the value is treated as the path to the runtime directory.
+* The root of the Helix repository under a directory named `runtime`,
+  if running from source.
+* The config directory under a directory named `runtime`.
+* The parent directory of the Helix executable under a directory
+  named `runtime`.
+
+If you installed Helix through a package manager, the package manager
+most likely installed the runtime directory and wrapped Helix in a
+script that sets `HELIX_RUNTIME`.
+
+If you are building from source, you should set up a link between
+the `runtime` directory in the Helix git repository and the config
+directory.
+
+| OS                   | Command                                          |
+| -------------------- | ------------------------------------------------ |
+| Windows (Cmd)        | `xcopy /e /i runtime %AppData%\helix\runtime`    |
+| Windows (PowerShell) | `xcopy /e /i runtime $Env:AppData\helix\runtime` |
+| Linux / macOS        | `ln -s $PWD/runtime ~/.config/helix/runtime`     |
+
diff --git a/runtime/help/topics/Runtime.md b/runtime/help/topics/Runtime.md
new file mode 120000
index 000000000..fe8400541
--- /dev/null
+++ b/runtime/help/topics/Runtime.md
@@ -0,0 +1 @@
+../../README.md
\ No newline at end of file