RFC: Frameworks headers install location

[Aleix Pol]

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

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