Join GitHub today
GitHub is home to over 20 million developers working together to host and review code, manage projects, and build software together.
docs/interfaces.md: improve interfaces documentation #1409
Conversation
jdstrand
added some commits
Jun 24, 2016
|
Since this is documentation and not code, I suggest reading interfaces.md via 'View' under /files. |
jdstrand
added some commits
Jun 24, 2016
niemeyer
reviewed
Jun 24, 2016
| -### network | ||
| +## Native vs classic interfaces |
niemeyer
Jun 24, 2016
Contributor
Needs some rewording. There's no "classic interface" and "native interface" in snapd. There's the classic Ubuntu system, and there's Ubuntu Core. The interface set on both of those is the same.
jdstrand
Jun 24, 2016
•
Edited 1 time
-
jdstrand
Jun 24, 2016
Contributor
-
Jun 24, 2016
I reworded this section and it is now called 'Transitional interfaces'.
niemeyer
reviewed
Jun 24, 2016
| @@ -12,184 +12,350 @@ Slots may support multiple connections to plugs. For example the OS snap | ||
| exposes the ``network`` slot and all applications that can talk over the | ||
| network connect their plugs there. | ||
| -## Supported Interfaces - Basic | ||
| +The availability of an interface depends on whether snapd is running on a | ||
| +classic (eg, traditional desktop or server) or on a native system. Interfaces |
niemeyer
Jun 24, 2016
Contributor
This is not generally true, and saying so undermines an important aspect of the system that we very much care about. Snaps are the same on classic and on Ubuntu Core, and interfaces are the same as well. Some very specific interfaces may be available or not, and this is not even just about classic or not. It's about the nature of the ecosystem. Not all devices will offer all interfaces.
jdstrand
Jun 24, 2016
•
Edited 1 time
-
jdstrand
Jun 24, 2016
Contributor
-
Jun 24, 2016
The interface set isn't the same though per implicit.go and confirmed by examining snap interfaces on a daily core image and on a desktop system. There are a lot of interfaces that aren't exposed in core: cups-control, gsettings, opengl, pulseaudio, unity7 and x11 and soon content. I wanted to call this out, but I wasn't sure how to do it without going with 'classic vs native'.
Do you have suggestions on how this should be described if not native vs classic? How do I describe those interfaces that only show up on devices that are traditional Linux systems (ie, what I referred to as 'classic').
UPDATE: also camera and optical-drive, but I'm not sure why those are classic only. A bug? Waiting on gadget snap?
jdstrand
Jun 28, 2016
Contributor
@niemeyer - can you review my comments? I'm not sure how to move forward. Thanks!
niemeyer
Aug 4, 2016
Contributor
Again, it's not classic vs. native. It's just that interfaces may be available or not for any given system.
I don't know why camera and optical-drive are classic only either. They shouldn't be.
niemeyer
reviewed
Jun 24, 2016
| -## Supported Interfaces - Basic | ||
| +The availability of an interface depends on whether snapd is running on a | ||
| +classic (eg, traditional desktop or server) or on a native system. Interfaces | ||
| +may also be implicit to the OS snap or implemented only via snaps providing the |
niemeyer
Jun 24, 2016
Contributor
The term "implicit" is an irrelevant implementation detail that we shouldn't surface on the UI or the documentation. These are real plugs and slots on the core snap. We're creating them dynamically simply because it was easier for us to put the system in place this way, but we don't want to surface this fact to the user, and in fact it most probably will go away altogether in favor of having these interfaces defined and controlled in the core snap itself.
|
First pass done, Jamie. A lot of the polishing is very welcome, but a few details need tweaking. |
niemeyer
added
the
Reviewed
label
Jun 24, 2016
jdstrand
added some commits
Jun 24, 2016
pedronis
removed
the
Reviewed
label
Jul 28, 2016
|
@niemeyer - ping regarding open questions from me in response to your initial review. |
niemeyer
reviewed
Aug 4, 2016
| -### network | ||
| +## Transitional interfaces |
niemeyer
reviewed
Aug 4, 2016
| -Usage: reserved | ||
| -Auto-Connect: yes | ||
| +* Auto-Connect: yes | ||
| +* Availability: OS snap (classic) |
niemeyer
Aug 4, 2016
Contributor
These should all be "core snap" now, but I'm not quite sure we should be documenting that as such. Devices may easily end up not offering certain slots, and other slots may easily move around to different snaps. The point of our interface design is precisely that we're not making any promises about what is available where, yet the system will behave correctly independently of that.
jdstrand
Aug 4, 2016
Contributor
Availability is gone, but any references to 'OS snap' are now 'core snap'.
niemeyer
reviewed
Aug 4, 2016
| +Can access OpenGL hardware. | ||
| + | ||
| +* Auto-Connect: yes | ||
| +* Availability: OS snap (classic) |
niemeyer
Aug 4, 2016
Contributor
Why classic? What if the device has a screen? What if I install a native snap system on my laptop and install a unity8 snap?
jdstrand
Aug 4, 2016
Contributor
I was just documenting the code. I don't know why opengl is classic only.
niemeyer
reviewed
Aug 4, 2016
| + | ||
| +### bool-file | ||
| + | ||
| +Can access GPIO paths for LED brightness and GPIO values. |
niemeyer
Aug 4, 2016
Contributor
We'll see an actual gpio interface soon (it's being worked on right now..). Can we please drop docs for bool-file for the time being? Not sure we'll want to keep it.
niemeyer
reviewed
Aug 4, 2016
| +* Auto-Connect: yes for snaps from same publisher, no otherwise | ||
| +* Availability: with providing snap | ||
| +* Attributes: | ||
| + * read (slot): read-only path from providing snap to expose to the consuming snap |
|
@niemeyer - I believe I addressed all of your concerns. I removed Availability and reworded to be more generic and reference |
|
This is what is failing in the integration test: FAIL: /home/jenkins-slave/workspace/github-snappy-integration-tests-cloud/src/github.com/snapcore/snapd/integration-tests/tests/create_user_test.go:36: createUserSuite.TestCreateUserCreatesUser That has nothing to do with this PR. |
|
retest this please |
jdstrand commentedJun 24, 2016
•
Edited 1 time
-
jdstrand
Jul 21, 2016