FreeBSD launchd — porting plan

A FreeBSD-only port of Apple's launchd that drops Mach IPC, replaces rc.d as PID 1, and lives in standard FreeBSD paths. Single repo, single build.sh: builds the GNUstep system-domain libraries + launchd inside a livecd staging chroot, boot-tests the resulting ISO in CI, publishes a continuous release. Pipeline lifted from freebsd-livecd-unionfs.

1. Goal & non-goals

1.1 Goal

Boot a FreeBSD 15.0 live ISO to a usable multi-user prompt with launchd as PID 1. Reach a console login:, then prove the supervisor with sshd. Other base service plists — syslogd, cron, devd, mountd, nfsd, nfsclient, etc. — ship in the repo so users can launchctl load what they want, but they aren't release-gating goals. No /etc/rc, no /etc/rc.d, no service(8). Every push to main rebuilds the ISO, boot-tests it in qemu, and (on green) publishes it as the continuous GitHub release.

1.2 Non-goals (this iteration)

• Not a port of every rc.d script. FreeBSD ships ~180; we'll port a server-essential ~12 and document the rest as "won't port" with reasons (§11).
• Not Linux, not NetBSD. FreeBSD-only — we use kqueue-flavored libdispatch features freely without portability shims (§7).
• No GUI stack. No libs-gui, libs-back, libs-opal, libs-quartzcore, no Workspace.app, no LoginWindow.app. Headless server.
• No Mach IPC compatibility shim. Third-party plists referencing MachServices get the key silently ignored (and logged at debug level).
• No libxpc emulation. XPC services are Mach-rooted; without Mach there's nothing to emulate.

2. Repository — single repo, single pipeline

One repo: pkgdemon/freebsd-launchd. It contains:

1. The Apple launchd-842.1.4 source (one-time fork, Mach paths gutted) under src/.
2. Our rc.d-replacement plists under plists/.
3. A build.sh that — modeled on freebsd-livecd-unionfs — extracts FreeBSD pkgbase, mounts a chroot, clones & builds the GNUstep system-domain libraries into /System/Library/, builds launchd into /sbin/, slims the rootfs, mkuzips it, and wraps it in a hybrid BIOS+UEFI cd9660 ISO.
4. A tests/boot-test.sh that boots the ISO under qemu+OVMF and watches serial for launchd-emitted markers.
5. A GitHub Actions workflow that runs build → test → release on every push.

No git submodules. Earlier versions of this plan considered a "system-domain Gershwin fork" as a submodule. Cleaner approach: build.sh simply git clones each upstream library at chroot-build time, builds, installs.

2.1 Top-level layout

freebsd-launchd/
├── LICENSE                       BSD-2-Clause
├── NOTICE                        Apple, swift-corelibs-libdispatch, GNUstep, us
├── README.md                     elevator pitch + quickstart
├── PLAN.md                       link to this published plan
├── build.sh                      lifted from livecd-unionfs; clones 6 upstreams, builds them in-chroot, calls make-launchd.sh, then ISO-wraps
├── make-launchd.sh               STANDALONE — builds + installs launchd from src/ to /sbin/; assumes /System/Library/ libs present. Reusable by gershwin-on-freebsd.
├── pkglist.txt                   runtime FreeBSD pkgs to install in chroot (start empty)
├── buildpkgs.txt                 build-only pkgs (cmake, ninja, gmake, autoconf, libtool) — purged before slim
├── repos/                        gitignored — populated by build.sh's git-clone stage; rsync'd into chroot
├── boot/
│   └── loader.conf               kernel modules + init kenv (init_path=/sbin/launchd)
├── ramdisk/
│   └── init.sh                   unionfs pivot: mounts /sysroot, kenv init_chroot, kenv init_path
├── overlays/
│   ├── etc/
│   │   ├── rc.conf               minimal — the launchd plists own the rest
│   │   ├── motd.template         banner
│   │   └── ld-elf.so.conf.d/system.conf   one line: /System/Library/Libraries
│   └── (more as needed)
├── plists/                       our rc.d-replacement LaunchDaemon plists
│   ├── org.freebsd.devd.plist
│   ├── org.freebsd.syslogd.plist
│   ├── org.freebsd.sshd.plist
│   ├── org.freebsd.cron.plist
│   ├── org.freebsd.rpcbind.plist
│   ├── org.freebsd.mountd.plist
│   ├── org.freebsd.nfsd.plist
│   ├── org.freebsd.nfsclient.plist
│   └── org.freebsd.phase.{filesystems,network,kld}-ready.plist
├── tests/
│   └── boot-test.sh              qemu+expect smoke test (extended marker set)
├── .github/workflows/
│   └── build.yml                 build → test → release (3 jobs, gated)
├── compat/                       FreeBSD-specific shims
├── scripts/
│   ├── import-source.sh          one-shot Apple launchd import (already done)
│   └── lint.sh                   forbidden-symbol grep
└── src/                          forked Apple launchd-842.1.4 (Mach paths deleted)
    ├── src/                      daemon: launchd.c, runtime.c, ipc.c, core.[cm], log.c
    ├── liblaunch/                wire-format library: launch.h, liblaunch.c
    ├── support/                  launchctl.c, wait4path.c
    ├── man/                      man pages
    └── rc/                       legacy rc.common — kept selectively

3. Architecture

3.1 Why this works on FreeBSD specifically

• Single-threaded user-visible state. All job-table mutation funnels through dispatch_get_main_queue(). Worker fan-out is libdispatch's problem; we never call pthread_create.
• PID 1 stays inside dispatch_main(), which is a kqueue wait under the hood. No custom poll loop.
• Per-job DISPATCH_SOURCE_TYPE_PROC with DISPATCH_PROC_EXIT gives clean per-pid death notification. SIGCHLD remains as a backstop for orphans PID 1 inherits.
• Shutdown is just dispatch_async to a stop-everyone-and-exit block.

4. Install paths

This repo follows FreeBSD hier(7) for binaries and only uses the /System tree for things that genuinely belong there (libraries the launchd daemon links against, plist directories the daemon scans).

Why split it this way: a sysadmin shelling into a FreeBSD box should find launchctl at the path service(8) would have been at — /sbin. Burying admin tools under /System/Library/Tools/ would only make sense for an all-in OS-distribution pivot; in a FreeBSD-shaped install where everything else lives in hier(7) locations, it's hostile.

5. Locked architectural decisions

6. File-by-file plan (src/)

Imported source: Apple launchd-842.1.4. 26,779 lines, 68 files originally. Phase 1 amputation deletes the wholly-Mach files; what remains is the substrate Phase 2 replaces. The Phase 2 rewrites (runtime.c, ipc.c, core.[cm], log.c, launchctl.c, plus the Mach-pruning of liblaunch.c) land as code reused from a previous attempt to install launchd in system; the file-by-file table below describes the target shape, not work typed from scratch.

6.1 Deleted on import (Mach-only)

• launchd.xcodeproj/, xcconfigs/, xcscripts/ — Xcode build infra
• src/*.defs — MIG interface definitions (Mach-RPC IDL)
• src/kill2.{c,h} — Apple kill2() syscall wrapper; replaced by POSIX kill(2)
• src/ktrace.{c,h} — Apple kdebug emitters
• SystemStarter/ — pre-launchd /System/Library/StartupItems mechanism (legacy since 10.4)
• liblaunch/libbootstrap.c, bootstrap.h, bootstrap_priv.h — Mach bootstrap-server client
• support/launchproxy.c — Mach-IPC inetd-style wrapper

6.2 Retained — Phase 2 fate

Total post-Phase-2: roughly 7-8k LOC vs Apple's ~22k pre-amputation. About 65% deletion.

6.3 Plist-key support — current state vs Apple's full surface

Apple's launchd parses ~80+ plist keys. Our vendored source from prior work handles a working subset; the rest are silently ignored at parse time (the plist still loads — the key just has no effect). The table below tracks what's implemented today, what's load-bearing for project-shipped plists, and what's pending.

Implementation pattern for a new key (~30-50 LOC each, in core.m):

1. Read the key from the plist's NSDictionary at job-load time.
2. Validate type (string vs dict vs array vs integer).
3. Apply at the appropriate point: env-build for EnvironmentVariables; chdir(2) before exec for WorkingDirectory; setuid(2)/setgid(2) for UserName/GroupName; open(2) + dup2(2) for Standard{Out,Error}Path; dispatch_source_create(DISPATCH_SOURCE_TYPE_TIMER, ...) for StartCalendarInterval; etc.

Phase-5 batch: implement EnvironmentVariables, StartCalendarInterval, WorkingDirectory, UserName/GroupName, Standard{Out,Error}Path, Umask as a focused "match more of Apple's plist schema" pass. Unlocks: cron-to-native-launchd migration, sshd with privsep user, per-daemon log redirection, and the rest of the conventional Apple plist idioms.

7. FreeBSD-only wins (vs a portable BSD+Linux design)

8. Dependencies — built in-chroot, no submodules

Five upstream libraries are cloned and built by build.sh inside the staging chroot, in dependency order, before launchd itself is built. We track upstream HEAD; if a breakage surfaces we'll address it then, not preemptively.

8.1 Host-side clone, chroot-side build — both in build.sh

Rule lifted from gershwin-on-freebsd: all git operations happen on the host, the chroot stays git-free. build.sh handles both halves inline:

1. Host stage (early in build.sh): git clone the six upstreams (5 GNUstep + Tessil/robin-map) into repos/<name>/ at the repo root, or git pull --ff-only if already present. Idempotent.
2. Chroot stage: extract pkgbase, mount the chroot, pkg install runtime + build deps, rsync -a ./repos/ work/rootfs/tmp/repos/ into the chroot, sed-patch libobjc2's CMakeLists.txt per §8.3, then run the build invocations from §8.4 with REPOS_DIR=/tmp/repos set in the environment.
3. launchd stage: after the GNUstep libs are installed, build.sh calls ./make-launchd.sh (chroot'd). That's the standalone-reusable script — it builds src/ against /System/Library/ and installs launchd/launchctl to /sbin/.

repos/ is in .gitignore. CI caches it on the runner so unchanged upstreams skip re-clone.

8.2 Upstream URLs & build order

Order is significant: tools-make writes /System/Library/Preferences/GNUstep.conf (the --with-layout=gershwin map), libobjc2 needs that config plus an established BlocksRuntime from libdispatch, and libs-base/libs-corebase drive their installs through gnustep-make with GNUSTEP_INSTALLATION_DOMAIN=SYSTEM.

8.3 Upstream patches

libdispatch — none, for now

We start with stock swift-corelibs-libdispatch at HEAD, no patches. The gershwin tree carries a 126-line FreeBSD kevent fix (busy-wait on certain timer fflags) but we want to see how launchd behaves against unpatched upstream first. If timer-driven jobs (StartInterval, ThrottleInterval) misbehave during Phase 3 the patch goes in patches/ and gets applied at host-side checkout; until then the directory doesn't exist.

libobjc2 — robinmap FetchContent → SOURCE_DIR

libobjc2's CMakeLists.txt calls FetchContent_Declare(robinmap GIT_REPOSITORY ...), which fires git at configure-time. The chroot is git-free by design, so this fails. The fix has two parts:

1. Add Tessil/robin-map to the host clone loop (§8.6) as a sibling to libobjc2.
2. After rsyncing repos/ into the chroot, before the libobjc2 cmake invocation, sed-patch the chroot copy of libobjc2/CMakeLists.txt to use SOURCE_DIR at the rsynced sibling path:

   sed -i '' \
       -e 's|GIT_REPOSITORY https://github.com/Tessil/robin-map/|SOURCE_DIR /tmp/repos/robin-map)|' \
       -e '/GIT_TAG[[:space:]]*v1\.4\.0)/d' \
       "$WORK/rootfs/tmp/repos/libobjc2/CMakeLists.txt"

Patching the chroot copy (not the host clone) keeps future git pull --ff-only runs clean against upstream libobjc2.

8.4 The exact build invocations

This block is what build.sh runs inside the chroot, after checkout.sh has populated repos/ on the host and stage 3 has rsync'd it to $REPOS_DIR=/tmp/repos. Verbatim — these commands are known-good for installing this set into /System/Library/.

FreeBSD-only simplification: we don't need the multi-OS detect_platform() dance the gershwin scripts carry. MAKE_CMD and CPUS are constants here:

MAKE_CMD=gmake
CPUS=$(sysctl -n hw.ncpu)

No case $OS in FreeBSD|GhostBSD|Linux ... switch. Anyone wanting Linux/NetBSD support forks the repo.

libdispatch

cd "$REPOS_DIR/swift-corelibs-libdispatch/Build"

cmake .. \
  -DCMAKE_INSTALL_PREFIX=/System/Library \
  -DCMAKE_INSTALL_LIBDIR=Libraries \
  -DINSTALL_DISPATCH_HEADERS_DIR=/System/Library/Headers/dispatch \
  -DINSTALL_BLOCK_HEADERS_DIR=/System/Library/Headers \
  -DINSTALL_OS_HEADERS_DIR=/System/Library/Headers/os \
  -DINSTALL_PRIVATE_HEADERS=ON \
  -DCMAKE_INSTALL_MANDIR=Documentation/man \
  -DCMAKE_BUILD_TYPE=Release \
  -DCMAKE_C_COMPILER=clang \
  -DCMAKE_CXX_COMPILER=clang++

"$MAKE_CMD" -j"$CPUS" || exit 1
"$MAKE_CMD" install   || exit 1

tools-make

cd "$REPOS_DIR/tools-make"
$MAKE_CMD distclean 2>/dev/null || true

./configure \
  --with-config-file=/System/Library/Preferences/GNUstep.conf \
  --with-layout=gershwin \
  --with-library-combo=ng-gnu-gnu \
  --with-objc-lib-flag=" " \
  LDFLAGS="-L/System/Library/Libraries" \
  CPPFLAGS="-I/System/Library/Headers" \
  libobjc_LIBS=" "

$MAKE_CMD         || exit 1
$MAKE_CMD install

Source GNUstep.sh after tools-make install

Required between tools-make and libobjc2. tools-make's install creates /System/Library/Makefiles/GNUstep.sh; sourcing it exports GNUSTEP_HEADERS, GNUSTEP_LIBRARY, GNUSTEP_MAKEFILES and adds /System/Library/Tools to PATH so gnustep-config resolves. Without this, libobjc2's cmake (which calls gnustep-config --variable=GNUSTEP_${GNUSTEP_INSTALL_TYPE}_HEADERS via find_program) can't find the tool, and install paths collapse to /usr/local/lib/libobjc.so + /objc/*.h — libs-base configure then fails with "Could not find Objective-C headers". libs-base's own AC_CONFIG_AUX_DIR also reads $GNUSTEP_MAKEFILES; sourcing once after tools-make covers both.

. /System/Library/Makefiles/GNUstep.sh

libobjc2

if [ -d "$REPOS_DIR/libobjc2/Build" ]; then
  rm -rf "$REPOS_DIR/libobjc2/Build"
fi
mkdir -p "$REPOS_DIR/libobjc2/Build"
cd "$REPOS_DIR/libobjc2/Build"

cmake .. \
  -DGNUSTEP_INSTALL_TYPE=SYSTEM \
  -DCMAKE_BUILD_TYPE=Release \
  -DCMAKE_C_COMPILER=clang \
  -DCMAKE_CXX_COMPILER=clang++ \
  -DEMBEDDED_BLOCKS_RUNTIME=OFF \
  -DBlocksRuntime_INCLUDE_DIR=/System/Library/Headers \
  -DBlocksRuntime_LIBRARIES=/System/Library/Libraries/libBlocksRuntime.so

"$MAKE_CMD" -j"$CPUS" || exit 1
"$MAKE_CMD" install   || exit 1

libs-base (Foundation)

--disable-tls is passed because launchd doesn't speak TLS; pulling in libgnutls/openssl just to satisfy NSStream/NSURLConnection's TLS code path would bloat the ISO. XSLT is not disabled — configure emits a warning but doesn't error.

export GNUSTEP_INSTALLATION_DOMAIN="SYSTEM"

cd "$REPOS_DIR/libs-base"
./configure \
  --with-dispatch-include=/System/Library/Headers \
  --with-dispatch-library=/System/Library/Libraries \
  --disable-tls

$MAKE_CMD -j"$CPUS" || exit 1
$MAKE_CMD install
$MAKE_CMD clean

libs-corebase (CoreFoundation)

cd "$REPOS_DIR/libs-corebase"
./configure \
  CPPFLAGS="-I/System/Library/Headers" \
  LDFLAGS="-L/System/Library/Libraries"

$MAKE_CMD -j"$CPUS" || exit 1
$MAKE_CMD install
$MAKE_CMD clean

8.5 Runtime linker

Two parts. (a) launchd is linked with -Wl,-rpath,/System/Library/Libraries in its Makefile so it finds its own libs without environment help. (b) For everything else on the system that wants to link our libs, a one-line file overlays/etc/ld-elf.so.conf.d/system.conf containing /System/Library/Libraries ships in the ISO and is picked up by ldconfig at first boot.

8.6 The clone loop inside build.sh

The git-clone stage is just a shell loop near the top of build.sh, before pkgbase extraction. The five GNUstep upstreams plus Tessil/robin-map (sibling source for libobjc2's robinmap dep — see §8.3). No pinning, no patches at clone-time — tracks upstream HEAD.

REPOS_DIR="$(pwd)/repos"

REPOS="
https://github.com/apple/swift-corelibs-libdispatch.git
https://github.com/gnustep/tools-make.git
https://github.com/gnustep/libobjc2.git
https://github.com/Tessil/robin-map.git
https://github.com/gnustep/libs-base.git
https://github.com/gnustep/libs-corebase.git
"

mkdir -p "$REPOS_DIR"
cd "$REPOS_DIR"

for REPO in $REPOS; do
    NAME=$(basename "$REPO" .git)
    if [ -d "$NAME/.git" ]; then
        echo "Updating $NAME..."
        ( cd "$NAME" && git fetch --all --tags && git pull --ff-only )
    else
        echo "Cloning $NAME..."
        git clone "$REPO"
    fi
done

cd -

8.7 Package lists — start minimal, add when something breaks

Stance: install nothing we don't need. The starting point is the absolute minimum that lets build.sh get past cmake and ./configure; everything else is added one package at a time, only when a build or runtime failure surfaces it. The gershwin desktop's Bootstrap.sh carries ~60 packages because it builds the full GUI stack — we are not building any of that, so we should not cargo-cult the list.

buildpkgs.txt — what Phase 2 shipped

cmake
ninja
gmake
autoconf
libtool
pkgconf

clang/clang++ ship in FreeBSD base, so they aren't listed. git is intentionally absent: all git clones happen on the host before the chroot exists; the chroot is git-free. pkgconf was added when libs-base configure couldn't find ICU — it queries via pkg-config icu-i18n / icu-uc. automake, llvm still left out.

pkglist.txt — what Phase 2 shipped

libxml2
icu

Both are runtime deps of libgnustep-base.so:

• libxml2 — libs-base XML branch (GSXML / NSXMLNode / XML NSPropertyListSerialization). Configure has a --disable-xml flag but we keep XML on; binary plists are not the only format we need to read.
• icu — libs-base unicode (NSLocale / NSString). Hard dep, no --disable flag.

Surprises during Phase 2 surfacing:

• libffi — predicted as a likely candidate, but already supplied by FreeBSD base. Not added.
• libgnutls — also predicted; we took the --disable-tls path (libs-base configure flag, see §8.4) instead. Not added.

Things from the gershwin Bootstrap.sh we explicitly do not add unless something forces our hand:

• libxslt — XSLT transforms only; we parse plists.
• gnutls / openssl — TLS in NSURLConnection; launchd doesn't speak TLS. Configure libs-base with --disable-tls if it has the flag; if not, deal with it then.
• mDNSResponder, dbus, cups, wget — no Bonjour, no D-Bus, no printing, no fetching in-chroot.
• squashfs-tools-ng, fusefs-squashfuse — we use mkuzip + geom_uzip + in-kernel unionfs, not squashfs.
• libvncserver, freerdp — remote desktop, not in scope.
• libjpeg-turbo, tiff, png, giflib, ImageMagick7, cairo, libXft, libXt, libxcb, xcb-util-*, xrandr, libXrandr, libXcomposite, xorg-fonts-truetype, freeglut — all GUI/image/X11. We have no display server.
• flite, portaudio, libao — audio. Not on a server.

The pattern: every package added to either list gets a one-line commit message naming the build step that demanded it. Future readers (and future-you) can then audit whether that demand still holds when the upstream changes.

8.8 Two scripts: build.sh (livecd) and make-launchd.sh (reusable)

Everything livecd-specific lives in build.sh: the git clones, the pkgbase extraction, the chroot setup, the GNUstep-library builds, the slim pass, the mkuzip, the cd9660 wrap. make-launchd.sh is the only standalone-reusable piece — it's what gershwin-on-freebsd will call to add launchd to a system that already has the GNUstep stack.

The gershwin-on-freebsd integration story

The whole reason for splitting make-launchd.sh out as standalone: gershwin-on-freebsd already builds the full GNUstep stack (libdispatch + libobjc2 + tools-make + libs-base + libs-corebase + libs-gui + libs-back + Workspace + LoginWindow + everything) into /System/Library/ via the upstream gershwin-developer meta-installer. It does not have launchd. To add launchd, that ISO builder just does:

# Inside the gershwin-on-freebsd chroot, after gershwin-developer's
# Install-System-Domain.sh has placed libdispatch + Foundation in /System/Library/

git clone https://github.com/pkgdemon/freebsd-launchd /tmp/launchd
cd /tmp/launchd
./make-launchd.sh           # checks for /System/Library/Libraries/*, builds, installs to /sbin/

# Wire launchd as PID 1 in the gershwin-on-freebsd loader.conf:
echo 'init_path="/sbin/launchd"' >> "$WORK/cdroot/boot/loader.conf"

That's the entire integration. No git submodule, no shared CI, no version coupling. gershwin-on-freebsd clones the launchd repo in its own build script and gets a tested, boot-verified launchd dropped on top of its existing /System/Library/ tree. Symmetrically, our own build.sh calls make-launchd.sh in its chroot — same script, same behavior, no code duplication.

9. The livecd build pipeline

Lifted directly from freebsd-livecd-unionfs. The skeleton — pkgbase extraction, chroot mount, slim, mkuzip, hybrid cd9660 — is unchanged. We add two new chroot stages between "pkg install" and "slim".

9.1 Why build inside the chroot, not on the host VM?

• Hermetic. What we link against = what we ship. No risk of accidentally linking against a host library that won't exist in the booted system.
• Same toolchain as the runtime. Compiler version, libc version, headers all match the rootfs we're shipping.
• The chroot already has every base header we need. The pkgbase base.txz contains the full base userland; buildpkgs.txt only adds cmake/ninja/clang-extras/git that aren't in base.

9.2 PID 1 handoff

Single-stage shebang chain. loader.conf sets init_path="/init.sh:/rescue/init". The kernel hits the #!/rescue/sh shebang at the top of /init.sh (handled unconditionally by imgact_shell — see §9.2.1) and exec's /rescue/sh as PID 1 with /init.sh as argv[1]. The script then:

1. Mounts devfs at /dev and reopens stdio from /dev/console (kernel hands PID 1 with fds 0/1/2 closed).
2. mdconfig + mount -t ufs/tmpfs/unionfs to layer the writable upper over the read-only uzip lower at /sysroot.
3. exec /rescue/chroot /sysroot /sbin/launchd — every exec preserves the same PID, so launchd inherits as the original PID 1 the kernel created.

The colon-fallback to /rescue/init is for the case where the kernel rejects /init.sh for any reason. In that fallback, /rescue/init is PID 1, reads init_script=/init.sh kenv, and invokes the same script as a child. The script detects $$ != 1 and uses the classic kenv init_chroot=/sysroot + exit pattern, falling back to FreeBSD's normal init flow (no launchd).

9.2.1 Why we don't go through init.c

An earlier draft of this section proposed setting kenv init_path=/sbin/launchd in the script and relying on init.c to re-read it after the init_chroot pivot. Source review settled this: FreeBSD's /sbin/init (and /rescue/init, which is the same code, just crunchgen'd) reads init_path exactly once at startup (sbin/init/init.c:245), and only re-checks it on the reroot recovery path (init.c:814) — never after the init_chroot pivot in the normal boot flow. The only re-exec hook in init.c is the init_exec kenv at init.c:321, fired before any userland code runs (too early to be useful for our pivot).

The shebang path bypasses init.c entirely. Verified by reading sys/kern/init_main.c + sys/kern/imgact_shell.c: start_init() calls kern_execve() with no PID-1-special-case (line 797); do_execve() iterates the imgact chain unconditionally (kern_exec.c:664-668); imgact_shell.c:108-110 has no guards on p->p_pid or P_SYSTEM. The shebang fires for the very first userspace exec exactly as it does for any other.

Caveats. Shell-script-as-init is undocumented in FreeBSD — no init(8) mention, no shipped init_path default uses it, no test in tests/sys/kern/ exercises it. The mechanism is purely a consequence of the kernel exec path being uniform. Documented here so future maintainers don't have to re-discover it.

10. CI & release pipeline

Three GitHub Actions jobs. Pattern lifted from freebsd-livecd-unionfs/.github/workflows/build.yml.

10.1 Boot-test marker set

The current livecd-unionfs test waits for one marker: login: on serial. We extend to two:

spawn qemu-system-x86_64 -m 4G -machine q35 -bios $OVMF \
    -cdrom $iso -display none -serial stdio -no-reboot

# Marker 1: launchd announces itself early
expect {
    timeout { puts "\nFAIL: launchd did not announce within 8 min"; exit 1 }
    "launchd: PID 1 ready" { puts "OK: launchd is PID 1" }
}

# Marker 2: getty came up via the launchd plist (or via init's /etc/ttys path)
expect {
    timeout { puts "\nFAIL: 'login:' prompt not seen"; exit 1 }
    "login:" { puts "OK: boot reached the login prompt" }
}

launchd: PID 1 ready is logged by our launchd.c after directory scan completes and the AF_UNIX server is accepting. Two markers means: the binary is PID 1 AND launchd's job model actually came up enough to spawn getty. Either marker missing fails the release gate — no broken ISO ships.

11. Boot flow without rcorder

FreeBSD rc.d uses rcorder(8) to topologically sort scripts by their # PROVIDE/# REQUIRE/# BEFORE headers. launchd philosophically rejects this in favor of runtime dependency — a job blocks on the resource it needs and launchd starts the provider on demand.

11.1 Socket-activated daemons (the easy 80%)

Daemons that listen on sockets — sshd, rpcbind, mountd, syslogd — declare their listen sockets in their plist's Sockets key. launchd opens the socket, listens on the daemon's behalf, and only forks the daemon when a connection arrives. Anything that needs the daemon just connect()s; the kernel queues the connection until the daemon answers. Eliminates ordering for socket clients: nfsd calling rpcbind via the loopback socket Just Works regardless of start order.

11.2 Phase no-op jobs (the awkward 15%)

Some "dependencies" aren't sockets — "filesystems mounted", "network configured", "kernel modules loaded". Each becomes a one-shot plist with a well-known label that touches a stamp file on success:

11.3 Explicit ordering (the last 5%)

Narrow extension to the plist schema: a RequiresPhase array key the bootstrapper resolves at load time. Daemons in WAITING until each listed phase's stamp file exists. Gives back rcorder-style declarative power for the few cases that need it without re-introducing a full topological sort.

11.4 devd is special

devd must run before netif because NIC IFATTACH events flow through it. Plan: a LaunchDaemons.early/ directory the bootstrapper loads before the main scan. Keeps the launchd binary simple and the early tier declarative.

12. rc.d port scope

12.0 Configuration mechanism — plists, not rc.conf

Every per-host configuration concern — hostname, interface IP, default route, WiFi credentials, daemon arguments — is expressed as a plist, not as a key in /etc/rc.conf, and not as a single-purpose file like /etc/hostname. There is no rc.conf parsing layer in this project. Users edit the plist directly (or, more commonly, edit it via GUI tooling that manipulates the plist).

Path conventions:

• /System/Library/LaunchDaemons/ — project-shipped plists (getty, devd, syslogd, etc.). Untouched by users.
• /Local/Library/LaunchDaemons/ — admin-installed and user-edited plists (hostname, per-iface networking, custom services). The "third-party" tier in the gershwin layout.

Concrete examples of the per-component pattern:

Why no rc.conf parser: rc.conf has 1000+ knobs accumulated over 30 years. Supporting "some" of them creates a confusing partial-compatibility layer. A plist's ProgramArguments shows the literal command that runs — no magic translation, no surprises. For users coming from FreeBSD muscle memory, the substitution is one-line: whatever you'd put after ifconfig_em0= in rc.conf goes into ProgramArguments verbatim.

Why no /etc/hostname shortcut: consistency. Every other concern is a plist; hostname becoming the lone single-line file would be the inconsistent choice.

WiFi keeps /etc/wpa_supplicant.conf because it's wpa_supplicant's own configuration file (we'd be reinventing the wheel to replace it). The plist just invokes wpa_supplicant; configuration of the WiFi credentials themselves stays in the file format the tool already reads.

12.1 Milestone 1 — launchd boots, console login

Smallest possible scope that proves launchd is PID 1: no plists, just the daemon itself + getty via the existing /etc/ttys path. The boot test watches for launchd: PID 1 ready and login: on serial.

12.2 Milestone 2 — sshd as the first launchd-supervised daemon

This is the proof-of-life milestone for the supervisor. Pick one daemon, give it a plist, watch launchd manage it. sshd is the right choice because it (a) is universally useful, (b) gives us an end-to-end smoke test (boot ISO → ssh in from outside → kill the sshd → see launchd respawn it), and (c) forces just enough networking to be real, no more.

Bring-up set for this milestone:

Boot-test extension: third marker watches for sshd listening (e.g. sshd: Server listening on 0.0.0.0 port 22). Gate the release on it.

12.3 Milestone 3 — remaining base services (shipped, not goal-gating)

Once milestone 2 is green, fill in plists for the rest of the FreeBSD base service set. These ship in the repo so users can launchctl load what they want; they don't gate the release. The ISO doesn't have to start nfsd to pass CI — it just has to ship a working plist for users who do want NFS.

12.4 Sketch: org.freebsd.sshd.plist

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key>            <string>org.freebsd.sshd</string>
  <key>ProgramArguments</key> <array>
                                <string>/usr/sbin/sshd</string>
                                <string>-i</string>
                              </array>
  <key>inetdCompatibility</key> <dict><key>Wait</key><true/></dict>
  <key>Sockets</key>          <dict>
    <key>Listeners</key>      <dict>
      <key>SockServiceName</key> <string>ssh</string>
      <key>SockType</key>        <string>stream</string>
      <key>Bonjour</key>         <false/>
    </dict>
  </dict>
  <key>RequiresPhase</key>    <array><string>network-ready</string></array>
</dict>
</plist>

12.5 Out of scope (won't port — server scope)

• Hardware-laptop: apm, apmd, powerd, bluetooth, hcsecd, sdpd, watchdogd
• Legacy / deprecated: sendmail, sendmail_submit, amd, ntpdate, ftpd, tftpd, inetd (launchd is the inetd replacement), ypbind/ypserv/yppasswdd (NIS, dead)
• Niche: accounting, bsnmpd, hastd, ctld, iscsid, nfscbd, gssd
• Firewall: port one path (probably pf); skip ipfw/ipfw_netflow/pflog/pfsync until requested
• Caching: local_unbound, NSS caches — not until requested

12.6 The "anything else becomes a one-shot" rule

Single most important translation rule: anything rc.d does that isn't "run a long-lived daemon" becomes a one-shot plist with RunAtLoad=true, KeepAlive=false, LaunchOnlyOnce=true. Examples: sysctl from /etc/sysctl.conf, kldload from kld_list, fsck -p + mount -a, swapon -a, /var/run + /tmp cleanup. Live config-file reload (service foo reload) is a strict improvement in launchd via WatchPaths / QueueDirectories.

12.7 Service enable / disable UX

Concrete scenario: sshd ships disabled by default. Admin enables it on a freshly-installed system. How?

Apple's model (the target)

The shipped plist at /System/Library/LaunchDaemons/org.freebsd.sshd.plist contains:

<key>Disabled</key>
<true/>

At every boot, launchd scans, sees the key, skips the job. The shipped plist is never edited by users or admins — it stays bit-for-bit stable across upgrades.

State changes go through one of three paths:

The persistence trick is a separate overrides file:

• Apple historical: /var/db/launchd.db/com.apple.launchd/overrides.plist
• Apple modern: /var/db/com.apple.xpc.launchd/disabled.plist
• This project: /var/db/org.freebsd.launchd/overrides.plist

At boot, launchd merges (a) the shipped plist's Disabled key (default state) with (b) the overrides file (user's persistent intent). The overrides file is a plist of {label: bool} entries — only present when a user has expressed an opt-in or opt-out for a specific job.

Modern launchctl verbs (macOS 10.10+) make this explicit:

sudo launchctl enable system/org.freebsd.sshd     # set persistent "enabled"
sudo launchctl disable system/org.freebsd.sshd    # set persistent "disabled"
sudo launchctl bootstrap system /System/Library/LaunchDaemons/org.freebsd.sshd.plist
sudo launchctl bootout system/org.freebsd.sshd

Status today

Implementation plan (Phase 5 batch)

~250 LOC of focused launchd surgery, lands alongside the EnvironmentVariables / StartCalendarInterval / etc. work in §6.3:

1. core.m (~150 LOC): at plist-scan time, read /var/db/org.freebsd.launchd/overrides.plist. For each scanned job, merge shipped.Disabled XOR override[label]. Apply the merged value. Add a vnode source on the overrides file so changes flush to running state without a daemon restart.
2. launchctl.c (~80 LOC): implement the -w flag and the modern enable / disable verbs. They write to the overrides file via launchd's IPC (or directly with file lock + send a "reload" IPC).
3. ipc.c (~30 LOC): new IPC verbs for "set persistent enable", "set persistent disable", "manual start", "manual stop".
4. varrun plist (one line): mkdir -p /var/db/org.freebsd.launchd so the overrides file has a home.

Pragmatic Phase 4 path

For the immediate sshd milestone (Phase 4 in §14), two options:

• A. Defer the override mechanism; ship sshd enabled by default. org.freebsd.sshd.plist with RunAtLoad=true, no Disabled key. Fastest to the proof-of-life milestone. Acceptable for a livecd; less acceptable for a secure-server posture.
• B. Implement the override mechanism first; ship sshd disabled by default. User runs sudo launchctl load -w /System/Library/LaunchDaemons/org.freebsd.sshd.plist to enable. The right Apple-shaped answer. Adds ~250 LOC to Phase 4's scope.

Recommendation: A for Phase 4 (get configd + sshd-as-supervised-daemon working end-to-end), B as a focused Phase 5 commit before we'd consider the system installable. Live ISO with sshd-on-by-default is fine — every boot has the same default-password posture, and that's already accepted.

13. Licensing

The repo is a composition of three source families. They coexist cleanly under a single top-level LICENSE with per-file headers preserved — no dual-licensing needed. Top-level: BSD-2-Clause (matches the FreeBSD ecosystem and your other repos; aligns with FreeBSD base itself).

13.1 Why BSD-2-Clause top-level (and not Apache 2.0)

1. FreeBSD ecosystem fit. FreeBSD base is BSD-2-Clause; freebsd-livecd-unionfs is BSD-2-Clause; a FreeBSD sysadmin opening the repo expects BSD-2-Clause. Apache 2.0 would be a momentary surprise.
2. Apple's headers don't depend on our top-level choice. Apple's @APPLE_APACHE_LICENSE_HEADER_START@ blocks stay on every Apple file regardless. Top-level license only governs files we ourselves author.
3. The patent-grant argument doesn't cut here. Apache 2.0's patent grant matters when contributors contribute patented inventions and you want downstream protection from their future-self assertions. For a port of someone else's already-Apache-2.0 code, the existing grant on those files is preserved by the file header — top-level license doesn't change that. We're not introducing patentable inventions of our own.
4. Smaller surface. BSD-2-Clause has no NOTICE requirement, no §4(d) ceremony. Cleaner.

Real-world precedent: FreeBSD base itself contains Apache-licensed code (e.g. portions of OpenJDK) under a BSD-2-Clause-licensed project umbrella. Apache files keep their headers; the project is BSD. Same pattern as here.

13.2 Why not dual-license

Dual licensing (e.g. "BSD-2-Clause OR Apache-2.0") makes sense when consumers need to pick either license at use time — typical for libraries that want to be drop-in for both GPL and permissive consumers. Nothing here is that case: consumers download the ISO, they don't relink against our .sos. Dual-licensing the top-level adds friction (every NOTICE-equivalent, every contribution, every dependency review considers two licenses) for zero downstream benefit.

13.3 Modifying Apple's launchd files — what the rules require

We will modify Apple files extensively (gut Mach paths, rewrite core.c, etc.). Apache 2.0 explicitly permits this. The compliance checklist per Apache 2.0 §4:

1. Keep the original copyright header verbatim. Every Apple file's @APPLE_APACHE_LICENSE_HEADER_START@ through @APPLE_APACHE_LICENSE_HEADER_END@ block stays at the top of the file, even after we delete 80% of the body.
2. Add a "Modified by..." note immediately below the Apple header. Apache 2.0 §4(b): "modified files must carry prominent notices stating that You changed the files." A two-line note suffices:

   /*
    * Modified 2026 by Joe Maloney for the freebsd-launchd project.
    * SPDX-License-Identifier: Apache-2.0  (this file remains Apache 2.0)
    */

   The SPDX line clarifies for tooling that this individual file stays Apache even though the project top-level is BSD-2-Clause.
3. Modified file stays Apache 2.0. Our changes to that file are Apache-licensed (inbound=outbound). The project top-level (BSD-2-Clause) doesn't override per-file licensing — Apache files in a BSD project remain Apache; BSD files in an Apache project remain BSD. License is per-file, not per-repo.
4. NOTICE file at repo root. Apple's launchd source ships with a NOTICE requirement. Even though BSD-2-Clause itself doesn't require one, we still ship a NOTICE at the repo root because some Apache files in our tree carry that requirement. Listing what's in there:

   freebsd-launchd
   Copyright 2026 Joe Maloney and contributors
   Licensed under BSD-2-Clause (see LICENSE).
   
   This product includes software developed by:
     - Apple Inc. (launchd, 2005-2012, Apache 2.0)
       https://github.com/apple-oss-distributions/launchd
       Modified by freebsd-launchd contributors; see git log.
   
     - Apple Inc. and the Swift project authors
       (swift-corelibs-libdispatch, Apache 2.0 + Runtime Library Exception)
       Linked at runtime; not included in this source tree.
   
     - The GNUstep Project
       (libs-base, libs-corebase, LGPL 2.1+ / 3 with linking exception)
       Linked at runtime; not included in this source tree.
   
     - The libobjc2 contributors
       (libobjc2, MIT) — linked at runtime; not in source tree.

5. New files we author (build.sh, make-launchd.sh, the plists, our compat shims) get a BSD-2-Clause SPDX header:

   /*
    * Copyright 2026 Joe Maloney and freebsd-launchd contributors
    * SPDX-License-Identifier: BSD-2-Clause
    */

None of this is novel — every Apache-derived BSD project (and there are many in the FreeBSD world) follows this pattern. A reader can run find . -name '*.[ch]' | xargs grep -l SPDX-License-Identifier and immediately see which files are Apache and which are BSD.

13.4 Shipping LGPL source for built-in-libraries

The ISO ships libgnustep-base.so and libgnustep-corebase.so (LGPL 2.1+ / LGPL 3 with linking exception) as built binaries. Per LGPL §6, recipients must be able to obtain the corresponding source. Two ways to satisfy this:

1. Ship source as a tarball under /System/Library/Source/ in the ISO. Self-contained, large.
2. Release notes link to the upstream commit the ISO was built from. §6 explicitly permits this. Cheaper, smaller ISO.

Plan goes with option 2 — see Q5 in §15.

14. Phased delivery

15. Open questions

16. References

• Pipeline source: github.com/pkgdemon/freebsd-livecd-unionfs — build.sh, tests/boot-test.sh, .github/workflows/build.yml all lifted from here.
• Apple source: github.com/apple-oss-distributions/launchd (last open-source release, launchd-842.1.4).
• libdispatch upstream: github.com/apple/swift-corelibs-libdispatch.
• FreeBSD devel/libdispatch port (reference for the kevent patch state): freshports.org/devel/libdispatch.
• FreeBSD hier(7): man.freebsd.org/hier(7).
• FreeBSD rc(8), rc.subr(8), rcorder(8): man.freebsd.org/rc.subr(8).

Plan v0 — generated 2026-05-04. This is a living document; updates land here before any code commits.