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

[Volker Krause]

On Saturday, 21 December 2019 20:12:48 CET Friedrich W. H. Kossebau wrote:
> 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?

Backward compatibility with new frameworks coming in with an existing internal 
and external user base is a good question though, this also came up with 
QKeychain recently.

That is, do we break ABI/API as part of the inclusion into Frameworks, to make 
them fully comply with all Framework policies, or do we allow for exemptions 
for the current major release in this case? Ultimately it's a tradeoff between 
ease of migration for existing code bases (which aren't just our own, but also 
those of the users the new framework brings in), and consistency in 
Frameworks.

I'm undecided on this myself still:

* Consistency is an important part of the Frameworks product story (even if we 
aren't perfectly following this everywhere).

* Attracting external components and having them opt to move under the 
Frameworks umbrella is a sign that we are doing things right IMHO. So let's 
make this easy for people and avoid scaring off their users by forcing a 
larger migration on them when joining Frameworks.

* We are less than two years away from KF6, a time where people expect to have 
to do a larger migration anyway. Deferring some of the necessary changes to 
then might be a compromise that works for now.

Thoughts?

Thanks,
Volker

PS: @Steve: I missed the doxygen discussion on IRC earlier, customizing 
doxygen is possible via docs/Doxyfile.local, which just gets appended to the 
Doxyfile from kapidox IIUC, maybe that helps already?
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 195 bytes
Desc: This is a digitally signed message part.
URL: <http://mail.kde.org/pipermail/kde-core-devel/attachments/20191221/8b387d66/attachment.sig>