commit: c0a54c9fd461c839f2fe53dd8b5bbfe766e6b6d5 Author: Michael Palimaka <kensington <AT> gentoo <DOT> org> AuthorDate: Wed Sep 13 13:18:35 2017 +0000 Commit: Andreas Sturmlechner <asturm <AT> gentoo <DOT> org> CommitDate: Thu Oct 26 08:22:31 2017 +0000 URL: https://gitweb.gentoo.org/repo/gentoo.git/commit/?id=c0a54c9f
kde5.eclass: improve documentation Bug: https://bugs.gentoo.org/629642 eclass/kde5.eclass | 65 +++++++++++++++++++++++++++++++++++++----------------- 1 file changed, 45 insertions(+), 20 deletions(-) diff --git a/eclass/kde5.eclass b/eclass/kde5.eclass index a72f2d23ce4..b05f96c78f4 100644 --- a/eclass/kde5.eclass +++ b/eclass/kde5.eclass @@ -4,9 +4,22 @@ # @ECLASS: kde5.eclass # @MAINTAINER: # k...@gentoo.org -# @BLURB: Support eclass for KDE 5-related packages. +# @BLURB: Support eclass for packages that follow KDE packaging conventions. # @DESCRIPTION: -# The kde5.eclass provides support for building KDE 5-related packages. +# This eclass is intended to streamline the creation of ebuilds for packages +# that follow KDE upstream packaging conventions. It's primarily intended for +# the three upstream release groups (Frameworks, Plasma, Applications) but +# is also for any package that follows similar conventions. +# +# This eclass unconditionally inherits kde5-functions.eclass and all its public +# functions and variables may be considered as part of this eclass's API. +# +# This eclass unconditionally inherits cmake-utils.eclass and all its public +# variables and helper functions (not phase functions) may be considered as part +# of this eclass's API. +# +# This eclass's phase functions are not intended to be mixed and matched, so if +# any phase functions are overriden the version here should also be called. if [[ -z ${_KDE5_ECLASS} ]]; then _KDE5_ECLASS=1 @@ -35,19 +48,22 @@ EXPORT_FUNCTIONS pkg_setup pkg_nofetch src_unpack src_prepare src_configure src_ # @ECLASS-VARIABLE: KDE_AUTODEPS # @DESCRIPTION: # If set to "false", do nothing. -# For any other value, add a dependency on dev-qt/qtcore:5 and kde-frameworks/extra-cmake-modules:5. +# For any other value, add dependencies on dev-qt/qtcore:5, kde-frameworks/kf-env +# and kde-frameworks/extra-cmake-modules:5. Additionally, required blockers may +# be set depending on the value of CATEGORY. : ${KDE_AUTODEPS:=true} # @ECLASS-VARIABLE: KDE_BLOCK_SLOT4 # @DESCRIPTION: -# This variable is used when KDE_AUTODEPS is set. -# If set to "true", add RDEPEND block on kde-apps/${PN}:4 +# This variable only has any effect when when CATEGORY = "kde-apps" and +# KDE_AUTODEPS is also set. If set to "true", add RDEPEND block on kde-apps/${PN}:4 : ${KDE_BLOCK_SLOT4:=true} # @ECLASS-VARIABLE: KDE_DEBUG # @DESCRIPTION: -# If set to "false", unconditionally build with -DNDEBUG. -# Otherwise, add debug to IUSE to control building with that flag. +# If set to "false", add -DNDEBUG (via cmake-utils_src_configure) and -DQT_NO_DEBUG +# to CPPFLAGS. +# Otherwise, add debug to IUSE. : ${KDE_DEBUG:=true} # @ECLASS-VARIABLE: KDE_DESIGNERPLUGIN @@ -76,7 +92,7 @@ EXPORT_FUNCTIONS pkg_setup pkg_nofetch src_unpack src_prepare src_configure src_ # @ECLASS-VARIABLE: KDE_DOC_DIR # @DESCRIPTION: -# Defaults to "doc". Otherwise, use alternative KDE handbook path. +# Specifies the location of the KDE handbook if not the default. : ${KDE_DOC_DIR:=doc} # @ECLASS-VARIABLE: KDE_QTHELP @@ -417,7 +433,8 @@ debug-print "${LINENO} ${ECLASS} ${FUNCNAME}: SRC_URI is ${SRC_URI}" # @FUNCTION: kde5_pkg_pretend # @DESCRIPTION: -# Do some basic settings +# Checks if the active compiler meets the minimum version requirements. +# phase function is only exported if KDE_GCC_MINIMAL is defined. kde5_pkg_pretend() { debug-print-function ${FUNCNAME} "$@" _check_gcc_version @@ -425,7 +442,7 @@ kde5_pkg_pretend() { # @FUNCTION: kde5_pkg_setup # @DESCRIPTION: -# Do some basic settings +# Checks if the active compiler meets the minimum version requirements. kde5_pkg_setup() { debug-print-function ${FUNCNAME} "$@" _check_gcc_version @@ -433,7 +450,9 @@ kde5_pkg_setup() { # @FUNCTION: kde5_pkg_nofetch # @DESCRIPTION: -# Display package publication status +# Intended for use in the KDE overlay. If this package matches something in +# KDE_UNRELEASED, display a giant warning that the package has not yet been +# released upstream and should not be used. kde5_pkg_nofetch() { if ! _kde_is_unreleased ; then return @@ -463,7 +482,7 @@ kde5_pkg_nofetch() { # @FUNCTION: kde5_src_unpack # @DESCRIPTION: -# Function for unpacking KDE 5. +# Unpack the sources, automatically handling both release and live ebuilds. kde5_src_unpack() { debug-print-function ${FUNCNAME} "$@" @@ -480,7 +499,8 @@ kde5_src_unpack() { # @FUNCTION: kde5_src_prepare # @DESCRIPTION: -# Function for preparing the KDE 5 sources. +# Wrapper for cmake-utils_src_prepare with lots of extra logic for magic +# handling of linguas, tests, handbook etc. kde5_src_prepare() { debug-print-function ${FUNCNAME} "$@" @@ -590,7 +610,8 @@ kde5_src_prepare() { # @FUNCTION: kde5_src_configure # @DESCRIPTION: -# Function for configuring the build of KDE 5. +# Wrapper for cmake-utils_src_configure with extra logic for magic handling of +# handbook, tests etc. kde5_src_configure() { debug-print-function ${FUNCNAME} "$@" @@ -632,7 +653,8 @@ kde5_src_configure() { # @FUNCTION: kde5_src_compile # @DESCRIPTION: -# Function for compiling KDE 5. +# Wrapper for cmake-utils_src_compile. Currently doesn't do anything extra, but +# is included as part of the API just in case it's needed in the future. kde5_src_compile() { debug-print-function ${FUNCNAME} "$@" @@ -641,7 +663,8 @@ kde5_src_compile() { # @FUNCTION: kde5_src_test # @DESCRIPTION: -# Function for testing KDE 5. +# Wrapper for cmake-utils_src_test with extra logic for magic handling of dbus +# and virtualx. kde5_src_test() { debug-print-function ${FUNCNAME} "$@" @@ -672,7 +695,9 @@ kde5_src_test() { # @FUNCTION: kde5_src_install # @DESCRIPTION: -# Function for installing KDE 5. +# Wrapper for cmake-utils_src_install with extra logic to avoid compressing +# certain types of files. For example, khelpcenter is not able to read +# compressed handbooks. kde5_src_install() { debug-print-function ${FUNCNAME} "$@" @@ -695,7 +720,7 @@ kde5_src_install() { # @FUNCTION: kde5_pkg_preinst # @DESCRIPTION: -# Function storing icon caches +# Sets up environment variables required in kde5_pkg_postinst. kde5_pkg_preinst() { debug-print-function ${FUNCNAME} "$@" @@ -705,7 +730,7 @@ kde5_pkg_preinst() { # @FUNCTION: kde5_pkg_postinst # @DESCRIPTION: -# Function to rebuild the KDE System Configuration Cache after an application has been installed. +# Updates the various XDG caches (icon, desktop, mime) if necessary. kde5_pkg_postinst() { debug-print-function ${FUNCNAME} "$@" @@ -726,7 +751,7 @@ kde5_pkg_postinst() { # @FUNCTION: kde5_pkg_postrm # @DESCRIPTION: -# Function to rebuild the KDE System Configuration Cache after an application has been removed. +# Updates the various XDG caches (icon, desktop, mime) if necessary. kde5_pkg_postrm() { debug-print-function ${FUNCNAME} "$@"
