feat(v3): add -tags flag to wails3 build command by leaanthony · Pull Request #4968 · wailsapp/wails

leaanthony · 2026-02-07T07:29:40Z

Summary

Adds a -tags CLI flag to wails3 build so users can pass custom Go build tags without modifying Taskfiles
Tags are forwarded as EXTRA_TAGS to platform Taskfiles and appended to the go build command
In production mode: -tags production,<extra>. In dev mode: -tags <extra>

Usage

wails3 build -tags gtk4
wails3 build -tags gtk4,server
wails3 build -tags gtk4 GOOS=linux

Files changed

v3/internal/flags/task_wrapper.go — Added Tags field to Build struct
v3/internal/commands/task_wrapper.go — Pass EXTRA_TAGS variable to task system
v3/internal/commands/task_wrapper_test.go — 3 new test cases
v3/internal/commands/build_assets/{darwin,linux,windows}/Taskfile.yml — Use EXTRA_TAGS in BUILD_FLAGS

Test plan

Existing TestWrapTask tests pass
Existing TestBuildCommand test passes
New TestBuildCommandWithTags — single tag passed correctly
New TestBuildCommandWithMultipleTags — comma-separated tags passed correctly
New TestBuildCommandWithoutTags — backward compatible, no EXTRA_TAGS when flag omitted

Closes #4957

🤖 Generated with Claude Code

Summary by CodeRabbit

New Features
- Added -tags flag to the build command for passing custom Go build tags to the compiler.
Bug Fixes
- Fixed file drag-and-drop issues on Windows and Linux.
- Fixed window show/hide, positioning, and max size enforcement on Linux/GTK4.
- Fixed DPI scaling on Linux/GTK4 with fractional scaling support.
- Fixed menu items duplicating when creating new windows on Linux/GTK4.
- Fixed mapped types with enum keys generation in JS/TS bindings.

coderabbitai · 2026-02-07T07:30:07Z

Walkthrough

This PR adds support for custom Go build tags via a new -tags flag in the wails3 build command. The implementation threads a Tags parameter from the command-line interface through the build wrapper, into task arguments, and propagates it as EXTRA_TAGS across platform-specific Taskfiles and Docker build contexts.

Changes

Cohort / File(s)	Summary
Build Taskfiles (Multi-platform) `v3/internal/commands/build_assets/darwin/Taskfile.yml`, `v3/internal/commands/build_assets/linux/Taskfile.yml`, `v3/internal/commands/build_assets/windows/Taskfile.yml`	Added EXTRA_TAGS variable to build tasks. Updated BUILD_FLAGS conditionally to include `-tags` with EXTRA_TAGS for development builds and append to production tags when present. Propagated EXTRA_TAGS to docker run commands via `-e EXTRA_TAGS` when set.
Docker Build Support `v3/internal/commands/build_assets/docker/Dockerfile.cross`	Introduced TAGS variable initialized to "production" with EXTRA_TAGS appended if provided. Modified go build invocation to use `-tags "$TAGS"` flag.
Build Command Wrapper `v3/internal/commands/task_wrapper.go`	Renamed unnamed parameter to `buildFlags`. Added logic to append EXTRA_TAGS to task arguments when Tags field is non-empty.
Build Flags Configuration `v3/internal/flags/task_wrapper.go`	Added Tags field to Build struct to accept comma-separated build tags from command-line input.
Build Command Tests `v3/internal/commands/task_wrapper_test.go`	Added three new test cases covering build behavior with single tags, multiple comma-separated tags, and no tags.
Changelog `v3/UNRELEASED_CHANGELOG.md`	Documented new `-tags` flag feature and multiple GTK4-related fixes for drag-and-drop, window management, DPI scaling, and menu handling.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

[v3] Pass build flags to binding generator #4023: Modifies BUILD_FLAGS propagation in Taskfile templates and build task variable handling, addressing similar build flag templating patterns.

Suggested labels

Enhancement, v3-alpha, go, size:XL, lgtm

Poem

🐰 With tags now threaded through our build,
From Darwin to Windows, our commands are filled,
GTK4 awaits with a -tags gtk4 call,
The build system adapts, embracing them all! 🏗️

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'feat(v3): add -tags flag to wails3 build command' clearly and concisely describes the main change of adding a new CLI flag for passing Go build tags.
Description check	✅ Passed	The PR description covers all critical template sections: summary of changes, usage examples, files changed, test plan with specific test cases, and issue reference (`#4957`).
Linked Issues check	✅ Passed	The PR implementation directly supports the primary objective of `#4957` by providing the -tags flag mechanism needed to build with GTK4 support via 'wails3 build -tags gtk4'.
Out of Scope Changes check	✅ Passed	All changes are directly related to implementing the -tags flag feature. The changelog, Taskfiles, flags struct, and task wrapper modifications are all necessary and within scope.

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

✨ Finishing touches

📝 Generate docstrings

🧪 Generate unit tests (beta)

Create PR with unit tests
Post copyable unit tests in a comment
Commit unit tests in branch feature/build-tags-passthrough

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

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

coderabbitai

Actionable comments posted: 1

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (2)

.github/workflows/build-and-test-v3.yml (1)

295-296: ⚠️ Potential issue | 🟡 Minor

Stale comment: wails build now supports -tags flag.

This PR adds -tags support to wails3 build, making this comment outdated. Consider updating the comment and optionally adding a GTK4 template build step that uses wails3 build -tags gtk4.

v3/internal/commands/build_assets/darwin/Taskfile.yml (1)

55-69: ⚠️ Potential issue | 🟡 Minor

build:docker does not receive or use EXTRA_TAGS.

The Docker cross-compilation path doesn't forward EXTRA_TAGS to the container's build command (line 69). If someone cross-compiles for macOS from Linux with -tags gtk4 (or any custom tag), the tags will be silently dropped.

Consider passing EXTRA_TAGS into the Docker command (e.g., via -e EXTRA_TAGS="{{.EXTRA_TAGS}}") and consuming it inside the container's build script, or at minimum document that custom tags are only supported for native builds.

🤖 Fix all issues with AI agents

In `@v3/internal/commands/build_assets/linux/Taskfile.yml`:
- Line 29: The build Docker tasks don’t forward EXTRA_TAGS and build.sh doesn’t
apply them; update all build:docker docker run invocations (Taskfile.yml entries
for Linux/Darwin/Windows) to include -e EXTRA_TAGS="{{.EXTRA_TAGS}}" (or pass as
an argument) so the container receives the value, and modify the
Dockerfile.cross entrypoint script build.sh to read EXTRA_TAGS (e.g., from env
or arg) and, when non-empty, append -tags "$EXTRA_TAGS" to the go build command
(ensuring it omits the flag when empty); target the docker run invocations named
build:docker and the build.sh script referenced by Dockerfile.cross.

🧹 Nitpick comments (1)

v3/internal/commands/task_wrapper_test.go (1)

202-344: Consider extracting common test setup into a helper.

Every TestBuild* function repeats ~30 lines of identical boilerplate (save/restore env, mock runTaskFunc, save/restore os.Args). A small helper like withMockedBuildEnv(t, func(captured...)) would reduce duplication and make future tests easier to add. That said, this matches the existing test style in the file, so it's entirely optional.

Copilot

Pull request overview

Adds support for passing custom Go build tags through wails3 build via a new -tags flag, wiring the value into Taskfile-driven builds so projects can opt into features like GTK4 without editing generated Taskfiles.

Changes:

Added -tags flag to the wails3 build command flags and forwarded it as EXTRA_TAGS into the task wrapper.
Updated platform build-assets Taskfiles (darwin/linux/windows) to incorporate EXTRA_TAGS into go build flags (dev vs production behavior).
Added new unit tests for build tag forwarding and adjusted CI workflow dependency lists / cache versions.

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
v3/internal/flags/task_wrapper.go	Adds `Tags` field to build flags to expose `-tags` CLI option.
v3/internal/commands/task_wrapper.go	Appends `EXTRA_TAGS=...` to Task CLI vars when `-tags` is provided.
v3/internal/commands/task_wrapper_test.go	Adds test cases validating `EXTRA_TAGS` forwarding behavior.
v3/internal/commands/build_assets/darwin/Taskfile.yml	Incorporates `EXTRA_TAGS` into BUILD_FLAGS used by native `go build`.
v3/internal/commands/build_assets/linux/Taskfile.yml	Incorporates `EXTRA_TAGS` into BUILD_FLAGS used by native `go build`.
v3/internal/commands/build_assets/windows/Taskfile.yml	Incorporates `EXTRA_TAGS` into BUILD_FLAGS used by native `go build`.
.github/workflows/cross-compile-test-v3.yml	Updates cached apt packages list/version used in CI.
.github/workflows/build-and-test.yml	Updates cached apt packages list/version and apt install list used in CI.
.github/workflows/build-and-test-v3.yml	Updates cached apt packages list/version used in CI.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-02-07T07:34:33Z

          ARCH: '{{.ARCH}}'
          DEV: '{{.DEV}}'
          OUTPUT: '{{.OUTPUT}}'
+          EXTRA_TAGS: '{{.EXTRA_TAGS}}'


EXTRA_TAGS is being passed through to this Taskfile, but the build:docker path still runs the wails-cross container without any way to apply those tags. As a result, wails3 build -tags ... won’t work when the build falls back to Docker (cross-compiling, missing compiler, etc.). Forward the tag list into the container (e.g., env/arg) and update the cross-compile image entrypoint to include the tags in its go build invocation (and, if applicable, match the native DEV/production tag behavior).

Copilot · 2026-02-07T07:34:33Z

          ARCH: '{{.ARCH}}'
          DEV: '{{.DEV}}'
          OUTPUT: '{{.OUTPUT}}'
+          EXTRA_TAGS: '{{.EXTRA_TAGS}}'


EXTRA_TAGS is now threaded through the build task, but build:docker does not pass it into the wails-cross container and the image build script does not add -tags to go build. This makes wails3 build -tags ... ineffective for non-macOS hosts cross-compiling via Docker. Propagate the tags into the container and have the container build script apply them consistently.

Copilot · 2026-02-07T07:34:33Z

        vars:
          ARCH: '{{.ARCH}}'
          DEV: '{{.DEV}}'
+          EXTRA_TAGS: '{{.EXTRA_TAGS}}'


The new EXTRA_TAGS variable is passed to the build task, but the Docker cross-compile path (build:docker) doesn’t forward it to the container (and the cross image’s build script doesn’t use it). That means wails3 build -tags ... won’t work for CGO builds that use Docker on non-Windows hosts. Consider passing the tags into docker run and updating the cross image entrypoint to include them in go build.

Suggested change

EXTRA_TAGS: '{{.EXTRA_TAGS}}'

Copilot · 2026-02-07T07:34:34Z

@@ -115,8 +115,8 @@ jobs:
        uses: awalsh128/cache-apt-pkgs-action@latest
        if: matrix.os == 'ubuntu-latest'
        with:
-          packages: libgtk-3-dev libwebkit2gtk-4.1-dev libwayland-dev build-essential pkg-config xvfb x11-xserver-utils at-spi2-core xdg-desktop-portal-gtk
-          version: 1.0
+          packages: libgtk-3-dev libwebkit2gtk-4.1-dev build-essential pkg-config xvfb x11-xserver-utils at-spi2-core xdg-desktop-portal-gtk
+          version: 1.1


The PR description’s “Files changed” section doesn’t mention the workflow updates in this PR (including v2 CI changes). Please either update the PR description to include these workflow changes or split them into a separate PR so the scope of the change is clear for reviewers.

cloudflare-workers-and-pages · 2026-02-07T07:35:38Z

Deploying wails with Cloudflare Pages

Latest commit:	`c83c044`
Status:	⚡️ Build in progress...

View logs

github-actions · 2026-02-07T07:35:56Z

⚠️ Missing Changelog Update

Hi @leaanthony, please update v3/UNRELEASED_CHANGELOG.md with a description of your changes.

This helps us keep track of changes for the next release.

Allow users to pass custom build tags via `wails3 build -tags gtk4` instead of requiring Taskfile modifications. Tags are forwarded as EXTRA_TAGS to platform Taskfiles and appended to the go build command alongside the existing production tag. Works for both native and Docker cross-compilation builds. Closes #4957 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

github-actions · 2026-02-07T07:48:43Z

⚠️ Missing Changelog Update

Hi @leaanthony, please update v3/UNRELEASED_CHANGELOG.md with a description of your changes.

This helps us keep track of changes for the next release.

Allow users to pass custom build tags via `wails3 build -tags gtk4` instead of requiring Taskfile modifications. Tags are forwarded as EXTRA_TAGS to platform Taskfiles and appended to the go build command alongside the existing production tag. Works for both native and Docker cross-compilation builds. Closes wailsapp#4957 Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Copilot AI review requested due to automatic review settings February 7, 2026 07:29

Copilot started reviewing on behalf of leaanthony February 7, 2026 07:30 View session

coderabbitai Bot reviewed Feb 7, 2026

View reviewed changes

Comment thread v3/internal/commands/build_assets/linux/Taskfile.yml

Copilot AI reviewed Feb 7, 2026

View reviewed changes

leaanthony mentioned this pull request Feb 7, 2026

[Feedback Wanted] Experimental GTK4 + WebKitGTK 6.0 Support #4957

Closed

28 tasks

leaanthony force-pushed the feature/build-tags-passthrough branch from e5fa302 to d7aba11 Compare February 7, 2026 07:40

Merge branch 'v3-alpha' into feature/build-tags-passthrough

c83c044

leaanthony merged commit 4097aa3 into v3-alpha Feb 7, 2026
9 of 12 checks passed

leaanthony deleted the feature/build-tags-passthrough branch February 7, 2026 07:48

leaanthony mentioned this pull request Mar 24, 2026

docs(v3): add missing docs for build tags, GTK4, and icon composer #5071

Merged

4 tasks

coderabbitai Bot mentioned this pull request May 9, 2026

feat: Add runtime devtools API with -runtimedevtools flag #5378

Open

This was referenced May 23, 2026

feat(v3:obfuscation): add Garble support with stable binding IDs #5337

Merged

fix(v3/templates): fix generate template to use embedded FS #5503

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat(v3): add -tags flag to wails3 build command#4968

feat(v3): add -tags flag to wails3 build command#4968
leaanthony merged 2 commits into
v3-alphafrom
feature/build-tags-passthrough

leaanthony commented Feb 7, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

coderabbitai Bot commented Feb 7, 2026 •

edited

Loading

Uh oh!

coderabbitai Bot left a comment

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Feb 7, 2026

Uh oh!

Copilot AI Feb 7, 2026

Uh oh!

Copilot AI Feb 7, 2026

Uh oh!

Copilot AI Feb 7, 2026

Uh oh!

cloudflare-workers-and-pages Bot commented Feb 7, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Feb 7, 2026

Uh oh!

Uh oh!

github-actions Bot commented Feb 7, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

leaanthony commented Feb 7, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Usage

Files changed

Test plan

Summary by CodeRabbit

Uh oh!

coderabbitai Bot commented Feb 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Estimated code review effort

Possibly related PRs

Suggested labels

Poem

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Feb 7, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 7, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 7, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 7, 2026

Choose a reason for hiding this comment

Uh oh!

cloudflare-workers-and-pages Bot commented Feb 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Deploying wails with Cloudflare Pages

Uh oh!

github-actions Bot commented Feb 7, 2026

⚠️ Missing Changelog Update

Uh oh!

Uh oh!

github-actions Bot commented Feb 7, 2026

⚠️ Missing Changelog Update

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

leaanthony commented Feb 7, 2026 •

edited by coderabbitai Bot

Loading

coderabbitai Bot commented Feb 7, 2026 •

edited

Loading

cloudflare-workers-and-pages Bot commented Feb 7, 2026 •

edited

Loading