Launch paths — specification (dock, .lnk, ramdisk, builds)

This document is a historical Sphinx-side launch routing reference.

Warning

This page is not the sole canonical source anymore.
For current platform contracts and daemon/CLI/GUI settings model, use:

• newdocs/README.md

• newdocs/system-architecture.md

• newdocs/settings-control-pattern.md

Executive summary

Problem	Phase 1 fix	Phase 2 fix
Dock .lnk + compositor PATH_* point at settings.elf / wander.elf / syslog.elf / pnp.elf that are never copied to esp/	Point SET / WAND / EVNT / PNP at real ELFs already on the ramdisk (see §2)	Add minimal stub crates (or full apps) and stage them back under /Applications/...; revert .lnk + PATH_* to semantic names
run_qemu.bat omits many copies build_all.bat performs	Mirror the dock-critical copy lines (§5)	Keep both scripts aligned always
LUA.lnk uses /bin/lua.elf	Change to /bin/luad.elf	Same

Policy: No in-process “fake” apps inside the compositor for dock launches — only sys_execve to real files. Phase 1 uses interim targets; Phase 2 restores meaningful binary names at the original paths.

1. Phase 1 — dock & compositor (target mapping)

Rule: Every dock icon must resolve to a path that exists on the FAT image after build_all.bat (release x86_64-unknown-p1start where applicable).

1.1 Dock index → .lnk → PATH_* fallback → on-disk file

Dock order and labels are fixed in apps/deskgui/src/deskgui/compositor.rs (DOCK_ICON_LABELS, DOCK_LNK_PATHS, launch_dock_icon).

Idx	Label	.lnk path (VFS / ramdisk)	EXEC= line (proposed)	PATH_* fallback (proposed) — same path semantics as .lnk
0	SET	\System\StartMenu\Dock\SET.lnk	EXEC=EXEC:/System/Apps/P1SCode/bin/p1side.elf	b"/System/Apps/P1SCode/bin/p1side.elf\0" (rename constant in code to e.g. PATH_DOCK_SET for clarity)
1	TERM	\System\StartMenu\Dock\TERM.lnk	EXEC=EXEC:/bin/gterm.elf	b"/bin/gterm.elf\0"
2	WAND	\System\StartMenu\Dock\WAND.lnk	EXEC=EXEC:/bin/surf.elf	b"/bin/surf.elf\0" (interim: web browser; Phase 2 → wander.elf)
3	EVNT	\System\StartMenu\Dock\EVNT.lnk	EXEC=EXEC:/bin/netstat.elf	b"/bin/netstat.elf\0" (single try; drop missing syslog.elf)
4	PNP	\System\StartMenu\Dock\PNP.lnk	EXEC=EXEC:/bin/ps.elf	b"/bin/ps.elf\0" (interim: process list; Phase 2 → pnp.elf)
5	DOOM	\System\StartMenu\Dock\DOOM.lnk	EXEC=EXEC:/Applications/Doom/doom.elf	b"/Applications/Doom/doom.elf\0"

launch_dock_icon match arms (proposed): one try_exec(PATH_*) per index matching the table above; EVNT no longer attempts /Applications/Syslog/syslog.elf in Phase 1.

p1side.elf caveat: build_all.bat copies it only if exist the release binary. If P1SCode is not built, SET will still fail until the project is built or Phase 2 adds settings.elf. Documented mitigation: optional compositor second fallback try_exec(/bin/surf.elf) for idx 0 only — implementation choice; not required for Phase 1 doc minimum.

1.2 Build artifact → esp/ staging (build_all.bat)

Logical path (POSIX, as in EXEC: / try_exec)	Staged path on FAT (esp\…)	Copy source (repo-relative, release)
/bin/gterm.elf	esp\bin\gterm.elf	apps\termd\target\x86_64-unknown-p1start\release\gterm
/bin/surf.elf	esp\bin\surf.elf	apps\surf\target\x86_64-unknown-p1start\release\surf
/bin/netstat.elf	esp\bin\netstat.elf	apps\netstat\target\x86_64-unknown-p1start\release\netstat
/bin/ps.elf	esp\bin\ps.elf	apps\coreutils\target\x86_64-unknown-p1start\release\ps
/Applications/Doom/doom.elf	esp\Applications\Doom\doom.elf	doom_port\doom.elf
/System/Apps/P1SCode/bin/p1side.elf	esp\System\Apps\P1SCode\bin\p1side.elf	apps\p1side\target\x86_64-unknown-p1start\release\p1side (conditional)

Target triple for user ELFs: x86_64-unknown-p1start (SDK\toolchain\x86_64-unknown-p1start.json), except Oasis (linux-gnu) and DOOM (doom_port).

2. Phase 2 — canonical /Applications/... (stub or real ELFs)

Restore semantic paths so .lnk and marketing/docs stay stable:

Path	Purpose	Implementation
/Applications/Settings/settings.elf	Settings	New apps/settings_stub (or full settings binary) → esp\Applications\Settings\settings.elf
/Applications/Wander/wander.elf	File explorer	New apps/wander_stub or extract wander UI to its own crate
/Applications/Syslog/syslog.elf	Events / logs	New apps/syslog_stub or real syslog daemon
/Applications/PnP/pnp.elf	Device manager	New apps/pnp_stub or real PnP tool

build_image.bat ends with python pack_ramdisk.py, which applies build/image.manifest (including Applications/Settings, Applications/Wander, Doom, Oasis, etc.). build_all.bat still means “full image + QEMU”; ad-hoc mkdir/copy into esp\ is only for quick partial syncs (e.g. run_qemu.bat parity). Remaining Phase 2 gaps are Syslog / PnP app trees once ELFs exist — add F lines to the manifest (and build steps) like the other /Applications/... entries.

After Phase 2: Revert §1.1 table .lnk + PATH_* + launch_dock_icon to these four Application paths; keep TERM / DOOM as today.

3. resolve_exec_line (exec_line.rs) — proposed CMD: map (Phase 1)

Keep EXEC: passthrough as-is. Update CMD: aliases so menus/dialogs that still emit CMD:SETTINGS etc. hit real ELFs until Phase 2:

CMD: token	Resolved path (Phase 1)	Phase 2 (optional revert)
TERMINAL	/bin/gterm.elf	unchanged
SETTINGS	/System/Apps/P1SCode/bin/p1side.elf	/Applications/Settings/settings.elf
WANDER	/bin/surf.elf	/Applications/Wander/wander.elf
EVENTS | SYSLOG	/bin/netstat.elf	/Applications/Syslog/syslog.elf
PNP	/bin/ps.elf	/Applications/PnP/pnp.elf
SURF	/bin/surf.elf	unchanged
PS | MONITOR | TASKMGR	/bin/ps.elf	unchanged
NETSTAT	/bin/netstat.elf	unchanged
DOOM	/Applications/Doom/doom.elf	unchanged

4. All StartMenu .lnk files — proposed EXEC= (Phase 1)

Update repo copies under esp/System/StartMenu/ and root templates LUA.lnk, DOOM.lnk where applicable, so pack_ramdisk.py packs the right text.

Dock/

File	Phase 1 EXEC= line (full)
esp/System/StartMenu/Dock/SET.lnk	EXEC=EXEC:/System/Apps/P1SCode/bin/p1side.elf
esp/System/StartMenu/Dock/TERM.lnk	EXEC=EXEC:/bin/gterm.elf
esp/System/StartMenu/Dock/WAND.lnk	EXEC=EXEC:/bin/surf.elf
esp/System/StartMenu/Dock/EVNT.lnk	EXEC=EXEC:/bin/netstat.elf
esp/System/StartMenu/Dock/PNP.lnk	EXEC=EXEC:/bin/ps.elf
esp/System/StartMenu/Dock/DOOM.lnk	EXEC=EXEC:/Applications/Doom/doom.elf

(Keep existing NAME= / COLOR= / CWD= lines as-is unless you want to trim.)

Development/

File	Phase 1 EXEC= line
esp/System/StartMenu/Development/P1SCode.lnk	(unchanged) EXEC=EXEC:/System/Apps/P1SCode/bin/p1side.elf
esp/System/StartMenu/Development/LUA.lnk	EXEC=EXEC:/bin/luad.elf

Also fix repo root LUA.lnk (copied by batch into esp).

Internet/

File	Phase 1 EXEC= line
esp/System/StartMenu/Internet/Surf.lnk	(unchanged) EXEC=EXEC:/bin/surf.elf

Games/ + root DOOM.lnk

File	Phase 1 EXEC= line
esp/System/StartMenu/Games/DOOM.lnk	(unchanged) EXEC=EXEC:/Applications/Doom/doom.elf
esp/System/StartMenu/DOOM.lnk	(unchanged) EXEC=EXEC:/Applications/Doom/doom.elf
Root DOOM.lnk	(unchanged)

5. run_qemu.bat — sync checklist (Phase 1)

Today run_qemu.bat is missing several ELFs that build_all.bat ships. For dock + common StartMenu entries to work under QEMU quick runs, add copies (mirror build_all.bat paths) for at least:

• gterm → esp\bin\gterm.elf and optionally esp\bin\termd.elf

• netstat → esp\bin\netstat.elf

• surf → esp\bin\surf.elf (already present in run_qemu)

• ps → esp\bin\ps.elf

• p1side → esp\System\Apps\P1SCode\bin\p1side.elf (conditional if exist, same as full build)

• sh, ifconfig, ping, nslookup — optional parity with full build

Then run python pack_ramdisk.py from the repo root (same as build_image.bat: manifest → build/staging/ → src/initramfs.bin → sync into esp/ unless --no-sync).

6. Launcher mechanics (reference)

launch_dock_icon(idx) (compositor.rs): first try_exec_from_lnk(DOCK_LNK_PATHS[idx]), then match idx fallbacks.

try_exec_from_lnk: reads .lnk text; first line starting with EXEC=; substring after EXEC= passed to resolve_exec_line; result passed to sys_execve via try_exec_path_unix.

.lnk format: use EXEC=EXEC:/abs/path so the post-EXEC= payload is EXEC:/abs/path, which resolve_exec_line accepts.

7. pack_ramdisk.py + build/image.manifest

Authoritative flow: build/image.manifest lists T (recursive tree copies into staging), F (required single files), and E (optional; missing source is skipped). pack_ramdisk.py wipes build/staging/, applies the manifest, adds stub fonts / optional cursors / autorun hooks, packs every file under staging into src/initramfs.bin (hard-coded skips: *.ani entries, path ending in \doom.wad), then merges staging → esp/ (overwrite only; does not delete extra files already on esp/).

When adding new shipped ELFs or trees, extend build/image.manifest (and ensure build_image.bat builds them before pack_ramdisk.py runs). Older notes about packing “only what is already under esp/” referred to legacy workflows and are obsolete.

8. Files to touch (implementation index)

Area	Files
Dock fallbacks + constants	apps/deskgui/src/deskgui/compositor.rs (PATH_*, launch_dock_icon)
CMD: aliases	apps/deskgui/src/deskgui/shell/exec_line.rs
StartMenu + Dock shortcuts	esp/System/StartMenu/**/*.lnk, root LUA.lnk
Staging / QEMU	build_all.bat, run_qemu.bat
Phase 2 stubs	new apps/*, new esp/Applications/... dirs, extend pack_ramdisk.py if needed
Kernel metadata (optional)	src/sys/app_manager.rs — align registered paths when Phase 2 lands

9. Brand flyout (APPS_SUB_TO_DOCK)

Indices [1, 2, 0, 3, 4, 5] still map Terminal → Wander → Settings → Events → PnP → DOOM to the same dock slots; no index change required once launch_dock_icon and .lnk match §1.1.

Document version: proposed Phase 1 + Phase 2 roadmap for P1Start launch routing. Implementation should follow §1–§5 first, then §2.