refactor!: rewrite zbuild as comptime library

[wemeetagain]

Summary

This PR rewrites zbuild from a CLI/codegen tool into a comptime Zig library that configures std.Build directly from build.zig.zon.

Major changes:

• replaces the old CLI/runtime-parser/codegen flow with configureBuild(b, @import("build.zig.zon"), ...)
• targets released Zig 0.16.0 and updates examples/docs to use direct @import("build.zig.zon")
• removes the old CLI-era parser/serializer/IR command surface and makes zbuild a library-first package
• returns a typed BuildResult from configureBuild
• adds a built-in help step and richer docs/examples for the new library model
• adds aliases for named aggregate top-level steps
• adds fixture integration coverage and GitHub Actions CI

Semantics tightened in this branch

This branch also hardens the model substantially beyond the initial rewrite:

• manifest-owned refs use enum literals, manual refs use bare strings, and dependency submodules use "dep:module"
• options_modules now generate typed config modules, namespaced -Dmodule.option flags, real enum types, and explicit optional fields when no default is provided
• depends_on is explicit: enum literals mean artifact install-step shorthand, strings mean exact top-level step names
• named modules, options modules, and dependency default modules now share one reserved zbuild-owned import namespace
• manual interop and dependency-backed refs now fail with targeted diagnostics instead of panics / silent shadowing
• fixture runs are now uncached, so integration regressions actually get exercised

Breaking changes / migration notes

• zbuild.zon and the old CLI workflow are gone; use standard build.zig.zon
• Zig 0.16.0+ is now required
• examples now use the released 0.16.0 package-import path directly; the pre-release workaround is removed
• reference syntax is stricter and more explicit than before:
  • enum literals for zbuild-owned refs
  • bare strings for manual modules/steps
  • "dep:module" for dependency submodules

Test plan

• zig build test --summary all
• zig build test:fixtures --summary all
• cd examples/simple && zig build
• cd examples/full && zig build
• cd examples/full && zig build info
• cd test/fixtures/aliases_nested && zig build check

The fixture suite covers the examples plus targeted negative cases for namespace collisions, dependency import/lazy-path failures, manual interop errors, stdlib passthrough support, and alias validation.

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request represents a fundamental shift in zbuild's architecture, transforming it from a CLI-driven code generator into a powerful, declarative comptime library for Zig projects. The change leverages Zig's @import("build.zig.zon") feature to process build manifests at compile time, drastically reducing boilerplate and improving type safety. The new design aims to streamline build configuration, making it more efficient and less error-prone by integrating directly with the native Zig build system.

Highlights

• Architectural Rewrite: Rewrote zbuild from a standalone CLI tool with runtime parsing and codegen into a comptime Zig library that directly configures std.Build from a ZON manifest.
• Codebase Reduction: Reduced the codebase significantly, eliminating approximately 6,400 lines of parser/serializer/IR code and replacing it with about 1,100 lines of comptime metaprogramming.
• Enhanced Documentation: Overhauled documentation, including a new README, a comprehensive schema reference, a motivation document explaining the new approach, and two compilable examples (simple and full).
• Typed BuildResult: configureBuild now returns a BuildResult struct with typed getters for all created entities, such as executables, libraries, modules, tests, runs, fmts, dependencies, and options modules.
• Comptime Validation: Implemented comptime cross-reference validation to catch typos in module, artifact, import, and depends_on references at compile time, improving build reliability.
• Flexible depends_on: Extended depends_on support to include explicit step references (e.g., "test:unit", "cmd:deploy") in addition to plain artifact names.
• Built-in Help Step: Added a built-in zig build help step that prints a formatted project overview derived from the manifest metadata.
• Improved runs Syntax: Introduced dual-form syntax for runs, allowing bare tuples for simple commands and a structured format with cmd, cwd, env, stdin, and depends_on for complex scenarios.
• Options Modules Update: Updated options modules to accept enum literals for type fields (e.g., .bool instead of "bool"), enhancing type safety and readability.
• Version Bump: Bumped the project version to 0.4.0 to reflect the significant changes and new features.

🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console.

Changelog

• README.md
  • Rewrote the introduction to reflect the new library-based approach.
  • Updated the 'Before and after' section with examples of the new declarative ZON configuration.
  • Replaced installation and usage instructions with a quickstart guide for the library.
  • Added a new 'Features' section detailing the library's capabilities.
  • Updated the 'Documentation' section with links to new schema and motivation documents.
• build.zig
  • Transformed the file from a CLI tool's build script to a library's build script.
  • Exposed configureBuild, Options, and BuildResult for external use.
  • Updated the zbuild_module to point to src/build_runner.zig.
  • Removed all CLI-specific executable and installation steps.
  • Simplified test setup to only include tests for the zbuild_module.
• build.zig.zon
  • Updated the project version from 0.2.0 to 0.4.0.
  • Modified the description to 'Declarative build configuration for Zig projects'.
• docs/AdvancedFeatures.md
  • Removed the file, as its content is no longer relevant to the new library architecture.
• docs/MOTIVATION.md
  • Removed the old motivation document.
• docs/TODO.md
  • Removed the old TODO list.
• docs/motivation.md
  • Added a new motivation document explaining the rationale behind the comptime library approach, its benefits, and inspirations.
• docs/schema.md
  • Added a comprehensive schema reference for all zbuild manifest fields, including details on modules, executables, libraries, objects, tests, fmts, runs, options modules, dependencies, LazyPath resolution, and comptime validation.
• examples/full/build.zig
  • Added a new build file demonstrating a full example project using the zbuild library, including modules, executables, libraries, tests, fmts, runs, and options modules.
• examples/full/build.zig.zon
  • Added a new manifest file for the full example project, defining its metadata and a dependency on zbuild.
• examples/full/src/lib.zig
  • Added a new example library source file for the full example.
• examples/full/src/main.zig
  • Added a new example main executable source file for the full example.
• examples/full/src/test.zig
  • Added a new example test source file for the full example.
• examples/simple/build.zig
  • Added a new build file demonstrating a minimal example project using the zbuild library.
• examples/simple/build.zig.zon
  • Added a new manifest file for the simple example project, defining its metadata and a dependency on zbuild.
• examples/simple/src/main.zig
  • Added a new example main executable source file for the simple example.
• src/Args.zig
  • Removed the file, as command-line argument parsing is no longer needed for the library.
• src/Config.zig
  • Removed the file, as the old configuration parsing and serialization logic is replaced by comptime processing.
• src/ConfigBuildgen.zig
  • Removed the file, as the old build file generation logic is replaced by direct std.Build configuration at comptime.
• src/GlobalOptions.zig
  • Removed the file, as global CLI options are no longer applicable.
• src/Manifest.zig
  • Removed the file, as the old manifest parsing logic is replaced by direct @import("build.zig.zon").
• src/Package.zig
  • Removed the file, as old package handling is no longer directly used.
• src/ZigEnv.zig
  • Removed the file, as the old Zig environment detection is no longer directly used.
• src/build_runner.zig
  • Added the core build_runner.zig file, which contains the configureBuild function and all comptime logic for processing the ZON manifest and configuring the std.Build graph.
• src/cmd_build.zig
  • Removed the file, as the old CLI build command is no longer needed.
• src/cmd_fetch.zig
  • Removed the file, as the old CLI fetch command is no longer needed.
• src/cmd_init.zig
  • Removed the file, as the old CLI init command is no longer needed.
• src/cmd_sync.zig
  • Removed the file, as the old CLI sync command is no longer needed.
• src/help.zig
  • Added the help.zig file, which provides comptime functions to generate formatted help text for the built-in zig build help step.
• src/main.zig
  • Removed the file, as the old CLI entry point is no longer needed.
• src/run_zig.zig
  • Removed the file, as the old Zig command runner is no longer needed.
• src/sync_build_file.zig
  • Removed the file, as the old build file synchronization logic is no longer needed.
• src/sync_manifest.zig
  • Removed the file, as the old manifest synchronization logic is no longer needed.
• test/fixtures/basic1.zbuild.zon
  • Removed the old test fixture.
• test/fixtures/basic2.zbuild.zon
  • Removed the old test fixture.
• test/fixtures/basic3.zbuild.zon
  • Removed the old test fixture.
• test/fixtures/basic4.zbuild.zon
  • Removed the old test fixture.
• test/fixtures/basic5.zbuild.zon
  • Removed the old test fixture.
• test/fixtures/basic6.zbuild.zon
  • Removed the old test fixture.
• test/sync.zig
  • Removed the old synchronization tests.
• zbuild.zon
  • Removed the project's own zbuild.zon file, as it is now configured via build.zig.zon and the new library.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This is an excellent and significant rewrite of zbuild. The move from a CLI tool with codegen to a comptime library is a huge architectural improvement, leveraging Zig's comptime capabilities to provide a more robust, declarative, and user-friendly build configuration experience. The code quality is high, and the new documentation is thorough and clear. I have one suggestion to improve the internal structure by centralizing some logic, but overall this is a fantastic contribution.