git.iko.soy/helix
on master help sign in
Add optional runtime fallback directory (#8610)
b5d691aSkyler Hawthorne
book/src/install.md+23−3
compare with master
unifiedsplit
@@ -224,7 +224,7 @@ Or, create a symbolic link:
224ln -Ts $PWD/runtime ~/.config/helix/runtime
224ln -Ts $PWD/runtime ~/.config/helix/runtime
225```
225```
226
226
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.
228
228
229#### Windows
229#### Windows
230
230
@@ -257,12 +257,32 @@ following order:
2571. `runtime/` sibling directory to `$CARGO_MANIFEST_DIR` directory (this is intended for
2571. `runtime/` sibling directory to `$CARGO_MANIFEST_DIR` directory (this is intended for
258 developing and testing helix only).
258 developing and testing helix only).
2592. `runtime/` subdirectory of OS-dependent helix user config directory.
2592. `runtime/` subdirectory of OS-dependent helix user config directory.
260−3. `$HELIX_RUNTIME`.
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)
261−4. `runtime/` subdirectory of path to Helix executable.
263+5. `runtime/` subdirectory of path to Helix executable.
262
264
263This order also sets the priority for selecting which file will be used if multiple runtime
265This order also sets the priority for selecting which file will be used if multiple runtime
264directories have files with the same name.
266directories have files with the same name.
265
267
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+
266### Validating the installation
286### Validating the installation
267
287
268To make sure everything is set up as expected you should run the Helix health
288To 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>) {
60/// 1. sibling directory to `CARGO_MANIFEST_DIR` (if environment variable is set)
60/// 1. sibling directory to `CARGO_MANIFEST_DIR` (if environment variable is set)
61/// 2. subdirectory of user config directory (always included)
61/// 2. subdirectory of user config directory (always included)
62/// 3. `HELIX_RUNTIME` (if environment variable is set)
62/// 3. `HELIX_RUNTIME` (if environment variable is set)
63+/// 4. `HELIX_DEFAULT_RUNTIME` (if environment variable is set *at build time*)
63−/// 4. subdirectory of path to helix executable (always included)
64+/// 5. subdirectory of path to helix executable (always included)
64///
65///
65/// Postcondition: returns at least two paths (they might not exist).
66/// Postcondition: returns at least two paths (they might not exist).
66fn prioritize_runtime_dirs() -> Vec<PathBuf> {
67fn prioritize_runtime_dirs() -> Vec<PathBuf> {
@@ -81,6 +82,14 @@ fn prioritize_runtime_dirs() -> Vec<PathBuf> {
81 rt_dirs.push(dir.into());
82 rt_dirs.push(dir.into());
82 }
83 }
83
84
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+
84 // fallback to location of the executable being run
93 // fallback to location of the executable being run
85 // canonicalize the path in case the executable is symlinked
94 // canonicalize the path in case the executable is symlinked
86 let exe_rt_dir = std::env::current_exe()
95 let exe_rt_dir = std::env::current_exe()