Guidelines and HOWTOs/Snap

 

Under Construction
This is a new page, currently under construction!

Want to run your application binaries on any Linux distribution? Snap makes that possible.

For general purpose information about snap, snapcraft and how to use them please have a look at their documentation as it excellently teaches you most generic information about snaps https://docs.snapcraft.io Even so this page will teach you a lot of the basics of snaps.

For a primer on YAML, the format used to describe snap building, have a look here https://docs.ansible.com/ansible/latest/reference_appendices/YAMLSyntax.html

TBD separate page specifically about how to use the content snap

 

Under Construction
This is a new page, currently under construction!

Binary Sources

Building a snap we'll lovingly call "snapping". At the time of writing you can snapcraft on two core systems: one is Ubuntu 16.04, the other is Ubuntu 18.04. Both of them are the LTS version of Ubuntu and therefore supported for what seems like forever. Snapcraft has native support to pull binary packages (i.e. debs) into the snap so that you might build against them without having to build the binaries yourselves. For example you could use Qt from Ubuntu directly without the need to build it in your snap. However, since the base systems are LTS the software is usually very dated. Seeing as you may need newer dependencies there's a bunch of ways you can get them besides pre-built Ubuntu debs:

As Snapcraft Parts

You can add any number of additional parts that build dependencies. For example you might build your own qtbase as part of snap. How much work this is can be vastly different between software. Building all of Qt can get quickly slow, at the same time relying on an ancient Qt may not be practical either. To gain access to newer foundations software you may instead want to get them ...

From KDE neon

We are in luck and KDE neon already builds packages for Ubuntu LTS, so you may choose to simply use neon debs on top of Ubuntu debs. This gives access to the latest Qt, KDE frameworks and other related libraries. This can be a huge time saver. Unfortunately Snapcraft's support for adding additional repositories is non-existent and so if you choose to go this route you may need to somewhat manually manage the build environment yourself e.g. using an especially prepared LXD container.

From PPAs

Much like KDE neon, this too will require you to manage the build environment manually. Also, when using PPAs beware that they may not be compatible with neon (so, ideally you should use either-or) and that many of them are not particularly trustworthy or well maintained (important vis-a-vis security).

Snapcraft

The tool to build snaps is called snapcraft. The definition for how to craft a snap is written down in snapcraft.yaml. Generally speaking a snapcraft.yaml will contain global metadata of the snap, a list of applications provided by the snap, and lastly a list of parts that when put together result in the snap. Access to the host system is controlled through a plug-and-slot system which is also used in the snapcraft.yaml. Each application may have one or multiple plugs it uses to get access to resources of the host system or other snaps. For example the 'desktop' plug gives access to host fonts and icons.

Types of Snap

With a broad overview of abilities and shortcomings let's dive right in and look at types of snaps we might build.

Standalone

A standalone snap is a snap which solely relies on a "core" but no other snaps. This is generally speaking the most reliable type of snap as everything the snap needs is inside the snap (except libc and friends which are in the core).

It is also the best supported way of building a snap since it's been around since the very beginning.

Advantages:

• Very reliable
• Easy to build and test
• You are always on your own and unrelated changes rarely if ever can impair your snap

Disadvantages:

• Huge in size (each standalone snap needs to ship their own Qt/l10n and necessary kf5 and other dependencies)
• You need to take care of setting up your execution environment yourself.
• You are always on your own and unrelated changes rarely if ever can improve your snap

Example

name: qtnetsample
version: '0'  # the version of the snap. has no semantic meaning
summary: This is my-snap's summary  # 79 char long summary
description: This is my-snap's description  # a longer description for the snap
confinement: strict  # use "strict" to enforce system access only via declared interfaces
grade: devel # use "stable" to assert the snap quality
base: core18 # the core this snap depends on

apps:
    qtnetsample:
        command: launcher qtnetsample # the launcher will setup the environment for qtnetsample to find libraries/plugins/data etc
        plugs: [x11, network, network-bind] # this snap will be able to act as xclient and talk over the network

parts:
    qtnetsample:
        build-packages: [qt5-default]
        plugin: cmake
        stage-packages: [libqt5network5, libqt5core5a]
        source: .

Shared Snap

A snap may also choose to use one or more Content Snaps (see glossary) to share part of the binaries or UI assets with other snaps. As shared content will generally be in the content snap, the ultimate size of the snap can be fairly small. Think of this as an approach more akin to how traditional binary package dependencies work. Albeit with many of the same complexities surrounding it.

For example KDE neon builds the kde-frameworks-5 content snap. It contains all of Qt and all (not-deprecated) KDE frameworks along with Plasma integration rigging.

Advantages:

• Application snap is super small
• You don't need to care of setting up the execution environment
• Integration and international improvements are all in one place (shared environment setup etc)
• Generally speaking when using the KF5 content snap SDK you can get access to KDE neon's Qt and Frameworks without having to actually add the deb sources.

Disadvantages:

• Up-front "cost" of a single application may be higher. e.g. if the application only uses QtCore, the content snap will still bring in all of Qt and all of KF5 through the content snap. It's like a shared library, the more it is used the smaller the cost per-user.
• Somewhat harder to build and test because of added complexity. Also managing deb build dependencies in addition to content snap SDKs is problematic TBD link to forum post
• Unrelated changes in the content snaps may impair your snap
• Since this type was introduced a while after snap initially came into being you still can feel rough edges when working with content snaps.

Example

---
name: kbruch
version: 18.12.1
confinement: strict
grade: stable
base: core18
adopt-info: kbruch # part to adopt appstream data from (first in parse list)
apps:
    kbruch:
        command: kf5-launch kbruch
        plugs:
        - kde-frameworks-5-plug
        - home
        - x11
        - opengl
        - network
        - network-bind
        - unity7
        - pulseaudio
        - desktop
        - desktop-legacy
        common-id: org.kde.kbruch.desktop
        desktop: "usr/share/applications/org.kde.kbruch.desktop"
slots:
    session-dbus-interface:
        interface: dbus
        name: org.kde.kbruch
        bus: session
plugs:
    kde-frameworks-5-plug:
        content: kde-frameworks-5-core18-all
        interface: content
        default-provider: kde-frameworks-5-core18
        target: kf5 # target directory where the content is mounted i.e. $SNAP/kf5/
parts:
    kbruch:
        build-snaps:
        - kde-frameworks-5-core18-sdk
        after:
        - kde-frameworks-5-env
        plugin: cmake
        source: src
        configflags:
        - "-DKDE_INSTALL_USE_QT_SYS_PATHS=ON"
        - "-DCMAKE_INSTALL_PREFIX=/usr"
        - "-DCMAKE_BUILD_TYPE=Release"
        - "-DENABLE_TESTING=OFF"
        - "-DBUILD_TESTING=OFF"
        - "-DKDE_SKIP_TEST_SETTINGS=ON"
        parse-info: [usr/share/metainfo/org.kde.kbruch.appdata.xml]
    kde-frameworks-5-env:
        plugin: dump
        source: https://github.com/apachelogger/kf5-snap-env.git

Execution Environment and Launchers

When binaries inside snaps get executed they only get a super minimal environment set up by snapd. The snap itself needs to take care of most of the higher level spin up of the environment.

Inside a confined snap the / will be the core snap, while the actual snap will be in SNAP=/snap/name/rev/.... As a result for example icons, which usually would be expected in $XDG_DATA_DIRS/icons meaning /usr/share/icons, will need to actually be looked for in $SNAP/usr/share/icons. The same applies to pretty much all XDG_* variables, LD_LIBRARY_PATH, various QT_* variables and so on and so forth.

Simply put: a snap's tree is not "merged" with the core's tree, rather it is "mounted" inside the core tree under $SNAP and so each snap needs to set up an environment which redirects or adds $SNAP to all lookup locations you can possibly imagine. As general assumptions about where things are on a Linux system no longer hold true. One the one hand that technically allows you to create a snap which entirely does away with the FHS, on the other it means someone needs to actually mangle the environment so files may be located properly.

That's why most, if not all, desktop application snaps will need a launch helper. The launcher will set up all the general purpose path variables so they point to $SNAP. A standard desktop launcher implementation is available here https://github.com/ubuntu/snapcraft-desktop-helpers. Obviously you can also write your own, but since there are lots of things to consider, even for simple applications, it's probably not a good idea to do so.

You can have a look at the standard environment by running

snap install hello-world
snap run --shell hello-world
env

This will drop you on a minimal shell inside the confined snap, where you can have a look around to see what the snap sees.

A Snap from Scratch

We'll create a snap bundle from scratch using LXD, the KDE neon repositories, and will also look at how to make use of the KDE Frameworks 5 content snap. Using LXD and managing the environment manually allows us to use the KDE neon repositories, it does however also mean that we need to take care of more things ourselves. It also means that snapcraft will need to be run with --destructive-mode to instruct it that it may install dependencies and the like into the actual system.

To follow along you'll need a working LXD setup. On most distributions you'll need to run lxd init before its ready to use.

lxc launch --ephemeral ubuntu:18.04 my_container # start an ephemeral container. it will be deleted once stopped
lxc exec my_container -- bash

You are now inside an Ubuntu 18.04 container. We'll continue to setup the neon repositories and the latest stable snapcraft.

apt-key adv --keyserver keyserver.ubuntu.com --recv E6D4736255751E5D
echo 'deb http://archive.neon.kde.org/unstable bionic main' > /etc/apt/sources.list.d/neon.list
apt update
snap install --stable --classic snapcraft
mkdir /workspace

Now we can start writing our snapcraft.yaml. You can either install a command line editor and write it inside the container or write it on your system and "upload" it to the container with the command lxc file push --recursive snapcraft.yaml my_container/workspace/. Let's start with the absolutely bare minimum.

---
name: kmplot
version: '0'
summary: Function Plotter
description: KmPlot is a program to plot graphs of functions.
confinement: strict
grade: stable
base: core18

parts:
    kmplot:
        plugin: cmake
        source: https://anongit.kde.org/kmplot.git

We've defined (not very good) metadata for the snap and a single part to build. Attempting to build this using snapcraft --destructive-mode will however result in an error similar to

CMake Error at CMakeLists.txt:1 (project):
  No CMAKE_CXX_COMPILER could be found.

We haven't installed any of our build dependencies. An easy fix. We'll simply add build-packages to our part. In this case the compiler is missing and it's usually best pulled in via the package "build-essential". You'd continue building your build-packages list until the software starts building. Fortunately I already know all the stuff that is needed so we can move ahead.

 

Tip
For software which is packaged through KDE neon (which is just about everything KDE) you can get a good list to start with by looking at the debian/control file of the Neon/release branch of the packaging repository at https://packaging.neon.kde.org

The part needs editing with build-packges specified before we can do another snapcraft run:

parts:
    kmplot:
        plugin: cmake
        source: https://anongit.kde.org/kmplot.git
        source-branch: Applications/19.04 # not needed for master
        build-packages: [build-essential, extra-cmake-modules, libkf5widgetsaddons-dev, libqt5svg5-dev, libkf5parts-dev, libkf5doctools-dev, libkf5crash-dev, gettext]

Snapcrafting our refined snapcraft.yaml should finally succeed in creating a snap. Unfortunately it will also print a long list of missing dependencies:

[...]
Staging kmplot 
Priming kmplot 
The 'kmplot' part needs the following libraries that are not included in the snap or base: 
usr/lib/x86_64-linux-gnu/libGL.so.1
usr/lib/x86_64-linux-gnu/libGLX.so.0
usr/lib/x86_64-linux-gnu/libGLdispatch.so.0
usr/lib/x86_64-linux-gnu/libKF5Archive.so.5
usr/lib/x86_64-linux-gnu/libKF5Attica.so.5
usr/lib/x86_64-linux-gnu/libKF5AuthCore.so.5
usr/lib/x86_64-linux-gnu/libKF5Codecs.so.5
usr/lib/x86_64-linux-gnu/libKF5Completion.so.5
usr/lib/x86_64-linux-gnu/libKF5ConfigCore.so.5
usr/lib/x86_64-linux-gnu/libKF5ConfigGui.so.5
usr/lib/x86_64-linux-gnu/libKF5ConfigWidgets.so.5
usr/lib/x86_64-linux-gnu/libKF5CoreAddons.so.5
usr/lib/x86_64-linux-gnu/libKF5Crash.so.5
usr/lib/x86_64-linux-gnu/libKF5DBusAddons.so.5
usr/lib/x86_64-linux-gnu/libKF5GlobalAccel.so.5
usr/lib/x86_64-linux-gnu/libKF5GuiAddons.so.5
usr/lib/x86_64-linux-gnu/libKF5I18n.so.5
usr/lib/x86_64-linux-gnu/libKF5IconThemes.so.5
usr/lib/x86_64-linux-gnu/libKF5ItemViews.so.5
usr/lib/x86_64-linux-gnu/libKF5JobWidgets.so.5
usr/lib/x86_64-linux-gnu/libKF5KIOCore.so.5
usr/lib/x86_64-linux-gnu/libKF5KIOWidgets.so.5
usr/lib/x86_64-linux-gnu/libKF5Parts.so.5
usr/lib/x86_64-linux-gnu/libKF5Service.so.5
usr/lib/x86_64-linux-gnu/libKF5SonnetCore.so.5
usr/lib/x86_64-linux-gnu/libKF5SonnetUi.so.5
usr/lib/x86_64-linux-gnu/libKF5TextWidgets.so.5
usr/lib/x86_64-linux-gnu/libKF5WidgetsAddons.so.5
usr/lib/x86_64-linux-gnu/libKF5WindowSystem.so.5
usr/lib/x86_64-linux-gnu/libKF5XmlGui.so.5
usr/lib/x86_64-linux-gnu/libQt5Core.so.5
usr/lib/x86_64-linux-gnu/libQt5DBus.so.5
usr/lib/x86_64-linux-gnu/libQt5Gui.so.5
usr/lib/x86_64-linux-gnu/libQt5Network.so.5
usr/lib/x86_64-linux-gnu/libQt5PrintSupport.so.5
usr/lib/x86_64-linux-gnu/libQt5Svg.so.5
usr/lib/x86_64-linux-gnu/libQt5TextToSpeech.so.5
usr/lib/x86_64-linux-gnu/libQt5Widgets.so.5
usr/lib/x86_64-linux-gnu/libQt5X11Extras.so.5
usr/lib/x86_64-linux-gnu/libQt5Xml.so.5
usr/lib/x86_64-linux-gnu/libX11.so.6
usr/lib/x86_64-linux-gnu/libXau.so.6
usr/lib/x86_64-linux-gnu/libXdmcp.so.6
usr/lib/x86_64-linux-gnu/libdouble-conversion.so.1
usr/lib/x86_64-linux-gnu/libfam.so.0
usr/lib/x86_64-linux-gnu/libfreetype.so.6
usr/lib/x86_64-linux-gnu/libgraphite2.so.3
usr/lib/x86_64-linux-gnu/libharfbuzz.so.0
usr/lib/x86_64-linux-gnu/libicudata.so.60
usr/lib/x86_64-linux-gnu/libicui18n.so.60
usr/lib/x86_64-linux-gnu/libicuuc.so.60
usr/lib/x86_64-linux-gnu/libpcre2-16.so.0
usr/lib/x86_64-linux-gnu/libpng16.so.16
usr/lib/x86_64-linux-gnu/libxcb-keysyms.so.1
usr/lib/x86_64-linux-gnu/libxcb.so.1
These dependencies can be satisfied via more stage-packages, more parts, or content sharing.
Snapping 'kmplot' |                                                                                                                                  
Snapped kmplot_18.12.1_amd64.snap

We can build the software fine, but snapcraft is concerned that we haven't "snapped" all the necessary dependencies. The list it prints is by no means exhaustive, it's only things snapcraft can easily detect, such as missing shared libraries. Getting the necessary dependencies on board is a bit tricky. The easiest way would be to simply take the list of build-packages and use the exact same list as stage-packages. Stage packages (and their dependencies) get put into the final snap. So, by using the build-packages also as stage-packages we'd put a whole bunch of buildtime-only stuff into our final snap unless we explicitly exclude files from getting primed. Since that is somewhat unreliable and probably not particularly advisable unless you have a firm grasp of all concepts involved, we'll opt to do it the other way around and only stage packages we know are need. So from the list of build-packages packages we'll simply look at their dependencies and try to infer which of their dependencies we need (if any).

• build-essential we'll leave out entirely, as the name suggests it only contains buildtime stuff such as make and gcc
• extra-cmake-modules similarly is only useful at build time as it contains cmake extensions
• libkf5widgetsaddons-dev is a dev package of a library and thus actually needed at runtime.

We'll inspect its package relationships with the command apt show libkf5widgetsaddons-dev | grep -P "(Depends|Recommends)".

Depends: libkf5widgetsaddons5 (= 5.56.0+p18.04+git20190322.0124-0), qtbase5-dev (>= 5.8.0~)
Recommends: libkf5widgetsaddons-doc (= 5.56.0+p18.04+git20190322.0124-0)

We can ignore qtbase5, its another dev package. libkf5widgetsaddons-doc is library documentation which we also do not need. libkf5widgetsaddons5 is the actual library and we'll definitely want it staged. We'll continue this review for all build-packages:

• libqt5svg5-dev: libray is libqt5svg5
• libkf5parts-dev: library is libkf5parts5
• libkf5doctools-dev: buildtime only, builds documentation
• gettext: buildtime only, builds localization
• libkf5crash-dev: library is libkf5crash5

We now have a list of packages that need staging and can update our part accordingly:

parts:
    kmplot:
        plugin: cmake
        source: https://anongit.kde.org/kmplot.git
        source-branch: Applications/19.04 # not needed for master
        build-packages: [build-essential, extra-cmake-modules, libkf5widgetsaddons-dev, libqt5svg5-dev, libkf5parts-dev, libkf5doctools-dev, libkf5crash-dev, gettext]
        stage-packages: [libkf5widgetsaddons5, libqt5svg5, libkf5parts5, libkf5crash5]

Snapcrafting our refined data should now create a snap without any additional warnings. This should be good enough to now. You can pull the snap out of the container with lxc file pull my_container/workspace/kmplot_0_amd64.snap . and install it into with snap install --force-dangerous kmplot_0_amd64.snap and try to run it snap run kmplot. Unsuccessfully...

error: cannot find app "kmplot" in "kmplot"

Before snapd can run an application the snap first needs to declare one. Let's add one:

apps:
    kmplot:
        command: kmplot
        plugs: [x11, opengl, desktop, desktop-legacy]

Plugs are a bit out of scope, for more information on them refer to the upstream snapcraft documentation. Snapcrafting, installing and running the new snap will unfortunately still result in problems:

kmplot(4481)/(qt.qpa.plugin) unknown: Could not find the Qt platform plugin "xcb" in ""
kmplot(4481)/(default) unknown: This application failed to start because no Qt platform plugin could be initialized. Reinstalling the application may fix this proble

This is where the environment helpers come in. Qt attempts to find the xcb plugin in /usr/... but actually needs to look in $SNAP/usr/...

 

Under Construction
This is a new page, currently under construction!

Glossary

Words you'll hear and not know what they mean:

• snap: The actual bundle format.
• snapd: The daemon that manages snap on a system.
• snapcraft: The build tool for building a snap.
• 'app: In the context of snapcraft/snapd this is the (portable) description of an 'executable' exposed to the outside (i.e. something snapd knows how to run).
• parts: In the context of snapcraft a part refers to one build entity. They describe where to get the source of the entity, how to build it, how to stage it into the final snap and which other parts are a dependency and need to be built first. A part is much like a "makefile" target.
• interfaces: A way for a snap to talk to the outside world (or another snaps). Split into slots and plugs. Each of which has their own security permissions as a client may need to be able to do different things from a server. https://docs.snapcraft.io/interface-management
• slot: The provider part of an interface. e.g. a kwin snap might have a wayland-client slot which exposes a way for clients to talk to kwin.
• plug: The client part of an interface. e.g. an application may plug into the wayland-client slot of kwin to talk to it.
• Core: A special snap containing the core aspects of any Linux OS (libc/libpthread/...). All snaps depend on exactly one core which provides the snap's understanding of what will be in "/" from the snap's POV. The core does not include a kernel! Kernels may be snaps.
• Content Snap: Special kind of snap that implements the "content" interface. It's kind of like a shared dependency between snaps allowing one snap to be bound into the scope of another snap. For example the KF5 content snap may be used to share all of KF5 across multiple snaps.
• Build Snap: Also a special kind of snap, it's the build-time variant of the Content Snap and contains header files etc. necessary to build against a Content Snap.
• stage, staging: As part of snapcrafting parts get "staged". This kind of means the same as make install, but it's actually a separate step after make install. For the process of staging, snapcraft will copy all files created by make install into a stage directory. You may also exclude certain files or reorganize the files (e.g. rename, or move to different directory). The stage is available for parts ordered after the current one, meaning that they for example can link against a newly built library.
• prime, priming: Is similar to staging but happens once all parts are built and staged. Priming is the process by which the snap tree is actually constructed. Priming, like staging, allows for excluding files (e.g. dev headers may be staged so other parts can build using them but later excluded from priming and thus left out of the final bundle).