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
01 Declaring plugs for app developers for Ubuntu Core developers for snapd developers
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 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
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: 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 write | Result |
|---|---|
| a top-level plug or slot, listed by some apps or hooks | only those apps and hooks get it |
| a top-level plug or slot that no app or hook lists | every app and every hook gets it |
a name under an app's or hook's plugs: that is not declared at top level | a 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/hooks | it 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-attributesandslot-attributes. prepare-plug-<plug>andprepare-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
| Case | Decided by |
|---|---|
| A store snap | the 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 --dangerous | the other side's snap-declaration, else the base declaration |
| Ubuntu Core, at seeding or in a remodel | also the gadget's connections: |
| After the user disconnected it | nothing: 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
- All about interfaces: plugs, slots and how a publisher asks for auto-connection.
- Interface auto-connection: the auto-connection process, constraints and
default-provider. - Process for aliases, auto-connections and tracks: the forum request and the vote.
- Interface hooks: reading and setting attributes around a connection.
- The snap format: every key of snap.yaml, including
plugs,slotsandapps.
Roads from here
INTERFACES AND CONFINEMENT
- Interfaces — back to the interfaces overview
- The content interface — the interface with the most attributes
- Classic confinement: when the sandbox is switched off — when interfaces are not enough
- Interfaces for users — what your users will see
- How interfaces are implemented — what snapd does with your declarations
- Workloads — permissions decided at runtime and why they are not here yet
HOOKS · code snapd runs inside a snap
- Hooks: interface hooks — checking a connection before it is made
POLICY · who may install and connect what
- Interface policy: the questions snapd asks — the rules your plugs and slots meet
- Snap-declaration rules — the store rules a publisher can be granted
DEVELOPING SNAPS · try, pack, run, debug
- Trying and packing a snap — building and installing while you work