Interfaces for snap developers

interfaces · for developers for app developers

Declaring plugs and slots in snap.yaml, assigning them to apps and hooks, giving them attributes, and what decides which plugs connect by themselves.

On the map: the builders' yard, inside the gatehouse

▶ Watch this deck — 4 scenes, ~3 min

01 Declaring plugs for app developers for Ubuntu Core developers for snapd developers

FOR DEVELOPERS photo-editor snap.yamlplugs:camera:sdcard:interface: removable-media apps:editor:plugs: [home, network, camera]convert:plugs: [home]hooks: may list plugs too editorhome · network · cameraconverthome: no camera for scripts home, network: named by an app,created as plugs of that interface sdcard: listed by no app or hook,so every app and hook gets it fixed when the snap is built
photo-editor's snap.yaml: top-level camera and sdcard plugs, the editor app listing home, network and camera, the convert app listing home; on the right, what each app gets, including the unlisted sdcard plug given to every app and hook

Top-level plugs name the plugs; each app or hook lists the ones it uses. A name listed only under an app becomes a plug of that interface. A top-level plug that no app or hook lists is given to every app and hook.

You're packaging the photo editor. In its snap.yaml, a top level plugs section names what the snap may ask for. Each app then lists the plugs it uses, so the editor and the convert command can differ: convert runs from scripts and needs home, but not the camera. Hooks can list plugs too. Two defaults are worth knowing. An app can name an interface directly, and the plug is created for it. And a top level plug that no app or hook lists goes to all of them. All of this is fixed when you build the snap.

02 Slots and attributes for app developers for Ubuntu Core developers for snapd developers

SLOTS AND ATTRIBUTES filter-pack snap.yamlslots:filters:interface: contentcontent: photo-filters photo-editor snap.yamlplugs:filters:interface: contentcontent: photo-filters attributes on both sides: the content label must match old-settings:interface: personal-filesread:- $HOME/.photo-editorattributes can nameexactly what is granted personal-files plug:allow-installation: false a store snap needs its own rule, naming the path
filter-pack's content slot and photo-editor's content plug with a matching content label; photo-editor's personal-files plug with a read path; the base declaration's allow-installation: false means a store snap needs its own rule naming the path

Slots are declared like plugs. Attributes on either side are part of what the rules check: content labels must match, and a personal-files plug's read paths need a store rule because the base declaration has allow-installation: false.

A snap can offer slots, too. filter-pack, a second snap made up for these decks, offers its filters through a content slot, and the photo editor's content plug connects to it. Both sides carry attributes, here the content label that has to match. Attributes can also say exactly what's granted. Say the editor reads its old settings from a dot directory in your home: a personal-files plug lists that path in its read attribute. The rules check attributes, and personal-files has allow-installation: false. So a store snap with that plug needs its own rule, naming the path.

03 What connects by itself

WHAT CONNECTS BY ITSELF not your call in snap.yaml: the declarations decide networkhomedesktop: connected by the base declaration cameraremovable-mediawait for the user request on the forumreviewers votea rule in snap-declaration $ sudo snap install --dangerous ./photo-editor_0.1_amd64.snapauto-connect: base declaration $ sudo snap connect photo-editor:camerano connection rule is read$ snap connections photo-editorwhat your users will see
Four plugs of photo-editor: network and home connect by themselves on a desktop, camera and removable-media wait for the user; the store can grant auto-connection through a forum request that ends as a rule in the snap-declaration; during development, a --dangerous install, snap connect and snap connections

Auto-connection is decided by the base declaration, or by a rule the store adds to the snap's snap-declaration after a forum request. A --dangerous install auto-connects by the base declaration, and snap connect is not held back by any connection rule; it still needs a matching slot.

Which of your plugs are connected when someone installs the photo editor? You don't decide that in snap.yaml. On a desktop, network and home connect by themselves under the base declaration. Camera and removable-media wait for the user. If your app can't do its job without one of those, the store can grant auto-connection: you ask on the forum, reviewers vote, and the grant arrives as a rule in your snap-declaration. While you develop, install with --dangerous. auto-connection then follows the base declaration, snap connect isn't held back by any connection rule, and snap connections shows what your users will see.

04 Where to go from here

ROADS Interfaces for developers contentboth sides of a shared directory Policythe rule that decides Interface hookscheck before connecting Try and packbuild and install while you work For userswhat your users will see
Roads for developers: content, policy, interface hooks, try and pack, and the users' deck

Roads: content, policy, interface hooks, try and pack, and what users see.

Plugs, slots, attributes and what connects by itself. Here's where to go deeper. Content has a deck of its own, with both sides of a shared directory. The policy district explains the rules your plugs meet, and how to read the one that decides. Interface hooks let your snap check or adjust a connection's attributes before it's made. Try and pack covers building and installing the snap while you work. And the users' deck shows what your users will see.

Read more

for app developers for Ubuntu Core developers for snapd developers

How plugs and slots are bound in snap.yaml

You writeResult
a top-level plug or slot, listed by some apps or hooksonly those apps and hooks get it
a top-level plug or slot that no app or hook listsevery app and every hook gets it
a name under an app's or hook's plugs: that is not declared at top levela plug of the interface with that name is created, for that app or hook
a top-level plug with interface: <name>a plug named differently from its interface, such as sdcard for removable-media
a hook that is not declared in snap.yaml but shipped in meta/hooksit gets every top-level plug and slot that no app or hook lists

for app developers for Ubuntu Core developers for snapd developers

Attributes

  • Attributes are keys on a plug or slot other than interface. Each interface defines its own.
  • The interface validates them when the snap is installed, and rules in the base declaration and snap-declarations can constrain them with plug-attributes and slot-attributes.
  • prepare-plug-<plug> and prepare-slot-<slot> hooks can read and set attributes for one connection before it is made; the rules are checked after those hooks.

Which plugs connect by themselves

CaseDecided by
A store snapthe plug's rule in the snap's snap-declaration, else the slot's in the provider's, else the base declaration
A snap installed with --dangerousthe other side's snap-declaration, else the base declaration
Ubuntu Core, at seeding or in a remodelalso the gadget's connections:
After the user disconnected itnothing: it stays disconnected until connected again or forgotten

When more than one slot qualifies and the rule does not allow several (slots-per-plug: *), nothing is connected.

Further reading

Roads from here

INTERFACES AND CONFINEMENT

HOOKS · code snapd runs inside a snap

POLICY · who may install and connect what

DEVELOPING SNAPS · try, pack, run, debug