Build your first snap

A single text file

Note: We strongly recommend using an Ubuntu 16.04 host, VM or container for this guide. While it is possible to use newer releases of Ubuntu, or other Linux distributions, this may result in incorrect libraries being pulled into the build.

Snapcraft uses a single text file to describe the entire build process for a snap: the snapcraft.yaml file.

To get started with a template, you can run snapcraft init.

It will create a new directory snap with a file named snapcraft.yaml in the current directory.
Let’s have a look inside:

$ cat snap/snapcraft.yaml
name: my-snap-name # you probably want to 'snapcraft register <name>'
version: '0.1' # just for humans, typically '1.2+git' or '1.3.2'
summary: Single-line elevator pitch for your amazing snap # 79 char long summary
description: |
  This is my-snap's description. You have a paragraph or two to tell the
  most important story about your snap. Keep it under 100 words though,
  we live in tweetspace and your description wants to look good in the Snap

grade: devel # must be 'stable' to release into candidate/stable channels
confinement: devmode # use 'strict' once you have the right plugs and slots

    # See 'snapcraft plugins'
    plugin: nil

This is the only file needed in the directory. Snapcraft can use local source code or fetch everything needed to build the snap from remote sources as you will see in the following example.

From an app to a snap

Your first snap is going to be a very straightforward one. We are going to snap GNU Hello, an app that prints “Hello, world!” on the command line.

Let’s edit the snapcraft.yaml file. First, we need to set the general metadata for the snap:

  • its name
  • the version of GNU Hello we are going to snap
  • a one-line summary and a user friendly description
  • grade and confinement, which inform the system if the snap is meant to be a stable release (grade: stable or devel) and if strict security policies should be enforced (confinement: strict or devmode).
name: hello
version: "2.10"
summary: GNU Hello, the "hello world" snap
description: GNU Hello prints a friendly greeting.
grade: stable
confinement: strict

Then, you need to declare [apps and commands](/build-snaps/metadata) shipped in the snap. In this case, we have a single app (`hello`) with a single command (`hello`).
    command: hello

Now, you need to tell snapcraft where to find the hello source code and how to build it. This is done with the `parts` keyword, which are [building blocks](/build-snaps/parts) that compose your snap.

In this case, it’s a single part, pulled from a remote tar.gz source, then built using the autotools plugin (which will run the usual autotools steps: configure, make, make install).

    plugin: autotools

Let's have a look at our final file:
name: hello
version: "2.10"
summary: GNU Hello, the "hello world" snap
description: GNU Hello prints a friendly greeting.
grade: stable
confinement: strict

    command: hello

    plugin: autotools

## Run snapcraft

You can now build a snap out of your snapcraft.yaml by running snapcraft in the project directory:

$ snapcraft
Preparing to pull gnu-hello
Pulling gnu-hello
Downloading 'hello-2.10.tar.gz'[=======================] 100%
Preparing to build gnu-hello
Building gnu-hello
Staging gnu-hello
Priming gnu-hello
No libraries to exclude from this release
Snapping 'hello' ...
Snapped hello_2.10_amd64.snap

Snapcraft just pulled the source code, built and snapped it.

The snap is now available in your directory (along with new parts, prime, and snap directories that allow faster iterations between builds of the same project).

$ ls
hello_2.10_amd64.snap  parts  snap  prime

The name of the `.snap` file is based on information in the `snapcraft.yaml` (its name and version) and the architecture you're building on: `__.snap`. Here, the snap was built on an amd64 machine, so the architecture used in the file name reflects that.

Install the snap

Now that everything needed for the hello app to run has been packaged inside a snap. You can install it locally.

The --dangerous flag needs to be used here because your snap has not been signed.

$ sudo snap install hello_2.10_*.snap --dangerous
hello 2.10 installed

Congratulations, you've just made and installed your first snap!

You can run the hello command to see it in action:

$ hello
Hello, World!

You can also use the `snap info` command to get more details about it:
$ snap info hello
name:      hello
summary:   "GNU Hello, the \"hello world\" snap"
description: GNU Hello prints a friendly greeting
  - hello
installed: 2.10 (x1) 65kB -
refreshed: 2016-12-23 17:03:55 +0100 CET

Record a manifest of the build

You can record a manifest full of details of the build, including information
about the machine where the snap was built, what was installed on that machine
during the build and what was installed inside the snap. Recording this
information is useful for the users to know exactly what they are installing
on their systems, and it is useful for you for security auditing. When there
is a report of a new security vulnerability, you will know if it affects your
snap by checking the manifest.

To record this manifest, run snapcraft with the environment variable

After the build is done, the manifest will be recorded into the file
prime/snap/manifest.yaml. After the snap is installed, it will be available
on /snap/<snap-name>/current/snap/manifest.yaml.

This file includes the values from the original snapcraft.yaml, plus the
following annotations for each part:

  • installed-packages: The names and versions of the packages installed during the build of the part.
  • stage-packages: The names and versions of the packages installed inside the snap.
  • installed-snaps: The names and revisions of the snaps installed in the machine during the build.
  • uname: System information, including kernel version, operating system name and architecture.

If snapcraft was executed in a container build, it will also record image-info,
with the fingerprint of the container image, the architecture and the date it
was created.

In addition to this, each plugin adds information
specific to its build process. For example, if the plugin uses a package manager
to install additional dependencies, the name and version of those dependencies
will be recorded.

More tutorials

Ubuntu Tutorials are just like learning from pair programming except you can do it on your own.

Recommended snap tutorials to get started: