Install layout spike — per-component paths across four layouts

For every component we plan to port, here are all the installed files (executables, libraries, headers, plists, configs, man pages, bundles) across four candidate layouts: Apple's actual macOS paths, an Apple-like /usr/lib/system/ layout on FreeBSD, gershwin's /System/Library/ layout, and a FreeBSD-base-style /usr/lib layout. Companion to the libdispatch Mach spike's install-path discussion and the Foundation spike.

1. Four layouts explained

Layout	Status	What it means
Apple macOS	reference	Where Apple actually puts these on macOS. Note: since Big Sur most system .dylib files are not files on disk — they're entries in /System/Library/dyld/dyld_shared_cache_*. Paths shown are logical (what dlopen() resolves to) even when no physical file exists.
/usr/lib/system/	new option	Apple-like layout on FreeBSD — mimics Apple's /usr/lib/system/ convention from pre-Big-Sur macOS. Each Libsystem sub-library lands as libsystem_<name>.so. Headers at the standard /usr/include/. Pitch: makes the Apple-source userland feel more Apple-shape without requiring the gershwin /System/Library/ hierarchy. Good fit for dispatch + xpc + kernel + notify + asl — the components Apple specifically calls "libsystem_*" on macOS.
Gershwin /System/Library/	project precedent	What gershwin-developer's Install-System-Domain.sh and freebsd-launchd's build.sh use today. Libraries at /System/Library/Libraries/, headers at /System/Library/Headers/, frameworks preserved as bundles at /System/Library/Frameworks/. Visual separation of Apple-source-as-system-services.
FreeBSD base /usr/lib	aspirational	Where these would live if shipped through pkgbase. Standard /usr/lib, /usr/include, etc. Flat: no framework bundles, no /System hierarchy. Mixes with FreeBSD base.

Apple-Unix paths (/sbin, /usr/sbin, /usr/libexec, /usr/bin, /etc) are universal across all four layouts — daemons, CLIs, and config files don't change paths based on whether the library convention is gershwin or base. Only libraries, headers, and framework bundles differ.

2. mach.ko

3. libmach

4. libdispatch

5. libxpc

6. liblaunch

7. launchd (daemon + launchctl)

8. asl (syslogd + aslmanager + libasl + syslog)

9. notifyd + libnotify + notifyutil

10. configd + scutil + SystemConfiguration.framework + libSystemConfiguration + plugins

11. CoreFoundation (swift-corelibs-foundation, non-Swift mode)

12. mDNSResponder

13. IPConfiguration (ipconfig + bootpd)

14. DiskArbitration (framework + daemon + agent)

15. Block.h / libBlocksRuntime

16. GNUstep stack (libobjc2 + libgnustep-base + libgnustep-corebase + tools)

17. Cross-cutting concerns

17.1. Framework bundles vs flat layout

Three frameworks in our porting scope: SystemConfiguration.framework, DiskArbitration.framework, and the optional CoreFoundation.framework wrapper. For each, the choice is:

• Bundle layout (gershwin / Apple) — preserves the Foo.framework/Versions/A/Foo + Foo.framework/Headers/ + Foo.framework/Resources/ directory structure. Apple-shape source compiles unchanged with -framework Foo.
• Flat layout (FreeBSD base) — /usr/lib/libFoo.so + /usr/include/Foo/*.h + /usr/share/Foo/*.plist. Apple-shape source needs link-line and include-path rewrites.

The bundle layout costs about 200 lines of build-system fiddling per framework (CMake's framework target or hand-rolled symlinks). Worth it for source compatibility with Apple imports; not worth it if we deeply rework each framework anyway.

17.2. Reverse-DNS plist naming

Apple uses com.apple.<name>.plist. Our project uses org.freebsd.<name>.plist for new daemons. Both coexist in the same directories — launchd loads any .plist regardless of prefix. If we import Apple's verbatim plists for daemons that don't conflict with FreeBSD-native ones (e.g. notifyd, mDNSResponder), we keep their com.apple. prefix; if we ship our own (org.freebsd.syslogd because we're replacing FreeBSD's syslogd), we use org.freebsd..

17.3. Project policy: /Local/Library always, never /Library

This applies to:

• /Local/Library/LaunchDaemons/ — third-party launchd plists (replaces Apple's /Library/LaunchDaemons/)
• /Local/Library/LaunchAgents/ — third-party launchd agents (replaces Apple's /Library/LaunchAgents/)
• /Local/Library/Preferences/ — third-party preferences including SCPreferences (replaces Apple's /Library/Preferences/)
• /Local/Library/Frameworks/ — third-party frameworks (replaces Apple's /Library/Frameworks/)
• Any other /Library/X Apple uses: becomes /Local/Library/X on our system

/System/Library/ is unchanged. That's where Apple's own system-level content lives, and we follow that convention for our Apple-source-userland's system content (libraries, headers, frameworks, system LaunchDaemons). The policy applies ONLY to the third-party root, not the system root.

~/Library/ (per-user) is unchanged. Per-user home-directory content stays in ~/Library/; gershwin already follows Apple's convention here. Per-user agent plists at ~/Library/LaunchAgents/, per-user preferences at ~/Library/Preferences/.

Apple-source verbatim imports (configd, DiskArbitration, IPConfiguration) that reference /Library/Preferences/SystemConfiguration/ internally need a small patch or runtime configuration substituting /Local/Library/Preferences/SystemConfiguration/. Handled per-port; small impact.

17.4. Apple-Unix paths are (mostly) universal — daemons could move to /System/Library/Tools/

The spike presents daemons at Apple-conventional Unix paths (/usr/sbin/notifyd, /usr/sbin/syslogd, /usr/libexec/configd, etc.) across all four columns. That's a choice, not a hard requirement. Gershwin has its own convention for "tools that the gershwin environment owns" via /System/Library/Tools/ — where GNUstep helper utilities (defaults, gdomap, gdnc, plutil) already live.

Daemon / CLI	Apple-Unix path (default in this spike)	Gershwin Tools path (alternative)
launchd	/sbin/launchd	no — PID 1 must be on the boot partition root for the kernel; /sbin/launchd is effectively required
launchctl	/bin/launchctl	/System/Library/Tools/launchctl — possible; matches GNUstep CLI convention
syslogd, notifyd, scutil, mDNSResponder, ipconfig, rtadvd, aslmanager	/usr/sbin/<name>	/System/Library/Tools/<name> — possible per daemon
configd, diskarbitrationd, IPConfiguration, bootpd, dhcp6d, IPConfigurationHelper, mDNSResponderHelper	/usr/libexec/<name>	/System/Library/Tools/<name> — possible but loses the /usr/libexec "implementation-detail-daemon" signal
syslog, notifyutil, dns-sd CLIs	/usr/bin/<name>	/System/Library/Tools/<name> — possible; matches GNUstep tools precedent most closely

Why the spike defaults to Apple-Unix paths

• Apple compatibility. Apple's macOS puts these at /usr/sbin/notifyd etc. Apple-source verbatim imports and any porting documentation reference those paths. Matching keeps source-level diffs minimal.
• FreeBSD admin recognizability. A sysadmin who knows FreeBSD's /usr/sbin/ for daemons and /usr/libexec/ for back-end daemons can navigate immediately.
• Gershwin's /System/Library/Tools/ is for GNUstep helper CLIs. defaults, gdomap, gdnc, plutil — command-line tools that gershwin ships. Daemons launchd starts aren't conceptually GNUstep tools; they're system services. Mixing them dilutes the meaning of the Tools dir.
• launchd plist ProgramArguments paths are flexible. launchd doesn't care where the daemon binary lives — the plist's Program or ProgramArguments[0] just needs an absolute path. So the choice is purely conventional, not technical.

When you'd want /System/Library/Tools/ instead

• If you want every executable installed by the gershwin / Apple-source userland to live under /System/Library/ with NOTHING in /usr/sbin or /usr/libexec — cleanest visual separation between Apple-source and FreeBSD-base.
• If you ever ship the whole stack as a single uzip / nullfs overlay rooted at /System/ — one mount, one tree, everything's there.
• If FreeBSD's own pkgbase ever ships its own notifyd at /usr/sbin/notifyd — we'd dodge the collision by being at /System/Library/Tools/notifyd instead.

Decision (current spike default, revisable): stick with Apple-Unix paths for daemons. Move to /System/Library/Tools/ only if a concrete reason emerges. The launchd plist abstraction makes this revisable at any time without breaking consumers.

.app bundles — /System/Applications/ for system-shipped apps

Distinct from CLI tools / daemons: any Apple-source component that ships as a .app bundle (DiskArbitrationAgent, future Apple-source GUI helpers, ...) lives at /System/Applications/Foo.app/ on our system, not /Applications/Foo.app/. The convention:

• /System/Applications/ — system-shipped Apple-source .app bundles (DiskArbitrationAgent, future menu/menubar/finder-equivalent apps if any)
• /Applications/ — user-installed .app bundles (apps the end user drags in)
• /Local/Library/ at the filesystem root, per the project policy in §17.3, replaces Apple's /Library/ for third-party content, but /Applications/ stays the same name (it's not under /Library, so the policy doesn't apply)

This mirrors Apple's modern (Catalina+) layout where Apple-system apps live at /System/Applications/ separate from user-installed apps at /Applications/.

17.5. Universal paths across all four layouts

The following paths are identical across every layout (daemons / CLIs / configs / runtime state don't depend on the library layout):

• /sbin/launchd, /sbin/launchctl — launchd path
• /usr/sbin/{syslogd, aslmanager, notifyd, scutil, mDNSResponder, ipconfig, rtadvd} — or /System/Library/Tools/ per §17.4
• /usr/libexec/{configd, diskarbitrationd, IPConfiguration, bootpd, dhcp6d, IPConfigurationHelper, mDNSResponderHelper}
• /usr/bin/{launchctl, syslog, notifyutil, dns-sd}
• /etc/{asl.conf, asl/, notify.conf, bootpd.plist, bootptab, rtadvd.conf}
• /var/log/asl/, /var/log/system.log, /var/db/{launchd.db, dhcpclient, SystemConfiguration}/
• /System/Library/LaunchDaemons/, /System/Library/LaunchAgents/ (system plists)
• /Local/Library/LaunchDaemons/, /Local/Library/LaunchAgents/, /Local/Library/Preferences/ (third-party content — our project policy, never plain /Library/)
• ~/Library/LaunchAgents/, ~/Library/Preferences/ (per-user)
• Man pages at /usr/share/man/manN/*.N

The four layouts diverge only on libraries, headers, and framework bundles.

17.5. Gershwin conditional-skip pattern

If freebsd-launchd-mach installs its libsystem_* libraries to a known location, gershwin-developer's Install-System-Domain.sh can detect their presence and skip the corresponding build entirely — deferring to our project's binaries. This avoids the dual-build / dual-install problem and gives our project ownership of the Apple-source-userland libraries when it's installed.

Pattern, added to gershwin-developer/Library/Scripts/Install-System-Domain.sh near the top:

LIBSYSTEM_DIR="/usr/local/lib/system"   # or /usr/lib/system

# --- libdispatch ---
if [ -f "$LIBSYSTEM_DIR/libsystem_dispatch.so" ]; then
    echo "==> freebsd-launchd-mach libsystem_dispatch.so detected — skipping libdispatch build"
    mkdir -p /System/Library/Libraries /System/Library/Headers
    ln -sf "$LIBSYSTEM_DIR/libsystem_dispatch.so" /System/Library/Libraries/libdispatch.so
    ln -sf /usr/include/dispatch /System/Library/Headers/dispatch
    ln -sf /usr/include/os       /System/Library/Headers/os
    # Block.h coordination automatic — both projects defer to base's /usr/include/Block.h
else
    # ... existing gershwin libdispatch build ...
fi

# --- libxpc (when freebsd-launchd-mach starts shipping it) ---
if [ -f "$LIBSYSTEM_DIR/libsystem_xpc.so" ]; then
    echo "==> freebsd-launchd-mach libsystem_xpc.so detected — skipping libxpc"
    ln -sf "$LIBSYSTEM_DIR/libsystem_xpc.so" /System/Library/Libraries/libxpc.so
    ln -sf /usr/include/xpc /System/Library/Headers/xpc
fi

# --- libmach, libnotify, libasl, libsystem_launch, libsystem_configuration ---
# Same pattern for each.

Why this is the right coordination model

• Single source of truth. When freebsd-launchd-mach is installed, IT owns the Apple-source-userland libraries. Gershwin defers. Headers and binaries match because they came from one project.
• No daily-driver coordination needed. Gershwin doesn't need to know our project's internal release cadence, ABIs, or patch series. It just checks for a file's existence.
• Plain gershwin installs still work. If freebsd-launchd-mach is NOT installed, the file isn't there, gershwin builds its own libdispatch as today. No regression for existing gershwin-on-FreeBSD users.
• Symlinks preserve consumer compatibility. GNUstep apps that compile against /System/Library/Libraries/libdispatch.so still find it — the symlink resolves to $LIBSYSTEM_DIR/libsystem_dispatch.so. Both call sites converge on the same binary.
• Block.h coordination automatic. Both projects defer to FreeBSD pkgbase's /usr/include/Block.h — one source of truth on the system regardless of which built libdispatch.

Where does $LIBSYSTEM_DIR point?

Choice	Pros	Cons
/usr/lib/system/	Exact match to Apple's pre-Big-Sur layout. Most Apple-canonical pitch.	Lives in FreeBSD base namespace. Latent pkgbase-collision risk if FreeBSD ever ships its own libsystem_* (unlikely but possible).
/usr/local/lib/system/	Standard FreeBSD ports placement. Clean separation from base. No pkgbase-collision risk. Where freebsd-launchd-mach's ports package would install by default.	Slightly less Apple-canonical (Apple uses /usr/lib/system/). The "libsystem_" prefix under /usr/local/ is mildly incongruous.

Recommended: /usr/local/lib/system/. The pkgbase-collision risk argues against /usr/lib/system/; ports placement matches how our project would actually ship as a FreeBSD package; and the coordination pattern doesn't care about the exact path. Gershwin just looks for the file.

Migration path — two phases

Phase 1: symlink layer (zero consumer change).

1. Phase 0 of the libxpc plan commits to a libdispatch Mach-backend patch in gershwin-developer/Library/Patches/. Same library gershwin builds today, with Mach support added.
2. When freebsd-launchd-mach starts shipping libsystem_dispatch.so standalone (out of the same patched source), add the conditional-skip block to Install-System-Domain.sh + symlinks at /System/Library/Libraries/ and /System/Library/Headers/. Consumers' existing -ldispatch / -I/System/Library/Headers keep working unchanged.
3. Gershwin-on-freebsd ISO builds automatically pick up freebsd-launchd-mach's version when the package is installed first in the build pipeline.

Phase 2 (optional, later): reconfigure consumers to reference /usr/local/lib/system/ directly.

Once Phase 1 is stable, gershwin's downstream parts can be updated to point at /usr/local/lib/system/ directly and retire the symlink layer. Concrete places that need updating:

File / setting	Current	After reconfigure
tools-make/FilesystemLayouts/gershwin — defines GNUSTEP_SYSTEM_LIBRARIES	/System/Library/Libraries	still /System/Library/Libraries for GNUstep stack; add /usr/local/lib/system to the search path for Apple-source libraries
tools-make/Makefiles/Library/library.make — library link flags	-L/System/Library/Libraries -ldispatch	add conditional: $(if -f /usr/local/lib/system/libsystem_dispatch.so, -L/usr/local/lib/system -lsystem_dispatch, -L/System/Library/Libraries -ldispatch)
GNUstep.conf at /System/Library/Preferences/GNUstep.conf	library/header dir vars all point to /System/Library/	add GNUSTEP_LIBSYSTEM_LIBRARIES=/usr/local/lib/system + GNUSTEP_LIBSYSTEM_HEADERS=/usr/include; GNUstep-aware tools read these
gershwin component build scripts (windowmanager, terminal, workspace, systempreferences, etc.) — their GNUmakefile / configure invocations	implicit -L/System/Library/Libraries via tools-make	inherits new search path automatically once tools-make is updated; no per-component change needed
ldconfig drop-in at /usr/local/libdata/ldconfig/freebsd-launchd	only lists /System/Library/Libraries	also list /usr/local/lib/system so runtime dlopen finds the libsystem_* binaries
pkg-config files	each .pc hardcodes /System/Library/Libraries	each libsystem_*.pc in /usr/local/libdata/pkgconfig/ hardcodes /usr/local/lib/system; gershwin's libdispatch.pc stays for fallback

The pattern for each consumer: pkg-config-driven where possible (pkg-config --libs libsystem_dispatch returns the right flags) plus ldconfig updates so runtime resolution works. Apps that link via the GNUstep build system inherit the new search path through tools-make; apps that build standalone use pkg-config.

Optional libSystem.so umbrella (mentioned in the libxpc plan §10): if we ever ship a single /usr/local/lib/system/libSystem.so that reexports all the libsystem_* libraries, consumers can just link -lSystem and get the whole Apple-userland surface in one symbol — closest to Apple's macOS link-line ergonomics. Ten-line linker script, deferrable until ergonomics matter.

Decision point: Phase 1 (symlinks only) is the right starting state — gives us the coordination without forcing gershwin-wide consumer changes. Phase 2 is a later cleanup, done if/when the symlink layer becomes operationally annoying. Many production projects stop at the symlink layer permanently.

17.6. Why /usr/local/lib/system/ (or /usr/lib/system/) is interesting

The new column added in this spike: instead of putting Apple-source libraries at /System/Library/Libraries/ (gershwin) or /usr/lib/ (base), put them under /usr/lib/system/ with Apple's macOS naming convention — libsystem_dispatch.so, libsystem_xpc.so, libsystem_kernel.so, libsystem_notify.so, libsystem_asl.so, libsystem_launch.so, libsystem_configuration.so.

This mimics Apple's /usr/lib/system/libsystem_*.dylib layout that existed on macOS before the Big-Sur dyld-shared-cache consolidation. Pros:

• Apple-aware tooling (DTrace probes, debuggers, profilers) that searches for libsystem_* finds the right files.
• Single namespace for "all the Apple-source userland libraries" via a single -L/usr/lib/system flag.
• Cleanly separates Apple-source from FreeBSD base (which is at plain /usr/lib/).
• Doesn't require a separate /System/Library/ hierarchy — lives within FreeBSD's standard /usr/lib.
• Matches Apple's actual macOS layout more closely than gershwin's /System/Library/Libraries/.
• An umbrella libSystem.so reexporting all of them (the optional umbrella mentioned in the libxpc plan §10) would naturally live alongside.

Cons:

• Diverges from gershwin's existing precedent. gershwin-developer's Install-System-Domain.sh installs libdispatch / libobjc2 / libgnustep-base / libgnustep-corebase to /System/Library/Libraries/. Switching to /usr/lib/system/ means coordinated path updates.
• The libsystem_ prefix on each filename is unusual for FreeBSD — sysadmins might not recognize "libsystem_xpc.so" as quickly as "libxpc.so."
• For libraries that don't have a clean "libsystem_" name (libobjc, libgnustep-base, libgnustep-corebase) we'd need a separate convention — mixing is ugly.

18. Recommendation

The /usr/lib/system/ path is a strong alternative — mimics Apple's actual macOS layout more closely than gershwin's /System/Library/Libraries/ does. If we ever revisit the project's overall path strategy (e.g. for pkgbase distribution), /usr/lib/system/ is the natural target. For now, the gershwin precedent wins on lower migration cost: our existing repos and build scripts already install to /System/Library/Libraries/.

If we revisited this decision later in the project's life:

Move	Migration cost	Benefit
Stay at gershwin layout (no change)	0	Status quo
Move to /usr/lib/system/	Medium — update gershwin-developer install scripts, freebsd-launchd build.sh, all consumer Makefiles. Possibly a coordinated gershwin patch.	Closer to Apple's layout; cleaner pkgbase migration story
Move to /usr/lib/ (flat base)	High — same as above plus framework-bundle teardown, header reorganization	Pkgbase-native

Last updated 2026-05-12. Per-component layout derived from grep over the local NextBSD, ravynOS, freebsd-launchd, freebsd-launchd-mach trees plus apple-oss-distributions repos for components not locally cloned (DiskArbitration, mDNSResponder, IPConfiguration / bootp). Apple paths verified against macOS SDK conventions; pre-Big-Sur paths preferred since FreeBSD has no dyld shared cache. Recommendations align with the project's existing freebsd-launchd build.sh and gershwin-developer Install-System-Domain.sh while documenting /usr/lib/system/ as a coherent alternative.