Include directory structure, and installation packages

[Daniel van Vugt]

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>


On 21/03/13 09:53, Daniel van Vugt wrote:
> 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
>>>
>>
>>
>