Snapcraft.yaml reference


#1

This document has been superseded by The snapcraft format documentation.

Information presented here might require knowledge on the snapcraft lifecycle.

Name Type Description Example Values
name
(mandatory)
string The name of the snap
Restrictions: Max len 40, must start with an ASCII character, can only use ASCII lowercase letters, numbers, and hyphens, and must have at least one letter.
my-awesome-app
version
(mandatory)
string A user facing version to display
NOTE: Needs to be wrapped with single-quotes when the value will be intepreted by the YAML parser as non-string
Restrictions: Max len. 32 chars
'1'
'1.2'
1.2.3
git (will be replaced by a git describe based version string)
version-script string A command with working directory of the source tree root that determines and prints the snap’s version string to the standard output.
This replaces the value of the version keyword, however the version keyword is still mandatory (but ignored).
cat version.txt
./snap/local/utilities/set-version.bash
summary
(mandatory)
string A 78 character limited sentence that summarizes the snap The super cat generator
description
(mandatory)
string A multiline description of the snap (use your imagination)
type enum The type of snap, implicitly set to app if not set.
More information about: gadget, kernel, base, core, app
[app|core|gadget|kernel|base]
confinement enum Determines if the snap should be restricted in access or not. Possible values are strict (for no access outside of declared interfaces through plugs), devmode (for unrestricted access) or classic. For more information, refer to Confinement [strict|devmode|classic]
icon string Relative path of a PNG/SVG icon from the source tree root to represent the snap share/icons/_package_name_.svg
logo.png
grade enum Defines the quality grade of the snap. It can be either devel (i.e. a development version of the snap, so not to be published to the stable or candidate channels) or stable (i.e. a stable release or release candidate, which can be released to all channels) [stable|devel]
architectures list[object] List of build and run architectures. Learn the syntax.
assumes list[string] A list of features that must be supported by the core in order for this snap to install.
passthrough type[object] Attributes to passthrough to snap.yaml without validation from snapcraft. Learn more at Using in-development features in `snapcraft.yaml`
apps dict A map of app-names representing entry points to run for the snap
apps.<app-name> dict
<app-name> is the name the snap will expose to run a program inside the snap. If <app-name> is named the same as name, the program will be invoked as app-name. However, if they differ, the program will be exposed as <snap-name>.<app-name>
apps.<app-name>.daemon enum If present, <app-name> will be considered a system daemon. If set to simple it is expected that the command configured is the main process, If set to oneshot, it is expected that the command configured will exit once it’s done (won’t be a long-lasting process), If set to forking, it is expected that the configured command will call fork() as part of its start-up where the parent process is expected to exit when start-up is complete, If set to notify, it is expected that the command configured will send a signal to systemd to indicate that it’s running. [simple|forking|oneshot|notify]
apps.<app-name>.command string The command to run inside the snap when <app-name> is invoked, it can be a command that is in the snap runtime’s command search PATHs($SNAP/usr/sbin:$SNAP/usr/bin:$SNAP/sbin:$SNAP/bin, or an executable’s path relative to $SNAP(NOTE: For classic confinement snaps only the latter one works as PATH isn’t modifed by wrapper in classic confinement) . If daemon is set, this will be the command to run the service. app-launch for a launcher placed under $SNAP/bin

bin/app-launch for a launcher placed under $SNAP/bin, when classic confinement is used
apps:<app-name>.desktop string A path relative to the prime directory pointing to a desktop file, snapcraft will take care of the rest. usr/share/applications/my-app.desktop
share/applications/my-app.desktop
apps.<app-name>.adapter enum Do not create a wrapper for the command holding common required environment variables supplied by the plugins used in parts. [none]
apps.<app-name>.environment dict A set of key-value pairs specifying the contents of environment variables. Key is the environment variable name; Value is the contents of the environment variable. LANG: C.UTF-8
apps.<app-name>.plugs list[string] A set of interfaces that <app-name> will plug into when running in strict confinement home
removable-media
raw-usb
NOTE: This key is NOT compatible with interfaces with attributes, refer plugs key for those interfaces
apps.<app-name>.slots NOTE: This key is NOT compatible with interfaces with attributes, refer slots key for those interfaces
apps.<app-name>.stop-command string Requires daemon to be declared. If present, It is the path to a command inside the snap to run to stop the service
apps.<app-name>.post-stop-command string Requires daemon to be declared. If present, It is the path to a command inside the snap to run after the service has been stooped
apps.<app-name>.stop-timeout string Requires daemon to be declared. It is the length of time with unit (10ns, 10us, 10ms, 10s, 10m) that the system will wait for the service to stop before terminating it via SIGTERM (and SIGKILL if that doesn’t work)
apps.<app-name>.restart-condition enum Condition to restart the daemon under. Defaults to on-failure. Refer to systemd.service manual on Restart for details [on-failure|on-success|on-abnormal|on-abort|always|never]
apps.<app-name>.socket dict If the daemon is socket activated, this section contains a map declaring sockets that will activate the service. If this section is declared, apps.<app-name>.plugs needs to declare the network-bind plug
apps.<app-name>.socket-mode integer Used together with unix sockets, and is the mode of such socket in octal.
apps.<app-name>.listen-stream string The socket abstract name or socket path. Valid formats are: <port>, [::]:<port>, [::1]:<port> and 127.0.0.1:<port> for TCP sockets, $SNAP_DATA/,$SNAP_COMMON/and@snap..` for Unix sockets
apps.<app-name>.passthrough type[object] Attributes to passthrough to snap.yaml for <app-name> without validation from snapcraft. Learn more at Using in-development features in `snapcraft.yaml`
plugs dict A set of plugs that the snap asserts, these plugs apply to all the apps home
removable-media
gnome-platform-plug
(NOTE: Differ from apps.<app-name>.plugs the value is in dict instead of list format, :(colon) must be postfixed to the interface name and shouldn’t start with -(dash-space)
plugs.<plug-name> dict A set of attributes of a plug read attribute for the home interface
plugs.<plug-name>.<attribute-name> string Value of the attribute all for read attribute of the home interface
slots dict A set of slots that the snap provides, these slots apply to all the apps
slots.<slot-name> dict A set of attributes of the slot
slots.<slot-name>.<attribute-name> dict Value of the attribute
parts dict A set of independent building blocks, conformed of either code or pre-built artifacts that will conform the snap
parts.<part-name> dict <part-name> represents the specific name of a building block which can be referenced by the command lne tool (i.e. snapcraft)
parts.<part-name>.plugin string Every part drives its build through a plugin, this entry declares the plugin that will drive the build process for <part-name>. Refer to snapcraft plugins for more information on the available plugins and the specific attributes they add to the parts.<part-name>. namespace
parts.<part-name>.source string A URL or path to a source tree to build. It can be a local path or remote, and can refer to a directory tree, a compressed archive or a revision control repository. This entry supports additional syntax, for more information refer to Advanced Grammar
parts.<part-name>.source-type enum Used when the type-of source entry cannot be detected [git|bzr|hg|svn|tar|deb|rpm|zip|7z]
parts.<part-name>.source-checksum string Used when the source represents a file, written in the format <algorithm>/<digest> where <algorightm> can be any of: md5, sha1, sha224, sha256, sha384, sha512, sha3_256, sha3_384 or sha3_512. When set, the source is cached for multiple uses in different snapcraft projects
parts.<part-name>.source-depth integer Source repositories under version control are cloned or checked out with full history. Specifying a depth will truncate the history to the specified number of commits
parts.<part-name>.source-branch string Work on a specific branch for source repositories under version control
parts.<part-name>.source-commit string Work on a specific commit for source repositories under version control
parts.<part-name>.source-tag string Work on a specific tag for source repositories under version control
parts.<part-name>.source-subdir string A path within the source to set as the working directory when building
parts.<part-name>.after list[string] Ensure that all the <part-name>s listed in after are staged before this part begins its lifecycle
parts.<part-name>.build-snaps list[string] A list of snap names to install that are necessary to build <part-name>. If a specific channel is required, the syntax is of the form <snap-name>/<channel>. This entry supports additional syntax, for more information refer to Advanced Grammar
parts.<part-name>.build-packages list[string] A list of package names to install using the build hosts package manager (e.g.; apt, dnf) that are necessary to build <part-name>. This entry supports additional syntax, for more information refer to Advanced Grammar
parts.<part-name>.stage-packages list[string] A list of package names to download and provide as part of <part-name> using the build hosts package manager (e.g.; apt, dnf) that are necessary for the runtime of <part-name>. This entry supports additional syntax, for more information refer to Advanced Grammar
parts.<part-name>.organize dict A map of files to rename, where the for the key/value pair, the key represents the path of a file inside the part while the value represents how the file is going to be staged. For more information, refer to Snapcraft filesets
parts.<part-name>.filesets
parts.<part-name>.stage list[string] A list of files from <part-name> to stage(link-missing-lifecycle). Rules applying to the list here are the same as those of filesets. Referencing of fileset keys is done with a $ prefixing the fileset key, which will expand with the value of such key
parts.<part-name>.prime list[string] A list of files from <part-name> to prime. Rules applying to the list here are the same as those of filesets. Referencing of fileset keys is done with a $ prefixing the fileset key, which will expand with the value of such key
parts.<part-name>.prepare multiline string If present, the shell script defined here is run before the build step of the plugin defined in parts.<part-name>.plugin starts. The working directory is the base build directory for the given part. The defined script is run with /bin/sh and set -e. A set of Environment Variables will be available to the script
parts.<part-name>.build multiline string If present, the shell script defined here replaces the build step of the plugin defined in parts.<part-name>.plugin starts. The working directory is the base build directory for the given part. The defined script is run with /bin/sh and set -e. A set of Environment Variables will be available to the script
parts.<part-name>.install multiline string If present, the shell script defined here is run after the build step of the plugin defined in parts.<part-name>.plugin starts. The working directory is the base build directory for the given part. The defined script is run with /bin/sh and set -e. A set of Environment Variables will be available to the script
parts.<part-name>.build-attributes enum A list of named attributes that modify the behavior of plugins. For more information, refer to snapcraft plugins
DEPRECATED: no-system-libraries
[no-system-libraries|no-install|debug]

The snapcraft format
Python as service and source hosting
Proposal: add command-chain to apps instead of generating opaque wrappers
Build your first snap
Classic confinement for bootstack-ops snap
The docs roadmap
Extracting information from sources in snapcraft parts
Add support for service timers
Install single file from stage-packages
Failed to launch apps with classic confinement
Proposed new documentation outline
#2

Feedback: apps:<app-name>.desktop is not documented


#3

version-script is also not documented.


#4

I’ve added the global plugs and slots keys, please help complete the content.


#5

apps..adapter does not make sense. The description reads like it is a boolean, but the type is enum[none] (?), and there are no valid enums values listed.


#6

Maybe the only accepted value is none? I’ve moved the part to the example values.


#7

Can this page be added to the sidebar on the new docs site here: https://discourse-docs.staging.snapcraft.io/t/snapcraft-yaml-reference/4276

The format for snap.yaml is already there so I think this page should be as well.

(apologies if that is already planned and hasn’t been done yet)


#8

@degville I believe that request goes to you ^


#9

Yes (thanks!). We’ve actually been talking about this the last couple of days, and I’m currently looking over the The snap format doc with a view to taking the same approach with snapcraft.yaml, and ultimately, adding a reference section to include both.