CMake config & target challenges on moving to KF5 namespace; dir structure & API dox (Re: Submitting Grantlee as a KF5 Framework)

[Friedrich W. H. Kossebau]

Am Samstag, 21. Dezember 2019, 13:03:17 CET schrieb Stephen Kelly:
> Great, Grantlee is now available at git at git.kde.org:grantlee.git.
> 
> I've pushed a few commits to make it depend on ECM etc.
> 
> Once the review period is finished it can be part of KF5 releases.

There are quite some things which yet need to be done for now:
to be a true KF module there is a set of policies which needs to be met, see 
https://community.kde.org/Frameworks/Policies

1) Framework directory structure:
   moving stuff into src/, autotests/ & docs/
2) Framework documentation:
   current system needs adaption to both online (KApiDox) and
   offline (ECMAddQCH) systems

I could do 1) if you like, and help with 2) on the ECMAddQCH part.

Another challenge would be moving into the KF5 namespace for the library 
artifacts (at least I would expect/recommend this to happen, for consistent 
user experience)
a) include dirs below subdir KF5/
b) CMake modules with KF5 prefix
c) CMake imported target in KF5 namespace

Now, the question is if we want Grantlee to be backwards-compatible after the 
move into KDE Frameworks, or if some breakage is possible?

When it comes to CMake targets & modules, the first challenge is:

Grantlee5 supports components, "Templates" & "TextDocument". To allow people 
doing e.g.
--- 8< ---
find_package(Grantlee5 CONFIG COMPONENTS Templates)
--- 8< ---
So when Grantlee becomes a component in KF5 itself, so people would use for 
finding it
--- 8< ---
find_package(KF5 CONFIG COMPONENTS Grantlee)
--- 8< ---
these two, "Templates" & "TextDocument", would need to become subcomponents. 
Which though is a concept CMake does not support.

So what to do here? Split Grantlee into two separate libs, with separate CMake 
config files? Done by KF5NewStuff, where one repo provides 2 separate configs.
Or just merge and do not allow making dep chain more narrow (Grantlee's 
TextDocument pulls in QtGui as dep, so fails if no devel package not present)?


Then Grantlee's CMake module brings two namespaced imported targets:
* Grantlee5::Templates
* Grantlee5::TextDocument
With Grantlee being part of KDE Frameworks, one would expect to have targets 
named like
* KF5::GrantleeTemplates
* KF5::GrantleeTextDocument
or similar.

Just, seems CMake does not expect the use case of exporting targets with 
different names, there is only one property available to set the base name, 
cmp. current
--- 8< ---
set_property(TARGET Grantlee_Templates PROPERTY EXPORT_NAME Templates)
--- 8< ---
So when wanting to keep backward compatibility, we are stuck here with the old 
basenames.
Do you know any simple trick to have a separate CMake config file with 
separate imported targets, which still refer to the same library executable?
Never done myself, so no idea what could be done. Doing a separate target and 
exporting that one will fail possibly once trying to set OUTPUT_NAME property 
to the same,
Perhaps one could do a manual cmake config file which has the old one as 
find_dependency and then defines an alias target on the imported target?

Cheers
Friedrich