[gentoo-dev] RFC: ecm-common.eclass: New eclass for easy outsourcing of common files for KDE packages

[Andreas Sturmlechner <asturm@gentoo.org>]

[-- Attachment #1: Type: text/plain, Size: 6555 bytes --]

ECM = extra-cmake-modules, used basically everywhere in kde.org

What does it do?
- Work with KF5 or KF6 in the background, so BDEPENDs are defined as :*
- Create a very simple root CMakeLists.txt in place of upstream's
- KDE projects are *very* standardised, so a few lines of CMake will
  already provide us with translations, docs, translated docs for 95%
  of packages.
- On top of that, ebuild consumers can define icons and files to install
- ... or inject their own Heredoc when ecm-common.eclass is not enough

What's the goal?
- Easily create ${PN}-common packages for other split ${PN} to depend upon
- Be able to depend on ${PN}-common:0 packages from e.g. both SLOT 5 and 6
- ... cause less friction with not having to set compatibility USE flags
  and dropping many blockers

When thought through to the end, it would enable us move *all* docs
(currently USE=handbook in KDE packages) and translations into separate
packages.


Ongoing development and model revdep usage in:
https://github.com/gentoo/kde/pull/999


--- /dev/null
+++ b/eclass/ecm-common.eclass
@@ -0,0 +1,188 @@
+# Copyright 2024 Gentoo Authors
+# Distributed under the terms of the GNU General Public License v2
+
+# @ECLASS: ecm-common.eclass
+# @MAINTAINER:
+# kde@gentoo.org
+# @SUPPORTED_EAPIS: 8
+# @PROVIDES: cmake
+# @BLURB: Standalone CMake calling std. ECM macros to install common files 
only.
+# @DESCRIPTION:
+# This eclass is used for installing common files of packages using ECM 
macros,
+# most of the time translations, but optionally also icons and kcfg files. 
This
+# is mainly useful for packages split from a single upstream tarball, or for
+# collision handling of slotted package versions, which need to share a 
common
+# files package.
+# Conventionally we will use ${PN}-common for these split packages.
+
+case ${EAPI} in
+       8) ;;
+       *) die "${ECLASS}: EAPI ${EAPI:-0} not supported" ;;
+esac
+
+if [[ -z ${_ECM_COMMON_ECLASS} ]]; then
+_ECM_COMMON_ECLASS=1
+
+inherit cmake
+
+# @ECLASS_VARIABLE: ECM_I18N
+# @PRE_INHERIT
+# @DESCRIPTION:
+# Will accept "true" (default) or "false".  If set to "false", do nothing.
+# Otherwise, add kde-frameworks/ki18n:* to BDEPEND, find KF[56]I18n and let
+# ki18n_install(po) generate and install translations.
+: "${ECM_I18N:=true}"
+
+# @ECLASS_VARIABLE: ECM_HANDBOOK
+# @PRE_INHERIT
+# @DESCRIPTION:
+# Will accept "true" or "false" (default).  If set to "false", do nothing.
+# Otherwise, add "+handbook" to IUSE, add kde-frameworks/kdoctools:* to 
BDEPEND
+# find KF[56]DocTools in CMake, call add_subdirectory(ECM_HANDBOOK_DIR)
+# and let let kdoctools_install(po) generate and install translated docbook
+# files.
+: "${ECM_HANDBOOK:=false}"
+
+# @ECLASS_VARIABLE: ECM_HANDBOOK_DIR
+# @PRE_INHERIT
+# @DESCRIPTION:
+# Default is "doc" which is correct for the vast majority of packages. 
Specifies
+# the directory containing untranslated docbook file(s) relative to ${S} to
+# be added via add_subdirectory.
+: "${ECM_HANDBOOK_DIR:=doc}"
+
+DESCRIPTION="Common files for ${PN/-common/}"
+
+case ${ECM_I18N} in
+       true)
+               BDEPEND+=" kde-frameworks/ki18n:*"
+               ;;
+       false) ;;
+       *)
+               eerror "Unknown value for \${ECM_I18N}"
+               die "Value ${ECM_I18N} is not supported"
+               ;;
+esac
+
+case ${ECM_HANDBOOK} in
+       true)
+               IUSE+=" +handbook"
+               BDEPEND+=" handbook? ( kde-frameworks/kdoctools:* )"
+               ;;
+       false) ;;
+       *)
+               eerror "Unknown value for \${ECM_HANDBOOK}"
+               die "Value ${ECM_HANDBOOK} is not supported"
+               ;;
+esac
+
+# @ECLASS_VARIABLE: ECM_INSTALL_ICONS
+# @DEFAULT_UNSET
+# @DESCRIPTION:
+# Array of <icon>:<icon_install_dir> tuples feed to ECMInstallIcons via
+# ecm_install_icons(ICONS <icon> DESTINATION <icon_install_dir)
+if [[ ${ECM_INSTALL_ICONS} ]]; then
+       [[ ${ECM_INSTALL_ICONS@a} == *a* ]] ||
+               die "ECM_INSTALL_ICONS must be an array"
+fi
+
+# @ECLASS_VARIABLE: ECM_INSTALL_FILES
+# @DEFAULT_UNSET
+# @DESCRIPTION:
+# Array of <file>:<destination_path> tuples to install by CMake via
+# install(FILES <file> DESTINATION <destination_path>)
+if [[ ${ECM_INSTALL_FILES} ]]; then
+       [[ ${ECM_INSTALL_FILES@a} == *a* ]] ||
+               die "ECM_INSTALL_FILES must be an array"
+fi
+
+# @FUNCTION: ecm-common_inject_heredoc
+# @DESCRIPTION:
+# Override this to inject custom Heredoc into the root CMakeLists.txt
+ecm-common_inject_heredoc() {
+       debug-print-function ${FUNCNAME} "$@"
+       # put your stuff here
+}
+
+# @FUNCTION: ecm-common_src_prepare
+# @DESCRIPTION:
+# Wrapper for cmake_src_prepare with a Heredoc replacing the standard
+# root CMakeLists.txt file to only generate and install translations.
+ecm-common_src_prepare() {
+       debug-print-function ${FUNCNAME} "$@"
+
+       local i
+
+cat <<-EOF > CMakeLists.txt
+cmake_minimum_required(VERSION 3.16)
+project(${PN} VERSION ${PV})
+
+find_package(ECM "5.115.0" REQUIRED NO_MODULE)
+set(CMAKE_MODULE_PATH \${CMAKE_CURRENT_SOURCE_DIR}/cmake/modules \$
{ECM_MODULE_PATH})
+
+set(KDE_INSTALL_DOCBUNDLEDIR "${EPREFIX}/usr/share/help" CACHE PATH "")
+
+include(KDEInstallDirs)
+include(ECMOptionalAddSubdirectory) # commonly used
+include(FeatureSummary)
+
+EOF
+
+       if [[ ${ECM_I18N} == true ]]; then
+cat <<-EOF >> CMakeLists.txt
+find_package(KF6I18n)
+if(NOT KF6I18n_FOUND)
+    find_package(KF5I18n REQUIRED)
+endif()
+ki18n_install(po)
+
+EOF
+       fi
+
+       if in_iuse handbook && use handbook; then
+cat <<-EOF >> CMakeLists.txt
+find_package(KF6DocTools)
+if(NOT KF6DocTools_FOUND)
+    find_package(KF5DocTools REQUIRED)
+endif()
+kdoctools_install(po)
+EOF
+               if [[ -d ${ECM_HANDBOOK_DIR} ]]; then
+cat <<-EOF >> CMakeLists.txt
+add_subdirectory(${ECM_HANDBOOK_DIR})
+
+EOF
+               fi
+       fi
+
+       if [[ ${ECM_INSTALL_ICONS} ]]; then
+cat <<-EOF >> CMakeLists.txt
+include(ECMInstallIcons)
+EOF
+               for i in "${ECM_INSTALL_ICONS[@]}"; do
+cat <<-EOF >> CMakeLists.txt
+ecm_install_icons(ICONS ${i%:*} DESTINATION ${i#*:})
+EOF
+               done
+       fi
+
+       for i in "${ECM_INSTALL_FILES[@]}"; do
+cat <<-EOF >> CMakeLists.txt
+install(FILES ${i%:*} DESTINATION ${i#*:})
+
+EOF
+       done
+
+       ecm-common_inject_heredoc
+
+cat <<-EOF >> CMakeLists.txt
+
+feature_summary(WHAT ALL INCLUDE_QUIET_PACKAGES 
FATAL_ON_MISSING_REQUIRED_PACKAGES)
+EOF
+
+       cmake_src_prepare
+}
+
+fi
+
+EXPORT_FUNCTIONS src_prepare

[-- Attachment #2: This is a digitally signed message part. --]
[-- Type: application/pgp-signature, Size: 789 bytes --]