1# Zig GNU C Library ("glibc") Support
2
3Zig supports building binaries that will dynamically link against the
4[GNU C Library ("glibc")](https://www.gnu.org/software/libc/) when run.
5This support extends across a range of glibc versions.
6
7By default, Zig binaries will not depend on any external C library, but
8they can be linked against one with the `-lc` option. The target ABI defines
9which C library: `musl` for the [musl C library](https://musl.libc.org/) or
10`gnu` for the GNU C library.
11
12A specific GNU C library version can be chosen with an appropriate
13`-target`. For example, `-target native-native-gnu.2.19` will use the
14default CPU and OS targets, but will link in a run-time dependency on
15glibc v2.19 (or later). Use `zig env` to show the default target and
16version.
17
18Glibc symbols are defined in the `std.c.` namespace in Zig, though the
19`std.os.` namespace is generally what should be used to access C-library
20APIs in Zig code (it is defined depending on the linked C library).
21
22See `src/glibc.zig` for how Zig will build the glibc components. The
23generated shared object files are sufficient only for compile-time
24linking. They are stub libraries that only indicate that which symbols
25will be present at run-time, along with their type and size. The symbols
26do not reference an actual implementation.
27
28## Targets
29
30The GNU C Library supports a very wide set of platforms and architectures.
31The current Zig support for glibc only includes Linux.
32
33Zig supports glibc versions back to v2.17 (2012) as the Zig standard
34library depends on symbols that were introduced in 2.17. When used as a C
35or C++ compiler (i.e., `zig cc`) zig supports glibc versions back to
36v2.2.5.
37
38## Glibc stubs
39
40The file `lib/libc/glibc/abilist` is a Zig-specific binary blob that
41defines the supported glibc versions and the set of symbols each version
42must define. See https://codeberg.org/ziglang/libc-abi-tools for the
43tooling to generate this blob. The code in `glibc.zig` parses the abilist
44to build version-specific stub libraries on demand.
45
46The generated stub library is used for compile-time linking, with the
47expectation that at run-time the real glibc library will provide the
48actual symbol implementations.
49
50### Public Headers
51
52The glibc headers are in `lib/libc/include/generic-glibc/`. These are
53customized and have a couple Zig-specific `#ifdef`s to make the single set
54of headers represent any of the supported glibc versions. There are
55currently a handful of patches to these headers to represent new features
56(e.g. `reallocarray`) or changes in implementation (e.g., the `stat()`
57family of functions).
58
59The related Zig https://github.com/ziglang/universal-headers is a project
60designed to more robustly build multi-version header files suitable for
61compilation across a variety of target C library versions.
62
63## Glibc static C-Runtime object files and libraries
64
65Linking against glibc also implies linking against several, generally
66"invisible" glibc C Runtime libraries: `crti.o`, `crtn.o`, `Scrt1.o` and
67`libc_nonshared.a`. These objects are linked into generated Zig binaries
68and are not run-time linking dependencies. Generally they provide
69bootstrapping, initialization, and mapping of un-versioned public APIs to
70glibc-private versioned APIs.
71
72Like the public headers, these files contain a couple customiziations for
73Zig to be able to build for any supported glibc version. E.g., for glibc
74versions before v2.32, `libc_nonshared.a` contained stubs that directed
75the `fstat()` call to a versioned `__fxstat()` call.
76
77These files used for these objects are in `lib/libc/glibc`. See the
78`tools/update_glibc.zig` tool for updating content in here from the
79upstream glibc.
80
81# More Information
82
83See
84https://github.com/ziglang/zig/commit/2314051acaad37dd5630dd7eca08571d620d6496
85for an example commit that updates glibc (to v2.38).