From 4ea2243e4d1a44f910857bd759845db70e3690a8 Mon Sep 17 00:00:00 2001
From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com>
Date: Sun, 18 Oct 2026 18:15:17 +0200
Subject: [PATCH] horizon-server on Linux: say which libraries the game needs,
and follow updates
On a Linux without ALSA's library (most minimal server images), the
game exits at once with the loader's "error while loading shared
libraries: libasound.so.2". The supervisor took that for a crash and
restarted it five times over two and a half minutes before giving up
with "see logs/latest.log", which holds nothing about it.
Now:
- `run` starts the game with --help first (it loads no game files) and,
if the system can't load it, stops at once with the loader's line and
the packages to install on Debian/Ubuntu, Fedora, Arch and NixOS;
- `init` prints the same as a warning after "Game:";
- install.sh lists the libraries `ldd` can't find, with the same advice;
- docs/server.md says so in the install section.
Also, a service installed without the installer's launcher on the PATH
ran `
/releases//horizon-server`: Linux reports the running
program with links resolved, so the unit pinned that release and an
update never reached it. The fallback now goes through `/current`
while it points at that release.
Found by the end-to-end install check on the ThinkPad (NixOS, no
nix-ld libraries) with v2026.10.18.15.
Co-Authored-By: Claude Opus 5.5
---
crates/horizon-server/src/engine.rs | 92 +++++++++++++++++++++++++
crates/horizon-server/src/init.rs | 3 +
crates/horizon-server/src/service.rs | 43 +++++++++++-
crates/horizon-server/src/supervisor.rs | 2 +
docs/server.md | 5 ++
packaging/server/install.sh | 12 ++++
6 files changed, 155 insertions(+), 2 deletions(-)
diff --git a/crates/horizon-server/src/engine.rs b/crates/horizon-server/src/engine.rs
index b39b5bed9..d1373bb05 100644
--- a/crates/horizon-server/src/engine.rs
+++ b/crates/horizon-server/src/engine.rs
@@ -49,6 +49,52 @@ pub fn program(config: &Config, dir: &Path) -> Result {
})
}
+/// Checks that the game program starts at all: `--help` loads no game files, so it fails only when the
+/// system can't load the program, as on a Linux without the ALSA and udev libraries it links (even a
+/// server needs them until there is a headless engine). The reason, with what to install.
+pub fn check_starts(program: &Path) -> Result<(), String> {
+ let output = Command::new(program)
+ .arg("--help")
+ .stdin(Stdio::null())
+ .stdout(Stdio::null())
+ .stderr(Stdio::piped())
+ .output()
+ .map_err(|e| format!("the game ({}) can't start: {e}", program.display()))?;
+ if output.status.success() {
+ return Ok(());
+ }
+ let stderr = String::from_utf8_lossy(&output.stderr);
+ Err(start_failure(program, output.status.code(), &stderr))
+}
+
+/// What to tell the owner when the game program exits at once.
+fn start_failure(program: &Path, code: Option, stderr: &str) -> String {
+ let reason = stderr
+ .lines()
+ .find(|l| !l.trim().is_empty())
+ .unwrap_or("")
+ .trim();
+ let mut text = format!(
+ "the game ({}) can't start{}{}",
+ program.display(),
+ code.map_or(String::new(), |c| format!(" (exit status {c})")),
+ if reason.is_empty() {
+ String::new()
+ } else {
+ format!(": {reason}")
+ }
+ );
+ if reason.contains("error while loading shared libraries") {
+ text.push_str(
+ "\nIt needs ALSA's and udev's libraries (libasound.so.2, libudev.so.1), even on a server. Install \
+ them:\n Debian, Ubuntu: sudo apt install libasound2 libudev1 (Ubuntu 24.04 and later: \
+ libasound2t64)\n Fedora, RHEL: sudo dnf install alsa-lib systemd-libs\n Arch: sudo pacman -S \
+ alsa-lib systemd-libs\n NixOS: enable programs.nix-ld with alsa-lib and udev in its libraries",
+ );
+ }
+ text
+}
+
/// Where the prepared game files may be, in the order they are tried.
pub fn resource_candidates(config: &Config, dir: &Path, program: Option<&Path>) -> Vec {
if !config.engine.resources.is_empty() {
@@ -195,4 +241,50 @@ mod tests {
assert_eq!(resources(&config, &server, Some(&program)), Ok(prepared));
std::fs::remove_dir_all(&root).unwrap();
}
+
+ #[test]
+ fn a_missing_library_says_what_to_install() {
+ let program = Path::new("/opt/horizon/horizon-client");
+ let text = start_failure(
+ program,
+ Some(127),
+ "/opt/horizon/horizon-client: error while loading shared libraries: libasound.so.2: cannot open \
+ shared object file: No such file or directory\n",
+ );
+ assert!(text.starts_with(
+ "the game (/opt/horizon/horizon-client) can't start (exit status 127): /opt/horizon/horizon-client: \
+ error while loading shared libraries: libasound.so.2"
+ ));
+ assert!(text.contains("sudo apt install libasound2 libudev1"));
+ let other = start_failure(program, Some(1), "something else\n");
+ assert_eq!(
+ other,
+ "the game (/opt/horizon/horizon-client) can't start (exit status 1): something else"
+ );
+ }
+
+ #[cfg(unix)]
+ #[test]
+ fn the_check_runs_the_program() {
+ use std::os::unix::fs::PermissionsExt;
+ let root =
+ std::env::temp_dir().join(format!("horizon-server-check-{}", std::process::id()));
+ std::fs::create_dir_all(&root).unwrap();
+ let script = |name: &str, body: &str| {
+ let path = root.join(name);
+ std::fs::write(&path, format!("#!/bin/sh\n{body}\n")).unwrap();
+ std::fs::set_permissions(&path, std::fs::Permissions::from_mode(0o755)).unwrap();
+ path
+ };
+ assert_eq!(check_starts(&script("starts", "exit 0")), Ok(()));
+ let fails = script("fails", "echo 'no luck' >&2; exit 3");
+ assert_eq!(
+ check_starts(&fails),
+ Err(format!(
+ "the game ({}) can't start (exit status 3): no luck",
+ fails.display()
+ ))
+ );
+ std::fs::remove_dir_all(&root).unwrap();
+ }
}
diff --git a/crates/horizon-server/src/init.rs b/crates/horizon-server/src/init.rs
index 757b6def8..bd595cddb 100644
--- a/crates/horizon-server/src/init.rs
+++ b/crates/horizon-server/src/init.rs
@@ -205,6 +205,9 @@ pub fn run(dir: &Path, answers: Answers) -> Result<(), String> {
match engine::program(&cfg, dir) {
Ok(program) => {
println!("Game: {}", program.display());
+ if let Err(e) = engine::check_starts(&program) {
+ println!("Warning: {e}");
+ }
match engine::resources(&cfg, dir, Some(&program)) {
Ok(resources) => println!("Game files: {}", resources.display()),
Err(e) => println!("{e}"),
diff --git a/crates/horizon-server/src/service.rs b/crates/horizon-server/src/service.rs
index 2cafa0e3d..6e6d59f23 100644
--- a/crates/horizon-server/src/service.rs
+++ b/crates/horizon-server/src/service.rs
@@ -32,7 +32,8 @@ pub fn name(dir: &Path) -> String {
}
/// The program the service runs: the `horizon-server` on the PATH (the installer's launcher, which keeps
-/// running the current version after an update), else this program.
+/// running the current version after an update), else this program, through the installer's `current`
+/// link when it runs from an installed release.
fn program() -> Result {
let on_path = std::env::var_os("PATH")
.map(|p| std::env::split_paths(&p).collect::>())
@@ -42,10 +43,30 @@ fn program() -> Result {
.find(|p| p.is_file());
match on_path {
Some(path) => Ok(path),
- None => std::env::current_exe().map_err(|e| e.to_string()),
+ None => std::env::current_exe()
+ .map(|exe| through_current(&exe))
+ .map_err(|e| e.to_string()),
}
}
+/// `/releases//horizon-server` as `/current/horizon-server` while `current` points at that
+/// release (install.sh and install.ps1's layout), so an update applies at the next restart. Linux reports
+/// the running program with links resolved, so the release's own path is what this program sees there.
+fn through_current(exe: &Path) -> PathBuf {
+ let current = (|| {
+ let release = exe.parent()?;
+ let releases = release.parent()?;
+ if releases.file_name()? != "releases" {
+ return None;
+ }
+ let current = releases.parent()?.join("current");
+ let name = exe.file_name()?;
+ let same = std::fs::canonicalize(¤t).ok()? == std::fs::canonicalize(release).ok()?;
+ same.then(|| current.join(name))
+ })();
+ current.unwrap_or_else(|| exe.to_path_buf())
+}
+
/// A systemd unit: a user unit, or with `user` a system unit running as that user.
pub fn systemd_unit(program: &Path, dir: &Path, user: Option<&str>) -> String {
let (run_as, wanted_by) = match user {
@@ -374,4 +395,22 @@ mod tests {
assert!(plist.contains("/srv/R&D"));
assert!(plist.contains("/srv/R&D/logs/supervisor.log"));
}
+
+ #[cfg(unix)]
+ #[test]
+ fn an_installed_release_runs_through_current() {
+ let root =
+ std::env::temp_dir().join(format!("horizon-service-current-{}", std::process::id()));
+ let release = root.join("releases/v1");
+ std::fs::create_dir_all(&release).unwrap();
+ let exe = release.join("horizon-server");
+ std::fs::write(&exe, "").unwrap();
+ // Not the release in use (or no installer layout): this program as it is.
+ assert_eq!(through_current(&exe), exe);
+ std::os::unix::fs::symlink(&release, root.join("current")).unwrap();
+ assert_eq!(through_current(&exe), root.join("current/horizon-server"));
+ let other = root.join("bin/horizon-server");
+ assert_eq!(through_current(&other), other);
+ std::fs::remove_dir_all(&root).unwrap();
+ }
}
diff --git a/crates/horizon-server/src/supervisor.rs b/crates/horizon-server/src/supervisor.rs
index ad056a77c..fdec60eff 100644
--- a/crates/horizon-server/src/supervisor.rs
+++ b/crates/horizon-server/src/supervisor.rs
@@ -76,6 +76,8 @@ pub fn run(dir: &Path) -> Result<(), String> {
let config = Config::load(dir)?;
let program = engine::program(&config, dir)?;
let resources = engine::resources(&config, dir, Some(&program))?;
+ // A game the system can't load would only crash again at every restart: say why at once.
+ engine::check_starts(&program)?;
let _lock = lock(dir)?;
let shared = Shared::new(dir);
let _endpoint = api::start(shared.clone())?;
diff --git a/docs/server.md b/docs/server.md
index 941a4341b..6c6c4a9b4 100644
--- a/docs/server.md
+++ b/docs/server.md
@@ -185,6 +185,11 @@ comes out of the headless-engine work.
it from GitHub Releases, and checks it against the SHA-256 GitHub publishes for each asset. It never asks
for sudo. Options: `--version vX.Y.Z`, `--dir` (default `~/.local/share/horizon`), `--bin` (default
`~/.local/bin`).
+ On Linux the game links ALSA's and udev's libraries (`libasound.so.2`, `libudev.so.1`) even as a server,
+ until the headless engine exists. Minimal server images often lack ALSA (Debian and Ubuntu:
+ `sudo apt install libasound2 libudev1`, `libasound2t64` on Ubuntu 24.04 and later). The script lists any
+ that are missing, `init` warns, and `run` stops at once with what to install, rather than restarting a
+ game that can't load.
- Windows:
`irm https://raw.githubusercontent.com/ludovic111/horizon/main/packaging/server/install.ps1 | iex`
The script does the same into `%LOCALAPPDATA%\Horizon` (`-Version`, `-Dir`), with junctions instead of
diff --git a/packaging/server/install.sh b/packaging/server/install.sh
index 221fcf0a8..08b710e37 100755
--- a/packaging/server/install.sh
+++ b/packaging/server/install.sh
@@ -86,6 +86,18 @@ for tool in horizon-server horizon-prepare; do
done
echo "Installed Horizon $TAG in $RELEASE; horizon-server and horizon-prepare are in $BIN."
+# The game links ALSA and udev, even as a server; minimal Linux images often lack them.
+if [ "$(uname -s)" = Linux ] && command -v ldd >/dev/null; then
+ MISSING=$(ldd "$RELEASE/horizon-client" 2>/dev/null | awk '/not found/ { printf "%s ", $1 }')
+ if [ -n "$MISSING" ]; then
+ echo "The game needs libraries this system doesn't have: $MISSING"
+ echo "Install them before starting a server:"
+ echo " Debian, Ubuntu: sudo apt install libasound2 libudev1 (Ubuntu 24.04 and later: libasound2t64)"
+ echo " Fedora, RHEL: sudo dnf install alsa-lib systemd-libs"
+ echo " Arch: sudo pacman -S alsa-lib systemd-libs"
+ echo " NixOS: enable programs.nix-ld with alsa-lib and udev in its libraries"
+ fi
+fi
case ":$PATH:" in
*":$BIN:"*) ;;
*) echo "Add $BIN to your PATH, for example: echo 'export PATH=\"$BIN:\$PATH\"' >> ~/.profile" ;;