Skip to content

USAGE.md

Latest commit

 

History

History
222 lines (174 loc) · 8.19 KB

USAGE.md

File metadata and controls

222 lines (174 loc) · 8.19 KB
Raw

hyper-linux-examples — usage

Prerequisites

Requirement Used for
Apple Silicon macOS Hypervisor.framework host for hl
Nix with flakes Reproducible application and guest package builds
Linux builder aarch64-linux packages; x86_64-linux for Rosetta qualification
Ambient X11 server Only the *-x11 applications

Linux builder setup is documented in the hyper-linux builder guide.

Runnable flake applications

nix run selector Guest X-server behavior
#xmms aarch64-linux Supervised AppKit-origin X; default
#xmms.x86_64-linux x86_64-linux Supervised AppKit-origin X
#xmms-x86_64-linux x86_64-linux Visible flat alias of the preceding app
#xmms-x11 aarch64-linux Use ambient DISPLAY
#xmms-x11-x86_64-linux x86_64-linux Use ambient DISPLAY
#xmms-remote host tool Control a running XMMS instance

With no XMMS arguments, the launcher mounts the pinned SoundHelix derivation read-only at /media and opens /media/demo.m3u:

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

Arguments after -- are opaque application arguments. They are neither reordered nor interpreted as host media paths:

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

The launchers expose ~/Music read-only at /home/user/Music. To expose a different directory, supply one explicit hl bind and use its guest path in the XMMS argument vector:

HL_APP_BIND="$PWD/media:/library:ro" \
  nix run github:zw3rk/hyper-linux-examples#xmms -- /library/demo.m3u

Application state is isolated in ~/.hl/instances/xmms-aarch64/home or ~/.hl/instances/xmms-x86_64/home. The complete host home is not exposed.

For raw X11, start or select an X server first:

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

Instance control

Select the player explicitly rather than relying on whichever XMMS happened to allocate session zero:

nix run github:zw3rk/hyper-linux-examples#xmms-remote -- \
  --instance native status
nix run github:zw3rk/hyper-linux-examples#xmms-remote -- \
  --instance x86_64 playlist-length
nix run github:zw3rk/hyper-linux-examples#xmms-remote -- \
  --instance native play-pause

Aliases native, aarch64, aarch64-linux, x64, x86_64, and x86_64-linux are accepted. Control failures are visible and nonzero by default; add --quiet for media-key or best-effort integrations.

Local sibling development

The root flake pins the coordinated public release candidates. Before those tags are published, or while changing the runtime siblings, use the Makefile's dirty-worktree path: overrides:

make help
make check
make run
make run-x64
make remote INSTANCE=native COMMAND=status

The equivalent direct local invocation is:

nix run \
  --override-input hyper-linux path:../hyper-linux \
  --override-input hyper-linux-x11 path:../hyper-linux-x11 \
  path:.#xmms

Enter the local development shell with the same sibling overrides:

nix develop \
  --override-input hyper-linux path:../hyper-linux \
  --override-input hyper-linux-x11 path:../hyper-linux-x11 \
  path:.

make flake-check-candidate instead uses the committed master tips of both sibling repositories. make flake-check-release resolves the public pins and is the release gate after the tags exist.

For simple local argument vectors, the Make target is parameterized rather than tied to XMMS:

make run APP=xmms-x11 RUN_ARGS='--help'

Use nix run ... -- ... directly when arguments contain shell-sensitive characters or must preserve exact quoting.

Application factory

The Apple Silicon host factory is exported as lib.aarch64-darwin.mkHyperLinuxApp. A descriptor provides:

Field Contract
name, x11Name, appName Package/program names and the visible application name
guestSystem Guest package system, currently aarch64-linux or x86_64-linux
instanceId Path-safe persistent-state identifier ([A-Za-z0-9][A-Za-z0-9._-]*)
sysroot, program Rooted guest sysroot and Linux executable
binds, homeBinds Static store mounts and optional host-home-relative mounts
defaultArgs Arguments used only when the user supplies no application arguments
guestCwd, homeSeed, audioBackend Guest working directory, initial home contents, and hl audio backend
prepare, ready, cleanup Optional application-specific lifecycle hooks

The prepare hook runs as prepare <instance-root> [application-arguments...] before hl starts. The readiness hook runs as ready <instance-root> <run-token> <supervised-pid> after the child starts and must return only when application-specific startup is complete. A readiness failure terminates and waits for the child, becomes the launcher exit status, and does not skip cleanup. The cleanup hook runs as cleanup <instance-root> <run-token> exactly once after the supervised process returns. Hooks must be bounded. HL_APP_BIND, HL_DISPLAY, and HL_APP_NAME are supported caller overrides. Other HL_APP_* variables are internal launcher state and callers must not set them. Generated launchers clear optional guest hooks that their descriptor did not select.

Each descriptor returns appkitApp/appkitPackage and x11App/x11Package. The X11 form uses the ambient DISPLAY and omits the AppKit X-server supervisor, but both forms still execute the Linux program via hl.

Verify and build guest packages

make check
make build-sysroot
make check-sysroot

make build-sysroot GUEST_SYSTEM=x86_64-linux
make check-sysroot GUEST_SYSTEM=x86_64-linux
make qualify-lifecycle LIFECYCLE_ITERATIONS=10

Builds have a 30-minute default timeout. Override BUILD_TIMEOUT_SECONDS, TIMEOUT, or GUEST_SYSTEM when necessary. Architecture-specific result links prevent one guest build from silently replacing the other:

Link Contents
result-xmms-<guest-system> Upstream-style XMMS package
result-sysroot-<guest-system> Loader, libraries, plugins, data, and XMMS
result-check-sysroot-<guest-system> Successful sysroot validation result

Exact package attributes remain available:

nix build .#packages.aarch64-linux.xmms
nix build .#packages.aarch64-linux.xmms-sysroot
nix build .#packages.x86_64-linux.xmms
nix build .#packages.x86_64-linux.xmms-sysroot

The bounded non-GUI qualification path is:

make -C ../hyper-linux hl
HL=../hyper-linux/_build/hl make smoke-xmms

Release qualification

Before publishing a coordinated examples candidate:

  1. Run make check against dirty local sibling worktrees.
  2. Run make flake-check-candidate against committed sibling tips.
  3. Build and validate both guest sysroots.
  4. Run make qualify-lifecycle for both guest architectures.
  5. Launch both AppKit apps and verify status, playback, and playlist length.
  6. Launch at least one raw-X11 selector against XQuartz or another X server.
  7. Publish the referenced hyper-linux and hyper-linux-x11 tags.
  8. Run nix flake lock, then make verify-release-lock to confirm both inputs use the expected zw3rk repositories and tags, with committed revisions and hashes.
  9. Run make flake-check-release without overrides.
  10. Commit the completed flake.lock with the release-facing CI and docs.
  11. Only then publish the examples commit. Publish a candidate tag only when the release plan defines its version and scope.

Do not publish examples commits before step 7: public and trusted CI intentionally evaluate the release-pinned inputs and must never turn a missing release lock into a successful skip. For the first publication, create the public repository only after the final release lock is committed.

Historical pre-fix behavior remains in fixtures/xmms/baseline/README.md. The concise interactive checklist is fixtures/xmms/REPRO.md.