Skip to content

Commit 4c8f201

Browse files
stackotterstackotter
committed
Document backends and their requirements, update readme, update guide
1 parent 827bb4b commit 4c8f201

11 files changed

+579
-216
lines changed

‎README.md

+89-152
Large diffs are not rendered by default.

‎Sources/SwiftCrossUI/SwiftCrossUI.docc/AppKitBackend.md

+51
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
# AppKitBackend
2+
3+
SwiftCrossUI's native macOS backend built on AppKit.
4+
5+
## Overview
6+
7+
`AppKitBackend` is the default backend on macOS, supports all current SwiftCrossUI features, and targets macOS 10.15+. It doesn't have any system dependencies other than a few system frameworks included on all Macs.
8+
9+
## Usage
10+
11+
```swift
12+
...
13+
14+
let package = Package(
15+
...
16+
targets: [
17+
...
18+
.executableTarget(
19+
name: "YourApp",
20+
dependencies: [
21+
.product(name: "SwiftCrossUI", package: "swift-cross-ui"),
22+
.product(name: "AppKitBackend", package: "swift-cross-ui"),
23+
]
24+
)
25+
...
26+
]
27+
...
28+
)
29+
```
30+
Figure 1: *adding `AppKitBackend` to an executable target*
31+
32+
```swift
33+
import SwiftCrossUI
34+
import AppKitBackend
35+
36+
@main
37+
struct YourApp: App {
38+
// You can explicitly initialize your app's chosen backend if you desire.
39+
// This happens automatically when you import any of the built-in backends.
40+
//
41+
// var backend = AppKitBackend()
42+
43+
var body: some Scene {
44+
WindowGroup {
45+
Text("Hello, World!")
46+
.padding()
47+
}
48+
}
49+
}
50+
```
51+
Figure 2: *using `AppKitBackend`*

‎Sources/SwiftCrossUI/SwiftCrossUI.docc/Basic Usage.md

-63
This file was deleted.

‎Sources/SwiftCrossUI/SwiftCrossUI.docc/DefaultBackend.md

+7
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
# DefaultBackend
2+
3+
An adaptive backend which uses different backends under the hood depending on the target operating system.
4+
5+
## Overview
6+
7+
The beauty of SwiftCrossUI is that you can write your app once and have it look native everywhere. For this reason I recommend using `DefaultBackend` unless you've got particular constraints. On macOS it uses `AppKitBackend`, on Windows it uses `WinUIBackend`, on Linux it uses `GtkBackend`, and on iOS and tvOS it uses `UIKitBackend`.

‎Sources/SwiftCrossUI/SwiftCrossUI.docc/Gtk3Backend.md

+89
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,89 @@
1+
# Gtk3Backend
2+
3+
A secondary Linux backend for older distros without Gtk 4.
4+
5+
## Overview
6+
7+
This backend supports Linux, macOS and Windows (maybe?), but its support for non-Linux platforms is significantly worse than `GtkBackend`'s (due to underlying Gtk 3 issues). Even on Linux, it's recommended to use `GtkBackend` over `Gtk3Backend` where possible.
8+
9+
> Warning: Non-Linux `Gtk3Backend` support is not a priority of this backend, and should only be used during development (e.g. to test your Linux UI natively on a Mac). There are multiple better choices of backend available on each non-Linux platform.
10+
11+
## System dependencies
12+
13+
Before you can use `Gtk3Backend` you must install the required system dependencies for your platform.
14+
15+
### Linux
16+
17+
```sh
18+
sudo apt install libgtk-3-dev
19+
```
20+
Figure 1: *installing Gtk 3 dev on an apt-based Linux distro*
21+
22+
If you are on a non-apt distro and the `GtkBackend` requirements end up differing significantly from the requirements stated above, please open a GitHub issue or PR so that we can improve the documentation.
23+
24+
### macOS
25+
26+
```sh
27+
brew install pkg-config gtk+3
28+
```
29+
Figure 2: *installing Gtk 3 using Homebrew*
30+
31+
If you don't have Homebrew, installation instructions can be found at [brew.sh](https://brew.sh).
32+
33+
It should also be possible to use `gtk3` installed via MacPorts, but I have not tested that.
34+
35+
### Windows
36+
37+
`gtk3` installation has not been tested on Windows, and neither has `Gtk3Backend`, although there shouldn't be anything to stop it from working (🤞). Follow the `gtk4` installation instructions from <doc:GtkBackend> and replace `gtk` with `gtk3` in any vcpkg commands or `vcpkg.json` manifest files.
38+
39+
If you try this on Windows open a GitHub issue (even if it works without changes) so that we can fix any issues you faced and update this documentation.
40+
41+
## Usage
42+
43+
```swift
44+
...
45+
46+
let package = Package(
47+
...
48+
targets: [
49+
...
50+
.executableTarget(
51+
name: "YourApp",
52+
dependencies: [
53+
.product(name: "SwiftCrossUI", package: "swift-cross-ui"),
54+
.product(name: "GtkBackend", package: "swift-cross-ui"),
55+
]
56+
)
57+
...
58+
]
59+
...
60+
)
61+
```
62+
Figure 3: *adding `Gtk3Backend` to an executable target*
63+
64+
```swift
65+
import SwiftCrossUI
66+
import Gtk3Backend
67+
68+
@main
69+
struct YourApp: App {
70+
// You can explicitly initialize your app's chosen backend if you desire.
71+
// This happens automatically when you import any of the built-in backends.
72+
//
73+
// var backend = Gtk3Backend()
74+
//
75+
// If you aren't using Swift Bundler, you may have to explicitly provide
76+
// your app's identifier for some Gtk3Backend features to work correctly
77+
// (such as handling custom URL schemes).
78+
//
79+
// var backend = Gtk3Backend(appIdentifier: "com.example.YourApp")
80+
81+
var body: some Scene {
82+
WindowGroup {
83+
Text("Hello, World!")
84+
.padding()
85+
}
86+
}
87+
}
88+
```
89+
Figure 4: *using `Gtk3Backend`*

‎Sources/SwiftCrossUI/SwiftCrossUI.docc/GtkBackend.md

+159
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,159 @@
1+
# GtkBackend
2+
3+
SwiftCrossUI's native Linux backend built on Gtk 4.
4+
5+
## Overview
6+
7+
While Gtk isn't the preferred UI framework on every Linux distro, it's the closest thing SwiftCrossUI has to a native Linux backend for now. The Qt backend may be brought back to life at some point to cover the rest of Linux distros.
8+
9+
For targetting older pre Gtk 4 Linux distros, see the secondary <doc:Gtk3Backend>
10+
11+
This backend supports Linux, macOS, and Windows, but its support for macOS has a few known issues worse due to underlying Gtk issues (and its support for Windows isn't well tested).
12+
13+
## System dependencies
14+
15+
Before you can use `GtkBackend` you must install the required system dependencies for your platform. Here are installation instructions tailored to each supported platform;
16+
17+
### Linux
18+
19+
```sh
20+
# Debian-based distros
21+
sudo apt install libgtk-4-dev clang
22+
23+
# Fedora-based distros
24+
sudo dnf install gtk4-devel clang
25+
```
26+
Figure 1: *installing the required dependencies on Debian-based and Fedora-based Linux distros*
27+
28+
If you run into errors related to not finding `gtk/gtk.h` when trying to build a swift-cross-ui project, try restarting your computer. This has worked in some cases (although there may be a more elegant solution).
29+
30+
If you are on a non-Debian non-Fedora distro and the `GtkBackend` requirements end up differing significantly from the requirements stated above, please open a GitHub issue or PR so that we can improve the documentation.
31+
32+
### macOS
33+
34+
```sh
35+
brew install pkg-config gtk4
36+
```
37+
Figure 2: *installing the required dependencies using Homebrew*
38+
39+
If you don't have Homebrew, installation instructions can be found at [brew.sh](https://brew.sh).
40+
41+
It should also be possible to use `gtk4` installed via MacPorts, but I have not tested that.
42+
43+
If you run into errors related to `libffi` or `FFI` when trying to build a swift-cross-ui project with `GtkBackend`, which can occur when certain older versions of the Xcode Command Line Tools are installed, try running the following command to patch libffi:
44+
45+
```sh
46+
sed -i '' 's/-I..includedir.//g' $(brew --prefix)/Library/Homebrew/os/mac/pkgconfig/*/libffi.pc
47+
```
48+
Figure 3: *fixing the `libffi` issue that some people face*
49+
50+
### Windows
51+
52+
On Windows things are a bit complicated (as usual), so we only support installation via [vcpkg](https://github.com/microsoft/vcpkg). First, install vcpkg;
53+
54+
```sh
55+
git clone https://github.com/microsoft/vcpkg C:\vcpkg
56+
C:\vcpkg\bootstrap-vcpkg.bat
57+
```
58+
Figure 4: *install vcpkg (requires git cli)*
59+
60+
> Warning: It's important to install vcpkg at the root of a drive due to limitations of the Gtk build system.
61+
62+
**After installation, make the following changes to your environment variables:**
63+
64+
1. Set the `PKG_CONFIG_PATH` environment variable to `C:\vcpkg\installed\x64-windows\lib\pkgconfig`. This is only required for building.
65+
2. Add `C:\vcpkg\installed\x64-windows\bin` to your `Path` environment variable. This is only required for running.
66+
67+
With vcpkg installed, you have two options for Gtk installation; global installation, and project-local installation
68+
69+
#### Global Gtk 4 installation (recommended)
70+
71+
Note that the command depends on your machine's architecture; choose between Figure 5 and Figure 6 accordingly.
72+
73+
Installation can take 45+ minutes depending on your machine.
74+
75+
```sh
76+
C:\vcpkg\vcpkg.exe install gtk --triplet x64-windows
77+
```
78+
Figure 5: *install Gtk 4 globally on x64 Windows*
79+
80+
```sh
81+
C:\vcpkg\vcpkg.exe install gtk --triplet arm64-windows
82+
```
83+
Figure 6: *install Gtk 4 globally on arm64 Windows*
84+
85+
> Warning: Run the chosen command at the root of your drive to ensure that vcpkg doesn't run in manifest mode.
86+
87+
#### Project-local Gtk 4 installation (more unreliable)
88+
89+
> Note: If the absolute path to your project contains spaces, it is possible that vcpkg will break, and installing globally will be a more reliable strategy.
90+
91+
To install Gtk 4 in a project-local dependency store you must setup a `vcpkg.json` manifest file and then run vcpkg, as detailed below;
92+
93+
First `vcpkg.json` at the root of your project and make sure that it includes the `gtk` dependency as demonstrated in Figure 7.
94+
95+
```json
96+
{
97+
"name": "project-name",
98+
"version-string": "main",
99+
"dependencies": ["gtk"]
100+
}
101+
```
102+
Figure 7: *an example `vcpkg.json` package manifest*
103+
104+
```sh
105+
C:\vcpkg\vcpkg.exe install --triplet x64-windows
106+
```
107+
Figure 8: *install the dependencies listed in your package manifest*
108+
109+
> Warning: Replace the triplet with `arm64-windows` if you're on ARM64
110+
111+
## Usage
112+
113+
```swift
114+
...
115+
116+
let package = Package(
117+
...
118+
targets: [
119+
...
120+
.executableTarget(
121+
name: "YourApp",
122+
dependencies: [
123+
.product(name: "SwiftCrossUI", package: "swift-cross-ui"),
124+
.product(name: "GtkBackend", package: "swift-cross-ui"),
125+
]
126+
)
127+
...
128+
]
129+
...
130+
)
131+
```
132+
Figure 9: *adding `GtkBackend` to an executable target*
133+
134+
```swift
135+
import SwiftCrossUI
136+
import GtkBackend
137+
138+
@main
139+
struct YourApp: App {
140+
// You can explicitly initialize your app's chosen backend if you desire.
141+
// This happens automatically when you import any of the built-in backends.
142+
//
143+
// var backend = GtkBackend()
144+
//
145+
// If you aren't using Swift Bundler, you may have to explicitly provide
146+
// your app's identifier for some GtkBackend features to work correctly
147+
// (such as handling custom URL schemes).
148+
//
149+
// var backend = GtkBackend(appIdentifier: "com.example.YourApp")
150+
151+
var body: some Scene {
152+
WindowGroup {
153+
Text("Hello, World!")
154+
.padding()
155+
}
156+
}
157+
}
158+
```
159+
Figure 10: *using `GtkBackend`*

‎Sources/SwiftCrossUI/SwiftCrossUI.docc/QtBackend.md

+3
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# QtBackend
2+
3+

0 commit comments

Comments
 (0)