Subject: Thoughts on the limits of public headers

From: Alexandros Frantzis <[email-masked]>
Date: Mon, 29 Sep 2014 19:25:58 +0300

Hi all,

we recently hid a lot of our public headers, to avoid frequent ABI
breaks.  As we start to gradually re-expose useful headers I think it
will be good to have broad guidelines about the limits of what we
expose.

One point I feel needs further discussion is the level (if any) at which
we stop re-exposing abstractions that are needed only by the default
implementations of higher abstractions.

For example, we have the mc::Compositor class, the default
implementation of which uses a mc::DisplayBufferCompositor(Factory), the
default implementation of which uses a mc::Renderer(Factory). Each level
we expose adds flexibility to the framework, but also increases our
public API/ABI. Furthermore, the further down we move in the abstraction
layers, the more potential for instability the API/ABI has, since it's
affected more by surrounding implementation decisions (which tend to be
more unstable) instead of higher level architectural decisions (which
tend to be more stable).

The level of exposure should be evaluated on a case by case basis, but
here are some aspects that I think the answer depends on:

1. Whether the exposed abstractions represent core concepts

2. How much we want to encourage reuse of a particular default
   implementation, by exposing the interfaces of its re-implementable
   dependencies

3. Related to (2): How much easier this makes the lives of developers
   trying to use the Mir framework

Thoughts?

Thanks,
Alexandros

---

From: Kevin DuBois <[email-masked]>
Date: Mon, 29 Sep 2014 17:26:11 -0400

This is good to think about, because it'll help us sort out the headers and
make sure that core concepts of mir are available to our users. It'll also
let us refocus; that is, make sure that the interfaces we want the
downstreams to use match up with the needs of the downstreams.

I think the compositor ecosystem is an example of where we're exposing too
much stuff that a user of mir would reasonably feel comfortable writing
(and even want to rewrite). One thing in particular, I don't think we
should provide classes that do GL/EGL plumbing. A user who comes to the mir
project wanting to customize the graphics displayed will be a user who can
compile a shader. (there's more than just the compositor system, but its a
good example)

So I agree with the criteria. The problems that we promise to solve
(eg, input processing, display/multimonitor, buffer management, ipc
processing, platform implementations) should be more hidden. For the
problems the users are trying to solve (eg, where to put the window on the
display, how to organize the scene, the optimal spring constant on the
window wobble, etc) we shouldn't assume too much, and just have clear
interfaces that can be implemented and injected into the mir system.

Cheers,
Kevin

On Mon, Sep 29, 2014 at 12:25 PM, Alexandros Frantzis <
[email-masked]> wrote:

> --
> Mir-devel mailing list
> [email-masked]
> Modify settings or unsubscribe at:
> https://lists.ubuntu.com/mailman/listinfo/mir-devel
>

---

From: Cemil Azizoglu <[email-masked]>
Date: Mon, 29 Sep 2014 17:20:36 -0500

To me, at this point, when to expose is more important than what to expose.
What we have now (Don't expose something unless it's used externally, but
have it ready in a staging/playground area) makes sense for efficiency
which is where the emphasis should be at this point. In time, we migrate
APIs, as they are proven useful, or as needed either internally or
externally, out of staging and publish them. That way ;

- we are not publishing API that isn't useful
- we are involving users and their exact/confirmed needs in the API design
process as opposed to speculating about what their needs are
- we are not shooting ourselves in the foot by maintaining a large exposed
surface area prematurely

Thanks,
Cemil

On Mon, Sep 29, 2014 at 4:26 PM, Kevin DuBois <[email-masked]>
wrote:

> This is good to think about, because it'll help us sort out the headers
> and make sure that core concepts of mir are available to our users. It'll
> also let us refocus; that is, make sure that the interfaces we want the

-- 
Cemil Azizoglu
Mir Display Server - Team Lead
Canonical USA

---

From: Daniel van Vugt <[email-masked]>
Date: Tue, 30 Sep 2014 09:42:31 +0800

Noting that the hiding of headers in Mir 0.8, while causing some 
teething problems, has been very successful in reducing ABI bumps. 
Although we did bump ABIs in 0.8 it wasn't until late in the cycle that 
changes were committed needing any bumps. So that's a great improvement.

I do like the idea of hiding everything till someone requests it. Our 
previous approach of trying to predict which classes people should use 
turned out to be less successful than any of us expected. Admittedly 
there's a delay there in a user requesting a header and getting a 
release with it, but the benefits are certainly worth it.

On Kevin's points... We don't expose the GL plumbing classes right now. 
Their headers are in src/ AFAICS. Although I would like to have time to 
start doing more external shell development myself that would probably 
use them, that's not happening right now. So by the current rules they 
stay private/hidden/internal.

---

From: Alan Griffiths <[email-masked]>
Date: Tue, 30 Sep 2014 10:47:39 +0100

On 30/09/14 02:42, Daniel van Vugt wrote:
> Although we did bump ABIs in 0.8 it wasn't until late in the cycle
> that changes were committed needing any bumps. So that's a great
> improvement.

I don't think anyone is currently arguing that we should re-expose
headers without consideration. But it was done with the expectation that
headers should be re-exposed "when appropriate".

This thread is about what "when appropriate" means as there are clearly
multiple interpretations.

> release with it, but the benefits are certainly worth it.

Our previous approach was not an intentional "predict which classes
people should" but a much less focussed - "if we need it in several
places then users might need it".

I don't like the idea of hiding everything that isn't in use by
Canonical's downstream projects until someone requests it. No-one that
isn't already invested in using Mir is going to expend the time needed
to know what features they want exposed and make a request.

The whole idea of Mir as a separate project (and not part of Unity8) is
that it should attract other downstream projects. That won't happen
unless we remove friction from the adoption process. If we create too
much friction they will find something that is easier to adopt.