Learning Zig at the Edges of the System

I recently put two implementations of the same audio command-line tool beside each other. The existing Python version remained the reference. A new Zig version had to prove that it could match the command shape, preserve the JSON contract, call the same installed FFmpeg and FFprobe binaries, and add value without forcing a replacement decision.

That setup changed the question I was asking. I was no longer asking whether Zig was faster, cleaner, or more interesting in the abstract. I was asking where a small native binary could make an operating system easier to ship, inspect, and trust.

That is a better way to learn a systems language. Start at the edge of a real system, give the language a bounded job, and make it earn the next one.

The rewrite instinct is usually wrong

A new language creates a predictable temptation: find the largest existing application and imagine rebuilding it. The imagined rewrite has none of the old codebase's accumulated friction, so the architecture looks clean. It also has none of the old codebase's accumulated behavior, which is the part users actually depend on.

I am taking the opposite approach with Zig. The web applications stay in TypeScript. The actor and runtime work stays where Elixir and OTP are the point. Existing Rust experiments do not move merely because another low-level language is available. FFmpeg keeps responsibility for codecs and containers because replacing mature media infrastructure would add risk without adding insight.

Zig gets the leaves: a receipt validator, an artifact packager, a bounded log scanner, a small audio probe. These are narrow programs with explicit inputs, machine-readable outputs, stable exit behavior, and little need for a long-running runtime. Their output artifact is often the product.

This boundary matters because language choice should follow system shape. A tiny executable that reads files, computes hashes, parses bytes, and exits has different requirements from a web product or a supervised process tree. The binary needs to start quickly, travel easily, fail clearly, and avoid dragging a package environment behind it. That is a credible place for Zig to compete.

Build the comparison before making the decision

The audio tool is the clearest example. Its Python implementation already provides local commands for probing media, resolving paths and hashes, converting files, extracting audio, trimming clips, normalizing levels, and generating waveforms. Those commands delegate codec and container work to FFmpeg and FFprobe. The CLI wraps those tools in a stable JSON interface and adds safety rules such as refusing to overwrite an output unless the operator explicitly allows it.

The Zig port sits beside that implementation. It supports a smaller comparable command surface, including doctor, resolve, probe, and dry-run conversion behavior. The two versions can be exercised against the same files and compared for behavior, startup feel, and performance before any replacement decision is made.

That side-by-side period is more useful than a benchmark written for a language argument. It reveals the actual integration costs. Does JSON output remain stable? Are subprocess errors captured correctly? Are paths handled consistently? Does the native binary simplify deployment enough to justify another implementation? Which operations should remain delegated to an external tool?

It also showed where Zig could contribute something specific. The Zig version includes native analysis for PCM 16-bit WAV files: peak level, RMS, duration, sample rate, and channel count. That operation is direct byte parsing plus numeric work. It does not require a new codec stack, and it benefits from precise control over data layout and allocation. The boundary is clean: Zig reads a format it can handle directly, while FFmpeg remains responsible for the broad and difficult media surface.

This is the kind of division I want from a polyglot system. Each language should own the part where its tradeoffs become useful, not spread because the team is excited about syntax.

Portability is a behavior, not a claim

My first Zig lab on the Mac mini was deliberately small. It accepted explicit arguments and emitted one compact, receipt-shaped JSON line. The useful proof was not that the program ran once. The useful proof was a repeatable sequence: report the Zig version, run tests, execute the sample, build a native release binary, and cross-compile a Linux x86_64 binary.

The machine currently resolves Zig 0.16.0. The lab has produced both a native arm64 Mach-O binary and a Linux x86_64 ELF binary. The small internal utilities that followed use the same discipline: test, build, and perform a cross-target compile check before being treated as useful.

Cross-compilation is easy to celebrate too early. Producing a file for another target does not prove the entire program works there. System calls, subprocess dependencies, filesystem assumptions, and integration behavior still need testing on the target environment. But a successful cross-target build is a meaningful early constraint. It catches accidental coupling and keeps distribution in the design conversation while the program is still small.

That is important for operator tools. A utility used by a person, a local agent, and CI should not require three unrelated installation stories if one compact executable can serve them. The deployment shape becomes part of the interface.

Small tools expose systems thinking

Leaf utilities look simple, but they force precise decisions. A receipt validator needs a stable definition of valid input and distinct outcomes for malformed content, missing files, and internal failures. An artifact packager needs deterministic ordering, byte sizes, and hashes so two runs can be compared. A log scanner needs bounded memory, explicit patterns, and an exit code that distinguishes findings from execution errors.

These are not glamorous problems. They are the mechanics that let larger automation remain legible. An agent can call a tool safely when stdout has a contract, stderr is not mixed into the payload, exit codes are stable, input scope is bounded, and side effects are explicit. The implementation language helps, but the contract is what makes the tool operational.

Working in Zig makes some of those decisions harder to avoid. Allocation is visible. Byte boundaries matter. Error paths are part of the function shape. Cross-target assumptions surface during the build. That friction is useful when the goal is to understand the machine-facing edge of the system.

The same lesson applies beyond Zig. Systems programming is not just writing code closer to hardware. It is learning to see the contracts that higher-level environments make easy to ignore: ownership, memory, process boundaries, file formats, failure classes, and the exact bytes crossing an interface.

Adoption should have a ratchet

I do not want language adoption to be driven by enthusiasm alone. A better rule is a ratchet: a successful narrow tool can justify a slightly more demanding tool, but a new language does not automatically move inward toward core products.

The first stage is a smoke project. Can the toolchain build, test, run, and cross-compile on the operator machine? The second stage is a real leaf utility with a stable contract. The third is side-by-side comparison against an existing implementation. Only then is there enough evidence to discuss replacement, wider distribution, or a deeper integration boundary.

This also makes stopping cheap. If a Zig utility is harder to maintain than the shell or Python it replaces, the experiment has still produced useful knowledge without destabilizing a central service. If it succeeds, the evidence is concrete: smaller deployment surface, clearer performance behavior, simpler cross-platform release, or direct access to low-level data that was awkward elsewhere.

The point is not to become a Zig shop. The point is to become more deliberate about where software boundaries belong.

A systems language earns its place one boundary at a time. The most convincing result is not a rewrite announcement. It is a small binary doing a real job, returning an exact result, and making the rest of the system easier to operate.