Undocumented interfaces

doc
1

I am researching approaches to presenting interface plugs and slots to PC users.

As I said during the Snappy sprint in London in June, the first step is to get a complete list of interfaces and what they do.

The interfaces reference currently lists 79 interfaces (one of them twice), including 22 that are not listed by snapd 2.26’s snap interfaces command (bluez, content, docker, dbus, fuse-support, fwupd, gpio, hidraw, i2c, iio, location-control, location-observe, lxd, maliit, mpris, serial-port, thumbnailer-service, ubuntu-download-manager, udisks2, unity8, unity8-calendar, and unity8-contacts).

Meanwhile, snap interfaces currently lists 64 interfaces, including 7 that are not listed in the interfaces reference (classic-support, hardware-random-control, hardware-random-observe, joystick, kubernetes-support, netlink-audit, and netlink-connector).

So, are either of these lists authoritative?

(I’m aware of the proposal to host documentation on the forum, but that addresses only one discrepancy, the content interface.)

Assuming that the answer is not “the online reference is authoritative”, how can I find out which of the undocumented interfaces are auto-connect, are transitional, or have attributes?

Thanks!

2

note that the snap interfaces output will differ depending on the environment you run it under …
the list on an Ubuntu Core system is different to what you get on a classic server or desktop …

and it will likely also start to differ between distro implementations once we have base snaps for different distros that allow you to install fedora snaps on ubuntu etc …

3

In addition to what @ogra said regarding snap interfaces, the canonical list maintained by the snappy team is https://github.com/snapcore/snapd/wiki/Interfaces. I went through that list last week and made sure it was up to date for 2.27. I don’t know who is maintaining the links you referenced.

4

We have work in progress and going out pretty soon that will create a new “snap interface” command that will report in a much nicer way which interfaces exist, a summary of what they do, which attributes are currently set on them (behind a flag), and an optional link to the documentation in the forum. This will be the most authoritative list as it will reflect exactly what is in the code.

1 Like
5

Thanks. I’ve begun compiling a spreadsheet of proposed interface categories and descriptions based on the wiki list. (Comments welcome!) Ideally these categories and descriptions would be built into snapd too, so that GUI runtime prompts and settings UI would not break when interfaces are added or removed afterward.

I’ve also reported the confused reference situation as a bug.

1 Like
6

Hey @mpt, thank you for doing this work. Once this is ready can you please start filing pull requests to update summary lines in individual interface files in the snapd tree? Do you plan to create forum threads that document particular interfaces? Snapd allows to add a documentation URL to any interface and I’d love to be able to use it.

7

Thanks to @jdstrand for many comments on the spreadsheet of proposed interface descriptions over the past couple of weeks. I’m now down to 38 out of 95 interfaces without a user-facing summary. If anyone else can comment with suggestions, I would be grateful.

Once this is ready can you please start filing pull requests to update summary lines in individual interface files in the snapd tree?

Yes, I would be happy to do that.

Do you plan to create forum threads that document particular interfaces?

Unfortunately I don’t know enough about any interface to write a forum post on it.

8

I don’t think there should be a forum post for each individual interface. For most interfaces, I think that it would be fine to point people at https://github.com/snapcore/snapd/wiki/Interfaces (which is updated for new interfaces) or to pull that into the forum and redirect it to the forum. It has extra details already for the interfaces that need it (eg, ‘core-support’ says what it is for and that it is reserved for core snaps).

Some interfaces are harder to use (eg content, dbus) and definitely should have a forum post dedicated to their use. There are also classes of interfaces that can be described together (eg, what interfaces should a desktop snap typically use?). I plan to write a forum post on desktop interfaces now that desktop, desktop-legacy and wayland are in snapd 2.28 (this post would include browser-support among other things). I’d be happy to write the dbus forum post. I think there is already one for content, but iirc it isn’t complete, so perhaps the author of that could review it and see if it should be updated.

1 Like
9

I’ll go through this again and see if we can get the number lower, but others, please feel free to join in on the fun! :slight_smile:

10

Here are two other classes:

  • “Using specific devices” - serial-port, iio, i2c, hidraw, and spi
  • network management, observability and connectivity: network-control, network-manager, network-observe, network-setup-control, network-setup-observe and network-status

I can take the network one, perhaps someone from CE could take the devices one? (cc @morphis)

11

Are you just looking for updates to https://docs.google.com/spreadsheets/d/1cFcHOfKxivaisi5PHiwescVy9veViZQYQeRangrwtOA/edit#gid=213514010 or more detailed documentation?

12

I was suggesting it might be nice to have a forum doc that explains how to use this class of interfaces. Part would be the developer side (set your gadget up like this (and why), then the slot shows up here, then your app is setup like that) and part the user side (connections and disconnections). Something that connects all the dots for someone wanting to work with these interfaces.

Eg, today we only have something like this for the content interface (though it is not complete). I plan to write something up for dbus, network stuff and desktop stuff. I was thinking perhaps CE could for devices since you have the most experience with them.

13

Sounds good to me. Do we have a template for that? We should ensure all documented interfaces follow the same structure so a reader always feels at home and knows what he can expect from the documentation of a specific interface.

14

We do not. Perhaps @davidcalle can comment? I was hoping to write my 3 up soon so will do that. I can them massage them into the template style as necessary.

15

I’ve done this and went through everything and commented, except for broadcom-asic-control and storage-framework (perhaps others could comment on those).

What is unclear to me is ‘Show in store details’. I’ve heard different things on this topic and not sure how they relate.

One was that the store would present a list of things that the snap is asking for so the user can make a decision prior to install.

On the other hand I’ve also heard that there would be a GUI for snap connections that is in two tiers: a top tier for things it is reasonable for a normal user to want to connect/disconnect, and a lower tier that a knowledgeable user could drill down into to see everything and perform any connects/disconnects

Is this column about the installation information, the 1st tier or not, a combination of the two or something else?

16

@morphis @jdstrand We don’t need to worry too much about formatting for now. Just having a topic which describes what the interface does and allows, what attributes it takes, and some examples, would already be fantastic. We can easily reformat and make them alike later.

17

@mpt As mentioned above, we are working on exposing summaries via a snap command, and the summaries in the code seem pretty good already, and in many cases better than what the spreadsheet suggests. For example, “use your camera” vs. “allows access to all cameras”. Is there a reason not to simply use the summaries we already have, and talk about and fix only the ones that happen to be inappropriate for some reason?

@zyga-snapd Let’s please not replace the summaries we agreed to without discussion on why. Note that even the phrasing is different and inconsistent with what we’re using.

18

How can I see these summaries all in one place? (I’m assuming some git pull command then some grep command.)

Because I don’t yet know how to access them, I don’t know whether they’re suitable or not. The three most likely reasons they might need tweaking are:

  • if the current grammar won’t work for pre-installation prompts (“{snap title} will be able to: •…”) or GUI run-time prompts (“{snap title} wants to…”)

  • if they use, without defining or characterizing, terms that end users likely won’t understand, like “framebuffer”, “Greengrass”, or “introspect”

  • if they don’t communicate anything that would help users make a decision, for example any summary of the form “access the ______ service”.

19

All of them are inside the interfaces/bulitin directory of the snapd source code (snapcore/snapd in GH).

Note that the question you responded to included fixing them if necessary.