Add optional runtime fallback directory (#8610)

1 files changed, 23 insertions, 3 deletions

diff --git a/book/src/install.md b/book/src/install.md
index 9c052917..01858034 100644
--- a/book/src/install.md
+++ b/book/src/install.md
@@ -224,7 +224,7 @@ Or, create a symbolic link:
 ln -Ts $PWD/runtime ~/.config/helix/runtime
 ```
 
-If the above command fails to create a symbolic link because the file exists either move `~/.config/helix/runtime` to a new location or delete it, then run the symlink command above again. 
+If the above command fails to create a symbolic link because the file exists either move `~/.config/helix/runtime` to a new location or delete it, then run the symlink command above again.
 
 #### Windows
 
@@ -257,12 +257,32 @@ following order:
 1. `runtime/` sibling directory to `$CARGO_MANIFEST_DIR` directory (this is intended for
   developing and testing helix only).
 2. `runtime/` subdirectory of OS-dependent helix user config directory.
-3. `$HELIX_RUNTIME`.
-4. `runtime/` subdirectory of path to Helix executable.
+3. `$HELIX_RUNTIME`
+4. Distribution-specific fallback directory (set at compile time—not run time—
+   with the `HELIX_DEFAULT_RUNTIME` environment variable)
+5. `runtime/` subdirectory of path to Helix executable.
 
 This order also sets the priority for selecting which file will be used if multiple runtime
 directories have files with the same name.
 
+#### Note to packagers
+
+If you are making a package of Helix for end users, to provide a good out of
+the box experience, you should set the `HELIX_DEFAULT_RUNTIME` environment
+variable at build time (before invoking `cargo build`) to a directory which
+will store the final runtime files after installation. For example, say you want
+to package the runtime into `/usr/lib/helix/runtime`. The rough steps a build
+script could follow are:
+
+1. `export HELIX_DEFAULT_RUNTIME=/usr/lib/helix/runtime`
+1. `cargo build --profile opt --locked --path helix-term`
+1. `cp -r runtime $BUILD_DIR/usr/lib/helix/`
+1. `cp target/opt/hx $BUILD_DIR/usr/bin/hx`
+
+This way the resulting `hx` binary will always look for its runtime directory in
+`/usr/lib/helix/runtime` if the user has no custom runtime in `~/.config/helix`
+or `HELIX_RUNTIME`.
+
 ### Validating the installation
 
 To make sure everything is set up as expected you should run the Helix health