6.7 KiB
Introduction
!!! note This guide is a work in progress.
Thanks for wanting to help out with development of Wails! This guide will help you get started.
Getting Started
-
Git clone this repository. Checkout the
v3-alphabranch. -
Install the CLI:
cd v3/cmd/wails3 && go install -
Optional: If you are wanting to use the build system to build frontend code, you will need to install npm.
Building
For simple programs, you can use the standard go build command. It's also possible to use go run.
Wails also comes with a build system that can be used to build more complex projects. It utilises the awesome Task build system.
For more information, check out the task homepage or run wails task --help.
Project layout
The project has the following structure:
```
v3
├── cmd/wails3 // CLI
├── examples // Examples of Wails apps
├── internal // Internal packages
| ├── runtime // The Wails JS runtime
| └── templates // The supported project templates
├── pkg
| ├── application // The core Wails library
| └── events // The event definitions
| └── mac // macOS specific code used by plugins
| └── w32 // Windows specific code
├── plugins // Supported plugins
├── tasks // General tasks
└── Taskfile.yaml // Development tasks configuration
```
Development
Adding window functionality
The preferred way to add window functionality is to add a new function to the pkg/application/webview_window.go file. This should implement all the functionality required for all platforms. Any platform specific code should be called via a webviewWindowImpl interface method. This interface is implemented by each of the target platforms to provide the platform specific functionality. In some cases, this may do nothing.
Once you've added the interface method, ensure each platform implements it. A good example of this is the SetMinSize method.
- Mac:
webview_window_darwin.go - Windows:
webview_window_windows.go - Linux:
webview_window_linux.go
Most, if not all, of the platform specific code should be run on the main thread. To simplify this, there are a number of invokeSync methods defined in application.go.
Updating the runtime
The runtime is located in v3/internal/runtime. When the runtime is updated, the following steps need to be taken:
wails3 task runtime:build
Events
Events are defined in v3/pkg/events. When adding a new event, the following steps need to be taken:
- Add the event to the
events.txtfile - Run
wails3 task events:generate
There are a number of types of events: platform specific application and window events + common events. The common events are useful for cross-platform event handling, but you aren't limited to the "lowest common denominator". You can use the platform specific events if you need to.
When adding a common event, ensure that the platform specific events are mapped. An example of this is in window_webview_darwin.go:
// Translate ShouldClose to common WindowClosing event
w.parent.On(events.Mac.WindowShouldClose, func(_ *WindowEventContext) {
w.parent.emit(events.Common.WindowClosing)
})
NOTE: We may try to automate this in the future by adding the mapping to the event definition.
Plugins
Plugins are a way to extend the functionality of your Wails application.
Creating a plugin
Plugins are standard Go structure that adhere to the following interface:
type Plugin interface {
Name() string
Init(*application.App) error
Shutdown()
CallableByJS() []string
InjectJS() string
}
The Name() method returns the name of the plugin. This is used for logging purposes.
The Init(*application.App) error method is called when the plugin is loaded. The *application.App
parameter is the application that the plugin is being loaded into. Any errors will prevent
the application from starting.
The Shutdown() method is called when the application is shutting down.
The CallableByJS() method returns a list of exported functions that can be called from
the frontend. These method names must exactly match the names of the methods exported
by the plugin.
The InjectJS() method returns JavaScript that should be injected into all windows as they are created. This is useful for adding custom JavaScript functions that complement the plugin.
Misc Tasks
Upgrading Taskfile
The Wails CLI uses the Task build system. It is imported as a library and used to run the tasks defined in Taskfile.yaml.
The main interfacing with Task happens in v3/internal/commands/task.go.
To check if there's an upgrade for Taskfile, run wails3 task -version and check against the Task website.
To upgrade the version of Taskfile used, run:
wails3 task taskfile:upgrade
If there are incompatibilities then they should appear in the v3/internal/commands/task.go file.
Usually the best way to fix incompatibilities is to clone the task repo at https://github.com/go-task/task and look at the git history to determine what has changed and why.
To check all changes have worked correctly, re-install the CLI and check the version again:
wails3 task cli:install
wails3 task -version
Opening a PR
Make sure that all PRs have a ticket associated with them providing context to the change. If there is no ticket, please create one first.
Ensure that all PRs have updated the CHANGELOG.md file with the changes made. The CHANGELOG.md file is located in the v3 directory.
Misc Tasks
Upgrading Taskfile
The Wails CLI uses the Task build system. It is imported as a library and used to run the tasks defined in Taskfile.yaml.
The main interfacing with Task happens in v3/internal/commands/task.go.
To check if there's an upgrade for Taskfile, run wails3 task -version and check against the Task website.
To upgrade the version of Taskfile used, run:
wails3 task taskfile:upgrade
If there are incompatibilities then they should appear in the v3/internal/commands/task.go file.
Usually the best way to fix incompatibilities is to clone the task repo at https://github.com/go-task/task and look at the git history to determine what has changed and why.
To check all changes have worked correctly, re-install the CLI and check the version again:
wails3 task cli:install
wails3 task -version