calog/PORTING.md

Porting calog

calog targets Linux, macOS, and Windows. Its core -- values, broker, the actor/threading model, and every engine adapter -- is portable C11. The only operating-system-specific surface is small and centralized:

• Threads: POSIX pthreads. Native on Linux and macOS; on Windows via mingw-w64's winpthreads.
• Sockets + DNS: BSD sockets + getaddrinfo, used only by the net/ssh/http libraries. BSD sockets on Linux/macOS, Winsock on Windows. All of this is behind src/calogPlatform.h.

There is no epoll/eventfd/kqueue, no fork/exec, and no dlopen in calog's own code (the actor model uses blocking sockets on per-context threads), so a port is a thin shim, not a rewrite.

The platform abstraction: src/calogPlatform.h

The net/ssh/http libraries use these instead of raw socket calls, so the same source compiles on all three platforms:

Abstraction	POSIX (Linux/macOS)	Windows
CalogSocketT	int	SOCKET
CALOG_INVALID_SOCKET	-1	INVALID_SOCKET
calogSockClose(fd)	close	closesocket
calogSockErrno() / calogSockErrStr()	errno / strerror	WSAGetLastError / FormatMessage
calogSockSetNonblock(fd, on)	fcntl(O_NONBLOCK)	ioctlsocket(FIONBIO)
calogSockInProgress(err)	EINPROGRESS	WSAEWOULDBLOCK/WSAEINPROGRESS
calogPoll(...)	poll	WSAPoll
calogPlatformNetInit() / Shutdown()	no-op	WSAStartup / WSACleanup
CALOG_MSG_NOSIGNAL	MSG_NOSIGNAL	0 (Windows has no SIGPIPE)

A socket fd is unsigned on Windows, so the code compares against CALOG_INVALID_SOCKET (never fd < 0). The abstraction is behavior-identical on POSIX (it maps to the same names), so the Linux and macOS builds are unchanged by it.

Build matrix

Target	Command	Runtime dependencies	DNS
Linux dev	make	glibc, libstdc++, libgcc, ASan/UBSan (dev only)	yes
Linux release	make release	glibc only (libstdc++/libgcc linked static)	yes
Linux static	make static on Alpine/musl	none (fully static)	yes (musl resolver)
Linux static	make static on glibc	none, but see caveat	no (glibc NSS needs dlopen)
macOS	make (Darwin auto-detected)	libSystem (always present)	yes
Windows	mingw-w64 build	core OS DLLs (kernel32, ws2_32)	yes

The Makefile auto-detects the platform (PLATFORM = linux/darwin/windows/posix) and adjusts the link line: DLLIB is -ldl on Linux (empty on macOS, where dlopen is in libSystem) and SOCKETLIBS is -lws2_32 on Windows.

Linux

• make -- the sanitized development build (ASan + UBSan + strict warnings).
• make release -- the distribution build: sanitizers off, -static-libstdc++ -static-libgcc, glibc dynamic. ldd collapses to just libc/libm + the loader. Because glibc stays dynamic, getaddrinfo can still dlopen its NSS modules, so DNS works. Runs on any mainstream glibc distro with nothing to install.
• make static on Alpine (musl) -- a fully static binary with zero runtime dependencies and working DNS (musl has a built-in resolver, no NSS/dlopen). This is the minimal-dependency artifact. Because calog builds every dependency from source, and Alpine's default toolchain is musl, no per-dependency changes are needed -- build it in an Alpine container.
• make static on glibc -- fully static, but name resolution and dlopen-based Lua C modules do not work (glibc NSS requires runtime dlopen). Connect by IP, or use the musl route above.

macOS (Darwin)

The C is already POSIX-compatible (pthreads, BSD sockets, getaddrinfo are all native), so the port is build configuration, not code -- confirmed by tools/crossBuild.sh, which links valid Mach-O executables for both x86_64 (Intel) and arm64 (Apple Silicon) using zig's bundled libSystem stub (calog only needs libSystem -- libc/pthreads/sockets -- so no Apple SDK/frameworks are required for the core). Apple does not support statically linking libc, but libSystem is part of the OS and always present, so "static everything except libSystem" is the natural minimal-deps build. Each vendored dependency builds its own way and needs a macOS configuration:

• OpenSSL: ./Configure darwin64-<arch>-cc
• Tcl: its configure detects Darwin
• mruby / Lua / SQLite / ENet / QuickJS / Squirrel / Berry / s7 / Wren: compile as-is with clang
• libssh2 / MariaDB: CMake with the macOS toolchain

Link against dynamic libSystem (the default); -ldl is dropped automatically (DLLIB is empty on Darwin) and the C++ runtime is libc++ (CXXLIB = -lc++). SIGPIPE is ignored at CLI startup, since macOS send() has no MSG_NOSIGNAL. ENet's unix.c backend is correct on macOS (BSD sockets).

Windows (mingw-w64)

calog's pthread code compiles unchanged on Windows against winpthreads (POSIX threads over the Win32 API), which is vendored at vendor/winpthreads/ and built from source like every other dependency (see its NOTICE.calog). src/calogPlatform.h handles the Winsock differences. Building uses a mingw-w64 toolchain (not MSVC) for its POSIX-ish environment; tools/crossBuild.sh cross- compiles from Linux with a single zig toolchain and is the tested path. Remaining work is build configuration:

• Build each vendored dependency for mingw (OpenSSL mingw64, Tcl's win/ makefile or configure, libssh2/MariaDB via CMake with the mingw toolchain, mruby with a mingw build_config).
• ENet selects its win32.c backend automatically (ENETBACKEND); the link adds -lws2_32 -lwinmm (handled by SOCKETLIBS).
• Static-link the runtime (-static -static-libgcc -static-libstdc++) so the binary depends only on core Windows DLLs, which are always present. DNS works through Winsock's getaddrinfo.

Remaining code review for Windows: calogFs.c and calogHttp.c use POSIX headers (dirent.h, sys/stat.h, sys/time.h) that mingw-w64 mostly provides, but path handling (/ vs \) and a few calls may need adjustment; calogSsh.c already guards sys/select.h (Winsock supplies fd_set/select), and httpSetTimeouts already branches on the Winsock SO_RCVTIMEO DWORD form.

Cross-compiling from Linux with zig (tools/crossBuild.sh)

A single zig toolchain cross-compiles C and C++ to musl-static and Windows without installing per-target toolchains, so the ports can be exercised on a plain Linux box:

ZIG=/path/to/zig ./tools/crossBuild.sh

It builds a representative set -- core + one engine of each kind (Lua, QuickJS, Squirrel/C++, my-basic) + the socket library (calogNet) -- because the crypto/db/http/ssh libraries pull in OpenSSL/MariaDB/PostgreSQL/libssh2, each needing its own per-target build. What it does:

• musl: fully static Linux binaries. These run on the build host, so the script builds AND runs them -- verifying the core, all four engine kinds, C++, and the socket abstraction on musl.
• Windows: builds vendor/winpthreads into libwinpthreads.a, then links real .exes (including the Winsock + ENet-win32 socket path). Verified as valid PE executables; running them needs wine.

Verified results (this repo): musl -- Lua, QuickJS, my-basic, Squirrel, and testNet all build and pass (fully static); Windows -- testEngineLua.exe and testNet.exe build against vendored winpthreads. Since the Windows binaries are the same source that passes on musl, the build is strong evidence; full run-verification needs a Windows host or wine.

Cross-compiling the archive stack with zig (tools/crossArchive.sh)

The compression/archive library (libarchive + its five codecs: zlib, bzip2, lz4, zstd, xz/liblzma) is the one vendored stack that leans on CMake, so it gets its own cross-build script. Same idea as crossBuild.sh, same single zig toolchain:

ZIG=/path/to/zig ./tools/crossArchive.sh

It builds all five codecs plus libarchive for musl (fully static, RUN on the host) and Windows x64 (a testArchive.exe verified as a PE), driving each through calog's real testArchive (compress/decompress round-trips through every codec). CMake cross-compilation with zig works by wrapping zig cc as a single-binary compiler (build/cross/bin/zcc-*) plus a toolchain file. The key asymmetry:

• musl toolchain does NOT set CMAKE_SYSTEM_NAME. A musl-static binary runs on this Linux host, so the build stays "native" (CMAKE_CROSSCOMPILING false) and CMake's try_run feature-detection executes normally. zig supplies its own musl sysroot, so no host headers leak in.
• Windows toolchain sets CMAKE_SYSTEM_NAME Windows -> cross mode. libarchive's single CHECK_C_SOURCE_RUNS is already guarded on CMAKE_CROSSCOMPILING (it degrades to a warning) and xz has no run-checks, so nothing needs pre-seeding.

Two target-specific gotchas the script handles:

• zlib on musl needs -DHAVE_UNISTD_H so it includes <unistd.h> for lseek. zlib's ./configure normally sets this; the object-rule build (no configure) must pass it, and musl -- unlike glibc -- does not declare lseek without the include. Only zlib is affected.
• libarchive on Windows pulls in system libraries the POSIX build does not: CNG crypto (-lbcrypt) for its AES/PBKDF2, and XmlLite + OLE (-lxmllite -lole32) for XAR, which libarchive auto-substitutes for the libxml2/expat we disable. The link adds -lbcrypt -lxmllite -lole32 -ladvapi32 -lcrypt32 -lshlwapi.

Everything lands under build/cross/ (gitignored); the vendored sources and the native vendor/*/build / _cmk trees the normal make uses are never touched.

Status

• Platform abstraction (calogPlatform.h) and the net/ssh/http conversion: done, verified behavior-identical on Linux (make test 30/30, socket + HTTP loopback smoke, ASan- and TSan-clean).
• Linux release target: done and verified -- ldd bin/calog shows only libc/libm + loader.
• Linux musl-static: run-verified via tools/crossBuild.sh (zig) -- core + Lua + QuickJS + my-basic + Squirrel + testNet all build fully static and pass on the host. Also works via make static in an Alpine container (musl default toolchain).
• Windows: build-verified via tools/crossBuild.sh -- testEngineLua.exe and testNet.exe (core + engine + Winsock socket abstraction) link against vendored winpthreads into real PE executables. Run-verification needs a Windows host or wine; the binaries are the same source that passes on musl.
• Build system: OS-aware (PLATFORM, DLLIB, CXXLIB, SOCKETLIBS, ENETBACKEND, vendored winpthreads); the Linux values are identical to before, so the dev build is unchanged.
• macOS: build-verified via tools/crossBuild.sh -- core + Lua + testNet link into valid Mach-O executables for both x86_64 and arm64 (zig's libSystem stub; no Apple SDK needed for calog's libc surface). Run-verification needs a Mac. The C code and Makefile hooks are all in place (libc++, no -ldl, SIGPIPE, native pthreads + BSD sockets).
• Archive stack (libarchive + zlib/bzip2/lz4/zstd/xz): musl run-verified, Windows build-verified via tools/crossArchive.sh (zig). The musl testArchive is fully static and passes all 22 checks on the host -- real compress/decompress through every codec and an xar read+write round-trip: the musl target now cross-builds OpenSSL (xar's MD5/SHA1) and libxml2 (its XML TOC), with iconv coming from musl's own libc, so its libarchive has full xar. The Windows build is a valid testArchive.exe (PE32+) linked against vendored winpthreads + the CNG/XmlLite system libs. This was the one CMake-heavy vendored stack, so it is the strongest cross-build evidence after the core. On Windows, xar needs no vendored XML/crypto/iconv at all: libarchive auto-uses the system XmlLite (its TOC) + CNG/bcrypt (its MD5/SHA1), both in the mingw sysroot, so the Windows testArchive.exe already has full xar. One musl gotcha worth noting: libarchive's FIND_PATH(iconv.h) returns the host /usr/include (glibc), whose headers break the musl compile, so the script pins ICONV_INCLUDE_DIR to an empty dir and lets zig cc resolve musl's own iconv.h implicitly.
• Full Windows CLI cross-built (build-verified). Every heavy vendored dependency now cross-compiles for x86_64-windows-gnu via zig -- OpenSSL, libxml2, PCRE2, libssh2, MariaDB, and the three hard ones PostgreSQL/libpq, Tcl, mruby (libpq needed a patched out-of-tree copy; see tools/crossWinFull.sh). The complete calog.exe links all 10 engines + all 20 libraries into a valid PE32+ that imports only Windows system DLLs (no vendored DLLs). Behavior-neutral #ifdef _WIN32 guards in calog's own source cover the small OS differences -- calogFs (mingw 1-arg mkdir, O_BINARY), calogHttp (no SIGPIPE), calogInternal (a memmem fallback), calogPlatform (__declspec(thread) -> _Thread_local, which also fixes a latent Windows thread-safety bug clang had been silently dropping), and calogNet (SO_EXCLUSIVEADDRUSE for listeners instead of the hijack-prone SO_REUSEADDR). Two libraries have a full Windows backend rather than a POSIX one: procRun spawns with CreateProcess + pipes (stdin fed on a helper thread while stdout/stderr drain, since anonymous pipes have no poll), and the HTTPS client reads trust anchors from the Windows ROOT/CA system certificate stores via CryptoAPI (CertOpenSystemStore) instead of a Unix CA-bundle path. All are behavior-neutral off Windows; the Linux suite stays green. Run-verification still needs a Windows host or wine.
• Full macOS CLI cross-built for both archs (build-verified). Every heavy vendored dependency now cross-compiles for x86_64-apple-darwin and arm64-apple-darwin via zig, whose libSystem stub supplies libc / pthreads / BSD sockets / getaddrinfo / dlopen / iconv -- so no Apple SDK is needed for calog's OS surface (see tools/crossMacFull.sh). The complete calog links all 10 engines + all 20 libraries into a valid Mach-O per arch (build/cross/mac-x64/calog x86_64, build/cross/mac-arm64/calog arm64), importing only libSystem -- no vendored dylibs, no -ldl. Two additive #if defined(__APPLE__) guards are in calog's own source: calogTimer waits with a relative pthread_cond_timedwait_relative_np timeout on Darwin, because macOS pthreads have no pthread_condattr_setclock to pin the condvar to CLOCK_MONOTONIC (the relative wait preserves the monotonic scheduling intent across wall-clock changes); and calogHttp's HTTPS client reads trust anchors from the macOS keychain via the Security framework (SecTrustCopyAnchorCertificates). Both are behavior-neutral off Darwin, and the Linux suite stays green. Run-verification still needs a Mac.
• macOS Keychain HTTPS trust needs the Apple SDK (optional). calog's OS surface (libc / pthreads / BSD sockets / getaddrinfo / dlopen / iconv) is all in zig's libSystem stub, so the runner needs no SDK. But the keychain trust path uses the Security + CoreFoundation frameworks, whose headers zig does not ship. When an SDK is present, tools/crossMacFull.sh compiles calogHttp with -DCALOG_MAC_KEYCHAIN_TRUST against the SDK framework headers; without one it omits keychain trust and HTTPS falls back to SSL_CERT_FILE / CALOG_CA_BUNDLE. Point CALOG_MACSDK at a MacOSX*.sdk directory to enable it. Linker gotcha: zig 0.16's Mach-O linker segfaults parsing the real multi-target SDK .tbd files, so calog links against hand-written minimal stubs (tools/macStubs/{CoreFoundation,Security}.tbd) that export only the handful of symbols the keychain code calls -- the binary still imports the real system frameworks by install-name at runtime. Both arch binaries are valid Mach-O importing Security.framework + CoreFoundation.framework (build-verified; run-verification still needs a Mac).
• Reproducible dependency builds (tools/crossDeps.sh). The full-CLI scripts above consume heavy pinned deps under build/cross/<target>/; crossDeps.sh rebuilds them from vendor/ source with a single zig toolchain, so the cross build is reproducible from a clean checkout rather than depending on ad-hoc pins. Usage: [ZIG=/path/to/zig] ./tools/crossDeps.sh <win|mac-x64|mac-arm64> [dep ...] (it regenerates the zig wrappers + CMake toolchain file first, so nothing under build/cross/ need pre-exist). It builds, in dependency order: the codecs (zlib/bzip2/lz4/zstd), xz, OpenSSL (mac also gets a BSD-ar repack, since zig's Mach-O linker cannot read OpenSSL's GNU-ar archives), libxml2, PCRE2, libssh2, MariaDB, PostgreSQL/libpq (the patched out-of-tree copy: mingw .obj->.o, a real ar rule for libpq.a, and pg_pthread_* symbol localization on Windows; libSystem pthreads and no patch on mac), Tcl, mruby, winpthreads (Windows only), and libarchive (mac = xar via the pinned OpenSSL+libxml2; Windows = codecs only, xar via system XmlLite/CNG). VERIFIED build-clean from vendor source for ALL THREE targets, all 12 deps (OUT= builds into a scratch dir without clobbering the pins): mac-x64 and mac-arm64 each build the full set in one clean invocation (OpenSSL confirmed Mach-O + !<arch> BSD repack); win builds the full set including the mingw-only bits -- winpthreads, the patched libpq (.obj->.o, real ar rule, pg_pthread_* localization, plus the Windows syslibs -lws2_32 -lcrypt32 -lsecur32 -lbcrypt ... so configure's -lcrypto link test passes), and the two .rc resources (libxml2's + libpq's win32ver.rc) compiled via a zig rc windres shim that handles both CMake's positional args and PostgreSQL's -i/-o/--include-dir form. The win CMake toolchain sets CMAKE_RC_COMPILER to that shim.
• Tcl re-vendored to close the last gap (2026-07-06). vendor/tcl had been trimmed to the native unix/linux build set (no win/, no macosx/), so cross-Tcl could not build from vendored source. The official tcl9.0.4 win/ + macosx/ subdirs are now restored, so all three ports build Tcl from vendor/; the native Linux build is unchanged (still testEngineTcl 13/0). All ports now match.