Subject: Include directory structure, and installation packages

From: Alan Griffiths <[email-masked]>
Date: Tue, 19 Mar 2013 13:50:07 +0000

Hi all,

>From discussions on recent MPs I think we lack a clear consensus on how
our headers relate to different use cases and how they are packaged. I
believe these are what we are wanting to support:

Use case 1:  client process, graphics toolkit.
Use case 2:  server process, graphics toolkit.
Use case 3:  server process, shell (or other use of mir as a library).

And the headers are organised with:

Use case 1:  client process, graphics toolkit.
    shared/mir_toolkit/ + client/mir_toolkit/ => <target>/mir_toolkit/

Use case 2:  server process, graphics toolkit.
    shared/mir_toolkit/ + server/mir_toolkit/ => <target>/mir/

Use case 3:  server process, use of mir as a library (shell).
    shared/mir/ + server/mir/  => <target>/mir/
   (and shared/mir_toolkit/common.h => <target>/mir_toolkit/ - which,
admittedly, is a bit odd)

We have some "internal" use cases:

Use case 4: examples - some are use case 1, some use case 3
Use case 5: tests - these have access to some internal headers too
(under src).

To support these, we have also accessory/mir

First question: have I missed an important use case?

Second question: any suggestions for better header layouts to support
these use cases?

Third question: does anyone else have anything further to add?

Thanks for reading,
Alan

---

From: Alexandros Frantzis <[email-masked]>
Date: Tue, 19 Mar 2013 17:35:43 +0200

> Second question: any suggestions for better header layouts to support

Here is an alternative, along with how it could be broken up into
packages:

shared/mir_toolkit/ => <target>/mir_toolkit: libmirtoolkit-common-dev
client/mir_toolkit/ => <target>/mir_toolkit: libmirtoolkit-client-dev
server/mir_toolkit/ => <target>/mir_toolkit: libmirtoolkit-server-dev

shared/mir + server/mir => <target>/mir: libmirserver-dev which will
depend on libmirtoolkit-common-dev (perhaps we can find a more suitable
name for libmirtoolkit-common-dev).

So, we would have something like:

#include <mir_toolkit/client.h>
#include <mir_toolkit/client_lightdm.h>

#include <mir_toolkit/server.h>
#include <mir_toolkit/server_bla.h>

#include <mir/compositor/compositor.h>
#include <mir/frontend/shell.h>

Thanks,
Alexandros

---

From: Robert Ancell <[email-masked]>
Date: Thu, 21 Mar 2013 11:46:36 +1300

Hi,

The current situation feels overly complicated to me and getting more so.

I think we only have two broad use cases:

1. A Mir client. While in theory this could be any type of application
this is in reality only toolkits and other display servers (e.g. Mir on
Mir, X on Mir etc).

The Mir client interface is relatively small and as a consumer of it I
would expect just to be able to include it with something simple like:

#include <mir.h>

or

#include <mir/client.h>

A Mir client links against libmirclient.so.

2. A Mir server. This is in practise Unity Shell and the System Compositor.

The Mir server interface is quite large and while it would be nice to be
able to #include <mir/server.h> due to compiler inefficiencies we might
need to do something like:

#include <mir/display_server.h>
#include <mir/application_model.h>
etc

I don't know the exact requirements for using a toolkit (e.g. Qt) inside
a Mir server, but I don't see any reason not to treat this as the same
case as being a server (i.e. using the same headers and linking to the
same library).

A Mir server links against libmirserver.so.

Other considerations:

1. Common interface information

Inevitably there some information that is common to the server and
client (e.g. enumerations).

2. Library versioning.

We should never install headers directly into /usr/include as then we
can only ever have one version of that interface installed at once.

Headers should be installed into /usr/include/mir-VERSION and pkg-config
should have -I/usr/include/mir-VERSION. Yes, it looks a bit confusing as
the header locations can have "mir" in them twice but from the header
consumers point of view they only see the subdirectories.

So to get back to the proposal below.

I think there are many more use cases if we want to get fine grained:
- client process, graphics toolkit
- client process, display server
- client process, test/diagnostics tool
- server process, shell
- server process, system compositor
- server process, graphics toolkit
...

But there's two main interfaces - Mir server and Mir client. The naming
is fairly generic but if we put "toolkit" or other names in there it
makes the interfaces sound specific when they aren't.

I think at the toplevel we should see:
include/client
include/server
include/common

Which should install:
include/client + include/common => <target>/client
include/server + include/common => <target>/server

All the internal interfaces (include/test, include/accessory etc) should
not be in the include/ directory as they're confusing things. I'd prefer
those headers to be beside the .cpp files or inside the test directory.

--Robert

---

From: Kevin DuBois <[email-masked]>
Date: Wed, 20 Mar 2013 16:39:39 -0700

I agree with Robert A. and Alan about general confusion for how we'll 
reshape mir for unity next (and what we'll call different components and 
use cases.)

The best understood use-case is Alan's "use case 1" and Robert's "1. A 
Mir client." use case. That is, a client connects to a mir server over 
ipc and can render.

Once we get to the server is where the question marks pop up. I'll 
traverse what I've heard/know about this (because thats all I know :) )....

In the mir code right now, we have a simple Z order and we paint our 
textures using OpenGL.

We know we will have to enable new things for the Unity Next. Like 
Robert, I don't know of a hard Qt requirement for Unity Next (eg, using 
QML/qt) to paint our textures.
At the moment, we can plug Qt to paint to the framebuffer in the mir 
server if we want, so lets leave that to them to decide.

The up in the air idea is around 'in process egl'. (i think Alan's "Use 
case 2: server process, graphics toolkit.") and some of the work that 
Robert C is looking at. As I understand it, this idea is to have a hunk 
of code inside of the server process that functions in a logically 
similar way to the IPC clients (that is, they both pop out a texture 
that can be painted to the framebuffer). This would let something like 
the Switcher operate in its own thread with its own renderloop, detached 
from the bigger scene painting to the framebuffer. To rephrase, 'in 
process egl' means to me a qt renderloop that cascades into another qt 
renderloop as a texture. I'm still unconvinced that we need this, and I 
don't have a proof of concept on Android (although I think it will work)

We have a rough agreement that Unity Next will set  implement some of 
our headers (including the scenegraph it needs to get a full desktop) 
and then set up a server configuration (different than 
default_server_configuration.cpp) that is invoked. This makes sense to me.

Cheers,
Kevin

---

From: Daniel van Vugt <[email-masked]>
Date: Thu, 21 Mar 2013 09:53:07 +0800

I think I agree with RobertA's position the most so far. However we're 
going to confuse and complicate the discussion if everyone goes into the 
kind of detail sene below.

I suggest the best way to establish a header layout is to just say what 
you want users of Mir to include. i.e. Express your opinion on the 
requirements. For example I would say something like:

Clients include:
    #include <mir/client/something.h>

Server includes:
    #include <mir/server/somethingelse.h>

Common stuff (if required at all):
    #include <mir/foo.h>
or
    #include <mir/common/foo.h>

And no underscores in header names(!)

All we need is a requirements definition really. We don't need to design 
the final solution in a mailing list.

Please also keep in mind that it's unlikely we will reach a "final 
solution" within the next few commits. The design will be iterated and 
evolve.

P.S. I think Launchpad (bugs) is a better medium for discussions like this.

---

From: Daniel van Vugt <[email-masked]>
Date: Thu, 21 Mar 2013 10:03:24 +0800

Though I am totally open to dropping the "client/" for client headers. 
It makes sense that the common use case (clients) is the simplest. As in:
   #include <mir/client.h>

---

From: Alan Griffiths <[email-masked]>
Date: Thu, 21 Mar 2013 12:01:55 +0000

> name for libmirtoolkit-common-dev).
Actually that says what I intended (and failed to say correctly) more
clearly.

---

From: Alan Griffiths <[email-masked]>
Date: Thu, 21 Mar 2013 12:05:12 +0000

> consumers point of view they only see the subdirectories.
I have no issue with <target> in the OP being "/usr/include/mir-VERSION"

---

From: Alan Griffiths <[email-masked]>
Date: Thu, 21 Mar 2013 12:14:31 +0000

On 21/03/13 01:53, Daniel van Vugt wrote:
> going to confuse and complicate the discussion if everyone goes into
> the kind of detail sene below.
>
> I suggest the best way to establish a header layout is to just say
> what you want users of Mir to include. i.e. Express your opinion on
> the requirements. For example I would say something like:
>
> Clients include:

At the risk of starting a side debate about renaming mir_toolkit I'll
try that:

client-side graphics toolkits include:

#include <mir_toolkit/something.h>

server-side graphics toolkits include:

#include <mir_toolkit/something.h>

server-side shell include:

#include <mir/somethingelse.h>

---

From: Robert Ancell <[email-masked]>
Date: Fri, 22 Mar 2013 10:43:14 +1300

> #include <mir/somethingelse.h>

What does a non toolkit client (e.g. mir on mir) include?
#include <mir_nontoolkitclient/somthing.h>?

Wont both toolkits and shells have overlapping requirements that will
require them to include both?
#include <mir_toolkit/something.h>
#include <mir/somethingelse.h>

I don't think the name of mir_toolkit is a side issue. We have two
external library interfaces. A client interface (libmirclient.so) and a
server interface (libmirserver.so). The names on the includes should
reflect that.

--Robert

---

From: Robert Ancell <[email-masked]>
Date: Fri, 22 Mar 2013 10:45:22 +1300

>    #include <mir/common/foo.h>
This makes sense to me.
> solution" within the next few commits. The design will be iterated and
+1

---

From: Daniel van Vugt <[email-masked]>
Date: Fri, 22 Mar 2013 09:40:06 +0800

I completely agree. Mir is a:
   (1) server library
   (2) client library
so it should have:
   (1) server headers
   (2) client headers
   (3) /maybe/ common headers

The word "toolkit" does not immediately or obviously come in there. 
"toolkit" to the wider English-speaking audience is a vague word that 
could mean many things with regards to software and libraries.

If we're to use the word "toolkit" anywhere, can someone please define 
it for the rest of us?

- Daniel

---

From: Daniel van Vugt <[email-masked]>
Date: Wed, 27 Mar 2013 11:16:56 +0800

OK, a definition of "toolkit" with respect to client headers was given 
on the hangout last night. That is anything intended to support 
/toolkit/ ports (Qt, GTK etc).

It seems the confusion has arisen because "toolkit" in the client 
headers is being used to encompass things that are not 
"toolkit"-specific at all. That's what I would like to see fixed.

Firstly, it is possible and even desirable to write native Mir apps 
without a "toolkit". Not just the examples we have now, but games are 
great examples. The "game" use case is never going away, and hopefully 
will arrive ASAP.

Secondly, "toolkit" is a broad word that could arguably be applied to 
/any/ API or set of APIs. I would rather we used words that are better 
at identifying the subject matter like "client" and "server". But there 
must be others...