Zynx SDK

The Zynx SDK is an optional, Zig-like cross toolchain for current static executable targets. It is not required for normal host builds. Dynamic runtime-loadable modules remain host/system mode only.

The default Linux SDK libc is musl. Current default targets are:

x86_64-linux-musl
aarch64-linux-musl
riscv64-linux-musl

LLVM-libc targets are experimental extras selected with make sdk TARGET=<triple>:

x86_64-linux-llvm
aarch64-linux-llvm
riscv64-linux-llvm

Darwin SDK targets are overlay SDKs:

x86_64-darwin-macho
aarch64-darwin-macho

Darwin targets support provider-backed system stubs. DARWIN_SDK_PROVIDER accepts auto, xcode, zig, or portable. The default auto provider uses the bundled third_party/zig-darwin snapshot, which is copied from Zig 0.16.0 and carries Zig's MIT license notice in third_party/zig-darwin/LICENSE.zig.

xcode records an external Xcode or Command Line Tools SDK path. zig and portable copy Darwin headers, libSystem.tbd, libSystem.B.tbd, and SDKSettings.json into the target sysroot, making Linux-to-Darwin SDK archives self-contained for link-time headers and stubs.

make sdk
make sdk TARGET=x86_64-linux-musl
make sdk TARGET=x86_64-linux-llvm
make sdk TARGET=aarch64-darwin-macho
make sdk SDK_TARGETS="x86_64-darwin-macho aarch64-darwin-macho"
make sdk-clean TARGET=x86_64-linux-musl

Useful SDK build knobs:

make sdk SDK_PACKAGE=OFF
make sdk TARGET=aarch64-darwin-macho DARWIN_SDK_PROVIDER=portable
make sdk TARGET=aarch64-darwin-macho DARWIN_SDK_PROVIDER=xcode DARWIN_SDKROOT=/path/to/MacOSX.sdk
make sdk TARGET=aarch64-darwin-macho DARWIN_SDK_PROVIDER=zig DARWIN_ZIG=/path/to/zig
make sdk TARGET=aarch64-darwin-macho DARWIN_SDK_SOURCE=/path/to/darwin-sdk-source

Linux SDK sysroots contain Linux headers, CRT files, musl libc or LLVM-libc, compiler-rt builtins, libunwind, zlib, libzynx.a, libzxrt.a, and Zynx .zxm module headers. OpenSSL and libcurl are not part of the current SDK baseline.

SDK builds download pinned musl, LLVM, Linux kernel, and zlib source archives through CMake. Musl is the default libc; LLVM is still used for compiler-rt builtins, libunwind, and host tools.

Option	Default	Purpose
SDK_MUSL_VERSION	1.2.6	musl release for default Linux SDK targets.
SDK_LINUX_KERNEL_VERSION	6.12.9	Linux UAPI headers release.
SDK_ZLIB_VERSION	1.3.2	zlib release staged into SDK sysroots.
SDK_PACKAGE	ON	Write tar.gz archives for completed targets.
SDK_HOST	auto	Host id used for SDK layout and archive names.

Host tools are staged per host and target under hosts/<host>/targets/<triple>/bin. By default, make sdk also writes distributable archives:

build/sdk/hosts/<host>/targets/<triple>/
build/sdk/archives/zynx-sdk-<host>-to-<triple>.tar.gz

<host> is the machine that can run the staged tools, for example x86_64-linux, aarch64-linux, x86_64-darwin, or aarch64-darwin. Current SDKs stage only the target linker (ld.lld or ld64.lld) and llvm-strip; heavier inspection tools such as llvm-nm, llvm-objdump, llvm-readobj, and llvm-objcopy are left to the host toolchain. Archives contain hosts/<host>/targets/<triple>/... and can be installed directly with zynx sdk install.

Darwin SDK tool discovery accepts versioned LLVM tool names such as ld64.lld-18; if only generic lld is found, it is staged as ld64.lld so LLD selects the Darwin driver from its executable name.

./zynx sdk list
./zynx sdk list --all-hosts
./zynx sdk path --target x86_64-linux-musl
./zynx sdk path --host x86_64-linux --target x86_64-linux-musl
./zynx sdk doctor --target x86_64-linux-musl
./zynx sdk doctor --host x86_64-linux --target x86_64-linux-musl
./zynx sdk install build/sdk/archives/zynx-sdk-x86_64-linux-to-x86_64-linux-musl.tar.gz

zynx sdk install installs a local archive. Network downloads and a prebuilt SDK registry are intentionally deferred.

When an installed zynx is launched from PATH, SDK discovery derives the install prefix from the actual executable path. For example, /usr/local/bin/zynx automatically sees /usr/local/share/zynx/sdk, and zynx sdk install <archive> defaults to that same installed SDK root. Installed SDK bin/ directories preserve executable permissions, so tools such as ld64.lld remain runnable after make install.

make uninstall removes installed SDKs from <prefix>/share/zynx/sdk, matching what make install installs.

./zynx --target x86_64-linux-musl main.zx -o app
./zynx --target aarch64-linux-musl --sdk /path/to/sdk main.zx -o app
./zynx --target aarch64-darwin-macho --sdk /path/to/sdk main.zx -o app

For *-linux-musl and *-linux-llvm, the compiler automatically uses the SDK ld.lld, SDK sysroot, and SDK module headers. It avoids host /usr/lib, glibc/GCC CRT discovery, and -lgcc.

The experimental *-linux-llvm targets use LLVM-libc and compile the SDK runtime with limited pthread/network fallbacks because LLVM-libc does not yet provide the full POSIX surface used by the host runtime.

For *-darwin-macho, the compiler automatically uses SDK ld64.lld, the Zynx overlay sysroot, the recorded Darwin system sysroot through -syslibroot, -platform_version macos, and -lSystem. libSystem.tbd is a link-time stub; runtime libSystem still comes from macOS. Fully static Darwin executables are not supported.

SDK discovery order:

1. --sdk <path>
2. ZYNX_SDK
3. in-tree build/sdk
4. installed <prefix>/share/zynx/sdk
5. ~/.local/share/zynx/sdk