hyper-linux-examples

Runnable Linux applications for hyper-linux (hl). The first example packages XMMS 1.2.11 for aarch64-linux and x86_64-linux guests and composes it with hyper-linux-x11 on Apple Silicon macOS.

Repository	Responsibility
hyper-linux	ELF runtime, rooted VFS, OSS audio, and host audio backends
hyper-linux-x11	Optional AppKit-origin X server and application supervisor
hyper-linux-examples	Guest packages, sysroots, reproducible media, and runnable app compositions

Try it

The default app uses an aarch64-linux guest, starts a supervised AppKit-origin X server, and opens a reproducible 17-track SoundHelix playlist:

nix run github:zw3rk/hyper-linux-examples#xmms

Select the x86_64-linux guest with either spelling:

nix run github:zw3rk/hyper-linux-examples#xmms.x86_64-linux
nix run github:zw3rk/hyper-linux-examples#xmms-x86_64-linux

Arguments after -- are passed to XMMS unchanged. ~/Music is available read-only inside the guest as /home/user/Music:

nix run github:zw3rk/hyper-linux-examples#xmms -- \
  /home/user/Music/SoundHelix/demo.m3u

Use an existing X11 server instead of the AppKit supervisor with #xmms-x11:

DISPLAY=:0 nix run github:zw3rk/hyper-linux-examples#xmms-x11

The raw-X11 launcher still uses hl; macOS cannot execute the Linux XMMS ELF directly. It only omits the AppKit X-server lifecycle wrapper.

Local development

With hyper-linux, hyper-linux-x11, and this repository in one parent directory, the Makefile uses dirty path: overrides automatically:

make check
make run
make run-x64

Run make help for package, sysroot, candidate, and runtime targets. Detailed commands, media mounts, and release qualification are documented in USAGE.md. Artifact pins and licenses are in fixtures/xmms/MANIFEST.md.

Design

The root flake exports a generic mkHyperLinuxApp factory. An application descriptor supplies its guest sysroot, executable, persistent home seed, mounts, default arguments, and optional prepare/readiness/cleanup hooks. The same descriptor produces both an AppKit-supervised launcher and an ambient-X11 launcher; the generic scripts contain no XMMS launch policy. Readiness failure terminates the supervised process and still performs generation cleanup. The exact factory and hook contract is documented in USAGE.md.

The initial XMMS package was extracted from the pre-split Hyper Linux worktree in July 2026. Runtime support remains in hyper-linux; application packaging belongs here.

License

Repository-authored Nix expressions and scripts are Apache-2.0, copyright 2026 Moritz Angermann <moritz@zw3rk.com>, zw3rk pte. ltd. Upstream XMMS is GPL-2.0-or-later; GLib/GTK 1.2 are LGPL-2.0-or-later. Compatibility patches remain under their respective upstream licenses. The demo MP3s come from the official SoundHelix audio examples page; this repository does not assign them a license. The generated smoke WAV is CC0.