Bundled libraries

Active contributors: andrewrk, alexrp, mlugg

Purpose

zig ships its own copies of the C runtime, C++ runtime, and unwinder sources for every supported platform so that zig cc, zig c++, and zig build-exe -target ... work as turnkey cross-compilers without an external toolchain. This page is a map of those bundled trees.

Directory layout

lib/
├── libc/
│   ├── glibc/      # glibc sources (bundled)
│   ├── musl/       # musl sources
│   ├── mingw/      # mingw-w64 sources
│   ├── wasi/       # wasi-libc stubs
│   ├── darwin/     # macOS/iOS libc shim + headers
│   ├── freebsd/    # FreeBSD libc + headers
│   ├── netbsd/     # NetBSD libc + headers
│   └── include/    # POSIX headers usable by multiple flavors
├── libcxx/         # libc++ sources (LLVM's)
├── libcxxabi/      # libc++abi sources
├── libunwind/      # libunwind sources
├── libtsan/        # ThreadSanitizer runtime sources
├── include/        # Clang resource headers (stdarg.h, intrinsics, ...)
├── compiler_rt/    # pure-Zig compiler-rt (see Compiler runtime)
└── compiler_rt.zig

Why both lib/libc/<flavor>/ and lib/libc/include/?

• lib/libc/<flavor>/ carries the flavor-specific sources and headers (glibc startup files, musl crt, wasi-libc stubs). These are compiled or linked into final binaries when the user targets that ABI.
• lib/libc/include/ carries POSIX headers that can be reused across flavors so multiple targets share a single copy.

Selection happens in src/Compilation.zig and lib/std/zig/LibCDirs.zig via the resolved Target.Os.Tag and Target.Abi.

libcxx / libcxxabi / libunwind / libtsan

These mirror the upstream LLVM project sources. When a user compiles C++ with zig c++ (or sets link_libcpp = true on a Module), the relevant subset is compiled and linked. -Duse-zig-libcxx in build.zig forces the use of these bundled versions even when an external libc++ is available.

Clang resource headers

lib/include/ is what zig cc points clang at as its "resource directory" — it carries the SIMD intrinsic headers, stdarg.h, stdatomic.h, __clang_* headers, and the assorted internal headers clang expects to find. These are taken from the matching LLVM release, and the version is pinned by the LLVM dependency in CMakeLists.txt.

How they are kept up to date

tools/ carries the maintenance scripts:

• tools/update_glibc.zig
• tools/update_mingw.zig
• tools/update_freebsd_libc.zig
• tools/update_netbsd_libc.zig
• tools/update-linux-headers.zig
• tools/process_headers.zig
• tools/fetch_them_macos_headers.zig, tools/macos-headers.c, tools/gen_macos_headers_c.zig

Run them with a working zig to regenerate the bundled trees from upstream releases.

Integration points

• zig cc / zig c++. src/Compilation.zig sets up the include paths to point at lib/libc/<flavor>/, lib/libc/include/, and lib/include/.
• zig build-exe -target .... Same path: the resolved target picks a libc flavor.
• Cross-compilation tests. test/c_abi/ and test/standalone/ exercise these paths.
• lib/std/zig/LibCInstallation.zig. Detects an installed system libc and produces the search-path record consumed by Compilation.

Key source files

File	Purpose
lib/libc/include/...	Cross-flavor POSIX headers.
lib/libc/<flavor>/...	Per-flavor libc sources/headers.
lib/libcxx/...	libc++ sources.
lib/libcxxabi/...	libc++abi sources.
lib/libunwind/...	libunwind sources.
lib/libtsan/...	TSan runtime.
lib/include/...	Clang resource headers.
lib/std/zig/LibCDirs.zig	Path resolution for the bundled libcs.
lib/std/zig/LibCInstallation.zig	System libc detection.
tools/update_*.zig	Maintenance scripts.