Merge lp://qastaging/~alan-griffiths/mir/discussion-migrate-demo-shell into lp://qastaging/mir

Our downstreams have been able to get along without our utility classes (
gl_program, gl_texture, gl_primitive, gl_renderer, etc) to this point, and re-exposing them exposes a lot of ABI that has been hidden and is not used. These classes are more utility classes of the way we've used GLES internally than a recommendation/suggestion to others as to how they should use GLES.

I think its possible to transition the demo shell from playground to examples with a bit of more in-depth "surgery" to have it target reimplementing our already-exposed /interfaces/ instead of overriding different components of utility classes.

FAILED: Continuous integration, rev:2140
http://jenkins.qa.ubuntu.com/job/mir-ci/2337/
Executed test runs:
    FAILURE: http://jenkins.qa.ubuntu.com/job/mir-android-vivid-i386-build/444/console
    SUCCESS: http://jenkins.qa.ubuntu.com/job/mir-clang-vivid-amd64-build/444
    FAILURE: http://jenkins.qa.ubuntu.com/job/mir-mediumtests-vivid-touch/418/console
    FAILURE: http://jenkins.qa.ubuntu.com/job/mir-vivid-amd64-ci/334/console
    FAILURE: http://jenkins.qa.ubuntu.com/job/mir-mediumtests-builder-vivid-armhf/418/console

Click here to trigger a rebuild:
http://s-jenkins.ubuntu-ci:8080/job/mir-ci/2337/rebuild

I'm pretty sure playground/ can access a superset of what examples/ can. That's why it exists.

So there's no reason to republish all those headers just yet, is there?

Quoting the README:

    The Playground

    These are mir demos that excercise private in-flux mir functionality.
    As such functionality matures, related headers become public and the playground
    code may become an example of how to use such feature.

The reason for this MP is to drive a discussion of what is preventing users of our supported API doing what we do in the mir_demo_server_shell example.

As I see it the only real problem highlighted by this MP is that the DemoRenderer class that has been implemented using some of our private gl tools. That is I don't see that access to the_compositor_report() or the_input_scene() is a big deal.

So the question is: how do we serve our current and potential users better?

1. Provide an example of shell decorations etc that doesn't use Mir internals
2. Design a way for users to implement shell decorations that we're happy to publish
3. Ignore the issue

Using our private gl tools isn't the only implementation option and (as Kevin says) our existing downstreams haven't found a need for this approach. It would be good to have an example that is more like what we expect users to do.

Definitely this migration is something that will have to happen in future. I was leaning toward keeping things as private as possible for as long as possible. That means I expected to keep much of this private (so we can freely change interfaces) until such time as some new shell developer asks us to expose parts. Putting things in the public API prematurely and then having to change them is a painful issue we keep encountering. So I'd prefer to keep as much as possible private for as long as possible to minimize the problem. We all share the goal of wanting releases in future that don't bump the server ABI, so letting it stabilize privately still feels like a good idea to me...

On a more practical note:
(1) Needs Fixing: mir_demo_server_shell now crashes immediately on startup.

OK, I didn't really think this would land in this form - I was more interested in highlighting the gaps between what we our supported API allows and what we believe reasonable Mir users would want to do.