diff --git a/docs/README.md b/docs/README.md index 7d35bda1e64c..2e2ca70ef4d1 100644 --- a/docs/README.md +++ b/docs/README.md @@ -23,6 +23,7 @@ an issue: * [Application Distribution](tutorial/application-distribution.md) * [Mac App Store Submission Guide](tutorial/mac-app-store-submission-guide.md) * [Windows Store Guide](tutorial/windows-store-guide.md) +* [Snapcraft Guide](tutorial/snapcraft-guide.md) * [Application Packaging](tutorial/application-packaging.md) * [Using Native Node Modules](tutorial/using-native-node-modules.md) * [Debugging Main Process](tutorial/debugging-main-process.md) diff --git a/docs/tutorial/snapcraft.md b/docs/tutorial/snapcraft.md new file mode 100644 index 000000000000..c8461a9571d3 --- /dev/null +++ b/docs/tutorial/snapcraft.md @@ -0,0 +1,184 @@ +# Snapcraft Guide (Ubuntu Software Center & More) + +This guide provides information on how to package your Electron application +for any Snapcraft environment, including the Ubuntu Software Center. + +## Background and Requirements + +Together with the broader Linux community, Canonical aims to fix many of the +common software installation problems with the [`snapcraft`][snapcraft.io) +project. Snaps are containerized software packages that include required +dependencies, auto-update, and work on all major Linux distributions without +system modification. + +There are three ways to create a `.snap` file: + +1) Using [`electron-forge`][electron-forge] or + [`electron-builder`][electron-builder], both tools that come with `snap` + support out of the box. This is the easiest option. +2) Using `electron-installer-snap`, which takes `electron-packager`'s output. +3) Using an already created `.deb` package. + +In all cases, you will need to have the `snapcraft` tool installed. We +recommend building on Ubuntu 16.04 (or the current LTS). + +```sh +snap install snapcraft --classic +``` + +While it _is possible_ to install `snapcraft` on macOS using Homebrew, it +is not able to build `snap` packages and is focused on managing packages +in the store. + +## Using `electron-installer-snap` + +The module works like [`electron-winstaller`][electron-winstaller] and similar +modules in that its scope is limited to building snap packages. You can install +it with: + +```sh +npm install --save-dev electron-installer-snap +``` + +### Step 1: Package Your Electron Application + +Package the application using [electron-packager][electron-packager] (or a +similar tool). Make sure to remove `node_modules` that you don't need in your +final application, since any module you don't actually need will just increase +your application's size. + +The output should look roughly like this: + +```text +. +└── dist + └── app-linux-x64 + ├── LICENSE + ├── LICENSES.chromium.html + ├── content_shell.pak + ├── app + ├── icudtl.dat + ├── libgcrypt.so.11 + ├── libnode.so + ├── locales + ├── natives_blob.bin + ├── resources + ├── snapshot_blob.bin + └── version +``` + +### Step 2: Running `electron-installer-snap` + +From a terminal that has `snapcraft` in its `PATH`, run `electron-installer-snap` +with the only required parameter `--src`, which is the location of your packaged +Electron application created in the first step. + +```sh +npx electron-installer-snap --src=out/myappname-linux-x64 +``` + +If you have an existing build pipeline, you can use `electron-installer-snap` +programmatically. For more information, see the [Snapcraft API docs][snapcraft-syntax]. + +```js +const snap = require('electron-installer-snap') + +snap(options) + .then(snapPath => console.log(`Created snap at ${snapPath}!`)) +``` + +## Using an Existing Debian Package + +Snapcraft is capable of taking an existing `.deb` file and turning it into +a `.snap` file. The creation of a snap is configured using a `snapcraft.yaml` +file that describes the sources, dependencies, description, and other core +building blocks. + +### Step 1: Create a Debian Package + +If you do not already have a `.deb` package, using `electron-installer-snap` +might be an easier path to create snap packages. However, multiple solutions +for creating Debian packages exist, including [`electron-forge`][electron-forge], +[`electron-builder`][electron-builder] or +[`electron-installer-debian`][electron-installer-debian]. + +### Step 2: Create a snapcraft.yaml + +For more information on the available configuration options, see the +[documentation on the snapcraft syntax][snapcraft-syntax]. +Let's look at an example: + +```yaml +name: myApp +version: 2.0.0 +summary: A little description for the app. +description: | + You know what? This app is amazing! It does all the things + for you. Some say it keeps you young, maybe even happy. + +grade: stable +confinement: classic + +parts: + slack: + plugin: dump + source: my-deb.deb + source-type: deb + after: + - desktop-gtk2 + stage-packages: + - libasound2 + - libgconf2-4 + - libnotify4 + - libnspr4 + - libnss3 + - libpcre3 + - libpulse0 + - libxss1 + - libxtst6 + electron-launch: + plugin: dump + source: files/ + prepare: | + chmod +x bin/electron-launch + +apps: + myApp: + command: bin/electron-launch $SNAP/usr/lib/myApp/myApp + desktop: usr/share/applications/myApp.desktop + # Correct the TMPDIR path for Chromium Framework/Electron to ensure + # libappindicator has readable resources. + environment: + TMPDIR: $XDG_RUNTIME_DIR +``` + +As you can see, the `snapcraft.yaml` instructs the system to launch a file +called `electron-launch`. In this example, it simply passes information on +to the app's binary: + +```sh +#!/bin/sh + +exec "$@" --executed-from="$(pwd)" --pid=$$ > /dev/null 2>&1 & +``` + +Alternatively, if you're building your `snap` with `strict` confinement, you +can use the `desktop-launch` command: + +```yaml +apps: + myApp: + # Correct the TMPDIR path for Chromium Framework/Electron to ensure + # libappindicator has readable resources. + command: env TMPDIR=$XDG_RUNTIME_DIR PATH=/usr/local/bin:${PATH} ${SNAP}/bin/desktop-launch $SNAP/myApp/desktop + desktop: usr/share/applications/desktop.desktop +``` + +[snapcraft.io]: https://snapcraft.io/ +[snapcraft-store]: https://snapcraft.io/store/ +[snapcraft-syntax]: https://docs.snapcraft.io/build-snaps/syntax +[electron-packager]: https://github.com/electron-userland/electron-packager +[electron-forge]: https://github.com/electron-userland/electron-forge +[electron-builder]: https://github.com/electron-userland/electron-builder +[electron-installer-debian]: https://github.com/unindented/electron-installer-debian +[electron-winstaller]: https://github.com/electron/windows-installer \ No newline at end of file