Proposal: `zag` – a small Zig tool for per-project Zig versions and declarative build.zig configuration

[felixuxx]

Hi everyone,

I’m not sure im in any position to be attempting such a thing because there’s a lot of things that i still dont understand enough about zig and i’ve also just joined the community a few days ago.

I want to sanity-check an idea with the community before I start building it. This is something I’d only attempt after I have a very solid understanding of Zig and the build system.

The tool could be tentatively called zag. The goal is not to replace zig build, not to add a new build DSL, and not to hide what Zig is doing. It’s meant to sit around the existing Zig tooling and reduce some repetitive project setup friction.

Problem I’m trying to address

After using the Zig build system for a while, a few pain points keep coming up:

• Managing Zig versions per project
• Repeating the same dependency setup boilerplate in build.zig
• Manually copying OS- and Zig-version-specific build configuration from README files

None of these are unsolvable, but they’re tedious and error-prone, especially across multiple projects.

What zag would do

zag would focus on three narrow responsibilities:

1. Per-project Zig version management(kind of like anyzig)

   • Detect required Zig version from build.zig.zon
   • Install/select that version automatically
   • Set up the environment so zig build works without manual steps

2. Dependency fetching (thin wrapper)

   • zag add <package> would internally call:

     zig fetch --save <package>
     ```bash
     

   • No custom dependency resolution logic

3. Optional, declarative build.zig augmentation

   • This is strictly opt-in and driven by the library author, not heuristics

   • A dependency may include a small config file (e.g. zag.zon)

   • That file describes how the dependency should be wired into build.zig

     • imports
     • link libraries
     • OS-specific or Zig-version-specific conditions

Example (very rough):

.{
    .zig = .{ .min = "0.14.0" },
    .build = .{
        .imports = &.{ "mylib" },
        .link = &.{
            .{ .os = "linux", .libs = &.{ "vulkan" } },
            .{ .os = "windows", .libs = &.{ "d3d12" } },
        },
    },
}

zag would only insert or update code inside clearly marked regions in build.zig, e.g.:

// zag:begin mylib
// zag:end mylib

Anything outside those markers is never touched.

Non-goals

To be explicit, zag would not:

• Replace zig build
• Introduce a new build language
• Guess or auto-generate configs
• Hide build logic from the user
• Require libraries to support it

If a dependency has no zag config, zag would simply fetch it and do nothing else.

Why I’m asking

Before investing time into this, I’d like feedback on:

• Whether this overlaps with existing or planned Zig tooling
• Whether the idea conflicts with Zig’s philosophy of explicitness
• Whether the opt-in, library-authored config approach seems reasonable
• Any obvious pitfalls I’m missing

I’m not proposing this as “the Zig way”, just exploring whether it’s a useful, non-invasive tool for people who want it.

[minkatter]

I do not quite see the value proposition here.

@felixuxx

Problem I’m trying to address

After using the Zig build system for a while, a few pain points keep coming up:

• Managing Zig versions per project
• Repeating the same dependency setup boilerplate in build.zig
• Manually copying OS- and Zig-version-specific build configuration from README files

• As you pointed out, the first is already more or less solved by anyzig
• What do you mean “repeating same dependency setup”? I do not see how zag.zon is any different in this respect other than being a declarative way to do the same thing.
• Again, I am not sure what you mean. Almost every Zig library or tool I have used is just zig build

You need to be more specific with your problem statement for an external party to see value in your ideas. General self-evident statements like this do not add anything to a technical discussion — it just feels like you do not like build.zig syntax.

A tool like anyzig is useful because it has a clear distinguishing technical goal that is not solved by Zig itself. It is not just a “different” way of achieving the same thing, but an enhancement to the system itself that is entirely optional.

@felixuxx

The tool could be tentatively called zag. The goal is not to replace zig build, not to add a new build DSL, and not to hide what Zig is doing. It’s meant to sit around the existing Zig tooling and reduce some repetitive project setup friction

Despite what you claim, you are in fact proposing just another build configuration tool. zag.zon is just another format a developer would have to learn.

[npc1054657282]

Just kidding: in the future, we’ll need to deal with the friction between different versions of zag.zon.