mirror of
https://github.com/wailsapp/wails.git
synced 2025-05-05 02:22:11 +08:00
218 lines
7.0 KiB
Markdown
218 lines
7.0 KiB
Markdown
# 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-alpha` branch.
|
|
- 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](https://nodejs.org/en/download).
|
|
|
|
## 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](https://taskfile.dev) 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
|
|
|
|
### Alpha Todo List
|
|
|
|
We are currently tracking known issues and tasks in the
|
|
[Alpha Todo List](https://github.com/orgs/wailsapp/projects/6). If you want to
|
|
help out, please check this list and follow the instructions in the
|
|
[Feedback](../getting-started/feedback.md) page.
|
|
|
|
### 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:
|
|
|
|
```shell
|
|
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.txt` file
|
|
- 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`:
|
|
|
|
```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:
|
|
|
|
```go
|
|
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.
|
|
|
|
The built-in plugins can be found in the `v3/plugins` directory. Check them out
|
|
for inspiration.
|
|
|
|
## Tasks
|
|
|
|
The Wails CLI uses the [Task](https://taskfile.dev) 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`.
|
|
|
|
### Upgrading Taskfile
|
|
|
|
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:
|
|
|
|
```shell
|
|
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:
|
|
|
|
```shell
|
|
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 `mkdocs-website/docs` directory.
|
|
|
|
## Misc Tasks
|
|
|
|
### Upgrading Taskfile
|
|
|
|
The Wails CLI uses the [Task](https://taskfile.dev) 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:
|
|
|
|
```shell
|
|
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:
|
|
|
|
```shell
|
|
wails3 task cli:install
|
|
wails3 task -version
|
|
```
|