This document describes the C toolchain driver resolution order, Zig preference, and cross-platform packaging strategy.
pyscriptc compiles textual LLVM IR and bundles the C runtime into a native binary via an external C compiler driver (zig cc or clang).
- Zig (
zig cc) is the preferred compiler driver across all platforms (macOS, Linux, Windows).- Bundles per-target sysroots and headers for cross-compilation (
--target). - Supports Windows targets without requiring Visual Studio or external MinGW installations.
- Zig 0.13+ wraps Clang 18+, satisfying the LLVM 15+ opaque pointer requirement.
- Bundles per-target sysroots and headers for cross-compilation (
- Clang is the Unix host fallback when Zig is not installed on macOS or Linux.
Toolchain driver selection follows this precedence in src/pyscriptc/cli.py (_apply_env_defaults and _require_toolchain):
- Explicit CLI flag:
--driver zigor--driver clangalways wins. - Environment variable:
PYSC_CC(zigorclang). - Cross-compilation or Windows target: If
--targetorPYSC_TARGETis set -> preferszig(required for bundled sysroots). - Windows host: If
sys.platform == "win32"-> preferszig. - Sanitizer requested: If
--sanitizeorPYSC_SANITIZEis set -> prefersclang(zig cchas no linkable ASan/UBSan runtime). - Zig on PATH: If
shutil.which("zig")is found -> preferszig. - Clang fallback: If
shutil.which("clang")is found on macOS/Linux -> falls back toclang. - Missing toolchain: If neither is found when compiling to a binary (
--run,--emit bin,--emit obj,--emit asm), fails up-front with an actionable diagnostic pointing topyscriptc doctorand installation options.
Commands that do not compile binary machine code (such as --emit ir and --emit llvm) require no C toolchain.
Zig can be installed via standard system package managers or from PyPI:
- PyPI wheel (
ziglang):pip install ziglang # or using uv: uv tool install ziglangziglangrepackages upstream Zig binaries as platform wheels. Caveat: its console script ispython-zig, notzig, soshutil.which("zig")does not find it out of the box. The actual binary is atsite-packages/ziglang/zig; add that directory to PATH or symlink it aszigbefore pyscriptc can use it. - Homebrew (macOS / Linux):
brew install zig
- Windows Package Manager (winget):
winget install zig.zig
- Linux distributions:
Distro package managers (
apt install zig,pacman -S zig, etc.) or official binaries from ziglang.org.
pyscriptc doctor inspects the machine and reports:
- The preferred compiler driver (
preferred_driverin JSON,driver: <name> (preferred)in human-readable text). - Resolved paths and versions of both
clangandzig. - Target triple and toolchain driver for default compilation.