Adding global metadata

doc
1

Global metadata attributes are used within snapcraft.yaml to identify the snap locally, and after publishing to the Snap Store, to identify your snap to users and potential users.

Attributes include a snap’s name and description, its level of confinement, and where the application icon can be found.

name: qfsview
summary: Visualise storage utilisation.
description: |
    qFSView displays files and folders as a rectangle with an
    area proportional to the storage they and their children use.
version: 1.0
icon: gui/qfsview.png
base: core18
grade: stable
confinement: strict

For the complete list of global metadata, see Snapcraft top-level metadata.

Recommended global metadata

Global metadata is a mixture of mandatory and optional values.

You can generate a buildable template of both required and recommended values with the snapcraft init command in a new project folder (see Snapcraft overview for more details).

The following attributes are mandatory:

  • name A snap’s name is important. It must start with an ASCII character and can only contain 1) letters in lower case, 2) numbers, and 3) hyphens, and it can’t start or end with a hyphen. For the Snap Store, it also needs to be both unique and easy to find.

    For help on choosing a name and registering it on the Snap Store, see Registering your app name.

  • summary The summary is a short descriptive sentence to tell prospective users about an application’s primary purpose, in fewer than 80 characters.

  • description Unlike the summary, the description can be as verbose as you need it to be. The above snippet shows the description text following a pipe symbol (|), which is used in YAML to maintain newline formatting in multiline text blocks.

    The following, for example, will ensure both Line one and Line two appear on separate lines:

    description: |
    Line one
    Line two

    While you shouldn’t write thousands of words, the more details you provide, the more likely people are to discover and use your application. Feature lists, update descriptions, a brief Getting started guide, are legitimate uses for the description.

  • version While having a value for version is mandatory, its value can be anything. Setting this to something like test makes sense while you’re first building your snap, and you can later replace this with a specific version, or a reference to a script that replaces the version number automatically.

    The value for version is also commonly imported for external metadata. See Using using external metadata for further details.

The following attributes should also be included:

  • base A base snap is a special kind of snap that provides a run-time environment with a minimal set of libraries that are common to most applications.

    See Base snaps for help selecting a base for your snap.

  • grade This should initially be devel and changed to stable when you have a snap ready for release.

  • confinement A snap’s confinement level is the degree of isolation it has from your system. When first building a snap, set this to devmode to initially limit the side-effects of confinement until you have a working snap.

    See Snap confinement for further details.

For convenience, and to help avoid duplicating sources, external metadata such as AppStream can be imported into snapcraft.yaml. See Using external metadata for further details.

Two further global attribites are apps: and parts:. These expand into separate sections that deal with how your snap is built and where its various resources are located. See Adding parts for the next logical step in snap building.

2

While this page suggests you can continue a multi-line description using a chevron “>”, there is no such symbol in the sample description; rather, there is a trailing pipe symbol on the “description:” line, which is not explained.

3

Thanks for the comment. I’ve removed the angle bracket/chevron statement and hopefully clarified the use of a pipe. People are still free to use the chevron (description: >) and double newline, as per YAML, but I don’t think I’ve ever seen it used in a snapcraft.yaml.

4

At end of “description” entry:

“* Feature lists, update descriptions, a brief Getting started guide, are legitimate uses for the summary.”

Pretty sure that last word should be “description”, not “summary”, no?

1 Like