From ff8759263165a250c8423e1d7aaba45e09ed2fd1 Mon Sep 17 00:00:00 2001 From: Lea Anthony Date: Sun, 8 Feb 2026 21:40:47 +1100 Subject: [PATCH] docs: third-pass final stragglers - logger, dialog method, FAQ fixes - concepts/bridge.mdx: Fixed logger to use slog (not fabricated application.NewDefaultLogger/logger.DEBUG) - concepts/manager-api.mdx: Fixed SetDefaultFilename -> SetFilename - faq.mdx: Fixed build output dir, removed fabricated -platform flag, corrected binary size reduction advice Co-Authored-By: Claude Opus 4.6 --- docs/src/content/docs/concepts/bridge.mdx | 6 +- .../src/content/docs/concepts/manager-api.mdx | 2 +- .../docs/contributing/build-packaging.mdx | 29 ++- .../docs/contributing/extending-wails.mdx | 6 +- .../content/docs/contributing/testing-ci.mdx | 2 +- docs/src/content/docs/faq.mdx | 18 +- .../docs/features/bindings/best-practices.mdx | 3 +- .../content/docs/features/dialogs/custom.mdx | 6 +- .../content/docs/guides/cross-platform.mdx | 185 +++++------------- .../docs/guides/customising-windows.mdx | 6 +- docs/src/content/docs/guides/gin-services.mdx | 2 +- docs/src/content/docs/guides/performance.mdx | 6 +- docs/src/content/docs/migration/v2-to-v3.mdx | 9 +- 13 files changed, 94 insertions(+), 186 deletions(-) diff --git a/docs/src/content/docs/concepts/bridge.mdx b/docs/src/content/docs/concepts/bridge.mdx index 7593d896a..6b38cecb0 100644 --- a/docs/src/content/docs/concepts/bridge.mdx +++ b/docs/src/content/docs/concepts/bridge.mdx @@ -612,10 +612,12 @@ func ProcessItems(items []Item) ([]Result, error) { ### Enable Debug Logging ```go +import "log/slog" + app := application.New(application.Options{ Name: "My App", - Logger: application.NewDefaultLogger(), - LogLevel: logger.DEBUG, + Logger: application.DefaultLogger(slog.LevelDebug), + LogLevel: slog.LevelDebug, }) ``` diff --git a/docs/src/content/docs/concepts/manager-api.mdx b/docs/src/content/docs/concepts/manager-api.mdx index f65eef733..e67111841 100644 --- a/docs/src/content/docs/concepts/manager-api.mdx +++ b/docs/src/content/docs/concepts/manager-api.mdx @@ -136,7 +136,7 @@ result, err := app.Dialog.OpenFile(). PromptForSingleSelection() result, err = app.Dialog.SaveFile(). - SetDefaultFilename("document.txt"). + SetFilename("document.txt"). PromptForSingleSelection() // Message dialogs diff --git a/docs/src/content/docs/contributing/build-packaging.mdx b/docs/src/content/docs/contributing/build-packaging.mdx index 78878200e..6f80f6b71 100644 --- a/docs/src/content/docs/contributing/build-packaging.mdx +++ b/docs/src/content/docs/contributing/build-packaging.mdx @@ -84,9 +84,7 @@ time then injects them using `go build -ldflags`. | macOS | amd64 / arm64 | `darwin` | cgo enabled (Objective-C) | Codesign & notarisation tasks available | | Linux | amd64 / arm64 | `linux` | pure Go (webkit option) | GTK/WebKitGTK headers required for CGO build | -`wails3 build -platform darwin/arm64` overrides GOOS/GOARCH. -If CGO is needed on the host that can't compile the target (e.g. building -Windows from Linux), the CLI falls back to **Docker** images (`ghcr.io/wailsapp/cross-compiler`). +Cross-compilation is done by setting `GOOS` and `GOARCH` environment variables. If CGO is needed on the host that can't compile the target (e.g. building Windows from Linux), a cross-compiler toolchain (like `mingw-w64`) is required. --- @@ -120,11 +118,11 @@ Task targets: `sign:mac`, `sign:windows`. | **AppImage** (default) | `internal/commands/appimage.go` | `linuxdeploy` + `linuxdeploy-plugin-gtk` | | **deb / rpm / pacman** | `internal/packager` | `fpm` (invoked via Go) | -Flags: +Linux packages can be generated using `wails3 tool package`: ``` -wails3 build -package deb # produces myapp_1.0.0_amd64.deb -wails3 build -package rpm +wails3 tool package -format deb -name myapp -config build/linux/nfpm/nfpm.yaml +wails3 tool package -format rpm -name myapp -config build/linux/nfpm/nfpm.yaml ``` ### macOS @@ -151,15 +149,12 @@ Extra resources: After a successful build the CLI prints: ``` -build/bin/ -├── myapp-linux-amd64 -└── myapp-linux-amd64.AppImage - -build/package/ -└── myapp_1.0.0_amd64.deb +bin/ +├── myapp +└── myapp.AppImage ``` -The exact files depend on `-platform` and `-package` flags. +The exact files depend on the platform and the tasks executed. --- @@ -168,9 +163,9 @@ The exact files depend on `-platform` and `-package` flags. | Need | Approach | |------|----------| | Run a linter before build | Add a `lint` task in **Taskfile.yml** and make `build` depend on it. | -| Extra linker flags | `wails3 build -ldflags "-H windowsgui"` | -| Skip packaging | `wails3 build -skip-package` (keeps raw binary). | -| Bring your own packager | Implement `internal/packager/.go`, register in `packager.go`. | +| Extra linker flags | Add `-ldflags` to the `go build` command in your platform Taskfile. | +| Skip packaging | Run `wails3 build` instead of `wails3 package` to get a raw binary. | +| Bring your own packager | Add custom packaging tasks to your platform Taskfile. | All Taskfile targets use environment variables exported by the CLI, so you can reference values like `$WAILS_VERSION` or `$WAILS_PLATFORM` inside custom tasks. @@ -186,7 +181,7 @@ reference values like `$WAILS_VERSION` or `$WAILS_PLATFORM` inside custom tasks. | **`wixl` not found** (Linux MSI cross-build) | WiX toolset not installed in Docker image | Use `--docker` build or install WiX manually. | | **Duplicated symbol `_WinMain`** | Mixed `windowsgui` flag and syso | Remove custom `-ldflags` or let Wails manage resources. | -Verbose mode: `wails3 build -verbose` dumps every command executed. +For verbose output, use `wails3 task -v build` to see every command executed. --- diff --git a/docs/src/content/docs/contributing/extending-wails.mdx b/docs/src/content/docs/contributing/extending-wails.mdx index ffff66b77..4a94147ef 100644 --- a/docs/src/content/docs/contributing/extending-wails.mdx +++ b/docs/src/content/docs/contributing/extending-wails.mdx @@ -210,9 +210,9 @@ Example: **Wayland** clipboard on Linux. ## 6. Debug Builds & Iteration Speed -* `wails3 dev -tags debug` adds extra log hooks (`logger_dev*.go`). -* Use `task reload` to rebuild runtime without restarting the whole app. -* Race detector: `wails3 dev -race` (see `pkg/application/RACE.md`). +* `wails3 build -tags debug` adds extra log hooks (`logger_dev*.go`). +* Use `wails3 task reload` to rebuild runtime without restarting the whole app. +* Race detector: add `-race` to the `go build` command in your Taskfile (see `pkg/application/RACE.md`). --- diff --git a/docs/src/content/docs/contributing/testing-ci.mdx b/docs/src/content/docs/contributing/testing-ci.mdx index 819afe324..e9f2d86e4 100644 --- a/docs/src/content/docs/contributing/testing-ci.mdx +++ b/docs/src/content/docs/contributing/testing-ci.mdx @@ -136,7 +136,7 @@ Key features: 1. `setup-go` @ 1.25 2. `go vet ./...` 3. `go test ./... -v -coverprofile=cover.out` - 4. Build CLI + sample app (`wails3 build -skip-package`) + 4. Build CLI + sample app (`wails3 build`) 5. Upload coverage to Codecov * Conditional **race** job on Ubuntu: ```yaml diff --git a/docs/src/content/docs/faq.mdx b/docs/src/content/docs/faq.mdx index 3e0a6bd17..19f78be18 100644 --- a/docs/src/content/docs/faq.mdx +++ b/docs/src/content/docs/faq.mdx @@ -33,7 +33,7 @@ Yes! Wails v3 is suitable for production applications. Many companies use Wails - Windows (7+) - macOS (10.13+) -- Linux (GTK3) +- Linux (GTK3 and GTK4) ## Development @@ -85,16 +85,15 @@ Use your browser's dev tools: wails3 build ``` -Your application will be in `build/bin/`. +Your application will be in `bin/`. ### Can I cross-compile? -Yes! Build for other platforms: +Cross-compilation is controlled by setting the `GOOS` and `GOARCH` environment variables. Note that CGo cross-compilation may require additional tooling: ```bash -wails3 build -platform windows/amd64 -wails3 build -platform darwin/universal -wails3 build -platform linux/amd64 +GOOS=windows GOARCH=amd64 wails3 build +GOOS=linux GOARCH=amd64 wails3 build ``` ### How do I create an installer? @@ -155,10 +154,10 @@ Wails doesn't include auto-update functionality, but you can implement it yourse ### Why is my binary large? -Go binaries include the runtime. Reduce size: +Go binaries include the runtime. The default Taskfiles already include `-ldflags "-s -w"` to strip debug symbols. You can further reduce size with UPX compression: ```bash -wails3 build -ldflags "-s -w" +upx --best bin/myapp ``` ### How do I improve performance? @@ -207,7 +206,8 @@ Ensure event names match exactly: app.Event.Emit("my-event", data) // JavaScript -OnEvent("my-event", handler) // Must match +import { Events } from '@wailsio/runtime' +Events.On("my-event", handler) // Must match ``` ### Build fails diff --git a/docs/src/content/docs/features/bindings/best-practices.mdx b/docs/src/content/docs/features/bindings/best-practices.mdx index 5b2d71d8d..2da45c5a6 100644 --- a/docs/src/content/docs/features/bindings/best-practices.mdx +++ b/docs/src/content/docs/features/bindings/best-practices.mdx @@ -285,7 +285,8 @@ func (s *Service) ProcessLargeFile(path string) error { } // JavaScript listens -OnEvent("progress", (data) => { +import { Events } from '@wailsio/runtime' +Events.On("progress", (data) => { updateProgress(data.percent) }) ``` diff --git a/docs/src/content/docs/features/dialogs/custom.mdx b/docs/src/content/docs/features/dialogs/custom.mdx index bce087343..8eede0344 100644 --- a/docs/src/content/docs/features/dialogs/custom.mdx +++ b/docs/src/content/docs/features/dialogs/custom.mdx @@ -199,14 +199,14 @@ func ShowConfirmdialog(message string) bool { ``` diff --git a/docs/src/content/docs/guides/cross-platform.mdx b/docs/src/content/docs/guides/cross-platform.mdx index 190a2a11f..3b51da037 100644 --- a/docs/src/content/docs/guides/cross-platform.mdx +++ b/docs/src/content/docs/guides/cross-platform.mdx @@ -7,146 +7,67 @@ sidebar: ## Overview -Wails supports cross-platform compilation, allowing you to build for Windows, macOS, and Linux from any platform. +Wails supports building for Windows, macOS, and Linux. The build process is driven by platform-specific Taskfiles that handle the details of compilation, icon generation, and packaging for each platform. ## Supported Platforms -```bash -# List available platforms -wails3 build -platform list +Wails supports the following target platforms: +- `windows/amd64`, `windows/arm64` +- `darwin/amd64`, `darwin/arm64` (universal binaries via `wails3 tool lipo`) +- `linux/amd64`, `linux/arm64` -# Common platforms: -# - windows/amd64 -# - darwin/amd64 -# - darwin/arm64 -# - darwin/universal -# - linux/amd64 -# - linux/arm64 +## How It Works + +When you run `wails3 build`, the main `Taskfile.yml` dispatches to the platform-specific Taskfile based on the current OS using `{{OS}}`: + +```yaml +tasks: + build: + cmds: + - task: "{{OS}}:build" ``` -## Building for Windows +Each platform Taskfile (in `build//Taskfile.yml`) handles the compilation with the appropriate flags and environment variables. -### From macOS/Linux +## Cross-Compilation + +To cross-compile, set the `GOOS` and `GOARCH` environment variables. Note that CGo cross-compilation may require additional tooling (e.g., a cross-compiler like `mingw-w64` for Windows builds from Linux/macOS). + +### Building for Windows from macOS/Linux ```bash -# Install dependencies (one-time) +# Install cross-compiler (one-time) # macOS: brew install mingw-w64 # Linux: apt-get install mingw-w64 -# Build for Windows -wails3 build -platform windows/amd64 +# Cross-compile +GOOS=windows GOARCH=amd64 go build -o myapp.exe ``` -### Windows-Specific Options +### Building for Linux from macOS/Windows ```bash -# With custom icon -wails3 build -platform windows/amd64 -icon app.ico - -# Console application -wails3 build -platform windows/amd64 -windowsconsole - -# With manifest -wails3 build -platform windows/amd64 -manifest app.manifest +GOOS=linux GOARCH=amd64 go build -o myapp ``` -## Building for macOS +### macOS Builds -### From Windows/Linux +macOS builds are best done on macOS due to code signing and notarization requirements. The macOS Taskfile supports building for different architectures: ```bash -# Note: macOS builds from other platforms have limitations -# Recommended: Use macOS for macOS builds +# Build for the current architecture +wails3 build -# Build for Intel Macs -wails3 build -platform darwin/amd64 - -# Build for Apple Silicon -wails3 build -platform darwin/arm64 - -# Universal binary (both architectures) -wails3 build -platform darwin/universal -``` - -### macOS-Specific Options - -```bash -# With custom icon -wails3 build -platform darwin/universal -icon app.icns - -# Code signing (macOS only) -wails3 build -platform darwin/universal -codesign "Developer ID" -``` - -## Building for Linux - -### From Any Platform - -```bash -# Build for Linux AMD64 -wails3 build -platform linux/amd64 - -# Build for Linux ARM64 -wails3 build -platform linux/arm64 -``` - -### Linux-Specific Options - -```bash -# With custom icon -wails3 build -platform linux/amd64 -icon app.png -``` - -## Build Matrix - -### Build All Platforms - -```bash -#!/bin/bash -# build-all.sh - -platforms=("windows/amd64" "darwin/universal" "linux/amd64") - -for platform in "${platforms[@]}"; do - echo "Building for $platform..." - wails3 build -platform "$platform" -o "dist/myapp-$platform" -done -``` - -### Using Taskfile - -```yaml -# Taskfile.yml -version: '3' - -tasks: - build:all: - desc: Build for all platforms - cmds: - - task: build:windows - - task: build:macos - - task: build:linux - - build:windows: - desc: Build for Windows - cmds: - - wails3 build -platform windows/amd64 -o dist/myapp-windows.exe - - build:macos: - desc: Build for macOS - cmds: - - wails3 build -platform darwin/universal -o dist/myapp-macos - - build:linux: - desc: Build for Linux - cmds: - - wails3 build -platform linux/amd64 -o dist/myapp-linux +# Create a universal binary using tool lipo +wails3 tool lipo -i bin/myapp-amd64 -i bin/myapp-arm64 -output bin/myapp-universal ``` ## CI/CD Integration ### GitHub Actions +The recommended approach for cross-platform builds is to use CI/CD with platform-specific runners: + ```yaml name: Build @@ -158,45 +79,35 @@ jobs: matrix: os: [ubuntu-latest, macos-latest, windows-latest] runs-on: ${{ matrix.os }} - + steps: - - uses: actions/checkout@v3 - - - uses: actions/setup-go@v4 + - uses: actions/checkout@v4 + + - uses: actions/setup-go@v5 with: - go-version: '1.21' - + go-version: '1.24' + - name: Install Wails run: go install github.com/wailsapp/wails/v3/cmd/wails3@latest - + - name: Build run: wails3 build - + - name: Upload artifact - uses: actions/upload-artifact@v3 + uses: actions/upload-artifact@v4 with: name: app-${{ matrix.os }} - path: build/bin/ + path: bin/ ``` ## Best Practices -### ✅ Do - -- Test on target platforms -- Use CI/CD for builds -- Version your builds -- Include platform in filename -- Document build requirements - -### ❌ Don't - -- Don't skip testing on target platform -- Don't forget platform-specific icons -- Don't hardcode paths -- Don't ignore build warnings +- **Build on target platform** - Use CI/CD runners matching target OS for reliable builds +- **Test on target platforms** - Cross-compiled binaries should be tested on their target OS +- **Use the Taskfile system** - Customize builds per platform in `build//Taskfile.yml` +- **Version your builds** - Use `-ldflags` in your Taskfile to embed version info ## Next Steps -- [Creating Installers](/guides/installers) - Package your application +- [Build Customization](/guides/build/customization) - Customize the build process - [Building](/guides/building) - Basic building guide diff --git a/docs/src/content/docs/guides/customising-windows.mdx b/docs/src/content/docs/guides/customising-windows.mdx index 915439a28..27f3999b5 100644 --- a/docs/src/content/docs/guides/customising-windows.mdx +++ b/docs/src/content/docs/guides/customising-windows.mdx @@ -69,9 +69,9 @@ You can also change the button states at runtime using the following methods on the `Window` interface: ```go -window.SetMinimiseButtonState(wails.ButtonHidden) -window.SetMaximiseButtonState(wails.ButtonEnabled) -window.SetCloseButtonState(wails.ButtonDisabled) +window.SetMinimiseButtonState(application.ButtonHidden) +window.SetMaximiseButtonState(application.ButtonEnabled) +window.SetCloseButtonState(application.ButtonDisabled) ``` ### Platform Differences diff --git a/docs/src/content/docs/guides/gin-services.mdx b/docs/src/content/docs/guides/gin-services.mdx index 89c4b68f5..515335dea 100644 --- a/docs/src/content/docs/guides/gin-services.mdx +++ b/docs/src/content/docs/guides/gin-services.mdx @@ -140,7 +140,7 @@ func (s *GinService) ServiceStartup(ctx context.Context, options application.Ser } // ServiceShutdown is called when the service shuts down -func (s *GinService) ServiceShutdown(ctx context.Context) error { +func (s *GinService) ServiceShutdown() error { // Clean up resources if needed return nil } diff --git a/docs/src/content/docs/guides/performance.mdx b/docs/src/content/docs/guides/performance.mdx index 1d38a1ef4..c6dd65d77 100644 --- a/docs/src/content/docs/guides/performance.mdx +++ b/docs/src/content/docs/guides/performance.mdx @@ -236,11 +236,9 @@ func (b *BatchProcessor) flush() { ### Binary Size -```bash -# Strip debug symbols -wails3 build -ldflags "-s -w" +The default Taskfiles already include `-ldflags "-s -w"` to strip debug symbols. You can further reduce binary size by adding `-trimpath` to the `go build` command in your Taskfile: -# Reduce binary size further +```bash go build -ldflags="-s -w" -trimpath ``` diff --git a/docs/src/content/docs/migration/v2-to-v3.mdx b/docs/src/content/docs/migration/v2-to-v3.mdx index 8db4f0f6f..4cbea5e72 100644 --- a/docs/src/content/docs/migration/v2-to-v3.mdx +++ b/docs/src/content/docs/migration/v2-to-v3.mdx @@ -456,13 +456,13 @@ EventsOn("update", (data) => { EventsEmit("action", data) // v3 -import { OnEvent, Emit } from '@wailsio/runtime' +import { Events } from '@wailsio/runtime' -OnEvent("update", (data) => { +Events.On("update", (data) => { console.log(data) }) -Emit("action", data) +Events.Emit("action", data) ``` ### Step 6: Update Configuration @@ -619,7 +619,8 @@ Check event names match exactly: app.Event.Emit("my-event", data) // JavaScript -OnEvent("my-event", handler) // Must match exactly +import { Events } from '@wailsio/runtime' +Events.On("my-event", handler) // Must match exactly ``` ## Testing Migration