Zynx SDK

The Zynx SDK is an opt-in, Zig-like cross toolchain for static Linux targets and Darwin overlays. Native builds do not need an SDK; use this page when you need SDK archives, --target, or zynx sdk management commands.

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

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

The musl ABI means the target uses the Zynx SDK sysroot with musl libc, compiler-rt builtins, libunwind, zlib, libzxrt.a, and Zynx standard library sources under lib/zynx/std. OpenSSL and libcurl are not part of the current baseline. LLVM-libc targets remain available as experimental extras:

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

Current SDK targets are static executable targets. Dynamic runtime module loading is host/system mode only. The experimental *-linux-llvm targets use LLVM-libc and compile the SDK runtime with limited pthread/network fallbacks because the current LLVM-libc SDK surface does not provide the full POSIX surface Zynx's host runtime uses.

Host Requirements

Default Linux SDK packaging is Linux-host-only. The Linux sysroot build installs Linux UAPI headers, and the kernel header tooling expects ELF host headers such as elf.h. On Darwin, default make sdk fails early with a direct diagnostic instead of reaching the Linux header build. Run SDK packaging validation on Linux CI or inside a Linux container.

Explicit Darwin SDK target builds remain separate overlays and are not a substitute for validating the default Linux SDK targets.

Quick Path

On a Linux host, build and inspect one static Linux SDK target:

make sdk TARGET=x86_64-linux-musl
./zynx sdk doctor --target x86_64-linux-musl

Install the archive into the active SDK root:

./zynx sdk install build/sdk/archives/zynx-sdk-x86_64-linux-musl.tar.gz

Compile with that target:

./zynx --target x86_64-linux-musl main.zx -o app

Use --sdk /path/to/sdk when you need to point the compiler at a specific SDK tree instead of relying on discovery.

Darwin Targets

Darwin SDK targets are separate overlays:

x86_64-darwin-macho
aarch64-darwin-macho

They are built with:

make sdk TARGET=aarch64-darwin-macho
make sdk SDK_TARGETS="x86_64-darwin-macho aarch64-darwin-macho"

Darwin SDK targets use a provider selected by DARWIN_SDK_PROVIDER. auto defaults to the bundled third_party/zig-darwin snapshot, so Linux-to-Darwin SDK archives do not require Xcode or Zig to be installed. portable copies from DARWIN_SDK_SOURCE, which can point at the bundled Zig Darwin subset, a Zig lib dir, Zig libc dir, Zig libc/darwin dir, or Apple SDK root. zig discovers an installed Zig and copies its Darwin libc surface. xcode records an external DARWIN_SDKROOT path, preserving the older macOS-only behavior.

The bundled and Zig providers copy usr/include, usr/lib/libSystem.tbd, usr/lib/libSystem.B.tbd, and SDKSettings.json into the target sysroot. This makes archives self-contained for link-time Darwin headers and stubs while still relying on the target macOS system libSystem at runtime.

Build SDKs

Build all default SDK targets:

make sdk

Build or remove one target:

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

Build an explicit target family:

make sdk SDK_TARGETS="x86_64-linux-llvm aarch64-linux-llvm riscv64-linux-llvm"
make sdk SDK_TARGETS="x86_64-darwin-macho aarch64-darwin-macho"

Common build knobs:

Option	Meaning
TARGET=<triple>	Build one SDK target.
SDK_TARGETS="..."	Build an explicit target list.
SDK_PACKAGE=OFF	Skip archive creation during local rebuilds.
SDK_JOBS=<n>	Set the parallel job count for SDK dependency builds.
DARWIN_SDK_PROVIDER=<mode>	Select auto, portable, zig, or xcode for Darwin overlays.

SDK Layout

The SDK layout is:

build/sdk/targets/<triple>/sdk.json
build/sdk/targets/<triple>/sysroot/
build/sdk/archives/zynx-sdk-<triple>.tar.gz

Linux target sysroots contain target headers, CRT files, static libraries, and Zynx standard library sources under lib/zynx. Darwin target sysroots are overlays for Zynx-owned archives and standard library sources. With the zig or portable Darwin providers, the same sysroot also contains the copied Darwin headers and libSystem.tbd stubs, so sdk.json records system_sysroot: "sysroot" and the archive can be used on Linux hosts without Xcode. The SDK does not package linker or strip binaries; SDK links use the compiler's built-in LLD frontend.

By default, make sdk packages every completed target into build/sdk/archives/zynx-sdk-<triple>.tar.gz. The archive contains targets/<triple>/..., so it can be installed directly with zynx sdk install. Set SDK_PACKAGE=OFF to skip archive creation during local rebuilds.

Source Pins

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 and libunwind. The SDK builder also installs Linux kernel API headers for each target architecture.

The SDK Linux headers pin defaults to SDK_LINUX_KERNEL_VERSION=6.12.9 using the official cdn.kernel.org tar.xz archive. Override SDK_LINUX_KERNEL_VERSION, SDK_LINUX_SOURCE_URL, and SDK_LINUX_SOURCE_SHA256 if you need to test a different kernel header release.

The SDK zlib pin defaults to SDK_ZLIB_VERSION=1.3.2 using the official zlib.net/fossils tar.gz archive. Override SDK_ZLIB_VERSION, SDK_ZLIB_SOURCE_URL, and SDK_ZLIB_SOURCE_SHA256 if you need to test a different zlib release.

The SDK musl pin defaults to SDK_MUSL_VERSION=1.2.6 using the official musl.libc.org/releases tar.gz archive. Override SDK_MUSL_VERSION, SDK_MUSL_SOURCE_URL, and SDK_MUSL_SOURCE_SHA256 if you need to test a different musl release.

Use An SDK

Use an SDK target from the compiler:

./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

SDK discovery order is:

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

When zynx is launched by name from PATH, <prefix> is derived from the actual executable path. For example, /usr/local/bin/zynx discovers /usr/local/share/zynx/sdk without needing --sdk or ZYNX_SDK.

For *-linux-musl and *-linux-llvm, Zynx automatically uses the SDK sysroot, SDK module path, and built-in LLD ELF frontend. The link is static-only in the current language and deliberately avoids host /usr/lib, GCC runtime libraries, and glibc-style CRT discovery.

For *-darwin-macho, Zynx uses the SDK overlay for Zynx archives and modules, the recorded Darwin system sysroot for headers/system stubs, and the built-in LLD Mach-O frontend. Fully static Darwin executables are not supported because libSystem is provided by the platform; libSystem.tbd is only a link-time stub.

Manage SDKs

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

zynx sdk install extracts a local archive into the SDK root. Network downloads and a prebuilt SDK registry are not part of the current SDK tooling. When an installed zynx is launched from PATH, sdk install defaults to the same installed SDK root, for example /usr/local/share/zynx/sdk.

Next Steps

• Use the Build Reference for make targets in the broader build workflow.
• Use the Install Guide for the shortest SDK command list.