docs(v3): add missing docs for build tags, GTK4, and icon composer by leaanthony · Pull Request #5071 · wailsapp/wails

leaanthony · 2026-03-24T13:17:34Z

Summary

CLI reference: Document the -tags flag on wails3 build command and the -iconcomposerinput/-macassetdir flags on wails3 generate icons
Building guide: Add "Custom Build Tags" section explaining -tags gtk4, -tags server, and combined tags
Linux packaging guide: Add comprehensive "GTK4 Support (Experimental)" section with dependency install commands, build instructions, and known behavioral differences from GTK3
Installation guide: Add note about optional GTK4 dependencies for Linux users

These gaps were identified by cross-referencing recent v3-alpha PRs (#4958 GTK4 support, #4968 -tags flag, #4934 icon composer) against the existing documentation.

Test plan

Verify docs site builds without errors
Check internal links resolve correctly (GTK4 section anchors, cross-references to dialogs/window reference)
Verify -tags flag examples match actual CLI behavior

🤖 Generated with Claude Code

Summary by CodeRabbit

New Features
- Added experimental GTK4/WebKitGTK 6.0 support for Linux builds
- Added Icon Composer support for macOS icon generation
- Introduced -tags flag for custom Go build tags
Documentation
- New GTK4 setup guide with dependency instructions and feature documentation
- New Icon Composer configuration and usage guide for macOS
- Updated build and CLI documentation with new capabilities
- Added optional GTK4 dependency notes to installation guide

…mposer Document the -tags flag for wails3 build (CLI reference + building guide), add GTK4 experimental support guide with dependencies and known differences, and document the -iconcomposerinput/-macassetdir flags for icon generation. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

cloudflare-workers-and-pages · 2026-03-24T13:17:53Z

Deploying wails with Cloudflare Pages

Latest commit:	`5f8971e`
Status:	🚫 Build failed.

View logs

github-actions · 2026-03-24T13:17:57Z

⚠️ 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.

coderabbitai · 2026-03-24T13:18:06Z

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: 15d31a6f-727f-4563-a603-fc6b4a4f13d7

📥 Commits

Reviewing files that changed from the base of the PR and between bb4fbf9 and 5f8971e.

📒 Files selected for processing (4)

docs/src/content/docs/guides/build/building.mdx
docs/src/content/docs/guides/build/linux.mdx
docs/src/content/docs/guides/cli.mdx
docs/src/content/docs/quick-start/installation.mdx

Walkthrough

Documentation updates across four guides adding support for custom Go build tags via the -tags CLI flag and comprehensive GTK4 support guidance. Changes include build tag syntax documentation, Icon Composer procedures for macOS icon generation, and Linux GTK4/WebKitGTK 6.0 setup instructions with behavioral differences.

Changes

Cohort / File(s)	Summary
Build Tags Documentation `docs/src/content/docs/guides/build/building.mdx`, `docs/src/content/docs/guides/cli.mdx`, `docs/src/content/docs/quick-start/installation.mdx`	Added `-tags` flag documentation for `wails3 build`, explaining comma-separated tag syntax and how tags are forwarded to Taskfile via `EXTRA_TAGS` environment variable. Includes examples for single and multiple tags.
GTK4 Support Guide `docs/src/content/docs/guides/build/linux.mdx`, `docs/src/content/docs/quick-start/installation.mdx`	Added comprehensive GTK4/WebKitGTK 6.0 experimental support documentation with dependency installation instructions, build commands using `-tags gtk4`, behavioral differences from GTK3 (file dialogs, menu styles, DPI scaling), and diagnostic guidance via `wails3 doctor`.
Icon Composer (macOS) `docs/src/content/docs/guides/cli.mdx`	Added new macOS Icon Composer documentation with `-iconcomposerinput` and `-macassetdir` flags, instructions for generating `Assets.car` and `icons.icns` using Apple's `actool`, and `cfBundleIconName` configuration guidance.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related issues

[Feedback Wanted] Experimental GTK4 + WebKitGTK 6.0 Support #4957: The GTK4 support documentation and -tags gtk4 build flag directly address the GTK4 support tracking issue.

Possibly related PRs

Add support for build tags to the wails project schema and update pro… #4439: Implements Go build tag parsing and merging logic that the documentation now describes for users.
feat(v3): add -tags flag to wails3 build command #4968: Contains code changes adding the -tags CLI flag and EXTRA_TAGS propagation that these docs document.

Suggested labels

Documentation, size:S

Poem

🐰 Hops through the docs with glee,
Build tags now flow so free,
GTK4 shines bright and true,
Icons composed, macOS too!
Thump thump — onward we go! 🎨

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The description covers the purpose and scope of changes, but lacks required elements including issue linkage, type selection checkboxes, and testing verification.	Add 'Fixes #' reference, select change type checkbox, verify testing platforms, and complete the changelog and checklist sections per template requirements.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately summarizes the main documentation additions across multiple guides: build tags, GTK4 support, and icon composer features.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

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

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch docs/v3-alpha-documentation-updates

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.}

Copilot

Pull request overview

This PR closes documentation gaps in the v3 docs around passing custom build tags, enabling experimental Linux GTK4 builds, and generating macOS Icon Composer-based icons, aligning the docs with recent v3-alpha feature work.

Changes:

Documented wails3 build -tags usage and how tags flow into Taskfiles.
Added “Custom Build Tags” guidance (GTK4/server examples) and a new “GTK4 Support (Experimental)” section in Linux packaging docs.
Expanded CLI docs for wails3 generate icons with Icon Composer / macOS asset catalog flags and usage.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 1 comment.

File	Description
docs/src/content/docs/quick-start/installation.mdx	Adds an installation note pointing Linux users to optional GTK4/WebKitGTK 6.0 setup and build tag usage.
docs/src/content/docs/guides/cli.mdx	Documents `-tags` on `wails3 build` and adds Icon Composer / macOS asset generation flags and guidance for `generate icons`.
docs/src/content/docs/guides/build/linux.mdx	Adds a comprehensive GTK4 (experimental) section: dependencies, build commands, and behavioral differences vs GTK3.
docs/src/content/docs/guides/build/building.mdx	Adds a “Custom Build Tags” section with examples and links to related guides.

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

Copilot · 2026-03-24T13:24:51Z

docs/src/content/docs/quick-start/installation.mdx

+       :::note[Optional: GTK4 Support]
+       Wails also has experimental GTK4 / WebKitGTK 6.0 support. If you want to build with GTK4, install the additional dependencies for your distribution and build with `wails3 build -tags gtk4`. See [Linux Packaging - GTK4](/guides/build/linux#gtk4-support-experimental) for details.
+       :::


This page’s Linux dependency snippets above still install WebKit2GTK 4.0 dev packages (e.g. libwebkit2gtk-4.0-dev / webkit2gtk4.0-devel), but v3’s Linux build uses pkg-config webkit2gtk-4.1 (and wails3 doctor recommends the 4.1 dev packages). Please update the earlier distro install commands to 4.1 so the quick-start instructions match actual build requirements.

Copilot AI review requested due to automatic review settings March 24, 2026 13:17

Copilot started reviewing on behalf of leaanthony March 24, 2026 13:18 View session

Copilot AI reviewed Mar 24, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

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

docs(v3): add missing docs for build tags, GTK4, and icon composer#5071
leaanthony wants to merge 1 commit intov3-alphafrom
docs/v3-alpha-documentation-updates

leaanthony commented Mar 24, 2026 •

edited by coderabbitai bot

Loading

Uh oh!

cloudflare-workers-and-pages bot commented Mar 24, 2026

Uh oh!

github-actions bot commented Mar 24, 2026

Uh oh!

coderabbitai bot commented Mar 24, 2026 •

edited

Loading

❌ Failed checks (1 warning)

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Mar 24, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

leaanthony commented Mar 24, 2026 • edited by coderabbitai bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Test plan

Summary by CodeRabbit

Uh oh!

cloudflare-workers-and-pages bot commented Mar 24, 2026

Deploying wails with Cloudflare Pages

Uh oh!

github-actions bot commented Mar 24, 2026

⚠️ Missing Changelog Update

Uh oh!

coderabbitai bot commented Mar 24, 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 issues

Possibly related PRs

Suggested labels

Poem

❌ Failed checks (1 warning)

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Mar 24, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

leaanthony commented Mar 24, 2026 •

edited by coderabbitai bot

Loading

coderabbitai bot commented Mar 24, 2026 •

edited

Loading