84 lines
3.7 KiB
Markdown
84 lines
3.7 KiB
Markdown
# Zig GNU C Library ("glibc") Support
|
|
|
|
Zig supports building binaries that will dynamically link against the
|
|
[GNU C Library ("glibc")](https://www.gnu.org/software/libc/) when run.
|
|
This support extends across a range of glibc versions.
|
|
|
|
By default, Zig binaries will not depend on any external C library, but
|
|
they can be linked against one with the `-lc` option. The target ABI defines
|
|
which C library: `musl` for the [musl C library](https://musl.libc.org/) or
|
|
`gnu` for the GNU C library.
|
|
|
|
A specific GNU C library version can be chosen with an appropriate
|
|
`-target`. For example, `-target native-native-gnu.2.19` will use the
|
|
default CPU and OS targets, but will link in a run-time dependency on
|
|
glibc v2.19 (or later). Use `zig env` to show the default target and
|
|
version.
|
|
|
|
Glibc symbols are defined in the `std.c.` namespace in Zig, though the
|
|
`std.os.` namespace is generally what should be used to access C-library
|
|
APIs in Zig code (it is defined depending on the linked C library).
|
|
|
|
See `src/glibc.zig` for how Zig will build the glibc components. The
|
|
generated shared object files are sufficient only for compile-time
|
|
linking. They are stub libraries that only indicate that which symbols
|
|
will be present at run-time, along with their type and size. The symbols
|
|
do not reference an actual implementation.
|
|
|
|
## Targets
|
|
|
|
The GNU C Library supports a very wide set of platforms and architectures.
|
|
The current Zig support for glibc only includes Linux.
|
|
|
|
Zig supports glibc versions back to v2.17 (2012) as the Zig standard
|
|
library depends on symbols that were introduced in 2.17.
|
|
|
|
## Glibc stubs
|
|
|
|
The file `lib/libc/glibc/abilist` is a Zig-specific binary blob that
|
|
defines the supported glibc versions and the set of symbols each version
|
|
must define. See https://github.com/ziglang/glibc-abi-tool for the
|
|
tooling to generate this blob. The code in `glibc.zig` parses the abilist
|
|
to build version-specific stub libraries on demand.
|
|
|
|
The generated stub library is used for compile-time linking, with the
|
|
expectation that at run-time the real glibc library will provide the
|
|
actual symbol implementations.
|
|
|
|
### Public Headers
|
|
|
|
The glibc headers are in `lib/libc/include/generic-glibc/`. These are
|
|
customized and have a couple Zig-specific `#ifdef`s to make the single set
|
|
of headers represent any of the supported glibc versions. There are
|
|
currently a handful of patches to these headers to represent new features
|
|
(e.g. `reallocarray`) or changes in implementation (e.g., the `stat()`
|
|
family of functions).
|
|
|
|
The related Zig https://github.com/ziglang/universal-headers is a project
|
|
designed to more robustly build multi-version header files suitable for
|
|
compilation across a variety of target C library versions.
|
|
|
|
## Glibc static C-Runtime object files and libraries
|
|
|
|
Linking against glibc also implies linking against several, generally
|
|
"invisible" glibc C Runtime libraries: `crti.o`, `crtn.o`, `Scrt1.o` and
|
|
`libc_nonshared.a`. These objects are linked into generated Zig binaries
|
|
and are not run-time linking dependencies. Generally they provide
|
|
bootstrapping, initialization, and mapping of un-versioned public APIs to
|
|
glibc-private versioned APIs.
|
|
|
|
Like the public headers, these files contain a couple customiziations for
|
|
Zig to be able to build for any supported glibc version. E.g., for glibc
|
|
versions before v2.32, `libc_nonshared.a` contained stubs that directed
|
|
the `fstat()` call to a versioned `__fxstat()` call.
|
|
|
|
These files used for these objects are in `lib/libc/glibc`. See the
|
|
`tools/update_glibc.zig` tool for updating content in here from the
|
|
upstream glibc.
|
|
|
|
# More Information
|
|
|
|
See
|
|
https://github.com/ziglang/zig/commit/2314051acaad37dd5630dd7eca08571d620d6496
|
|
for an example commit that updates glibc (to v2.38).
|