Snapcraft overview

1

Snapcraft is a powerful and easy to use command line tool for building snaps. It helps you to:

  • build and then publish your snaps on the Snap store
  • use channels, tracks and branches to finely control updates and releases
  • build and debug snaps within a confined environment
  • update and iterate over new builds without rebuilding the environment
  • test and share your snaps locally

On Linux distributions with snap support, the easiest way to install snapcraft is via its snap:

sudo snap install snapcraft --classic

The --classic argument is required because snapcraft uses classic confinement.

Snapcraft can also be installed and run on Apple’s macOS. See Install snapcraft on macOS for details.

See below for a general overview of Snapcraft’s capabilities, and see Creating a snap for a more detailed look at the process, alongside a selection of self-contained examples for some popular languages and frameworks, including Go, Python and C/C++.

ⓘ If you’re using an apt installed version of snapcraft, such as the package for Ubuntu 18.04 LTS, you need to remove this (sudo apt remove snapcraft) and install snapcraft from its snap to access the latest features.

Working with snapcraft

At the heart of the snapcraft build process is a file called snapcraft.yaml. This file describes a snap’s build dependencies and run-time requirements, it integrates remote repositories and extensions, and runs custom scripts and hooks for better integration with CI systems.

Snapcraft 3.0, and later releases, are designed to use bases (see Base snaps) and LXD or Multipass to both simplify the build process and to confine the build environment within a virtual machine. Confining the build in this way isolates potentially conflicting libraries and other files from your host system, and vice-versa.

Snapcraft offers a variety of options when using LXD and Multipass. See Build options for details on build options and build providers for details on interacting with LXD and Multipass.

Creating snapcraft.yaml

To get started, run snapcraft init. This creates a buildable snapcraft.yaml template within a snap sub-directory relative to your current filesystem location. If the command cannot be found, make sure /snap/bin is on your PATH.

The typical snap build process centres on iterating over the configuration of parts, plugins and interfaces within this snapcraft.yaml file:

  • parts are the raw building blocks of a snap, used to collect and build binaries and their dependencies.
  • plugins are used within parts to better integrate projects using languages and framework.
  • interfaces enable resources from one snap to be shared with another, and with the host system.

The following lists how you might want to approach building a new snap for your application with snapcraft.yaml:

  1. describe your application with top-level metadata
  2. use parts metadata to import and build your application and its dependencies
    • incorporate plugins within parts to easily integrate applications using specific languages and frameworks, or work with binary files directly. You can also write your own plugin.
    • use plugin metadata to locate your project, or sync with a remote repository
    • set build dependencies, if required, and any run-time dependencies
  3. add interface metadata to connect external system resources to your application

Building your snap

When you are ready to test the contents of snapcraft.yaml, simply run snapcraft --debug in the same directory where you initialised the snap.

If this is the first time you’ve built a snap with snapcraft, you will either need to have a build provider installed, or you will be prompted to install it before the build continues:

$ snapcraft --debug
LXD is required but not installed. Do you wish to install LXD and configure it with the defaults? [y/N]: y

The --debug argument isn’t necessary, but it helps when testing a new snapcraft.yaml.

With --debug, if snapcraft encounters an error it will automatically open a shell within your snap’s build environment. You can then explore the build issue directly, working on your project within the parts directory, or the files being staged within prime, depending on the build stage when the error occurred.

ⓘ See iterating over a build for more information about the --debug flag (and the related flags --shell and --shell-after).

Critically, you can update snapcraft.yaml outside of the build environment and run snapcraft within the build environment to incorporate any external changes and continue with the build. If there are no further errors, your snap will be built.

ⓘ See Debugging building snaps for common problems and their solutions.

To see snapcraft build the template created by snapcraft init, simply run snapcraft --debug:

$ snapcraft --debug
Launching instance...
Executed: pull my-part
Executed: overlay my-part
Executed: build my-part
Executed: stage my-part
Executed: prime my-part
Executed parts lifecycle
Generated snap metadata
Created snap package my-snap-name_0.1_amd64.snap

The build process will proceed through the Snapcraft lifecycle, installing and building your project’s dependencies, as described by your snapcraft.yaml. The time this takes will depend on the complexity of your project and the capabilities of your system.

Testing your snap locally

After a snap has been built, it can be installed locally with the --devmode flag, enabling your unsigned and unconfined snap to be installed:

sudo snap install my-snap-name_0.1_amd64.snap --devmode
my-snap-name 0.1 installed

For a more comprehensive and iterative break-down of the snap building process, see Creating a snap.

ⓘ To see what’s new in each release of Snapcraft, take a look at Snapcraft release notes.

1 Like
2

minor grammer correction: change you to your

1 Like
3

Blockquote use parts metadata to import and build your application and its dependencies incorporate plugins within parts to easily integrate applications using specific languages and frameworks, or work with binary files directly. You can also You can also write your own plugin.

Please kindly remove extraneous “You can also” in the above section 2.

1 Like
4

Good spot - thank you!

5

However, the guides for all languages and platforms that use snapcraft.yaml (except, oddly, Java) say “Snaps are defined in a single YAML file placed in the root of your project”.

If both the project root and snap/ are allowed locations, this should be made explicit.

[Prompted by a question in build.snapcraft.io#1094.]

6

@degville Snapcraft format claims that the three main concerns in a snapcraft.yaml are:

  1. top-level metadata
  2. apps
  3. parts

This Snapcraft overview page suggests instead that its:

  1. parts
  2. plugins
  3. interfaces
7

@degville hey there, just want to mention that

Given how it is phrased will need constant updating, how about a mention of “Since”, and the version bases were introduced was 3.0

8

Good idea, will do - thanks!

9

Right at the beginning of the “Building your snap” section, one reads:

" When you are ready to test the contents of snapcraft.yaml, simply run snapcraft --debug in the same directory where you initialised the snap."

I would add, right there, that this requires Multipass, and not leave that note until later, just to avoid surprises.

10

I mentioned this elsewhere but is there any value to mentioning “–jailmode” near the bottom of the page with the other installation options?

11

Thanks for the suggestion. You are prompted to install Multipass if it’s not installed, but I added that note so that people are prepared for this question.

12

Example toward the end that uses both --devmode and --dangerous; --devmode implies --dangerous, so using both seems potentially misleading.

13

Good point. Thanks for letting me know.

14

This page suggests writing your own local plugins; that is no longer supported for SC7/Core22.

15

Regarding running “snapcraft init”, it might be worth mentioning that there is nothing magic about that, and one can simply manually set up a new project by copying some other snapcraft.yaml file and starting fresh.