gershwin-on-freebsd: livecd rework + launchd port

Plan to integrate the freebsd-launchd work (livecd architecture + launchd PID 1 + kmodloader + configd stub) into the gershwin-on-freebsd project. Sequenced: livecd rework first, then launchd, then the Apple-shaped helper daemons. Holds the line on packages — gershwin-on-freebsd's existing resources/packages/ lists are the source of truth and we add nothing new in either phase.

Goal

Take what we've learned building freebsd-launchd — the livecd boot pattern (cd9660 → mkuzip → tmpfs → unionfs cascade), the /boot/firmware symlink workaround for kernel-namei firmware loading, the in-chroot GNUstep build, the launchd-as-PID-1 Option D pivot, the kmodloader hardware-bind daemon, the netconfigd stub — and land it in the gershwin-on-freebsd project as a sequenced, reversible series of changes.

Gershwin-on-freebsd already does most of the work. It already uses pkg-base. It already builds a hybrid EFI/BIOS ISO via mkisoimages.sh. It already does the cd9660+uzip+tmpfs+unionfs cascade. It already builds the GNUstep stack into /System/Library/. The integration is therefore not a rewrite — it's a cleanup pass on the livecd (Phase 1) followed by an additive launchd port (Phase 2).

Constraints (hard)

Source-of-truth split

Three repos, one direction of dependency: gershwin-on-freebsd consumes both gershwin-developer and freebsd-launchd; the other two don't know about each other.

Architecture (target end state)

Phase 1 (landed) keeps stock /sbin/init+rc.d but introduces the unionfs+chroot architecture. Phase 2 changes the last line of init.sh and the loader knobs to swap stock init for launchd; the rest of the cascade body is reused unchanged. Phase 3 fills in the Apple-shaped helpers.

Phase 1: livecd rework landed

Three commits on pkgdemon/gershwin-on-freebsd:main. Init stays stock; rc.d stays the service manager — but the boot architecture now mirrors freebsd-livecd-unionfs (single uzip rootfs + tmpfs upper + unionfs + init_chroot kenv pivot), making Phase 2's launchd swap a single-line change.

1.1 Switch gershwin-developer to feat/libs-corebase done — 1d2150b

One-line change at build.sh:281:

git clone --branch feat/libs-corebase --depth 1 \
    https://github.com/gershwin-desktop/gershwin-developer "${RELEASE_DIR}/Developer"

Diff between main and feat/libs-corebase in gershwin-developer: two commits (~10 lines) that add libs-corebase to the build orchestrator. There is no patched/forked libs-corebase — it's plain upstream gnustep/libs-corebase HEAD with a vanilla configure invocation. Once feat/libs-corebase merges to main upstream, drop the --branch flag — but until then, the user's open upstream PR (gershwin-developer#32) is the source of truth and we leave it alone.

This enables CoreFoundation-shaped APIs (libgnustep-corebase.so) for everything downstream — including freebsd-launchd in Phase 2, which links against it for plist parsing.

1.2 /boot/firmware symlink — not needed

1.3 Live-mount cascade rework: single-root unionfs + init_chroot pivot done — 3b97e40

This was originally underscoped as "tighten init_script (cosmetic)." That was wrong — gershwin's livecd had to actually move to the freebsd-livecd-unionfs runtime model before Phase 2 could land cleanly. What changed:

Before: resources/overlays/boot/init_script ran a 14-mount cascade (per-subdir nullfs of /Developer, /System, /Local, /bin, /lib, /libexec, /sbin, /usr, /boot, /root, plus tmpfs at /nvidia, /compat, /tmp, /media) plus 5 unionfs mounts on top, plus cp -R /media/.uzip/var → /var (~10–50 MB physical copy) and cp -R /media/.uzip/etc → /tmp; nullfs /tmp/etc /etc (~5–20 MB physical copy). No chroot — kernel root stayed cd9660. Mount points to track: 19.

After: resources/overlays/init.sh at cdroot top-level. Cascade:

mdconfig -a -t vnode -o readonly -f /rootfs.uzip -u 0
mount -t ufs -o ro /dev/md0.uzip /sysroot   # lower
mount -t tmpfs tmpfs /upper                  # writable upper
mount -t unionfs /upper /sysroot             # combined
mount -t devfs devfs /sysroot/dev
# … gershwin live-mode tweaks against /sysroot/… …
kenv init_chroot=/sysroot
exit 0

/sbin/init (still PID 1, real FreeBSD binary from /rescue/init since /sbin/init isn't on the cd9660) reads init_chroot kenv at init.c:333 and chroots into /sysroot before continuing multi-user. Kernel root stays cd9660; userland sees the unionfs as /. Mount points: 6.

Loader.conf:

# Phase 1 additions:
unionfs_load="YES"
init_shell="/rescue/sh"
init_script="/init.sh"   # was /boot/init_script

Build.sh changes:

• prepare_boot_env: dropped the 30+ mountpoint mkdir list (now only /sysroot, /upper, /dev); dropped the /etc/login.conf workaround (chroot makes it unnecessary); added unionfs.ko to the kept-modules list; cp init.sh from overlays/ top-level instead of overlays/boot/init_script.
• generate_iso: rootfs.uzip now lives at cdroot top-level (not /boot/rootfs.uzip) so /init.sh can mdconfig -f /rootfs.uzip directly.

Live-mode tweaks preserved (rcorder surgery, SMBIOS hostname, VirtualBox detect, sendmail/linux/dbus rc.conf overrides) — paths retargeted to /sysroot/… since they run before the chroot.

Footprint impact: disk unchanged; RAM at idle ~15–70 MB lower; boot speed faster (two recursive cp -R passes go away); cognitive load much lower (one mount stack instead of nineteen).

1.4 CI boot-test gate done — 7caefbf

Workflow split into three jobs: build → test → release. release only fires on push to main and only when both prior jobs pass.

tests/boot-test.sh (lifted from freebsd-launchd, simplified to single stage): runs qemu-system-x86_64 with OVMF, KVM if available else TCG single-thread, -display none -serial stdio. Watches the serial log for any of: "login:" (getty prompt), "Starting local daemons" (rc multi-user marker), or "Welcome to Gershwin/FreeBSD" (banner). 10-minute timeout. Boot log uploaded as artifact on failure.

The test job runs on ubuntu-latest (not the freebsd-vm) and pulls qemu+expect+ovmf via apt-get — same pattern as freebsd-launchd's CI.

1.5 Phase 1 acceptance criteria

• met ISO builds in CI without changes to package lists.
• met ISO boots in QEMU past /etc/rc.d/root within 10 minutes (CI run 25495932941, commit 6ff5abe).
• met Post-rework architecture confirmed working under chroot — init.sh cascade clean, /etc/rc reaches multi-user.
• deferred Boot on the Lenovo test laptop and verify WiFi firmware loads. The architecture is structurally identical to the QEMU-validated path; hardware test before final Phase-2 ship is sufficient.
• met The continuous GH release publishes per push, gated by boot-test that verifies real multi-user reach (not the prior 1m5s loader-banner false positive).

Phase 2: launchd port starts only after Phase 1 ships

Goal: replace stock /sbin/init+rc.d with launchd as PID 1, while keeping the same package set and the same observable services. This is the bulk of the work.

2.1 Build launchd in the chroot

Add a new build stage in build.sh, between build_gershwin_components and configure_system. Cloned inside the chroot to match gershwin's existing pattern (build.sh:281 already clones gershwin-developer the same way).

build_launchd() {
    log "Building freebsd-launchd from source..."

    # Host-side git clone writing into the chroot's Sources tree.
    # Matches gershwin's existing build.sh:281 pattern verbatim — same
    # destination convention (gershwin-developer's $SCRIPT_DIR/../Sources
    # from Checkout.sh:10) and same in-chroot Sources layout. Lands as
    # a sibling to libdispatch, tools-make, libobjc2, libs-base,
    # libs-corebase, libs-gui, libs-back already cloned by Checkout.sh.
    git clone --depth 1 https://github.com/pkgdemon/freebsd-launchd \
        "${RELEASE_DIR}/Developer/Library/Sources/freebsd-launchd"

    # Build setup mirrors build_gershwin_components: resolv.conf for
    # any network-touching configure step, devfs for /dev/null-style
    # subprocess pipes that gmake/configure want.
    cp /etc/resolv.conf "${RELEASE_DIR}/etc/resolv.conf"
    mount -t devfs devfs "${RELEASE_DIR}/dev" 2>/dev/null || true

    # GNUstep environment is already populated by gershwin-developer's
    # make install. launchd just needs to compile against libgnustep-base
    # and libgnustep-corebase, both already at /System/Library/Libraries.
    chroot "${RELEASE_DIR}" sh -c "
        . /System/Library/Makefiles/GNUstep.sh &&
        cd /Developer/Library/Sources/freebsd-launchd &&
        ./configure --prefix=/ &&
        gmake -j\$(sysctl -n hw.ncpu) &&
        gmake install
    "

    umount "${RELEASE_DIR}/dev" 2>/dev/null || true
    rm -f "${RELEASE_DIR}/etc/resolv.conf"
}

Wired into main at build.sh:441:

build_gershwin_components
build_launchd                # NEW
configure_system

2.2 Swap to Option D + launchd PID 1

Phase 1 already moved init.sh to cdroot top-level, restructured to the /sysroot unionfs model, and delivered the live-mount cascade body. Phase 2 only needs to change how the kernel exec's init.sh (init_script kenv → Option D shebang) and what init.sh does at the end (set init_chroot kenv → exec launchd in the chroot).

Concrete migration:

1. Update loader.conf: remove init_script="/init.sh" and init_shell="/rescue/sh"; add init_path="/init.sh". (The #!/rescue/sh shebang on init.sh is already there from Phase 1.) With Option D, the kernel's imgact_shell resolves the shebang and exec's /init.sh as PID 1 directly — no /sbin/init, no init_chroot kenv path.
2. Update init.sh tail: replace

   kenv init_chroot=/sysroot
   kenv -u init_script
   kenv -u init_shell
   exit 0

   with

   exec chroot /sysroot /sbin/launchd

   The cascade body above (mdconfig + ufs + tmpfs + unionfs + devfs + gershwin live tweaks) stays unchanged.
3. Delete the rcorder surgery from init.sh. launchd reads its own dependency graph from plist RunAtLoad/KeepAlive/socket-activation keys; it doesn't care about # REQUIRE: lines in /etc/rc.d/*.

Reference: freebsd-launchd's plan §boot walks through the Option D mechanics. The diff against Phase 1's init.sh is small (delete the rcorder block, swap the last 4 lines for one).

2.3 LaunchDaemon plist set narrowed

Phase 2's launchd plist set is small. Per user direction 2026-05-07: only port what's actually needed to boot gershwin to login. Most services don't earn their plist yet.

Everything else in configure_system stays as-is. dbus, cupsd, avahi-daemon, avahi-dnsconfd, ntpd, smartd, moused, webcamd, dsbdriverd, initgfx — none get launchd plists in Phase 2. With launchd as PID 1 there is no /sbin/init, no /etc/rc, and so the _enable=YES lines for those services don't fire — they sit harmlessly in rc.conf. Gershwin boots to login with just the bedrock + dshelper + loginwindow + getty + dhcpcd; the desktop reaches a usable login screen without dbus or the rest.

Phase 3 follow-ups (one at a time, each on user signal):

• org.freedesktop.dbus.plist — likely first, enables IPC for desktop components. User flagged this 2026-05-07.
• cupsd, avahi, ntpd, smartd — added when each earns its keep.
• moused, webcamd — need device-event triggering (Phase 3+'s kmodloader / configd surface).
• dsbdriverd, initgfx — overlap with kmodloader; revisit after kmodloader is integrated.

2.4 configure_system rc.conf cleanup

Two new lines added to configure_system's sysrc block, two implicitly removed:

• Add: root_rw_mount="NO" if not already in init.sh's runtime overrides — but init.sh already covers this; leave configure_system alone unless the runtime override stops being applied.
• Remove: dshelper_enable="YES" and loginwindow_enable="YES" — replaced by their plists. Removing prevents rc.d (which isn't running) from being a phantom dependency in future audits.
• Leave alone: every other _enable=YES line. Dead weight under launchd PID 1, but harmless.

2.5 Phase 2 acceptance criteria

• met launchd is PID 1 — verified by reaching LoginWindow under the launchd path.
• met Boot-test reaches the gershwin GUI greeter — LoginWindow comes up, Eau theme bridge registers via DO. (Replaces the original "getty login: prompt" criterion — getty isn't shipped under Phase 2's gershwin shape.)
• met The gershwin plists (org.gershwin.dshelper, org.gershwin.loginwindow, org.gnustep.gdomap) load — dshelper PID 103 confirmed running in CI run 25504336947.
• met dhcpcd leases an IP on the test interface (em0: leased 10.0.2.15 from QEMU's NAT).
• deferred Lenovo hardware test. Architecture is structurally validated under QEMU; hardware boot to LoginWindow before final ship.
• met QEMU boot-test in CI gates releases.

Out of scope for Phase 2: dbus, cupsd, avahi, ntpd, smartd, moused, webcamd. Those start under rc.d today; with launchd as PID 1 they don't start at all. Their plists land in Phase 3+ on user signal.

Known gap — single-user mode (deferred): boot -s at the loader sets RB_SINGLE in kern.boothowto, but our init.sh doesn't check it — it always exec's launchd, which then tries to load LoginWindow on a system with no X. Stock FreeBSD and macOS both handle single-user as a "root shell on console, no auth, no daemons" recovery mode. Implementation sketch for the future: branch in init.sh after the cascade — if boothowto & 0x10, exec chroot /sysroot /bin/sh -i; else exec chroot /sysroot /sbin/launchd. No getty needed (single-user bypasses auth). Routing around launchd in init.sh is simpler than porting macOS's single-user-aware launchd codepath. Per user direction 2026-05-07: "this can come much later it isn't important right now. i just want to document the gap."

Phase 3: polish (deferred) post-launchd

Phase 3 is the long tail of Apple-shaped helper daemons that earn their keep one at a time. None of them block Phase 2 from being usable. Listed in priority order:

Post-launchd cleanup deferred

Once Phase 2 lands and gershwin boots reliably with launchd as PID 1 + a working org.gershwin.loginwindow.plist, do this single follow-up commit on pkgdemon/gershwin-on-freebsd:main. End-user UX takes precedence over development diagnostics from this point.

Revert the Phase 1 boot diagnostics (commit 02e4e9a)

• resources/overlays/boot/loader.mute.d/loader.conf — uncomment boot_mute="YES" (restore the polished animation).
• resources/overlays/boot/loader.conf — drop the diagnostics block: boot_verbose="YES", console="comconsole vidconsole", comconsole_speed="115200".

Retire the CI boot-test gate (commit 7caefbf)

• .github/workflows/build.yml — collapse the build → test → release split back to the original single-job build + publish flow. Drop the test job and its needs: wiring on release.
• tests/boot-test.sh — delete.
• tests/ — delete the directory if no other tests live there.

Why deferred, not skipped: during Phase 1/2 the verbose boot output + the boot-test gate are valuable diagnostic surface — both for catching kernel/init regressions in CI and for reading dmesg on real hardware while the architecture is in flux. After launchd + loginwindow stabilize, neither earns its keep. The CI overhead of a per-push boot-test (build + qemu run on every push) becomes pure tax once the fast-iteration phase ends.

What does NOT need reverting: the exec >/dev/console 2>&1 in init.sh (commit 206f8a7). It lives inside the else branch of the boot_mute check — when boot_mute="YES" is restored, the silencing branch fires and the explicit redirect is dead code. Leave it; it gives future debugging cycles visible output for free.

Single commit suggested title: "post-Phase-2 cleanup: restore quiet boot, retire CI boot-test gate" with reference to commits 02e4e9a + 7caefbf in the body.

LoginWindow plist

Three things share the name "LoginWindow"; keep them straight.

Phase 2's org.gershwin.loginwindow.plist is the small, concrete, useful thing. Sketch:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>org.gershwin.loginwindow</string>
    <key>ProgramArguments</key>
    <array>
        <!-- TODO: identify what gershwin's current loginwindow rc script
             actually exec's; pkg shows it under /usr/local/etc/rc.d/loginwindow
             after install_gershwin_software lands. Likely a wrapper script
             around slim or a custom greeter -->
        <string>/usr/local/sbin/loginwindow</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
    <key>StandardOutPath</key>
    <string>/var/log/loginwindow.log</string>
    <key>StandardErrorPath</key>
    <string>/var/log/loginwindow.err</string>
</dict>
</plist>

Authored once we read the actual rc script in the post-install image — the ProgramArguments path is a guess until then. StandardOutPath/StandardErrorPath are recorded as not-yet-implemented in freebsd-launchd's plist parser; they're written for the eventual implementation, ignored harmlessly today.

File-by-file change inventory

gershwin-on-freebsd

gershwin-developer

freebsd-launchd

Open questions

Decisions log

• Sequencing: livecd first, launchd second. Per user direction 2026-05-06.
• Packages: gershwin-on-freebsd's existing lists are the source of truth; no additions. Per user direction 2026-05-06.
• gershwin-developer branch: feat/libs-corebase. Per user direction 2026-05-06.
• freebsd-launchd source location: /Developer/Library/Sources/freebsd-launchd/, matching gershwin-developer's $SCRIPT_DIR/../Sources convention. Per user direction 2026-05-06.
• LoginWindow: launchd plist in Phase 2; no port of Apple's loginwindow.app. Research-confirmed unportable as of 2026-05-06.
• dhclient vs dhcpcd: Phase 2 adds dhcpcd from ports and removes FreeBSD-dhclient from the base list in the same commit. Lifts freebsd-launchd's existing org.freebsd.dhcpcd.plist verbatim. Per user direction 2026-05-06.
• wpa_supplicant: Phase 2 adds wpa_supplicant from ports and removes FreeBSD-wpa from the base list in the same commit. Per user direction 2026-05-06.
• No other package edits: the four-line dhcpcd / wpa_supplicant swap is the entire scope of package changes. Existing resources/packages/{base,vital-base,gershwin,drivers,vital-gershwin} entries are not re-audited, re-derived, or pruned beyond those four lines, regardless of what looks redundant under launchd. Per user direction 2026-05-06.
• Phase 1 underscoping correction: the original v0 plan called §1.3 "tighten init_script (cosmetic)" and parked the architectural rework in Phase 2. After conversation 2026-05-06 with the user noting that gershwin still does per-subdir nullfs + cp -R, scope was corrected — Phase 1 owns the architectural rework to single-root unionfs + init_chroot kenv pivot (mirroring freebsd-livecd-unionfs). Phase 2 then becomes a single-line tail change to init.sh + loader.conf knob swap.
• Mechanism for Phase 1 vs Phase 2 pivot: Phase 1 uses init_chroot kenv (read by stock /sbin/init after init_script exits). Phase 2 swaps to Option D shebang (kernel exec's /init.sh directly as PID 1, replacing init entirely). Both are documented mechanisms in FreeBSD; Option D is freebsd-launchd-specific because launchd replaces /sbin/init. Per agent research 2026-05-06.
• Firmware symlink: not adopted in Phase 1. Gershwin's init_chroot chroot operates against a real mount tree, so kernel-namei resolves /sysroot/boot/firmware through the unionfs to the real files in the uzip. The freebsd-launchd bug doesn't apply. Reconsider only if hardware testing fails. Decision 2026-05-06.
• init_script cosmetic tightening: not done. Risk/value didn't justify it for a load-bearing shell script. The full architectural rework subsumed any "cleanup" intent. Decision 2026-05-06.
• chroot stays git-free — exception for gershwin integration: the freebsd-launchd standalone repo follows the rule (host-side clone + rsync into chroot). gershwin-on-freebsd's existing pattern is the opposite — build.sh:281 clones gershwin-developer inside the chroot, and Checkout.sh (running in chroot) clones each upstream into /Developer/Library/Sources/. Phase 2's build_launchd follows gershwin's pattern (chroot git clone) to keep one consistent integration shape. Per user direction 2026-05-07.
• Fork-only workflow: all gershwin work lands in pkgdemon/gershwin-on-freebsd (the user's fork) directly on main; no PRs to gershwin-desktop, no topic branches. Per user direction 2026-05-06.
• Post-rework debugging trail (2026-05-07):
  • Initial CI on the rework looked silent on serial after kernel handoff (only kernel printf messages visible). Spent several iterations chasing this.
  • Two coupled root causes identified by parallel agents reading init.c + diff'ing freebsd-livecd-unionfs: (a) /sbin/init mounts devfs after running init_script, so init's open_console() for the child's stdio falls back to /dev/null. Fix: init.sh mounts devfs first, then re-execs stdio onto /dev/console. (b) boot_serial="YES" was missing in loader.conf — userspace stdio routed to vidconsole (invisible under QEMU -display none). Working repo had it; we didn't.
  • Once visibility was restored, the actual blocker surfaced: /etc/rc.d/root aborts the boot trying mount -uw / (mount(8) inspects the global kernel mount table, which still reports / as cd9660 even after the chroot). Fix: root_rw_mount="NO" in /sysroot/etc/rc.conf, same as freebsd-livecd-unionfs.
  • Earlier "green" CI runs were 1m5s false positives — boot-test was matching the FreeBSD loader's beastie banner ("Welcome to FreeBSD") before the kernel even started. Tightened markers to multi-user-only signals: login:, Starting local daemons, Setting hostname, Mounting local filesystems.

Plan v3, 2026-05-07 — Phase 1 + Phase 2 fully landed and CI-green (Phase 2 ends at run 25504336947, commit ebe7320). Phase 3 polish (dbus, kmodloader, gdomap lo0 fix, dshelper daemonization, ASL, single-user mode) follows on user signal.