RFC: Frameworks headers install location

[Ahmad Samir]

On 12/4/22 02:17, Aleix Pol wrote:
> Back when we did KF5, what we tried to do was mainly to make sure kde4
> code still compiled after the big split.
> 
> I think that stanradrising how they're placed within submodules of
> include/KF6 is a good idea.
> 
> The fact that headers from some repositories can be included using the
> project name is more an artifact of time than a feature. Those that
> are meant to be used that way (e.g. Plasma or Purpose), are already
> namespaced within "include/KF*/<projectname>".
> 
> Ensuring that no KF6 project brings "include/KF6" as its include
> directories will be a useful cleanup.
> Aleix
> 

Thanks for the feedback.

We discussed that again in the previous KF6 meeting[1], and since there are no objections so far, 
we'll go ahead and put that into motion, starting with[2].

[1] https://invent.kde.org/teams/frameworks-devs/kf6-workboard/-/issues/3#note_431116
[2] https://invent.kde.org/frameworks/syntax-highlighting/-/merge_requests/305

Thanks,
Ahmad Samir

> On Tue, Apr 5, 2022 at 4:19 PM Ahmad Samir <a.samirh78 at gmail.com> wrote:
>>
>> Hello.
>>
>> - In KF5, ECM, magically, added /usr/include/KF5/ to the CMake targets interface include directories
>> (IIUC for reasons of backwards compatibility, which was necessary in the 4-5 transition era, I could
>> be wrong because I wasn't around at that time :))
>>
>> - While building KF against Qt6, this suddenly broke building in some modules due to #include
>> directives not finding the headers, as /usr/include/KF6/ didn't have the same magic-injection
>> treatment as KF5
>>
>> - To fix the issue, proper paths had to be added to targets interface include directories so that
>> module A linking against module B will have the proper include paths to search for headers
>>
>> - The typical include dir layout for a KF module is:
>> /usr/include/KF*/ModuleName/{ForwardingHeaderA,headera.h}
>>
>> e.g. KCMutils, #include <KCModuleData>, and /usr/include/KF5/KCMUtils added to KCMutils target
>> include dirs.
>>
>> - If there is a namespace, the original plan was to guard the include paths, by making them match
>> the C++ namespaces, e.g.:
>> /usr/include/KF*/ModuleName/NameSpace/ForwardingHeaderA
>> /usr/include/KF*/ModuleName/namespace/headera.h
>>
>> e.g. KSynatxHighlighting:
>> /usr/include/KF*/KSyntaxHighlighting/
>> /usr/include/KF*/KSyntaxHighlighting/KSyntaxHighlighting/Repository
>> /usr/include/KF*/KSyntaxHighlighting/ksyntaxhighlighting/repository.h
>>
>>
>> There are some issues with the namespace use-case:
>> - On case-insensitive and/or case-preserving filesystems (which still exist in 2022...) extra care
>> has to be taken so that installation actually works, as you can't have two dirs in the same path
>> with the same name but different cases
>> - Compiler warnings when using e.g. #include <KSyntaxHighlighting/Repository> if the dir that was
>> installed first was ksyntaxhighlighting, and all files ended up there (and vice-versa, e.g. if the
>> CamelCase dir got installed first #include <ksyntaxhighlighting/repository.h> would give a warning)
>> - A more complicated layout
>>
>> The proposal is to change the layout when there is a namespace:
>> - Only have one dir, /usr/include/KF*/ModuleName/NameSpace/, where all headers (ForwadingHeaders and
>> lowercase.h ones) are installed
>>
>>
>> Pros:
>> - less complicated layout/setup (simpler CMake code)
>> - all KDE namespaces are CamelCase, we don't have any that are lower case
>> - we promote/encourage using FowardingHeaders everywhere; that's what we use in our own code and
>> what the API docs advise to use
>>
>> Cons:
>> - The case not matching when using <KSyntaxHighlighting/repository.h>, but as I said above the
>> argument for this is mitigated by the fact that all our namespaces are CamelCase
>>
>> If we agree with that change this will be for KF6 so as not to break source compatibility for KF5.
>>
>> Best regards,
>> Ahmad Samir