electron/docs/tutorial/snapcraft.md

184 lines
5.7 KiB
Markdown
Raw Normal View History

2018-02-01 00:01:38 +00:00
# Snapcraft Guide (Ubuntu Software Center & More)
This guide provides information on how to package your Electron application
2018-02-01 00:57:45 +00:00
for any Snapcraft environment, including the Ubuntu Software Center.
2018-02-01 00:01:38 +00:00
## Background and Requirements
Together with the broader Linux community, Canonical aims to fix many of the
common software installation problems with the [`snapcraft`](https://snapcraft.io/)
2018-02-01 00:01:38 +00:00
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:
2018-02-01 00:01:38 +00:00
2018-02-02 00:32:58 +00:00
1) Using [`electron-forge`][electron-forge] or
2018-02-01 17:43:26 +00:00
[`electron-builder`][electron-builder], both tools that come with `snap`
support out of the box. This is the easiest option.
2018-02-02 00:32:58 +00:00
2) Using `electron-installer-snap`, which takes `electron-packager`'s output.
3) Using an already created `.deb` package.
2018-02-01 00:01:38 +00:00
In all cases, you will need to have the `snapcraft` tool installed. We
2018-02-01 00:01:38 +00:00
recommend building on Ubuntu 16.04 (or the current LTS).
```sh
snap install snapcraft --classic
```
2018-02-01 01:00:19 +00:00
While it _is possible_ to install `snapcraft` on macOS using Homebrew, it
2018-02-02 00:32:58 +00:00
is not able to build `snap` packages and is focused on managing packages
2018-02-01 01:00:19 +00:00
in the store.
2018-02-01 00:01:38 +00:00
2018-02-02 00:32:58 +00:00
## Using `electron-installer-snap`
2018-02-01 00:01:38 +00:00
2018-02-02 00:32:58 +00:00
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:
2018-02-01 00:01:38 +00:00
```sh
npm install --save-dev electron-installer-snap
```
2018-02-02 00:32:58 +00:00
### Step 1: Package Your Electron Application
2018-02-01 00:01:38 +00:00
2018-02-01 17:43:26 +00:00
Package the application using [electron-packager][electron-packager] (or a
2018-02-01 00:01:38 +00:00
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 increase
2018-02-01 00:01:38 +00:00
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
├── v8_context_snapshot.bin
└── version
2018-02-01 00:01:38 +00:00
```
2018-02-02 00:32:58 +00:00
### Step 2: Running `electron-installer-snap`
2018-02-01 00:01:38 +00:00
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
2018-02-01 00:01:38 +00:00
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`
2018-02-02 00:32:58 +00:00
programmatically. For more information, see the [Snapcraft API docs][snapcraft-syntax].
2018-02-01 00:01:38 +00:00
```js
const snap = require('electron-installer-snap')
snap(options)
.then(snapPath => console.log(`Created snap at ${snapPath}!`))
```
2018-02-02 00:32:58 +00:00
## Using an Existing Debian Package
2018-02-01 00:01:38 +00:00
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.
2018-02-02 00:32:58 +00:00
### Step 1: Create a Debian Package
2018-02-01 00:01:38 +00:00
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
2018-02-01 17:43:26 +00:00
for creating Debian packages exist, including [`electron-forge`][electron-forge],
[`electron-builder`][electron-builder] or
[`electron-installer-debian`][electron-installer-debian].
2018-02-01 00:01:38 +00:00
2018-02-02 00:32:58 +00:00
### Step 2: Create a snapcraft.yaml
2018-02-01 00:01:38 +00:00
For more information on the available configuration options, see the
2018-02-01 17:43:26 +00:00
[documentation on the snapcraft syntax][snapcraft-syntax].
Let's look at an example:
2018-02-01 00:01:38 +00:00
```yaml
name: myApp
version: '2.0.0'
2018-02-01 00:01:38 +00:00
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:
2018-02-15 21:08:55 +00:00
- desktop-gtk3
2018-02-01 00:01:38 +00:00
stage-packages:
- libasound2
- 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 passes information on to the
app's binary:
2018-02-01 00:01:38 +00:00
```sh
#!/bin/sh
exec "$@" --executed-from="$(pwd)" --pid=$$ > /dev/null 2>&1 &
```
2018-02-01 17:47:15 +00:00
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
```
2018-02-01 00:01:38 +00:00
[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/electron-packager
2018-02-01 00:01:38 +00:00
[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