feat(v3): add APP_TAGS, APP_LDFLAGS, APP_CGO_ENABLED build customizat…

[mortenolsrud]

…ion vars

Description

Projects that need custom build tags (e.g. sqlite_fts5 for CGO SQLite), custom ldflags (e.g. -X main.Version=...), or CGO overrides currently must edit platform Taskfiles directly. This creates merge conflicts on every Wails version bump.

Add project-level build customization variables defined in the root Taskfile.yml (user-owned, never overwritten) and consumed by all platform Taskfiles (framework-owned, safely regenerable):

• APP_TAGS — build tags included on every platform and mode
• APP_TAGS_{LINUX,DARWIN,WINDOWS,ANDROID,IOS,SERVER} — platform-specific tags
• APP_LDFLAGS — linker flags appended to all builds
• APP_CGO_ENABLED — optional CGO override (empty = platform default)
• EXTRA_TAGS — unchanged semantics (per-invocation CLI override)

All variables are env-overridable for ad-hoc builds (APP_TAGS="extra" task build). Empty values produce no change from current behavior (fully backwards compatible).

Also adds EXTRA_TAGS + APP_* support to Android and iOS Taskfiles, which previously had no user-extensible tag mechanism.

Desktop dev builds now always emit -tags dev (matching mobile pattern) to simplify the conditional logic.

Type of change

• 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?

Verified on a production Wails Android app that uses APP_TAGS: "sqlite_fts5,sqlite_foreign_keys" and APP_LDFLAGS: "-X main.Version=1.0.0":

1. task build — tags correctly appear in go build invocation
2. task android:build — Android build includes APP_TAGS + APP_TAGS_ANDROID
3. EXTRA_TAGS="debug_sql" task build — env override composes correctly
4. Empty APP_* vars — build behavior identical to before (backwards compat)
5. Existing EXTRA_TAGS usage unchanged

• Windows
• macOS
• Linux

Linux: Ubuntu 22.04.5 LTS

Test Configuration

Wails v3.0.0-alpha2.111
Go 1.26.4
Ubuntu 22.04.5 LTS
go-task v3.x

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 customizable global and platform-specific build tags, linker flags, and CGO settings.
  • Added support for extra tags and configurable build options across native and Docker targets.
  • Enhanced Android, iOS, Linux, macOS, Windows, and server builds for development, production, and obfuscated configurations.
• Documentation
  • Documented customization options, precedence rules, defaults, migration steps, and platform limitations.
• Tests
  • Added coverage for build flags, CGO handling, Docker propagation, and configuration overrides.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

Walkthrough

The build templates add shared variables for Go tags, linker flags, and CGO settings. Server, mobile, native, and Docker builds now apply these variables. Tests and documentation cover propagation, precedence, and platform behavior.

Changes

Build customization

Layer / File(s)	Summary
Shared customization contract v3/internal/templates/_common/Taskfile.tmpl.yml, v3/internal/templates/taskfile_template_test.go	Adds application and platform build variables. Tests verify environment preservation, CLI overrides, and empty defaults.
Server and mobile build flags v3/internal/commands/build_assets/Taskfile.tmpl.yml, v3/internal/commands/build_assets/android/Taskfile.yml, v3/internal/commands/build_assets/ios/Taskfile.yml	Builds now compose configurable tags, linker flags, CGO settings, and binding-generation flags.
Native platform flags v3/internal/commands/build_assets/darwin/Taskfile.yml, v3/internal/commands/build_assets/linux/Taskfile.yml, v3/internal/commands/build_assets/windows/Taskfile.yml	Native builds resolve effective CGO settings and apply platform, application, extra, obfuscation, and linker flags.
Docker propagation v3/internal/commands/build_assets/docker/*, v3/internal/commands/build_assets/{darwin,linux,windows}/Taskfile.yml	Docker builds receive customization values and construct matching production build flags.
Validation and documentation v3/internal/commands/taskfile_build_customization_test.go, v3/internal/commands/taskfile_obfuscation_test.go, docs/src/content/docs/guides/build/customization.mdx	Tests and documentation cover customization syntax, precedence, CGO behavior, Docker propagation, and migration.

Estimated code review effort: 4 (Complex) | ~45 minutes

Possibly related PRs

• wailsapp/wails#5695: Updates overlapping server build and Dockerfile logic.
• wailsapp/wails#4968: Adds related extra Go build-tag handling.
• wailsapp/wails#4023: Modifies related binding-generation and build-flag propagation.

Suggested labels: Enhancement, go

Suggested reviewers: leaanthony

Poem

I’m a rabbit with flags in my pack,
Tags and linker bits neatly stacked.
CGO hops in line,
Through Docker they shine,
While builds follow each track.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 7.69% 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 clearly identifies the main change: adding APP_TAGS, APP_LDFLAGS, and APP_CGO_ENABLED build customization.
Description check	✅ Passed	The description covers motivation, implementation, testing, configuration, and most checklist items, although documentation and test checkboxes are inconsistent.
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.

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

[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/windows/Taskfile.yml`:
- Around line 60-63: Update the build dispatch logic to compute one effective
CGO-enabled value by preferring APP_CGO_ENABLED over CGO_ENABLED before
selecting build:native or build:docker. Reuse that same effective value for the
native build environment’s CGO_ENABLED setting, ensuring APP_CGO_ENABLED=1
routes through Docker and APP_CGO_ENABLED=0 overrides CGO_ENABLED=1.

🪄 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 Plus

Run ID: 559bec92-1930-4f38-ab7e-5849058de0ee

📥 Commits

Reviewing files that changed from the base of the PR and between e63d2bd and 70fe920.

📒 Files selected for processing (7)

• v3/internal/commands/build_assets/Taskfile.tmpl.yml
• v3/internal/commands/build_assets/android/Taskfile.yml
• v3/internal/commands/build_assets/darwin/Taskfile.yml
• v3/internal/commands/build_assets/ios/Taskfile.yml
• v3/internal/commands/build_assets/linux/Taskfile.yml
• v3/internal/commands/build_assets/windows/Taskfile.yml
• v3/internal/templates/_common/Taskfile.tmpl.yml

[Copilot]

🟡 Changes recommended

The server Taskfile template incorrectly references EXTRA_TAGS inside a with block (breaking extra tags), and APP_CGO_ENABLED handling won’t honor a YAML numeric 0 override due to falsey checks.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

This review doesn't count toward merge requirements. Sign up for the private preview to control whether Copilot approvals count.

Pull request overview

Adds project-level, env-overridable build customization variables (tags, ldflags, and CGO override) to avoid editing platform Taskfiles directly, and threads those variables through all platform/server build Taskfiles while standardizing desktop dev builds to always include -tags dev.

Changes:

• Introduces root Taskfile variables APP_TAGS*, APP_LDFLAGS, and APP_CGO_ENABLED for additive build customization.
• Updates platform Taskfiles (Windows/Linux/macOS/Android/iOS) and server build template to compose APP_* with existing tag/ldflag behavior.
• Adjusts Windows build dispatch to resolve an “effective” CGO setting before choosing native vs Docker build.

File summaries

File	Description
v3/internal/templates/_common/Taskfile.tmpl.yml	Adds user-owned build customization vars (APP_TAGS*, APP_LDFLAGS, APP_CGO_ENABLED) to the root Taskfile template.
v3/internal/commands/build_assets/windows/Taskfile.yml	Composes APP_TAGS*/APP_LDFLAGS into build flags and introduces effective CGO resolution for docker/native dispatch.
v3/internal/commands/build_assets/linux/Taskfile.yml	Composes APP_TAGS*/APP_LDFLAGS into build flags and adds APP_CGO_ENABLED override support.
v3/internal/commands/build_assets/darwin/Taskfile.yml	Composes APP_TAGS*/APP_LDFLAGS into build flags and adds APP_CGO_ENABLED override support.
v3/internal/commands/build_assets/android/Taskfile.yml	Adds APP_TAGS* + APP_LDFLAGS composition for Android builds.
v3/internal/commands/build_assets/ios/Taskfile.yml	Adds APP_TAGS* + APP_LDFLAGS composition for iOS builds.
v3/internal/commands/build_assets/Taskfile.tmpl.yml	Extends server build flags template to include APP_TAGS*/APP_LDFLAGS/EXTRA_TAGS.

Review details

Suppressed comments (1)

v3/internal/commands/build_assets/windows/Taskfile.yml:69

• CGO_ENABLED is derived with if .APP_CGO_ENABLED, so a YAML numeric APP_CGO_ENABLED: 0 will be ignored (treated as false) and the environment will fall back to the default. This breaks the intended “override CGO_ENABLED” behavior for disabling CGO.

      GOOS: windows
      CGO_ENABLED: '{{if .APP_CGO_ENABLED}}{{.APP_CGO_ENABLED}}{{else}}{{.CGO_ENABLED | default "0"}}{{end}}'
      GOARCH: '{{.ARCH | default ARCH}}'

• Files reviewed: 7/7 changed files
• Comments generated: 4
• Review effort level: Lite

We're testing this review assessment. Please use 👍 or 👎 to tell us if it's correct.

[coderabbitai]

Note

GitHub couldn't provide a complete incremental comparison for this pull request, so CodeRabbit is performing a full review instead. This review may take a little longer.

[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/windows/Taskfile.yml`:
- Line 104: Update the EFFECTIVE_CGO_ENABLED fallback in the Windows Docker
build task to default to "0" instead of "1", matching the existing Windows task
defaults while preserving explicit APP_CGO_ENABLED and CGO_ENABLED overrides.

🪄 Autofix

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 Plus

Run ID: 5dacd80f-e86a-42ca-a0d0-a8478af20fc8

📥 Commits

Reviewing files that changed from the base of the PR and between f80dad5 and 5ca2b20.

📒 Files selected for processing (13)

• docs/src/content/docs/guides/build/customization.mdx
• v3/internal/commands/build_assets/Taskfile.tmpl.yml
• v3/internal/commands/build_assets/android/Taskfile.yml
• v3/internal/commands/build_assets/darwin/Taskfile.yml
• v3/internal/commands/build_assets/docker/Dockerfile.cross
• v3/internal/commands/build_assets/docker/Dockerfile.server
• v3/internal/commands/build_assets/ios/Taskfile.yml
• v3/internal/commands/build_assets/linux/Taskfile.yml
• v3/internal/commands/build_assets/windows/Taskfile.yml
• v3/internal/commands/taskfile_build_customization_test.go
• v3/internal/commands/taskfile_obfuscation_test.go
• v3/internal/templates/_common/Taskfile.tmpl.yml
• v3/internal/templates/taskfile_template_test.go

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

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