GNOME 3.34 snapcraft extension

We constantly strive to empower developers. Part of that aim extends to making development easier, for example improving build tools and documentation. As an element of this continued effort, we would like to introduce the new gnome-3-34 snapcraft extension!

What is the GNOME snapcraft extension?

The gnome-3-34 snapcraft extension is a code addition to snapcraft itself that abstracts away some commonly used snapcraft.yaml lines while also tailoring the build environment of GNOME application snaps. While this extension contains GNOME in the name and is tailored to GNOME apps, it is worth noting that the extension provides many of the components needed for desktop applications in general, making it useful for a broader set of applications than just GNOME.

Before the gnome-3-34 snapcraft extension, it was common to copy/paste code snippets found in all GNOME applications, which made building a snap less intuitive and a little cumbersome. So these values have been provided by just using the extension. These additions improve the overall build environment of GNOME application snaps and are accomplished through the use of a build snap (gnome-3-34-1804-sdk) and a platform snap (gnome-3-34-1804).
Note that this gnome-3-34 snapcraft extension should not be confused with GNOME Shell extensions, which are available to modify the GNOME Shell behaviors of the GNOME desktop.

The build snap builds 35 libraries from source that are commonly used across GNOME applications. Examples include glib, gtk, and gnome-desktop. These libraries are built to provide newer versions of these packages that exist in the core18 base snap (a subset of the Ubuntu 18.04 archive). It is common for GNOME applications to release a gnome-3-34 branch of their project when the 3.34 version of GNOME is released (or shortly thereafter). Keeping this in mind, the build snap looks for this first to provide access to various GNOME libraries on their gnome-3-34 branch, to distribute the latest stable version that corresponds to the GNOME 3.34 release. The libraries built in the gnome-3-34-1804-sdk build snap are:

• libtool
• libffi
• glib (2.62)
• pixman (0.38.4)
• cairo (1.16.0)
• gobject-introspection (gnome-3-34 branch)
• vala (0.46)
• gee (0.20.2)
• atk (gnome-3-34 branch)
• at-spi2-core (2.34.0)
• at-spi2-atk (2.34.1)
• fribidi (1.0.7)
• harfbuzz (2.6.2)
• pango (1.44.6-2)
• librsvg (2.44)
• gdk-pixbuf (2.38)
• epoxy (1.5.3)
• json-glib (1.4)
• libpsl (0.21.0)
• libsoup (2.68.2)
• librest (0.7)
• gtk (3.24.10)
• gtk-locales
• mm-common (1.0.0)
• glibmm (2.62.0)
• cairomm (1.12.2)
• pangomm (2.42.0)
• atkmm (2.28.0)
• gtkmm (3.24.2)
• gtksourceview (4.4.0)
• libdazzle (3.34)
• libcanberra
• gsettings-desktop-schemas (gnome-3-34 branch)
• gnome-desktop (gnome-3-34 branch)
• cogl (1.22)
• clutter
• clutter-gtk (1.8.4)
• libpeas (1.22.0)
• pycairo (1.18.1)
• pygobject (3.34)
• libhandy (libhandy-0-0 branch)

There are also several packages included from the Ubuntu 18.04 apt repository:

• gcc
• pkg-config
• libpcre3-dev
• zlib1g-dev
• libmount-dev
• libxml2-dev
• libsqlite3-dev
• libbrotli-dev
• libthai-dev
• libfontconfig1-dev
• libxrender-dev
• libxft-dev
• libxcb-shm0-dev
• libxcb-render0-dev
• libxext-dev
• libxi-dev
• libxrandr-dev
• libxcursor-dev
• libxcomposite-dev
• libxdamage-dev
• libxinerama-dev
• libwayland-dev
• wayland-protocols
• libxkbcommon-dev
• libgl1-mesa-dev
• libegl1-mesa-dev
• libdbus-1-dev
• libxtst-dev
• gettext
• shared-mime-info
• libwebkit2gtk-4.0-dev
• libgcr-3-dev
• libnotify-dev
• libsecret-1-dev
• itstool
• libudev-dev
• libseccomp-dev
• libjpeg-dev
• liblcms2-dev
• libgspell-1-dev
• python3-minimal
• libxml2-utils
• libgtksourceview-3.0-dev
• libtdb1
• libvorbisfile3
• libegl-mesa0

The platform snap takes the build snap and makes all of those libraries available to your snap at build time without needing to include the pieces of the build snap that are unnecessary at runtime (like compilers) in your final snap. 

In addition to using the build and platform snaps, the gnome-3-34 snapcraft extension also sets a couple of environment variables, links, default plugs for the app to use, and a default build-environment for each part in your snap to use.

Plugs available

The documentation describes how the slots and plugs connect to provide access to an interface. Desktop applications typically consume information from interfaces with the use of plugs and there are a few GNOME-sepcific interfaces that are common among GNOME applications that have been included in the snapcraft extension.

When you use the gnome-3-34 snapcraft extension, these plugs are provided automatically to your snapcraft.yaml.

    plugs:
        gtk-3-themes:
            interface: content
            target: $SNAP/data-dir/themes
            default-provider: gtk-common-themes
        icon-themes:
                interface: content
                target: $SNAP/data-dir/icons
                default-provider: gtk-common-themes
        sound-themes:
                interface: content
                target: $SNAP/data-dir/sounds
                default-provider: gtk-common-themes
        platform_snap:
                interface: content
                target: $SNAP/gnome-platform
                default-provider: gnome-3-34-1804

Your app may still  need additional plugs, but you can expect the following plugs to be automatically available to your apps as well:

plugs: [ desktop, desktop-legacy, gsettings, wayland, x11 ]

Environment variables set for the building application

The following “build-environment” section is made available to each part built in your snap. If you define other build-environment variables, then those will get added to these and the set is used. If you define another value for one of these variables, then the value you’ve defined will be used instead of the value defined within the extension.

 build-environment:
   - PATH: /snap/gnome-3-34-1804-sdk/current/usr/bin:$PATH
   - XDG_DATA_DIRS: /snap/gnome-3-34-1804-sdk/current/usr/share:/usr/share:$XDG_DATA_DIRS
   - LD_LIBRARY_PATH:/snap/gnome-3-34-1804-sdk/current/lib/$SNAPCRAFT_ARCH_TRIPLET:/snap/gnome-3-34-1804-sdk/current/usr/lib/$SNAPCRAFT_ARCH_TRIPLET:/snap/gnome-3-34-1804-sdk/current/usr/lib:/snap/gnome-3-34-1804-sdk/current/usr/lib/vala-current:$LD_LIBRARY_PATH
   - PKG_CONFIG_PATH: /snap/gnome-3-34-1804-sdk/current/usr/lib/$SNAPCRAFT_ARCH_TRIPLET/pkgconfig:/snap/gnome-3-34-1804-sdk/current/usr/lib/pkgconfig:/snap/gnome-3-34-1804-sdk/current/usr/share/pkgconfig:$PKG_CONFIG_PATH
   - GETTEXTDATADIRS:/snap/gnome-3-34-1804-sdk/current/usr/share/gettext-current:$GETTEXTDATADIRS
   - GDK_PIXBUF_MODULE_FILE: /snap/gnome-3-34-1804-sdk/current/usr/lib/$SNAPCRAFT_ARCH_TRIPLET/gdk-pixbuf-current/loaders.cache

Environment variables set for the running application

The following environment is set when your application is run.

 environment:
   - SNAP_DESKTOP_RUNTIME: $SNAP/gnome-platform
   - GTK_USE_PORTALS: 1

Layouts set

The host’s gjs, webkit2gtk-4.0, and iso-codes are used so they don’t need to be packaged as part of the snap (would greatly inflate the size).

    layout:
        /usr/lib/$SNAPCRAFT_ARCH_TRIPLET/webkit2gtk-4.0:
            bind: $SNAP/gnome-platform/usr/lib/$SNAPCRAFT_ARCH_TRIPLET/webkit2gtk-4.0
        /usr/share/xml/iso-codes:
            bind: $SNAP/gnome-platform/usr/share/xml/iso-codes

When should I use it?

The gnome-3-34 snapcraft extension is useful for GNOME Gtk 3 apps and we are focusing on Gtk 3 because it is the most common. When Gtk 4 is released, future extensions can be expected to support that as well. However, if you have an app using a Gtk version prior to 3, then this extension is not ideal and you should either not use the extension at all or wait until the app is using Gtk 3 to apply the gnome-3-34 snapcraft extension.

Why should I use it?

By using the gnome-3-34 snapcraft extension, you reduce the overall size of the snapcraft.yaml while making it more readable as well, which makes it easier to maintain.

How do I use it?

To implement the extension in an existing snapcraft.yaml file, just follow a few steps. Note that any lines that are red and start with a “ – “ should be removed, while any lines that are green and start with a “+” should be added. 
To demonstrate these changes, let’s look at tali, a GNOME dice game. After these changes, we will have updated tali’s snapcraft.yaml to use the gnome-3-34 snapcraft extension.

1. Remove the lines regarding the bits provided by the gnome-3-34 extension. As outlined in the previous section, the gnome-3-34 extension provides a set of common plugs.

- plugs:
-    gnome-3-28-1804:
-        interface: content
-        target: $SNAP/gnome-platform
-        default-provider: gnome-3-28-1804
-    gtk-3-themes:
-        interface: content
-        target: $SNAP/data-dir/themes
-        default-provider: gtk-common-themes
-    icon-themes:
-        interface: content
-        target: $SNAP/data-dir/icons
-        default-provider: gtk-common-themes
apps:
    tali:
        command: desktop-launch tali
-        plugs:
-            - desktop
-            - desktop-legacy
-            - gsettings
-            - unity7
-            - wayland

2. You also likely have a desktop-helpers part (the part could be named anything but the source is the desktop helpers scripts). Remove this part and any mentions of the part thereafter.

    parts:
-    desktop-gnome-platform:
-        source: https://github.com/ubuntu/snapcraft-desktop-helpers.git
-        source-subdir: gtk
-        plugin: make
-        make-parameters: ["FLAVOR=gtk3"]
-        build-packages:
-            - build-essential
-            - libgtk-3-dev
-        override-build: |
-            snapcraftctl build
-            mkdir -pv $SNAPCRAFT_PART_INSTALL/gnome-platform
        tali:
-        after: [desktop-gnome-platform]
...

3. Remove any build-packages listed in any of your parts that have been listed above. You no longer need to install these from the core snap since we’ve provided newer versions via the build snap.

parts:
  tali:
    source: .
    source-type: git
    override-build: |
sed -i.bak -e 's|=org.gnome.Tali$|=${SNAP}/meta/gui/org.gnome.Tali.png|g' data/org.gnome.Tali.desktop.in
snapcraftctl build
            mkdir -p $SNAPCRAFT_PART_INSTALL/meta/gui/
            cp ../src/data/icons/256x256/org.gnome.Tali.png  $SNAPCRAFT_PART_INSTALL/meta/gui/
              cp ../install/snap/tali/current/usr/share/applications/org.gnome.Tali.desktop $SNAPCRAFT_PART_INSTALL/meta/gui/
    plugin: meson
    meson-parameters: [--prefix=/snap/tali/current/usr]
    organize:
      snap/tali/current/usr: usr
-    build-packages:
-      - gettext
-      - itstool
-      - libglib2.0-dev
-      - libgtk-3-dev
-      - librsvg2-dev

4. In order to have access to the gnome-3-34 extension, you need to specify it in the apps section.

apps:
    tali:
+       extensions: [gnome-3-34]
        command: desktop-launch tali

5. Change the command with which your app is launched.

apps:
    tali:
        extensions: [gnome-3-34]
-       command: desktop-launch tali
+       command: usr/bin/tali

6. Look for any other changes that may be needed (determined by building changes 1-5 above, installing the snap, and running it). In the tali example, no additional changes were needed.

That’s it! Often this leads to removing about 30 lines and adding one so good job slimming down your yaml!

Next Steps

The plan is to create a new GNOME snapcraft extension for each GNOME release and any snapcraft.yaml using the gnome-3-34 extension should be able to update to the newest GNOME snapcraft extension.

However, there are plans to eventually use a shared base with flatpaks, namely freedesktop-sdk. This would replace the core18 base along with the GNOME snapcraft extensions. Since this is a long-term plan, there will continue to be a parallel effort to maintain and develop new GNOME snapcraft extensions until the switch to freedesktop-sdk has been made.

Summary and conclusion

To summarize a bit, a feature has been added to snapcraft that makes building Gtk 3 apps easier by slimming down the snapcraft.yaml file. Using this gnome-3-34 snapcraft extension makes the snap metadata more intuitive and maintainable by removing commonly used code snippets. Use of this new gnome-3-34 snapcraft extension is an optional but highly recommended method to provide your snapcraft.yaml with the required information.

Photo by Samantha Gades on Unsplash