vdm/docs/08-porting.md

08 — Porting guide (macOS first, Windows later)

Read docs/adr/0020-cross-platform-strategy.md first; this file is the concrete inventory it refers to. Rule: Linux behaviour never changes. #ifdef never appears in logic.

Directory layout

Platform backends live beside the code they serve, one directory per OS:

core/src/io/platform/linux/file_ops.cpp        core/src/io/platform/macos/file_ops.cpp
core/src/io/platform/file_ops.hpp              # the seam — no #ifdef, no OS types
daemon/src/rpc/platform/linux/{wakeup,peercred,instance_lock,runtime_dir}.cpp
daemon/src/rpc/platform/macos/{...}.cpp
daemon/src/rpc/platform/*.hpp                  # the seams
cmake/platform.cmake                           # VELOX_OS_* + source selection

cmake/platform.cmake sets exactly one of VELOX_OS_LINUX, VELOX_OS_MACOS, VELOX_OS_WINDOWS, and exposes velox_platform_sources(<target> <dir>) which adds <dir>/platform/<os>/*.cpp. Selection happens there and nowhere else.

The seams

Five interfaces cover the whole port. Signatures are indicative, not binding — the owning lane settles them in Phase 0.

Seam	Interface	Why
File preallocation	Result<void> preallocate(int fd, uint64_t bytes)	posix_fallocate is Linux/glibc
Cache advice	void advise_dontneed(int fd, uint64_t off, uint64_t len)	posix_fadvise has no macOS equivalent
Durable flush	Result<void> flush_durable(int fd)	fdatasync vs F_FULLFSYNC
Loop wakeup	class Wakeup { int pollfd(); void signal(); void drain(); }	eventfd is Linux-only
Peer identity	Result<PeerId> peer_of(int fd)	SO_PEERCRED vs LOCAL_PEERCRED
Single instance	Result<Lock> acquire(string_view runtime_dir)	abstract sockets are Linux-only
Runtime dir	string runtime_dir(), string data_dir()	XDG vs ~/Library

API mapping

Linux (today)	macOS	Windows (later)	Note
posix_fallocate(fd,0,n)	fcntl(F_PREALLOCATE) then ftruncate(n)	SetFileValidData / SetEndOfFile	macOS needs the ftruncate; F_PREALLOCATE alone does not set size. Fall back to ftruncate on failure, exactly as the Linux path already does for EOPNOTSUPP
posix_fadvise(DONTNEED)	no equivalent — no-op	FILE_FLAG_NO_BUFFERING	Do not substitute F_NOCACHE: it changes caching for the whole descriptor, not a written range. A no-op is honest; record it
fdatasync(fd)	fcntl(fd, F_FULLFSYNC), fall back to fsync	FlushFileBuffers	fsync on macOS does not guarantee the drive flushed. .veloxpart resume integrity depends on this — use F_FULLFSYNC
pwrite	same	WriteFile + OVERLAPPED	POSIX, no work
O_NOFOLLOW	same	FILE_FLAG_OPEN_REPARSE_POINT	POSIX, no work
eventfd	self-pipe (pipe2/`O_NONBLOCK	O_CLOEXEC`)	event object
timerfd	poll() timeout computed from the next deadline	waitable timer	Simplest port: the loop already has a deadline set
SO_PEERCRED + struct ucred	getpeereid(fd,&uid,&gid)	named-pipe token	Same-UID check is the security property; keep it
abstract socket \0velox-daemon-<hash>	socket file in the runtime dir + `flock(LOCK_EX	LOCK_NB)`	named mutex
$XDG_RUNTIME_DIR	$TMPDIR (per-user, already private)	%LOCALAPPDATA%	macOS has no XDG runtime dir
$XDG_DATA_HOME	~/Library/Application Support/Velox	%APPDATA%
libsecret / Secret Service	Keychain (Security.framework)	DPAPI / Credential Manager	Behind the credential-store seam. CLAUDE.md §4 still applies: never SQLite, never logs
systemd user units	launchd plist (~/Library/LaunchAgents)	Service/Task Scheduler	Phase 3

Build dependencies

Ubuntu	macOS (Homebrew)
qt6-base-dev, qt6-svg-dev, qt6-tools-dev	qt@6
libcurl4-openssl-dev	system libcurl, or curl
libsqlite3-dev	system sqlite, or sqlite
libssl-dev	openssl@3 (set OPENSSL_ROOT_DIR)
libsecret-1-dev	none — Keychain is in the SDK
nlohmann-json3-dev	nlohmann-json
nodejs, npm	node

The root CMakeLists.txt currently does pkg_check_modules(LIBSECRET REQUIRED ...) unconditionally. That must become Linux-only, or macOS cannot configure at all. It is the single hard blocker for a first macOS build.

What does not change

contracts/ and both generated clients, tools/mockd, tests/conformance, tools/testserver, the whole extension, and every hostile-mode expectation. If a port tempts you to change a fixture or a schema, stop — that is a contract change and it goes through PROTO.

Verification gates

• Phase 0 done: Ubuntu suite still 57/57, and git diff shows only moves behind seams.
• Phase 1 done: veloxd, velox, libveloxcore build on macOS; core unit tests pass.
• Phase 2 done: conformance (mockd and live veloxd) and the engine hostile-mode matrix pass on macOS; one real download completes with a matching SHA-256.
• Phase 3 done: .dmg or Homebrew formula installs and runs on a clean machine.