Makefile

# hyper-linux-examples — XMMS demos + sysroots for hyper-linux (hl)
#
# Copyright (c) 2026 Moritz Angermann <moritz@zw3rk.com>, zw3rk pte. ltd.
# SPDX-License-Identifier: Apache-2.0

.DEFAULT_GOAL := help

NIX ?= nix
TIMEOUT ?= timeout
BUILD_TIMEOUT_SECONDS ?= 1800
CHECK_TIMEOUT_SECONDS ?= 120
LIFECYCLE_ITERATIONS ?= 10
LIFECYCLE_TIMEOUT_SECONDS ?= 900
GUEST_SYSTEM ?= aarch64-linux
NIX_PKG_SYS = packages.$(GUEST_SYSTEM)
HL_SOURCE ?= ../hyper-linux
HL_X11_SOURCE ?= ../hyper-linux-x11
HL_REF ?= master
HL_X11_REF ?= master
LOCAL_OVERRIDES = \
	--override-input hyper-linux "path:$(abspath $(HL_SOURCE))" \
	--override-input hyper-linux-x11 "path:$(abspath $(HL_X11_SOURCE))"
CANDIDATE_OVERRIDES = \
	--override-input hyper-linux "git+file://$(abspath $(HL_SOURCE))?ref=$(HL_REF)" \
	--override-input hyper-linux-x11 "git+file://$(abspath $(HL_X11_SOURCE))?ref=$(HL_X11_REF)"

##@ General

.PHONY: help
help: ## Show this help
	@awk 'BEGIN {FS = ":.*##"; printf "\n\033[1mUsage:\033[0m\n  make \033[36m<target>\033[0m\n"} \
		/^##@/ { printf "\n\033[1m%s\033[0m\n", substr($$0, 5) } \
		/^[a-zA-Z0-9_.-]+:.*?## / { printf "  \033[36m%-28s\033[0m %s\n", $$1, $$2 }' $(MAKEFILE_LIST)

##@ Verification

.PHONY: verify-media
verify-media: ## Verify smoke WAV SHA-256
	cd fixtures/xmms/media && shasum -a 256 -c smoke-440-660.wav.sha256

.PHONY: verify-source
verify-source: ## Check source paths, scripts, and control protocol tests
	./scripts/verify-source.sh

.PHONY: verify verify-release-lock flake-check flake-check-candidate flake-check-release shellcheck lint-actions check
verify: verify-source verify-media flake-check ## Run fast checks without building Linux packages

flake-check: ## Evaluate every flake output against dirty local siblings
	$(TIMEOUT) $(CHECK_TIMEOUT_SECONDS) $(NIX) flake check path:. \
		--no-build --all-systems --no-write-lock-file $(LOCAL_OVERRIDES)

flake-check-candidate: ## Evaluate against committed local sibling tips
	$(TIMEOUT) $(CHECK_TIMEOUT_SECONDS) $(NIX) flake check path:. \
		--no-build --all-systems --no-write-lock-file $(CANDIDATE_OVERRIDES)

verify-release-lock: ## Require both public runtime inputs in flake.lock
	@$(NIX) eval --impure --raw --expr '\
		let \
		  lock = builtins.fromJSON (builtins.readFile ./flake.lock); \
		  inputs = (builtins.getAttr lock.root lock.nodes).inputs; \
		  expected = { \
		    hyper-linux = { repo = "hyper-linux"; ref = "v0.3.0-rc2"; }; \
		    hyper-linux-x11 = { repo = "hyper-linux-x11"; ref = "v0.1.0-rc2"; }; \
		  }; \
		  locked = name: \
		    builtins.hasAttr name inputs && \
		    (let \
		       node = builtins.getAttr (builtins.getAttr name inputs) lock.nodes; \
		       want = builtins.getAttr name expected; \
		     in node ? locked && node ? original && \
		        node.locked.type == "github" && \
		        node.locked.owner == "zw3rk" && \
		        node.locked.repo == want.repo && \
		        node.locked ? rev && node.locked ? narHash && \
		        node.original.type == "github" && \
		        node.original.owner == "zw3rk" && \
		        node.original.repo == want.repo && \
		        node.original.ref == want.ref); \
		in if locked "hyper-linux" && locked "hyper-linux-x11" \
		   then "exact public release inputs locked\n" \
		   else builtins.throw "flake.lock does not contain the exact public release inputs"'

flake-check-release: verify-release-lock ## Evaluate the release-pinned public inputs
	$(TIMEOUT) $(CHECK_TIMEOUT_SECONDS) $(NIX) flake check path:. \
		--no-build --all-systems --no-write-lock-file

shellcheck: ## Lint repository shell scripts
	shellcheck scripts/*.sh tests/*.sh

lint-actions: ## Validate GitHub Actions workflows
	actionlint .github/workflows/*.yml

check: verify shellcheck lint-actions ## Run the complete fast local gate

##@ Nix packages (Linux — needs a matching builder on Darwin)

.PHONY: build-glib12
build-glib12: ## Build glib 1.2.10 for GUEST_SYSTEM
	$(TIMEOUT) $(BUILD_TIMEOUT_SECONDS) $(NIX) build path:.#$(NIX_PKG_SYS).glib12 \
		--no-write-lock-file $(LOCAL_OVERRIDES) -L

.PHONY: build-gtk12
build-gtk12: ## Build gtk+ 1.2.10 for GUEST_SYSTEM
	$(TIMEOUT) $(BUILD_TIMEOUT_SECONDS) $(NIX) build path:.#$(NIX_PKG_SYS).gtk12 \
		--no-write-lock-file $(LOCAL_OVERRIDES) -L

.PHONY: build-xmms
build-xmms: ## Build XMMS 1.2.11 binary package
	$(TIMEOUT) $(BUILD_TIMEOUT_SECONDS) $(NIX) build path:.#$(NIX_PKG_SYS).xmms \
		--no-write-lock-file $(LOCAL_OVERRIDES) -L -o result-xmms-$(GUEST_SYSTEM)

.PHONY: build-sysroot
build-sysroot: ## Build XMMS sysroot (libs + plugins + bin) for hl --sysroot
	$(TIMEOUT) $(BUILD_TIMEOUT_SECONDS) $(NIX) build path:.#$(NIX_PKG_SYS).xmms-sysroot \
		--no-write-lock-file $(LOCAL_OVERRIDES) -L -o result-sysroot-$(GUEST_SYSTEM)

.PHONY: build
build: build-sysroot ## Alias: build xmms-sysroot

.PHONY: check-sysroot
check-sysroot: ## Build and validate the selected guest sysroot
	$(TIMEOUT) $(BUILD_TIMEOUT_SECONDS) $(NIX) build path:.#checks.$(GUEST_SYSTEM).xmms-sysroot \
		--no-write-lock-file $(LOCAL_OVERRIDES) -L -o result-check-sysroot-$(GUEST_SYSTEM)

##@ Runtime qualification

# Path to hl binary: sibling repo build, PATH, or HL override.
HL ?= $(shell command -v hl 2>/dev/null || echo ../hyper-linux/_build/hl)
SYSROOT ?= $(CURDIR)/result-sysroot-$(GUEST_SYSTEM)

.PHONY: smoke-xmms
smoke-xmms: build-sysroot ## Run a non-GUI XMMS version smoke under hl
	@test -x "$(HL)" || { echo "hl not found at $(HL); set HL=… or build sibling hyper-linux"; exit 1; }
	$(TIMEOUT) $(CHECK_TIMEOUT_SECONDS) ./scripts/smoke-xmms.sh "$(HL)" "$(SYSROOT)"

.PHONY: qualify-lifecycle qualify-lifecycle-native qualify-lifecycle-x64
qualify-lifecycle: qualify-lifecycle-native qualify-lifecycle-x64 ## Repeat launch and QUIT on both guest architectures

qualify-lifecycle-native: check-local-siblings ## Repeat native XMMS launch and QUIT
	launcher="$$( $(TIMEOUT) $(BUILD_TIMEOUT_SECONDS) $(NIX) build \
		--no-link --print-out-paths --no-write-lock-file \
		$(LOCAL_OVERRIDES) path:.#xmms )/bin/xmms" && \
	$(TIMEOUT) $(LIFECYCLE_TIMEOUT_SECONDS) \
		./scripts/qualify-xmms-lifecycle.sh "$$launcher" scripts/xmms_remote.py \
		native "$(LIFECYCLE_ITERATIONS)"

qualify-lifecycle-x64: check-local-siblings ## Repeat x86_64 XMMS launch and QUIT
	launcher="$$( $(TIMEOUT) $(BUILD_TIMEOUT_SECONDS) $(NIX) build \
		--no-link --print-out-paths --no-write-lock-file \
		$(LOCAL_OVERRIDES) path:.#xmms.x86_64-linux )/bin/xmms-x86_64-linux" && \
	$(TIMEOUT) $(LIFECYCLE_TIMEOUT_SECONDS) \
		./scripts/qualify-xmms-lifecycle.sh "$$launcher" scripts/xmms_remote.py \
		x86_64 "$(LIFECYCLE_ITERATIONS)"

##@ Runnable applications (macOS; local sibling overrides)

APP ?= xmms
RUN_ARGS ?=

.PHONY: check-local-siblings
check-local-siblings: ## Verify that both local runtime sibling flakes exist
	@$(NIX) flake metadata "path:$(abspath $(HL_SOURCE))" --no-write-lock-file >/dev/null 2>&1 || \
		{ echo "hyper-linux flake missing or invalid: $(HL_SOURCE)"; exit 1; }
	@$(NIX) flake metadata "path:$(abspath $(HL_X11_SOURCE))" --no-write-lock-file >/dev/null 2>&1 || \
		{ echo "hyper-linux-x11 flake missing or invalid: $(HL_X11_SOURCE)"; exit 1; }

.PHONY: run run-x64 run-x11 run-x11-x64
run: check-local-siblings ## Run APP (default: xmms); pass simple args with RUN_ARGS
	$(NIX) run --no-write-lock-file $(LOCAL_OVERRIDES) "path:.#$(APP)" \
		$(if $(strip $(RUN_ARGS)),-- $(RUN_ARGS),)

run-x64: APP = xmms.x86_64-linux
run-x64: run ## Run AppKit-wrapped XMMS in an x86_64-linux guest

run-x11: APP = xmms-x11
run-x11: run ## Run XMMS against the ambient DISPLAY

run-x11-x64: APP = xmms-x11-x86_64-linux
run-x11-x64: run ## Run x86_64-linux XMMS against ambient DISPLAY

INSTANCE ?= native
COMMAND ?= status
.PHONY: remote
remote: check-local-siblings ## Control INSTANCE=native|x86_64 with COMMAND=status|play|...
	$(NIX) run --no-write-lock-file $(LOCAL_OVERRIDES) path:.#xmms-remote -- \
		--instance "$(INSTANCE)" "$(COMMAND)"

##@ Maintenance

.PHONY: clean
clean: ## Remove Nix result links
	rm -f result result-xmms-* result-sysroot-* \
		result-check-sysroot result-check-sysroot-*
	rmdir appkit 2>/dev/null || true

.PHONY: flake-check-media
flake-check-media: ## Run Darwin-only media SHA check via flake
	$(TIMEOUT) $(CHECK_TIMEOUT_SECONDS) $(NIX) build path:.#checks.aarch64-darwin.media-sha256 \
		--no-write-lock-file $(LOCAL_OVERRIDES) -L