mirror of
https://github.com/wailsapp/wails.git
synced 2026-03-14 14:45:49 +01:00
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 <noreply@anthropic.com>
This commit is contained in:
Lea Anthony
parent
ce95358854
commit
ff87592631
13 changed files with 92 additions and 184 deletions
|
|
@ -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,
|
||||
})
|
||||
```
|
||||
|
||||
|
|
|
|||
|
|
@ -136,7 +136,7 @@ result, err := app.Dialog.OpenFile().
|
|||
PromptForSingleSelection()
|
||||
|
||||
result, err = app.Dialog.SaveFile().
|
||||
SetDefaultFilename("document.txt").
|
||||
SetFilename("document.txt").
|
||||
PromptForSingleSelection()
|
||||
|
||||
// Message dialogs
|
||||
|
|
|
|||
|
|
@ -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/<name>.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.
|
||||
|
||||
---
|
||||
|
||||
|
|
|
|||
|
|
@ -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`).
|
||||
|
||||
---
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
})
|
||||
```
|
||||
|
|
|
|||
|
|
@ -199,14 +199,14 @@ func ShowConfirmdialog(message string) bool {
|
|||
</div>
|
||||
|
||||
<script>
|
||||
import { OnEvent, Emit } from '@wailsio/runtime'
|
||||
import { Events } from '@wailsio/runtime'
|
||||
|
||||
OnEvent("set-message", (message) => {
|
||||
Events.On("set-message", (message) => {
|
||||
document.getElementById("message").textContent = message
|
||||
})
|
||||
|
||||
function confirm(result) {
|
||||
Emit(result ? "confirm-yes" : "confirm-no")
|
||||
Events.Emit(result ? "confirm-yes" : "confirm-no")
|
||||
}
|
||||
</script>
|
||||
```
|
||||
|
|
|
|||
|
|
@ -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/<platform>/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/<platform>/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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
}
|
||||
|
|
|
|||
|
|
@ -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
|
||||
```
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue