📝 Add snapcraft documentation

2018-01-31 16:01:38 -08:00 · 2018-01-31 16:01:38 -08:00 · b49a284ccf
commit b49a284ccf
parent 67196bdd3e
1 changed files with 181 additions and 0 deletions
--- a/docs/tutorial/snapcraft-guide.md
+++ b/docs/tutorial/snapcraft-guide.md
@ -0,0 +1,181 @@
+# Snapcraft Guide (Ubuntu Software Center & More)
+
+This guide provides information on how to package your Electron application
+for the Ubuntu Software Center or any other Snapcraft environment.
+
+## 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.
+
+Snapcraft is the primary way to get your application into the Ubuntu Software
+Center, but the underlying [Snap Store](snapcraft-store) supports all major
+Linux distributions, too.
+
+There are two ways to create a `.snap` file:
+
+1) Using `electron-installer-snap`, which takes `electron-packager's` output
+2) Using an already created `.deb` package
+3) Using [`electron-forge`](electron-forge) or
+   [`electron-builder`](electron-builder), both tools that come with `snap`
+   support out of the box (not further documented here, please see those
+   frameworks for further guidance)
+
+In both 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, you are
+less likely to encounter issues when running `snapcraft` on an actual Linux
+distribution.
+
+# Using `electron-installer-snap`
+
+The module works like `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
+├── Ghost.exe
+├── LICENSE
+├── content_resources_200_percent.pak
+├── content_shell.pak
+├── d3dcompiler_47.dll
+├── ffmpeg.dll
+├── icudtl.dat
+├── libEGL.dll
+├── libGLESv2.dll
+├── locales
+│   ├── am.pak
+│   ├── ar.pak
+│   ├── [...]
+├── natives_blob.bin
+├── node.dll
+├── resources
+│   ├── app
+│   └── atom.asar
+├── snapshot_blob.bin
+├── squirrel.exe
+└── ui_resources_200_percent.pak
+```
+
+## Step 2: Running electron-installer-snap
+
+From a terminal that has `snapcraft` in its `PATH`, run `electron-installer-snap`
+with the only required parameter `--out`, 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 API docs.
+
+```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`]() 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](https://docs.snapcraft.io/build-snaps/syntax).
+In this 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
+    build-packages:
+      - patchelf
+    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 &
+```
+
+[snapcraft.io]: https://snapcraft.io/
+[snapcraft-store]: https://snapcraft.io/store/
+[snapcraft-syntax]: https://docs.snapcraft.io/build-snaps/syntax
+[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