diff options
| -rw-r--r-- | book/src/install.md | 26 | ||||
| -rw-r--r-- | helix-loader/src/lib.rs | 11 |
2 files changed, 33 insertions, 4 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 diff --git a/helix-loader/src/lib.rs b/helix-loader/src/lib.rs index 82ed2ede..5337d602 100644 --- a/helix-loader/src/lib.rs +++ b/helix-loader/src/lib.rs @@ -60,7 +60,8 @@ pub fn initialize_log_file(specified_file: Option<PathBuf>) { /// 1. sibling directory to `CARGO_MANIFEST_DIR` (if environment variable is set) /// 2. subdirectory of user config directory (always included) /// 3. `HELIX_RUNTIME` (if environment variable is set) -/// 4. subdirectory of path to helix executable (always included) +/// 4. `HELIX_DEFAULT_RUNTIME` (if environment variable is set *at build time*) +/// 5. subdirectory of path to helix executable (always included) /// /// Postcondition: returns at least two paths (they might not exist). fn prioritize_runtime_dirs() -> Vec<PathBuf> { @@ -81,6 +82,14 @@ fn prioritize_runtime_dirs() -> Vec<PathBuf> { rt_dirs.push(dir.into()); } + // If this variable is set during build time, it will always be included + // in the lookup list. This allows downstream packagers to set a fallback + // directory to a location that is conventional on their distro so that they + // need not resort to a wrapper script or a global environment variable. + if let Some(dir) = std::option_env!("HELIX_DEFAULT_RUNTIME") { + rt_dirs.push(dir.into()); + } + // fallback to location of the executable being run // canonicalize the path in case the executable is symlinked let exe_rt_dir = std::env::current_exe() |