git.iko.soy/helix
on master help sign in
Add optional runtime fallback directory (#8610)
commitb5d691a5d7e791f9b9581d96217f80ea10a6f2ca authorSkyler Hawthorne <skyler@dead10ck.com> dateWed 25 Oct 2023, 12:08 (3 years ago) parent68c7537
2 files changed+33−4
compare with master
unifiedsplit
book/src/install.md+23−3 helix-loader/src/lib.rs+10−1
book/src/install.md+23−3
@@ -224,7 +224,7 @@ Or, create a symbolic link:
224224ln -Ts $PWD/runtime ~/.config/helix/runtime
225225```
226226
227−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.
227+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.
228228
229229#### Windows
230230
@@ -257,12 +257,32 @@ following order:
2572571. `runtime/` sibling directory to `$CARGO_MANIFEST_DIR` directory (this is intended for
258258 developing and testing helix only).
2592592. `runtime/` subdirectory of OS-dependent helix user config directory.
260−3. `$HELIX_RUNTIME`.
261−4. `runtime/` subdirectory of path to Helix executable.
260+3. `$HELIX_RUNTIME`
261+4. Distribution-specific fallback directory (set at compile time—not run time—
262+ with the `HELIX_DEFAULT_RUNTIME` environment variable)
263+5. `runtime/` subdirectory of path to Helix executable.
262264
263265This order also sets the priority for selecting which file will be used if multiple runtime
264266directories have files with the same name.
265267
268+#### Note to packagers
269+
270+If you are making a package of Helix for end users, to provide a good out of
271+the box experience, you should set the `HELIX_DEFAULT_RUNTIME` environment
272+variable at build time (before invoking `cargo build`) to a directory which
273+will store the final runtime files after installation. For example, say you want
274+to package the runtime into `/usr/lib/helix/runtime`. The rough steps a build
275+script could follow are:
276+
277+1. `export HELIX_DEFAULT_RUNTIME=/usr/lib/helix/runtime`
278+1. `cargo build --profile opt --locked --path helix-term`
279+1. `cp -r runtime $BUILD_DIR/usr/lib/helix/`
280+1. `cp target/opt/hx $BUILD_DIR/usr/bin/hx`
281+
282+This way the resulting `hx` binary will always look for its runtime directory in
283+`/usr/lib/helix/runtime` if the user has no custom runtime in `~/.config/helix`
284+or `HELIX_RUNTIME`.
285+
266286### Validating the installation
267287
268288To make sure everything is set up as expected you should run the Helix health
helix-loader/src/lib.rs+10−1
@@ -60,7 +60,8 @@ pub fn initialize_log_file(specified_file: Option<PathBuf>) {
6060/// 1. sibling directory to `CARGO_MANIFEST_DIR` (if environment variable is set)
6161/// 2. subdirectory of user config directory (always included)
6262/// 3. `HELIX_RUNTIME` (if environment variable is set)
63−/// 4. subdirectory of path to helix executable (always included)
63+/// 4. `HELIX_DEFAULT_RUNTIME` (if environment variable is set *at build time*)
64+/// 5. subdirectory of path to helix executable (always included)
6465///
6566/// Postcondition: returns at least two paths (they might not exist).
6667fn prioritize_runtime_dirs() -> Vec<PathBuf> {
@@ -81,6 +82,14 @@ fn prioritize_runtime_dirs() -> Vec<PathBuf> {
8182 rt_dirs.push(dir.into());
8283 }
8384
85+ // If this variable is set during build time, it will always be included
86+ // in the lookup list. This allows downstream packagers to set a fallback
87+ // directory to a location that is conventional on their distro so that they
88+ // need not resort to a wrapper script or a global environment variable.
89+ if let Some(dir) = std::option_env!("HELIX_DEFAULT_RUNTIME") {
90+ rt_dirs.push(dir.into());
91+ }
92+
8493 // fallback to location of the executable being run
8594 // canonicalize the path in case the executable is symlinked
8695 let exe_rt_dir = std::env::current_exe()