From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from lists.gentoo.org (pigeon.gentoo.org [208.92.234.80]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by finch.gentoo.org (Postfix) with ESMTPS id 4B66B1396D0 for ; Wed, 13 Sep 2017 13:19:10 +0000 (UTC) Received: from pigeon.gentoo.org (localhost [127.0.0.1]) by pigeon.gentoo.org (Postfix) with SMTP id 915751FC051; Wed, 13 Sep 2017 13:19:09 +0000 (UTC) Received: from smtp.gentoo.org (woodpecker.gentoo.org [IPv6:2001:470:ea4a:1:5054:ff:fec7:86e4]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by pigeon.gentoo.org (Postfix) with ESMTPS id 5E2F51FC051 for ; Wed, 13 Sep 2017 13:19:09 +0000 (UTC) Received: from oystercatcher.gentoo.org (unknown [IPv6:2a01:4f8:202:4333:225:90ff:fed9:fc84]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by smtp.gentoo.org (Postfix) with ESMTPS id 0100233D3CE for ; Wed, 13 Sep 2017 13:19:08 +0000 (UTC) Received: from localhost.localdomain (localhost [IPv6:::1]) by oystercatcher.gentoo.org (Postfix) with ESMTP id 9ADFA9064 for ; Wed, 13 Sep 2017 13:19:06 +0000 (UTC) From: "Michael Palimaka" To: gentoo-commits@lists.gentoo.org Content-Transfer-Encoding: 8bit Content-type: text/plain; charset=UTF-8 Reply-To: gentoo-dev@lists.gentoo.org, "Michael Palimaka" Message-ID: <1505308727.3bcc9956ad8f2669d6e6b17f42c5ee541d6dfd34.kensington@gentoo> Subject: [gentoo-commits] proj/kde:master commit in: eclass/ X-VCS-Repository: proj/kde X-VCS-Files: eclass/kde5.eclass X-VCS-Directories: eclass/ X-VCS-Committer: kensington X-VCS-Committer-Name: Michael Palimaka X-VCS-Revision: 3bcc9956ad8f2669d6e6b17f42c5ee541d6dfd34 X-VCS-Branch: master Date: Wed, 13 Sep 2017 13:19:06 +0000 (UTC) Precedence: bulk List-Post: List-Help: List-Unsubscribe: List-Subscribe: List-Id: Gentoo Linux mail X-BeenThere: gentoo-commits@lists.gentoo.org X-Archives-Salt: 21d23d71-c147-4f11-9794-bac2206e1521 X-Archives-Hash: 1c87dd40065fd27a7ed13c9cb78f3106 commit: 3bcc9956ad8f2669d6e6b17f42c5ee541d6dfd34 Author: Michael Palimaka gentoo org> AuthorDate: Wed Sep 13 13:18:35 2017 +0000 Commit: Michael Palimaka gentoo org> CommitDate: Wed Sep 13 13:18:47 2017 +0000 URL: https://gitweb.gentoo.org/proj/kde.git/commit/?id=3bcc9956 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 17763f1640..738b1268d5 100644 --- a/eclass/kde5.eclass +++ b/eclass/kde5.eclass @@ -4,9 +4,22 @@ # @ECLASS: kde5.eclass # @MAINTAINER: # kde@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 @@ -416,7 +432,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 @@ -424,7 +441,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 @@ -432,7 +449,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 @@ -462,7 +481,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} "$@" @@ -479,7 +498,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} "$@" @@ -589,7 +609,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} "$@" @@ -635,7 +656,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} "$@" @@ -644,7 +666,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} "$@" @@ -675,7 +698,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} "$@" @@ -698,7 +723,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} "$@" @@ -708,7 +733,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} "$@" @@ -729,7 +754,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} "$@"