Include directory structure, and installation packages

[Robert Ancell]

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

On 20/03/13 02:50, Alan Griffiths wrote:
> 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
>