[V3] feat(build): add Zig Taskfile extension

[FanaticExplorer]

Description

Adds an optional Zig build Taskfile (build/Taskfile.zig.yml) that provides zig:build tasks (linux/windows/darwin) using Zig as the C/C++ compiler for CGO. The root Taskfile template optionally imports it, so Zig builds are available without changing the default wails3 build flow.

Type of change

Please select the option that is relevant.

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• This change requires a documentation update

How Has This Been Tested?

Please describe the tests that you ran to verify your changes. Provide instructions so we can reproduce. Please also list any relevant details for your test configuration using wails doctor.

• Windows
• macOS
• Linux

If you checked Linux, please specify the distro and version.

Windows 11 (Build 26200), Zig 0.16.0, Go 1.26.

Reproduction steps:

1. Install Zig from https://ziglang.org/download
2. wails3 task zig:build
3. (Optional) wails3 task zig:build:windows ARCH=amd64

Test Configuration

# System

┌────────────────────────────────────────────────────────────────────────────────────────────────────────┐
| Name              | Windows 10 Home                                                                    |
| Version           | 2009 (Build: 26200)                                                                |
| ID                | 25H2                                                                               |
| Branding          | Windows 11 Home                                                                    |
| Platform          | windows                                                                            |
| Architecture      | amd64                                                                              |
| Go WebView2Loader | true                                                                               |
| WebView2 Version  | 148.0.3967.96                                                                      |
| CPU               | AMD Ryzen 7 6800HS with Radeon Graphics                                            |
| GPU 1             | NVIDIA GeForce RTX 3050 Laptop GPU (NVIDIA) - Driver: 32.0.15.9649                 |
| GPU 2             | AMD Radeon(TM) Graphics (Advanced Micro Devices, Inc.) - Driver: 32.0.21043.10005  |
| Memory            | 16GB                                                                               |
└────────────────────────────────────────────────────────────────────────────────────────────────────────┘

# Build Environment

┌──────────────────────────────────────────────────────────────────────┐
| Wails CLI      | v3.0.0-dev                                          |
| Go Version     | go1.26.1                                            |
| -buildmode     | exe                                                 |
| -compiler      | gc                                                  |
| CGO_CFLAGS     |                                                     |
| CGO_CPPFLAGS   |                                                     |
| CGO_CXXFLAGS   |                                                     |
| CGO_ENABLED    | 1                                                   |
| CGO_LDFLAGS    |                                                     |
| DefaultGODEBUG | cryptocustomrand=1,tlssecpmlkem=0,urlstrictcolons=0 |
| GOAMD64        | v1                                                  |
| GOARCH         | amd64                                               |
| GOOS           | windows                                             |
└──────────────────────────────────────────────────────────────────────┘

# Dependencies

┌────────────────────────────────────────────────────────────────────────────────┐
| npm                        | 11.11.1                                           |
| NSIS                       | v3.11                                             |
| MakeAppx.exe (Windows SDK) | Not Installed                                     |
| MSIX Packaging Tool        | Not Installed                                     |
| SignTool.exe (Windows SDK) | Not Installed                                     |
| docker                     | *Not installed (optional - for cross-compilation) |
|                                                                                |
└─────────────────────────── * - Optional Dependency ────────────────────────────┘

# Checking for issues

 SUCCESS  No issues found

# Diagnosis

 SUCCESS  Your system is ready for Wails development!

Need documentation? Run: wails3 docs
 ♥   If Wails is useful to you or your company, please consider sponsoring the project: wails3 sponsor

Checklist:

• (v2 only) I have updated website/src/pages/changelog.mdx with details of this PR (v3 changelog entries are added automatically)
• My code follows the general coding style of this project
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes

Summary by CodeRabbit

• New Features

  • Added Zig-enabled cross-platform build configuration for Linux, macOS, and Windows, with optional code obfuscation, architecture-aware toolchain selection, and consistent output artifacts.

• Chores

  • Updated build templates to optionally include the Zig toolchain for the new build tasks.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: e58eec6d-cabe-4fda-b6ef-939bd4401632

📥 Commits

Reviewing files that changed from the base of the PR and between bee0a8d and 3510a31.

📒 Files selected for processing (1)

• v3/internal/commands/build_assets/Taskfile.zig.yml

🚧 Files skipped from review as they are similar to previous changes (1)

• v3/internal/commands/build_assets/Taskfile.zig.yml

---

Walkthrough

Adds a Taskfile (v3/internal/commands/build_assets/Taskfile.zig.yml) that implements a top-level build dispatcher and OS-specific Zig-based CGO build tasks for Linux, macOS, and Windows, and registers this Taskfile as an optional zig include in the common Taskfile template.

Changes

Zig cross-platform build integration

Layer / File(s)	Summary
Zig build Taskfile with dispatcher and platform implementations v3/internal/commands/build_assets/Taskfile.zig.yml	Adds a top-level build task that dispatches to build:linux, build:darwin, and build:windows. Each platform task runs prerequisites (go mod tidy, frontend build, icon generation), checks preconditions (Zig and optional garble), computes BUILD_FLAGS from DEV/EXTRA_TAGS/OBFUSCATED, sets GOOS/GOARCH/CGO/CC/CXX with Zig target triples, and runs garble build (when obfuscated) or go build. Windows task includes syso generation and cleanup.
Template registration for Zig Taskfile include v3/internal/templates/_common/Taskfile.tmpl.yml	Adds an optional zig include entry pointing to ./build/Taskfile.zig.yml in the Taskfile template includes section.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• wailsapp/wails#3748: Related Taskfile/template include refactor that introduced modular platform include patterns.

Suggested labels

Documentation, v3-alpha

Suggested reviewers

• leaanthony

Poem

🐰 A tiny rabbit taps the keys tonight,
Zig and CGO stitched neat and tight,
Linux, Mac, and Windows take the cue,
Dispatcher hops and builds anew,
Binaries born — a hop, a bite.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the main feature: adding a Zig-based build Taskfile extension to the V3 codebase.
Description check	✅ Passed	The PR description covers the key sections: feature summary, type of change marked correctly, testing details with Windows configuration and reproduction steps provided, and most checklist items completed; documentation update is flagged as required.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[FanaticExplorer]

Just noticed this PR included quite a lot of files (mostly .beads/*) — I think they were auto-generated when I tried to use bd to follow the instructions. I can remove them if you’d like and keep this PR focused on the --zig changes.

(Sorry for this, it's my first ever PR to the open-source 😄)

---

After a bit of thinking, I decided to remove those myself. Now, only changes in this PR are the files related to the feature.

[savely-krasovsky]

I didn't know that you can build Go CGO with anything other than GCC 🤔

[leaanthony]

I like the idea of this, but mostly from the perspective of providing better extension options for the build system. Taskfile already handles importing task files so I'm imagining a world where this could be downloaded and placed in the build directory and "just work". The best way to achieve that is to provide a cross platform "has" command to do the binary lookups rather than adding more a more as time goes on. I'm up for refactoring has-cc to be that generic command. This should allow you to create Taskfile.zig.yaml which could be imported then wails3 task zig:build would be available.

To be clear, I love the idea of Zig builds without docker, but I'm mindful of feature creep for the main CLI & Taskfiles and think a more sustainable option is to provide the tools to enable it.

Thoughts?

[FanaticExplorer]

Thanks a lot for taking a look — as my first open-source contribution, it means a lot!

I agree: making the has tool expandable sounds like a better approach than adding more dedicated has-* commands. I’ll work on that.
I’m just not 100% sure I understand the second part. In your vision, should we move all Zig-related logic into a separate Taskfile (e.g. Taskfile.zig.yml) and expose Zig builds via tasks like zig:build (using wails3 tool has zig for detection), instead of adding a --zig flag / modifying the main platform Taskfiles?

Once you clarify that part, I’d be happy to rework my PR to fit this. 😁

[leaanthony]

Yes that's right! Taskfiles can import other taskfiles. If you look at the ones in a Wails project you'll see that you have the main one and that imports the platform specific files. When you import you give it a namespace so you can call tasks within them.

I can do the "has" change in a different PR as it will affect existing Taskfiles 👍

This is a great first PR to Open Source. Keep going!

[FanaticExplorer]

Done! Took me some time, but I hope you'll like it 😇

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@v3/internal/commands/build_assets/Taskfile.zig.yml`:
- Around line 111-117: The Windows build command hardcodes the output to
'{{.BIN_DIR}}/{{.APP_NAME}}.exe' and ignores the caller-provided 'OUTPUT' var;
update the build command template (the line building the .exe) to use
'{{.OUTPUT}}' when present and fall back to '{{.BIN_DIR}}/{{.APP_NAME}}.exe'
otherwise (preserve existing use of BUILD_FLAGS and any OBUSCATED/DEV tags), so
the Windows path respects the parent-task 'OUTPUT' variable just like other
platforms.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 37e6b3b3-b119-430b-bc77-dab1981baa2f

📥 Commits

Reviewing files that changed from the base of the PR and between aa31c67 and bee0a8d.

📒 Files selected for processing (2)

• v3/internal/commands/build_assets/Taskfile.zig.yml
• v3/internal/templates/_common/Taskfile.tmpl.yml

[FanaticExplorer]

Fair note, CodeRabbit CLI didn't run well on my pc, so I couldn't find this issue myself locally 😭

[FanaticExplorer]

@leaanthony just wanted to let you know that I changed the name and description of the PR

Also, I noticed your commit 1691ea8 in master, can you clarify if my current PR goes along with it, or should I update my Taskfile?
(or clear this bit messy commit history 0_0)