[FEATURE] Option to build & install QCH file with the public API dox

Using the new extra-cmake-modules module ECMAddQch (since 5.36.0)
this adds the option to automatically build and install a file
in QCH format with the docs about the public API, which then can be
used e.g. in Qt Assistant, Qt Creator or KDevelop.

Additionally the installed cmake config files will be extended
with a target KF5Plasma_QCH containing information about how to "link"
into the generated QCH file, which then can be used in the cmake build
system of other libraries building on this library, by
simply listing this target in "LINK_QCHS" of their ecm_add_qch() usage.
And a respective doxygen tag file with all the metadata about the
generated QCH file and used for the "linking" will be created and
installed.

Pass -DBUILD_QCH=ON to cmake to enable this.

CMakeLists.txt

@@ -21,9 +21,13 @@ include(CMakePackageConfigHelpers)
 include(ECMSetupVersion)
 include(KDEFrameworkCompilerSettings NO_POLICY_SCOPE)
 include(ECMQtDeclareLoggingCategory)
+include(ECMAddQch)
 include(KDEPackageAppTemplates)
 include(ECMGenerateQmlTypes)
 
+option(BUILD_QCH "Build API documentation in QCH format (for e.g. Qt Assistant, Qt Creator & KDevelop)" OFF)
+add_feature_info(QCH ${BUILD_QCH} "API documentation in QCH format (for e.g. Qt Assistant, Qt Creator & KDevelop)")
+
 ecm_setup_version(PROJECT
                   VARIABLE_PREFIX PLASMA
                   VERSION_HEADER "${CMAKE_CURRENT_BINARY_DIR}/plasma_version.h"
@@ -146,12 +150,44 @@ if(BUILD_COVERAGE)
     set(CMAKE_EXE_LINKER_FLAGS "${CMAKE_EXE_LINKER_FLAGS} -lgcov")
 endif()
 
+# make plasma_version.h available
+include_directories(${CMAKE_CURRENT_BINARY_DIR})
+
+################# list the subdirectories #################
+if (KF5DocTools_FOUND)
+    add_subdirectory(docs)
+endif()
+add_definitions(-DTRANSLATION_DOMAIN=\"libplasma5\")
+if (IS_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}/po")
+    ki18n_install(po)
+    kdoctools_install(po)
+endif()
+add_subdirectory(src)
+
+if (BUILD_EXAMPLES)
+    add_subdirectory(examples)
+endif()
+
+add_subdirectory(autotests)
+add_subdirectory(tests)
+add_subdirectory(templates)
+
 ################ create PlasmaConfig.cmake and install it ###########################
 
 # create a Config.cmake and a ConfigVersion.cmake file and install them
 
 set(CMAKECONFIG_INSTALL_DIR "${KDE_INSTALL_CMAKEPACKAGEDIR}/KF5Plasma")
 
+if (BUILD_QCH)
+    ecm_install_qch_export(
+        TARGETS KF5Plasma_QCH
+        FILE KF5PlasmaQchTargets.cmake
+        DESTINATION "${CMAKECONFIG_INSTALL_DIR}"
+        COMPONENT Devel
+    )
+    set(PACKAGE_INCLUDE_QCHTARGETS "include(\"\${CMAKE_CURRENT_LIST_DIR}/KF5PlasmaQchTargets.cmake\")")
+endif()
+
 configure_package_config_file(
   "${CMAKE_CURRENT_SOURCE_DIR}/KF5PlasmaConfig.cmake.in"
   "${CMAKE_CURRENT_BINARY_DIR}/KF5PlasmaConfig.cmake"
@@ -176,26 +212,4 @@ install(EXPORT KF5PlasmaTargets
 install(FILES ${CMAKE_CURRENT_BINARY_DIR}/plasma_version.h
         DESTINATION ${KDE_INSTALL_INCLUDEDIR_KF5} COMPONENT Devel )
 
-# make plasma_version.h available
-include_directories(${CMAKE_CURRENT_BINARY_DIR})
-
-################# list the subdirectories #################
-if (KF5DocTools_FOUND)
-    add_subdirectory(docs)
-endif()
-add_definitions(-DTRANSLATION_DOMAIN=\"libplasma5\")
-if (IS_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}/po")
-    ki18n_install(po)
-    kdoctools_install(po)
-endif()
-add_subdirectory(src)
-
-if (BUILD_EXAMPLES)
-    add_subdirectory(examples)
-endif()
-
-add_subdirectory(autotests)
-add_subdirectory(tests)
-add_subdirectory(templates)
-
 feature_summary(WHAT ALL FATAL_ON_MISSING_REQUIRED_PACKAGES)

KF5PlasmaConfig.cmake.in

@@ -3,6 +3,7 @@
 # Any changes in this ".cmake" file will be overwritten by CMake, the source is the ".cmake.in" file.
 
 include("${CMAKE_CURRENT_LIST_DIR}/KF5PlasmaTargets.cmake")
+@PACKAGE_INCLUDE_QCHTARGETS@
 
 set(Plasma_INSTALL_PREFIX "@PACKAGE_CMAKE_INSTALL_PREFIX@")
 

src/plasma/CMakeLists.txt

@@ -170,21 +170,28 @@ ecm_generate_headers(Plasma_CamelCase_HEADERS
     PREFIX Plasma
 )
 
+set(Plasma_HEADERS
+    ${Plasma_HEADERS}
+    version.h
+)
+
+set(PlasmaScripting_HEADERS
+    scripting/appletscript.h
+    scripting/dataenginescript.h
+    scripting/scriptengine.h
+)
+
 
 install(FILES
         ${Plasma_HEADERS}
         ${CMAKE_CURRENT_BINARY_DIR}/plasma/plasma_export.h
-        version.h
         DESTINATION ${KDE_INSTALL_INCLUDEDIR_KF5}/plasma COMPONENT Devel)
 
 install(FILES ${Plasma_CamelCase_HEADERS}
         DESTINATION ${KDE_INSTALL_INCLUDEDIR_KF5}/Plasma COMPONENT Devel)
 
 
-install(FILES
-    scripting/appletscript.h
-    scripting/dataenginescript.h
-    scripting/scriptengine.h
+install(FILES ${PlasmaScripting_HEADERS}
     DESTINATION ${KDE_INSTALL_INCLUDEDIR_KF5}/plasma/scripting COMPONENT Devel)
 
 install(FILES
@@ -206,3 +213,28 @@ install(FILES data/operations/storage.operations DESTINATION ${PLASMA_DATA_INSTA
 
 install(TARGETS KF5Plasma EXPORT KF5PlasmaTargets ${KF5_INSTALL_TARGETS_DEFAULT_ARGS})
 
+if(BUILD_QCH)
+    ecm_add_qch(
+        KF5Plasma_QCH
+        NAME Plasma
+        BASE_NAME KF5Plasma
+        VERSION ${KF5_VERSION}
+        ORG_DOMAIN org.kde
+        SOURCES # using only public headers, to cover only public API
+            ${Plasma_HEADERS}
+            ${PlasmaScripting_HEADERS}
+            Mainpage.dox
+        MD_MAINPAGE "${CMAKE_SOURCE_DIR}/README.md"
+        LINK_QCHS
+            Qt5Gui_QCH
+            KF5Service_QCH
+            KF5Package_QCH
+        BLANK_MACROS
+            PLASMA_EXPORT
+            PLASMA_DEPRECATED
+            PLASMA_DEPRECATED_EXPORT
+        TAGFILE_INSTALL_DESTINATION ${KDE_INSTALL_QTQCHDIR}
+        QCH_INSTALL_DESTINATION ${KDE_INSTALL_QTQCHDIR}
+        COMPONENT Devel
+    )
+endif()