From b49a284ccfd84014cfb5496008b744698e86f911 Mon Sep 17 00:00:00 2001 From: Felix Rieseberg Date: Wed, 31 Jan 2018 16:01:38 -0800 Subject: [PATCH 1/9] :memo: Add snapcraft documentation --- docs/tutorial/snapcraft-guide.md | 181 +++++++++++++++++++++++++++++++ 1 file changed, 181 insertions(+) create mode 100644 docs/tutorial/snapcraft-guide.md diff --git a/docs/tutorial/snapcraft-guide.md b/docs/tutorial/snapcraft-guide.md new file mode 100644 index 0000000000..7d038fee06 --- /dev/null +++ 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 From 1184eca58156cbc9bb2d6b0a21d4168012990fcd Mon Sep 17 00:00:00 2001 From: Felix Rieseberg Date: Wed, 31 Jan 2018 16:52:38 -0800 Subject: [PATCH 2/9] :wrench: Fix various typos, implement feedback --- docs/tutorial/snapcraft-guide.md | 56 +++++++++++++++----------------- 1 file changed, 26 insertions(+), 30 deletions(-) diff --git a/docs/tutorial/snapcraft-guide.md b/docs/tutorial/snapcraft-guide.md index 7d038fee06..23b00f7f13 100644 --- a/docs/tutorial/snapcraft-guide.md +++ b/docs/tutorial/snapcraft-guide.md @@ -15,7 +15,7 @@ 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: +There are three ways to create a `.snap` file: 1) Using `electron-installer-snap`, which takes `electron-packager's` output 2) Using an already created `.deb` package @@ -24,7 +24,7 @@ There are two ways to create a `.snap` file: 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 +In all cases, you will need to have the `snapcraft` tool installed. We recommend building on Ubuntu 16.04 (or the current LTS). ```sh @@ -33,7 +33,7 @@ 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. +distribution. As of today, it is not able ot build `snap` packages, for instance. # Using `electron-installer-snap` @@ -46,7 +46,7 @@ npm install --save-dev electron-installer-snap ## Step 1: Package Your Electron Application -Package the application using [electron-packager][electron-packager] (or a +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. @@ -54,33 +54,27 @@ 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 +. +└── 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 +## 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 +with the only required parameter `--src`, which is the location of your packaged Electron application created in the first step. ```sh @@ -88,7 +82,7 @@ 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. +programmatically. For more information, see the [API docs](snapcraft-syntax). ```js const snap = require('electron-installer-snap') @@ -109,13 +103,14 @@ building blocks. 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). +[`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](https://docs.snapcraft.io/build-snaps/syntax). -In this example +Let's look at an example: ```yaml name: myApp @@ -176,6 +171,7 @@ 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-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 From 311c0873dbe6c85b956080e0d946b27c449fed47 Mon Sep 17 00:00:00 2001 From: Felix Rieseberg Date: Wed, 31 Jan 2018 16:54:23 -0800 Subject: [PATCH 3/9] :memo: Link to the guide --- docs/README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/README.md b/docs/README.md index 7d35bda1e6..2e2ca70ef4 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) From 45119845e8d19449ade2113e59abe38ca5b65a2d Mon Sep 17 00:00:00 2001 From: Felix Rieseberg Date: Wed, 31 Jan 2018 16:56:46 -0800 Subject: [PATCH 4/9] :memo: Callout forge/builder as easiest --- docs/tutorial/snapcraft-guide.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/tutorial/snapcraft-guide.md b/docs/tutorial/snapcraft-guide.md index 23b00f7f13..6eb837f3b9 100644 --- a/docs/tutorial/snapcraft-guide.md +++ b/docs/tutorial/snapcraft-guide.md @@ -21,8 +21,7 @@ There are three ways to create a `.snap` file: 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) + support out of the box. This is the easiest option. In all cases, you will need to have the `snapcraft` tool installed. We recommend building on Ubuntu 16.04 (or the current LTS). From 9d0d83a002c91d70c54c9b6fe4fe4b3ad5c6b483 Mon Sep 17 00:00:00 2001 From: Felix Rieseberg Date: Wed, 31 Jan 2018 16:57:45 -0800 Subject: [PATCH 5/9] :memo: Some more words --- docs/tutorial/snapcraft-guide.md | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/docs/tutorial/snapcraft-guide.md b/docs/tutorial/snapcraft-guide.md index 6eb837f3b9..bd8f918a7f 100644 --- a/docs/tutorial/snapcraft-guide.md +++ b/docs/tutorial/snapcraft-guide.md @@ -1,7 +1,7 @@ # 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. +for any Snapcraft environment, including the Ubuntu Software Center. ## Background and Requirements @@ -11,10 +11,6 @@ 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 three ways to create a `.snap` file: 1) Using `electron-installer-snap`, which takes `electron-packager's` output From 77dcddf157143121153e2d52837e7d673b7fcd84 Mon Sep 17 00:00:00 2001 From: Felix Rieseberg Date: Wed, 31 Jan 2018 17:00:19 -0800 Subject: [PATCH 6/9] :memo: Even more words --- docs/tutorial/snapcraft-guide.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/tutorial/snapcraft-guide.md b/docs/tutorial/snapcraft-guide.md index bd8f918a7f..8776f95742 100644 --- a/docs/tutorial/snapcraft-guide.md +++ b/docs/tutorial/snapcraft-guide.md @@ -26,9 +26,9 @@ recommend building on Ubuntu 16.04 (or the current LTS). 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. As of today, it is not able ot build `snap` packages, for instance. +While it _is possible_ to install `snapcraft` on macOS using Homebrew, it +is not able to build `snap` packages and is focused on managed packages +in the store. # Using `electron-installer-snap` From 495c6dcff55c0e77d1567d79c8845e4086be458e Mon Sep 17 00:00:00 2001 From: Felix Rieseberg Date: Thu, 1 Feb 2018 09:43:26 -0800 Subject: [PATCH 7/9] :memo: Some more words --- docs/tutorial/snapcraft-guide.md | 26 ++++++++++++-------------- 1 file changed, 12 insertions(+), 14 deletions(-) diff --git a/docs/tutorial/snapcraft-guide.md b/docs/tutorial/snapcraft-guide.md index 8776f95742..b980323770 100644 --- a/docs/tutorial/snapcraft-guide.md +++ b/docs/tutorial/snapcraft-guide.md @@ -6,17 +6,17 @@ 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) +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-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` +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. This is the easiest option. In all cases, you will need to have the `snapcraft` tool installed. We @@ -27,7 +27,7 @@ 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 managed packages +is not able to build `snap` packages and is focused on managing packages in the store. # Using `electron-installer-snap` @@ -41,7 +41,7 @@ npm install --save-dev electron-installer-snap ## Step 1: Package Your Electron Application -Package the application using [electron-packager](electron-packager) (or a +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. @@ -77,7 +77,7 @@ 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](snapcraft-syntax). +programmatically. For more information, see the [API docs][snapcraft-syntax]. ```js const snap = require('electron-installer-snap') @@ -97,14 +97,14 @@ building blocks. 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). +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](https://docs.snapcraft.io/build-snaps/syntax). +[documentation on the snapcraft syntax][snapcraft-syntax]. Let's look at an example: ```yaml @@ -125,8 +125,6 @@ parts: source-type: deb after: - desktop-gtk2 - build-packages: - - patchelf stage-packages: - libasound2 - libgconf2-4 From be7e46b3fe4dafd440bff04c7c27291c0d493b72 Mon Sep 17 00:00:00 2001 From: Felix Rieseberg Date: Thu, 1 Feb 2018 09:47:15 -0800 Subject: [PATCH 8/9] :memo: A word on strict --- docs/tutorial/snapcraft-guide.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/docs/tutorial/snapcraft-guide.md b/docs/tutorial/snapcraft-guide.md index b980323770..31bcb43a32 100644 --- a/docs/tutorial/snapcraft-guide.md +++ b/docs/tutorial/snapcraft-guide.md @@ -161,6 +161,18 @@ to the app's binary: 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 From 6cf0c56eaf9dbe3afa244b25d1287436f718b9d2 Mon Sep 17 00:00:00 2001 From: Felix Rieseberg Date: Thu, 1 Feb 2018 16:32:58 -0800 Subject: [PATCH 9/9] :memo: Some more words --- .../{snapcraft-guide.md => snapcraft.md} | 28 ++++++++++--------- 1 file changed, 15 insertions(+), 13 deletions(-) rename docs/tutorial/{snapcraft-guide.md => snapcraft.md} (87%) diff --git a/docs/tutorial/snapcraft-guide.md b/docs/tutorial/snapcraft.md similarity index 87% rename from docs/tutorial/snapcraft-guide.md rename to docs/tutorial/snapcraft.md index 31bcb43a32..c8461a9571 100644 --- a/docs/tutorial/snapcraft-guide.md +++ b/docs/tutorial/snapcraft.md @@ -13,11 +13,11 @@ system modification. There are three 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 +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). @@ -27,19 +27,20 @@ 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 +is not able to build `snap` packages and is focused on managing packages in the store. -# Using `electron-installer-snap` +## 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: +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 +### 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 @@ -66,7 +67,7 @@ The output should look roughly like this: └── version ``` -## Step 2: Running `electron-installer-snap` +### 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 @@ -77,7 +78,7 @@ 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][snapcraft-syntax]. +programmatically. For more information, see the [Snapcraft API docs][snapcraft-syntax]. ```js const snap = require('electron-installer-snap') @@ -86,14 +87,14 @@ snap(options) .then(snapPath => console.log(`Created snap at ${snapPath}!`)) ``` -# Using an Existing Debian Package +## 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 +### 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 @@ -101,7 +102,7 @@ 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 +### Step 2: Create a snapcraft.yaml For more information on the available configuration options, see the [documentation on the snapcraft syntax][snapcraft-syntax]. @@ -180,3 +181,4 @@ apps: [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