ECM 5.85: introducing KDE_COMPILERSETTINGS_LEVEL concept

[Friedrich W. H. Kossebau]

Hi,

((kde-core-devel as CC:, please reply only to kde-devel)

TL;DR
Starting with ECM 5.85 KDECompilerSettings will provide some stricter 
settings, which you can control on the toplevel by KDE_COMPILERSETTINGS_LEVEL 
and then again per settings category, for a stable set of settings matching 
your project requirements across ECM versions, not affected by the minimal 
required ECM version.
Make sure to include KDECompilerSettings right after find_package(ECM), before 
any other find_package() calls (best done in any case due to a current flaw).
While your minimum required ECM version is < 5.85, no other change is needed.
Port any usage of KDEFrameworkCompilerSettings outside of KDE Frameworks 
modules to that once you can afford to require ECM >= 5.85.
For more, see docs on
    https://api.kde.org/ecm/kde-module/KDECompilerSettings.html


This is a heads-up for a new mechanism introduced with ECM 5.85 to control the 
set of compiler settings for your project when using ECM's KDECompilerSettings 
(and your way out of repurposing KDEFrameworkCompilerSettings to easily gain a 
more strict set of settings).

It enables KDECompilerSettings to offer new variants of settings (which 
usually mean more strictness and enforcing usage of more modern standards), 
while allowing consumers to pin-point a certain settings variant as well as 
overwriting individual settings, without being coupled to the minimum required 
ECM version.


Basic usage:

Set KDE_COMPILERSETTINGS_LEVEL to the version whose set of settings you desire 
right before including KDECompilerSettings, 

    find_package(ECM 5.85.0 NO_MODULE)
    set(CMAKE_MODULE_PATH /* other paths as needed */ ${ECM_MODULE_PATH})
    set(KDE_COMPILERSETTINGS_LEVEL 5.85.0)  # <- new, to set before including
    include(KDECompilerSettings NO_POLICY_SCOPE)

WARNING:
Also make sure to call include(KDECompilerSettings) right after 
find_package(ECM), before any other find_package() calls. There is currently a 
design flaw in ECM code which relies on the minimum required version as passed 
to the find_package(ECM) call, and any further calls of find_package(ECM) like 
e.g. can happen in the chain behind find_package(KF5) can overwrite this with 
the version used in those calls (someone needed to fix this, you, dear 
reader?).
As work-around for now everyone has to include the ECM modules right before 
invoking anything else.


KDE_COMPILERSETTINGS_LEVEL cannot be higher than min required ECM:

As at the time of writing older ECM versions it cannot be foreseen what future 
ECM versions might have as new settings for their respective 
KDE_COMPILERSETTINGS_LEVEL version, the max version that can be used for 
KDE_COMPILERSETTINGS_LEVEL is the one of the minimum required ECM version. 
That ensures that for a given KDE_COMPILERSETTINGS_LEVEL version it is a known 
set of settings you can expect to be set.


Setting KDE_COMPILERSETTINGS_LEVEL to not get new settings right now:

KDE_COMPILERSETTINGS_LEVEL <= 5.84.0 will give you the settings as used to 
before so far.
KDE_COMPILERSETTINGS_LEVEL == 5.85.0 will bring lots of new strict settings, 
matching those of previous KDEFrameworkCompilerSettings and then some.
Future KDE_COMPILERSETTINGS_LEVEL can then contain any more settings which 
seem sensible as default, whatever ECM community decides here.


KDE_COMPILERSETTINGS_LEVEL defaulting to minimum required ECM version:

For convenience for those who are fine to also update their code to match 
latest settings when bumping the minimum required ECM version to gain access 
to newer ECM features, KDE_COMPILERSETTINGS_LEVEL defaults to the minimum 
required ECM version. So those can spare that extra line. But be prepared for 
potential code update work when bumping the required version any time :)
So recommended is to explicitly set KDE_COMPILERSETTINGS_LEVEL once requiring 
at least ECM >= 5.85.0, to save one from potential build breakages due to more 
strict settings when just wanting some other new ECM feature and bumping the 
required version without further thought.


Overwriting the settings set from KDE_COMPILERSETTINGS_LEVEL:

As there is no one-set-of-settings-fits-all, each settings category also has 
additional controls to overwrite the default defined by the level. Those 
controls are usually further variables which have to be set before including 
KDECompilerSettings, here a few examples:
* KDE_SKIP_PEDANTIC_WARNINGS_SETTINGS
* KDE_SKIP_MISSING_INCLUDE_DIRS_WARNINGS_SETTINGS
* KDE_QT_MODERNCODE_DEFINITIONS_LEVEL

For a detailed listing and further info please consult the documentation at
    https://api.kde.org/ecm/kde-module/KDECompilerSettings.html


If you have further questions, please do not hesitate to ask here on the kde-
devel ML (please reply only there, not kde-core-devel).

Cheers
Friedrich

PS: Please someone volunteer to fix the ECM_GLOBAL_FIND_VERSION design flaw. 
Might be easy to fix, not yet thought more about myself, simply done too much 
ECM/CMake work lately, so needing a break, thus do not look at me here in the 
near future, if you would have :)