zig-common

The pieces the stackhands Zig tools share: Linux system calls with named errors, file handling checked on the open descriptor, running a child program, gzip in place and the .licensed-logs list, and command-line plumbing.

Documentation: https://stackhands.github.io/zig-common/

It holds only what at least two tools need, or what one tool needs in a form the next port will reuse. It is Linux only and needs Zig 0.17.1.

Use it from a tool

// build.zig.zon
.dependencies = .{
    .zig_common = .{
        .url = "git+https://github.com/stackhands/zig-common#<commit>",
        .hash = "<hash zig fetch prints>",
    },
},

// build.zig
const common = b.dependency("zig_common", .{ .target = target, .optimize = optimize });
mod.addImport("zig_common", common.module("zig_common"));

zig fetch --save git+https://github.com/stackhands/zig-common#<commit> writes the entry and its hash.

Modules

module	what it does
sys	std.os.linux calls with EINTR retried and errno mapped to a Zig error set
fsx	open without following a final symbolic link, checks on the descriptor (fstat), cp-style copy, line append, atomic replace keeping owner, mode and access ACLs, directory iteration, rm -rf that never follows links, realpath through /proc/self/fd
proc	run a program by absolute path with an empty signal mask, default handlers and no descriptors above 2, by default in its own session; stdin fed and stdout and stderr read at once, each with a cap; an optional deadline, SIGTERM, a grace period, SIGKILL to the process group; a cancel flag a signal handler can set; group members left after the child exits are killed before it is reaped; which looks a name up in an explicit PATH
logs	gzip -9 in place with gzip's header (name, mtime, OS byte), owner, mode and times kept; rewrite of .licensed-logs entries
env	the environment as raw bytes with getenv's first-entry rule, duplicate names found, a child environment built with each name once, shell name check
state	private files in a shared directory: trusted only when the open file is a regular file of this user with one link and no group or other bits, a lock trusted the same way, atomic 0600 writes; RootLock, a flock gate plus a POSIX record lock on a sidecar, with a deadline
json	a JSON reader with Python's two string encodings (surrogateescape text, one byte per code point), Python values, and json.dumps(indent=N, sort_keys=True) byte for byte, float repr included
pytext	byte strings as Python text: the surrogateescape character, the 'replace' decoder, str.isspace, strip and split, shlex.quote
atomic	atomic_write: replace a file only after its bytes, owner, mode and every ACL form (GPFS NFSv4, NFSv4, POSIX access) are durable and read back; fault points before write, fsync and rename
cli	messages to stdout and stderr that ignore a closed stream, exit code 2 for a refused invocation, the version line

Test

zig build test --summary all

Compatibility

COMPAT.md lists the library version, the Zig version, and the tool versions built on each.

License

MIT, see LICENSE.

Part of stackhands

zig-common is one of the stackhands tools for building, installing and maintaining an HPC software stack with EasyBuild on top of EESSI.

Tool	Job	Docs
eb-stack	Solve, shard and plan an EasyBuild build list; admit builds under a scratch inode budget	docs
eb-staged-rebuild	Rebuild an installation in a staged tree and swap it in, so running jobs keep their paths	docs
eessi-arch-guard	Reload EESSI in a Slurm task that inherited it for another CPU or GPU	docs
eb-local	Install software with EasyBuild on top of EESSI into a directory a user or project owns	docs
eb-keep-logs	Keep a failed build's EasyBuild log and command output; rotate a pipeline's log tree	docs
rfc9162	Append-only Merkle logs hashed as RFC 9162, with tiled storage and signed checkpoints	docs
zig-common	The shared Zig library under the Zig tools: system calls, checked files, child processes	docs