You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This book is built using [Honkit](https://github.com/honkit/honkit).
21
21
22
-
Deployment happens automatically via GitLab CI when pushed to the GitLab
23
-
mirror. Each ref (branch or tag) is deployed to Google Cloud Storage under
24
-
`https://docs.itch.zone/itch/REF`, e.g. `master` or `v0.14.0`. It's recommended
25
-
to push tags when there are significant changes to the book so that older
26
-
versions may be referenced.
22
+
Deployment happens automatically via GitHub Actions (`.github/workflows/docs.yml`) when pushed to the `master` branch. The docs are deployed to GitHub Pages.
27
23
28
24
The primary docs displayed at `https://itch.io/docs/itch/` are proxied from
29
-
the `master` deployment on Google Cloud Storage. To update the these docs push
30
-
to GitLab's master branch.
25
+
the GitHub Pages deployment. To update, push to the `master` branch.
31
26
32
-
The `master` branch is also deployed to GitHub Pages for preview. Create tags
33
-
for substantial versions of the app and book to preserve older versions for
34
-
reference.
27
+
Create tags for substantial versions of the app and book to preserve older
For final deployment, we maintain a GitLab remote where builds are executed on our own self-hosted runners. These runners handle code signing for executables and publishing releases to itch.io using [butler](https://itch.io/docs/butler/).
11
+
Builds, code signing, and publishing are all handled by GitHub Actions. The CI
12
+
workflow runs multi-platform builds, signs executables (Azure Code Signing for
13
+
Windows, Apple notarization for macOS), and publishes releases to itch.io using
14
+
[butler](https://itch.io/docs/butler/). Releases are also published as GitHub
15
+
Releases.
12
16
13
17
## Build scripts
14
18
15
-
GitLab CI uses a YAML configuration file. Its format is detailed in the [GitLab CI](https://docs.gitlab.com/ee/ci/) documentation.
19
+
GitHub Actions uses a YAML workflow configuration file. Its format is detailed in the [GitHub Actions](https://docs.github.com/en/actions) documentation.
16
20
17
-
itch's [CI config](https://github.com/itchio/itch/blob/master/.gitlab-ci.yml) is relatively straight-forward, most of the complexity lives in individual shell scripts in the `release/` directory.
21
+
itch's [CI workflow](https://github.com/itchio/itch/blob/master/.github/workflows/build.yml) is relatively straight-forward, most of the complexity lives in individual shell scripts in the `release/` directory.
18
22
19
-
### Unit tests & linting
23
+
### Testing
20
24
21
-
The codebase is covered by a certain amount of unit tests, in `src/tests`.
22
-
23
-
On every commit, the CI executes all unit tests, and runs the TypeScript compiler in check mode to make sure that there are no compile errors.
25
+
***Type checking**: CI runs the TypeScript compiler in check mode on every commit to catch compile errors
26
+
***Integration tests**: Go-based integration tests run against the packaged binary after each build
24
27
25
28
### Building
26
29
27
-
The building scripts run some common steps on every platform:
30
+
TypeScript is compiled via [esbuild](https://esbuild.github.io/) into two bundles, one for the main process and one for the renderer.
28
31
29
-
* Compiling [TypeScript](https://www.typescriptlang.org/) code to ES2017, into several bundles
30
-
* Bundling static asset files
32
+
Static assets are copied to the build output and a minimal `package.json` is generated with the correct app name and version.
31
33
32
34
### Packaging
33
35
36
+
All platforms use [`@electron/packager`](https://www.npmjs.com/package/@electron/packager) to produce a portable Electron application directory. The app is not archived into an ASAR.
37
+
34
38
#### Windows
35
39
36
-
.exe + resources is built with [electron-packager](https://www.npmjs.com/package/electron-packager), then [electron-winstaller](https://github.com/electron/windows-installer) generates `-full.nupkg`, `-delta.nupkg`, and `RELEASES`, needed for Squirrel.Windows update.
40
+
`@electron/packager` produces an `.exe`with resources. The executable is signed in a separate CI job using Azure Code Signing.
37
41
38
-
#### macOS / OS X
42
+
#### macOS
39
43
40
-
.zip is built with `7za`\(7-zip command-line\), .dmg is built with [node-appdmg](https://www.npmjs.com/package/appdmg), with a custom background made in GIMP.
44
+
`@electron/packager` produces `.app` bundles for both x64 and arm64 architectures. A separate CI job signs the bundles with `@electron/osx-sign` and notarizes them with `@electron/notarize`.
41
45
42
46
#### Linux
43
47
44
-
The .desktop file is generated via `release/X.desktop.in` files + `sed`. All locale files are parsed for translations of the app's name and description.
45
-
46
-
deb & rpm packages are generated thanks to [fpm](https://github.com/jordansissel/fpm).
48
+
`@electron/packager` produces an application directory, tarballed to preserve file permissions.
47
49
48
50
### Publishing releases
49
51
50
-
All release artifacts are signed on our self-hosted GitLab runners and then published directly to itch.io using [butler](https://itch.io/docs/butler/). Butler handles uploading, diffing, and serving updates to users.
52
+
***On every push/PR**: The workflow builds and type-checks on all three platforms, but does not upload artifacts, sign, or publish. This validates that the code compiles and packages correctly.
53
+
***On `workflow_dispatch`**: The full pipeline runs -- build, code signing (separate jobs for Windows and macOS), and artifact upload. If the dispatch is triggered on a git tag, two additional jobs run:
54
+
***GitHub Release**: Creates a release (marked as prerelease if the tag contains "canary") with `.tar.gz` archives for all platforms
55
+
***itch.io deployment**: Downloads all signed artifacts, validates macOS bundle structure, and uses butler to push to the appropriate itch.io channel (`itchio/itch` or `itchio/kitch`)
When making large structural changes, it is sometimes useful to have a completely separate version of the app with no expectations of stability.
62
68
63
-
`kitch` is exactly that. It is meant to be installed in parallel of the stable app, and has a distinct branding \(blue instead of itch.io hot pink\), uses different folders \(`%APPDATA%/kitch`, `~/.config/kitch`, `~/Library/Application
69
+
`kitch` is exactly that. It is meant to be installed in parallel of the stable app, and has a distinct branding \(blue instead of itch.io hot pink\), uses different folders \(`%APPDATA%/kitch`, `~/.config/kitch`, `~/Library/Application
**At build time:** The variant is selected based on git tags. A tag containing the `-canary` suffix produces a kitch build, while all other tags produce itch. The default `package.json` name is `"kitch"`, so local development always runs as kitch.
88
+
89
+
**At runtime:** The app calls `app.getName()` to read the package.json name field, which sets `env.isCanary`, `env.appName`, and `env.channel` accordingly.
***No version pinning** -- canary always fetches the latest versions of components like butler and itch-setup, rather than pinning to specific versions
20
+
21
+
For a full technical breakdown, see the [canary channel](../developing/continuous-deployment.md#the-canary-channel) section in the developer docs.
Copy file name to clipboardExpand all lines: installing/dependencies.md
+9-9Lines changed: 9 additions & 9 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -4,8 +4,6 @@ itch uses a few external tools to download & manage content.
4
4
5
5
It installs and keeps them up-to-date automatically, which means you should never have to worry about them. However, in the interest of you knowing what runs on your computer, they're documented here.
6
6
7
-
Everything is downloaded from our download server at `https://dl.itch.zone`.
8
-
9
7
Third-party programs are built from source. Home-grown programs are continuously built on our CI servers.
10
8
11
9
## Directories
@@ -20,19 +18,21 @@ All dependencies are downloaded and extracted into the following folders:
20
18
21
19
### butler
22
20
23
-
butler is a homemade \(itch.io-made\) command-line tool, distributed under the MIT license.
21
+
butler is a homemade command-line tool written in Go, distributed under the MIT license.
22
+
23
+
It runs as a daemon process (butlerd) that communicates with the itch app via JSON-RPC 2.0 over TCP. butler handles downloading, installing, updating, and launching games, and maintains a SQLite database to track installation data.
24
24
25
-
Its source code is available here, for you to audit, debug, and improve at will:
25
+
Its source code is available for you to audit, debug, and improve at will:
Building your own version is as simple as running:
29
+
### itch-setup
30
+
31
+
itch-setup is a Go program that handles the initial installation of the itch app on all platforms. It also manages self-update checks and restarts the app when a new version is available.
30
32
31
-
```
32
-
go get -v github.com/itchio/butler
33
-
```
33
+
Its source code is available here:
34
34
35
-
\(assuming you have Go 1.9+ installed on your system\)
0 commit comments