sys_resolver

sys_resolver is what lets software written for classic Linux run on Zainium OS without a /usr, /etc or /bin at the root. It has two parts:

Where it runs

libsys_resolver.so is preloaded (LD_PRELOAD) into systemd services, login shells and PAM sessions, so practically every program you start uses it. It has no C library of its own, so it works the same in musl and glibc programs.

Path resolution

When a program opens, runs or inspects a path that does not exist and whose first component is bin, sbin, lib, usr, opt, var, etc or boot, the resolver maps it:

1. a leading /usr/local/ or /usr/ is removed;
2. lib64 becomes lib;
3. lib/modules → drivers/modules, lib/firmware → drivers/hardware/firmwares, boot → kernel;
4. the result is tried under /overlayer/syshub, the musl directory, /overlayer/zexlib/union and /overlayer/zaisys, in that order; the first one that exists is used.

Paths that exist are never touched, and /home, /tmp and the virtual filesystems are out of scope.

It covers opening and creating files (open, openat, fopen, …), running programs (execve, execvp, posix_spawn, script interpreters in #! lines), inspecting files (stat, access, faccessat, eaccess, readlink, realpath, statfs, …), walking directories (opendir, scandir, ftw, nftw), dlopen, inotify and extended attributes, and the user and group lookups (getpwnam, getgrgid, …).

Loader redirection

A binary built on another distribution names a loader that Zainium does not have at that path — /lib64/ld-linux-x86-64.so.2 for glibc, /lib/ld-musl-x86_64.so.1 for musl. When such a program is started, sys_resolver runs it with this system's loader of the same C library, keeping its name as argv[0]. Prebuilt glibc programs therefore run once glibc is installed (elevate zex install glibc).

Choosing the toolchain

By default cc, gcc, g++, cpp and pkg-config build for musl. sys_resolver can point them at glibc:

eval "$(sys-resolver env glibc)"     # this shell only
elevate sys-resolver set glibc       # system default (set musl to go back)
sys-resolver get                     # which toolchain builds use, and why
ZAINIUM_LIBC=glibc make              # one command

Programs keep running with the C library they were linked against; only the toolchain changes. See musl and glibc.

The sys-resolver command

Limits

The loader does not preload libraries into statically linked or setuid programs, so sys_resolver cannot help them. Such programs need real Zainium paths — which every Zainium package already uses.