Include directory structure, and installation packages

[Daniel van Vugt]

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.


On 21/03/13 06:46, Robert Ancell wrote:
> 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
>>
>
>