zig-ecosystem-tooling-gaps

name	zig-ecosystem-tooling-gaps
description	Current Zig ecosystem and tooling gap assessment workflow for coding agents as of 2026-05-13. Use when evaluating Zig adoption risk, dependency hygiene, package management, ZLS/editor behavior, compiler or stdlib regressions, pre-1.0 API churn, cross-platform support tiers, unofficial package indexes, toolchain pinning, CI matrices, or mitigation plans for Zig 0.15/0.16-era ecosystem gaps.

Zig Ecosystem Tooling Gaps

Operating Mode

Use this skill to separate real ecosystem risk from stale folklore. Start with the exact local baseline:

zig version
test -f build.zig.zon && sed -n '1,160p' build.zig.zon
test -f .zigversion && cat .zigversion
command -v zls >/dev/null && zls --version || true

As of 2026-05-13, Zig 0.16.0 is the latest tagged release and 0.17.0-dev builds are available. Orca-style repos may still pin 0.15.2; treat the repo pin as binding unless the task is an upgrade.

Risk Model

• Zig is pre-1.0. Language, stdlib, build APIs, package metadata, compiler behavior, and linker behavior can change across minor releases.
• Non-trivial projects may encounter compiler bugs, miscompilations, regressions, or target-specific gaps. Reduce and verify before blaming project code.
• Ecosystem maturity varies by domain. Do not assume Rust/Go-level package depth, registry conventions, IDE support, or long-term API stability.
• Current docs and examples on the web often target older Zig releases. Verify examples against the project-pinned Zig before applying them.

Package Management Gaps

• Zig has a built-in package manager and build.zig.zon, but no official central package repository.
• Treat build.zig.zon as the source of truth for dependency identity, URLs, hashes, fingerprints, and package paths.
• Prefer upstream repositories, signed releases where available, exact hashes, and tracked provenance over unofficial package indexes.
• Use zig fetch and Zig-suggested hashes/fingerprints instead of hand-written values.
• Keep dependency cache output such as zig-pkg/ out of source unless the repo intentionally vendors it.
• For temporary dependency forks on Zig 0.16.0+, prefer zig build --fork=/path/to/clone over editing fetched cache contents.

ZLS And Editor Tooling

• Keep Zig and ZLS in sync. Tagged ZLS releases target matching Zig releases; ZLS master targets Zig master.
• ZLS is useful but not authoritative. Compiler/test output wins over editor diagnostics.
• If editor behavior is wrong, capture zig version, zls --version, editor config, and whether the project has a check step.
• Prefer a zig build check step for build-on-save diagnostics. It should compile/analyze without installing artifacts.
• ZLS schema/config options change over time; use version-matched schema docs for tagged releases.

Version Drift Hotspots

For 0.15.x to 0.16.x work, inspect:

• std.Io, filesystem, process, networking, and environment APIs.
• @cImport moving toward build-system C translation.
• @Type replacement by specific type-creating builtins.
• Managed-to-unmanaged container migration.
• heap.ArenaAllocator, removed thread-safe allocator wrappers, and allocator naming/defaults.
• Package metadata strictness, local overrides, project-local zig-pkg, and test-timeout/build flags.
• Fuzzer interface changes and release-mode behavior.

Do not mix 0.16 examples into 0.15 implementation without labeling them as migration-only.

Cross-Platform Reality Check

• Use Zig's current target/tier table before claiming platform support.
• Treat Tier 1 and Tier 2 as stronger signals, but still verify the project.
• Treat Tier 3, Tier 4, and additional platforms as requiring explicit compile, link, and runtime proof for the project.
• For Zig 0.16.0, note current minimums before support claims: Linux 5.10, macOS 13.0, Windows 10, FreeBSD 14.0, NetBSD 10.1, OpenBSD 7.8.
• Cross-compilation proves code generation/linking for a target, not runtime semantics or OS integration.

Triage Playbook

When something breaks:

1. Record exact command, target, optimize mode, Zig version, ZLS version if relevant, and host OS.
2. Reproduce with the project-pinned Zig.
3. Try latest stable Zig only to classify drift, not to redefine the project contract.
4. Check dependency versions and build.zig.zon hashes/fingerprints.
5. Minimize the failure to a single source file or tiny build step.
6. Search official Zig issue trackers/release notes for matching bugs, miscompilations, regressions, and breaking changes.
7. Prefer small compatibility shims and documented migration notes over broad rewrites.

Mitigation Checklist

• Pin Zig in docs, CI, scripts, and build.zig.zon.minimum_zig_version.
• Add CI for native build/test plus important cross-target compile lanes.
• Keep a check step for fast compiler diagnostics and ZLS build-on-save.
• Maintain migration notes per Zig release.
• Vendor or fork critical dependencies only with explicit provenance and update workflow.
• Gate upgrades with zig build, zig build test, package-surface checks, target builds, and CLI/editor sanity checks.
• Report ecosystem limitations honestly in release notes and customer-facing docs.

Source Refresh

Refresh before current-state claims:

• https://ziglang.org/download/
• https://ziglang.org/download/0.16.0/release-notes.html
• https://ziglang.org/documentation/0.16.0/
• https://ziglang.org/learn/getting-started/
• https://zigtools.org/zls/releases/
• https://zigtools.org/zls/releases/0.16.0/
• https://zigtools.org/zls/guides/build-on-save/