1 |
commit: 3bcc9956ad8f2669d6e6b17f42c5ee541d6dfd34 |
2 |
Author: Michael Palimaka <kensington <AT> gentoo <DOT> org> |
3 |
AuthorDate: Wed Sep 13 13:18:35 2017 +0000 |
4 |
Commit: Michael Palimaka <kensington <AT> gentoo <DOT> org> |
5 |
CommitDate: Wed Sep 13 13:18:47 2017 +0000 |
6 |
URL: https://gitweb.gentoo.org/proj/kde.git/commit/?id=3bcc9956 |
7 |
|
8 |
kde5.eclass: improve documentation |
9 |
|
10 |
Bug: https://bugs.gentoo.org/629642 |
11 |
|
12 |
eclass/kde5.eclass | 65 +++++++++++++++++++++++++++++++++++++----------------- |
13 |
1 file changed, 45 insertions(+), 20 deletions(-) |
14 |
|
15 |
diff --git a/eclass/kde5.eclass b/eclass/kde5.eclass |
16 |
index 17763f1640..738b1268d5 100644 |
17 |
--- a/eclass/kde5.eclass |
18 |
+++ b/eclass/kde5.eclass |
19 |
@@ -4,9 +4,22 @@ |
20 |
# @ECLASS: kde5.eclass |
21 |
# @MAINTAINER: |
22 |
# kde@g.o |
23 |
-# @BLURB: Support eclass for KDE 5-related packages. |
24 |
+# @BLURB: Support eclass for packages that follow KDE packaging conventions. |
25 |
# @DESCRIPTION: |
26 |
-# The kde5.eclass provides support for building KDE 5-related packages. |
27 |
+# This eclass is intended to streamline the creation of ebuilds for packages |
28 |
+# that follow KDE upstream packaging conventions. It's primarily intended for |
29 |
+# the three upstream release groups (Frameworks, Plasma, Applications) but |
30 |
+# is also for any package that follows similar conventions. |
31 |
+# |
32 |
+# This eclass unconditionally inherits kde5-functions.eclass and all its public |
33 |
+# functions and variables may be considered as part of this eclass's API. |
34 |
+# |
35 |
+# This eclass unconditionally inherits cmake-utils.eclass and all its public |
36 |
+# variables and helper functions (not phase functions) may be considered as part |
37 |
+# of this eclass's API. |
38 |
+# |
39 |
+# This eclass's phase functions are not intended to be mixed and matched, so if |
40 |
+# any phase functions are overriden the version here should also be called. |
41 |
|
42 |
if [[ -z ${_KDE5_ECLASS} ]]; then |
43 |
_KDE5_ECLASS=1 |
44 |
@@ -35,19 +48,22 @@ EXPORT_FUNCTIONS pkg_setup pkg_nofetch src_unpack src_prepare src_configure src_ |
45 |
# @ECLASS-VARIABLE: KDE_AUTODEPS |
46 |
# @DESCRIPTION: |
47 |
# If set to "false", do nothing. |
48 |
-# For any other value, add a dependency on dev-qt/qtcore:5 and kde-frameworks/extra-cmake-modules:5. |
49 |
+# For any other value, add dependencies on dev-qt/qtcore:5, kde-frameworks/kf-env |
50 |
+# and kde-frameworks/extra-cmake-modules:5. Additionally, required blockers may |
51 |
+# be set depending on the value of CATEGORY. |
52 |
: ${KDE_AUTODEPS:=true} |
53 |
|
54 |
# @ECLASS-VARIABLE: KDE_BLOCK_SLOT4 |
55 |
# @DESCRIPTION: |
56 |
-# This variable is used when KDE_AUTODEPS is set. |
57 |
-# If set to "true", add RDEPEND block on kde-apps/${PN}:4 |
58 |
+# This variable only has any effect when when CATEGORY = "kde-apps" and |
59 |
+# KDE_AUTODEPS is also set. If set to "true", add RDEPEND block on kde-apps/${PN}:4 |
60 |
: ${KDE_BLOCK_SLOT4:=true} |
61 |
|
62 |
# @ECLASS-VARIABLE: KDE_DEBUG |
63 |
# @DESCRIPTION: |
64 |
-# If set to "false", unconditionally build with -DNDEBUG. |
65 |
-# Otherwise, add debug to IUSE to control building with that flag. |
66 |
+# If set to "false", add -DNDEBUG (via cmake-utils_src_configure) and -DQT_NO_DEBUG |
67 |
+# to CPPFLAGS. |
68 |
+# Otherwise, add debug to IUSE. |
69 |
: ${KDE_DEBUG:=true} |
70 |
|
71 |
# @ECLASS-VARIABLE: KDE_DESIGNERPLUGIN |
72 |
@@ -76,7 +92,7 @@ EXPORT_FUNCTIONS pkg_setup pkg_nofetch src_unpack src_prepare src_configure src_ |
73 |
|
74 |
# @ECLASS-VARIABLE: KDE_DOC_DIR |
75 |
# @DESCRIPTION: |
76 |
-# Defaults to "doc". Otherwise, use alternative KDE handbook path. |
77 |
+# Specifies the location of the KDE handbook if not the default. |
78 |
: ${KDE_DOC_DIR:=doc} |
79 |
|
80 |
# @ECLASS-VARIABLE: KDE_QTHELP |
81 |
@@ -416,7 +432,8 @@ debug-print "${LINENO} ${ECLASS} ${FUNCNAME}: SRC_URI is ${SRC_URI}" |
82 |
|
83 |
# @FUNCTION: kde5_pkg_pretend |
84 |
# @DESCRIPTION: |
85 |
-# Do some basic settings |
86 |
+# Checks if the active compiler meets the minimum version requirements. |
87 |
+# phase function is only exported if KDE_GCC_MINIMAL is defined. |
88 |
kde5_pkg_pretend() { |
89 |
debug-print-function ${FUNCNAME} "$@" |
90 |
_check_gcc_version |
91 |
@@ -424,7 +441,7 @@ kde5_pkg_pretend() { |
92 |
|
93 |
# @FUNCTION: kde5_pkg_setup |
94 |
# @DESCRIPTION: |
95 |
-# Do some basic settings |
96 |
+# Checks if the active compiler meets the minimum version requirements. |
97 |
kde5_pkg_setup() { |
98 |
debug-print-function ${FUNCNAME} "$@" |
99 |
_check_gcc_version |
100 |
@@ -432,7 +449,9 @@ kde5_pkg_setup() { |
101 |
|
102 |
# @FUNCTION: kde5_pkg_nofetch |
103 |
# @DESCRIPTION: |
104 |
-# Display package publication status |
105 |
+# Intended for use in the KDE overlay. If this package matches something in |
106 |
+# KDE_UNRELEASED, display a giant warning that the package has not yet been |
107 |
+# released upstream and should not be used. |
108 |
kde5_pkg_nofetch() { |
109 |
if ! _kde_is_unreleased ; then |
110 |
return |
111 |
@@ -462,7 +481,7 @@ kde5_pkg_nofetch() { |
112 |
|
113 |
# @FUNCTION: kde5_src_unpack |
114 |
# @DESCRIPTION: |
115 |
-# Function for unpacking KDE 5. |
116 |
+# Unpack the sources, automatically handling both release and live ebuilds. |
117 |
kde5_src_unpack() { |
118 |
debug-print-function ${FUNCNAME} "$@" |
119 |
|
120 |
@@ -479,7 +498,8 @@ kde5_src_unpack() { |
121 |
|
122 |
# @FUNCTION: kde5_src_prepare |
123 |
# @DESCRIPTION: |
124 |
-# Function for preparing the KDE 5 sources. |
125 |
+# Wrapper for cmake-utils_src_prepare with lots of extra logic for magic |
126 |
+# handling of linguas, tests, handbook etc. |
127 |
kde5_src_prepare() { |
128 |
debug-print-function ${FUNCNAME} "$@" |
129 |
|
130 |
@@ -589,7 +609,8 @@ kde5_src_prepare() { |
131 |
|
132 |
# @FUNCTION: kde5_src_configure |
133 |
# @DESCRIPTION: |
134 |
-# Function for configuring the build of KDE 5. |
135 |
+# Wrapper for cmake-utils_src_configure with extra logic for magic handling of |
136 |
+# handbook, tests etc. |
137 |
kde5_src_configure() { |
138 |
debug-print-function ${FUNCNAME} "$@" |
139 |
|
140 |
@@ -635,7 +656,8 @@ kde5_src_configure() { |
141 |
|
142 |
# @FUNCTION: kde5_src_compile |
143 |
# @DESCRIPTION: |
144 |
-# Function for compiling KDE 5. |
145 |
+# Wrapper for cmake-utils_src_compile. Currently doesn't do anything extra, but |
146 |
+# is included as part of the API just in case it's needed in the future. |
147 |
kde5_src_compile() { |
148 |
debug-print-function ${FUNCNAME} "$@" |
149 |
|
150 |
@@ -644,7 +666,8 @@ kde5_src_compile() { |
151 |
|
152 |
# @FUNCTION: kde5_src_test |
153 |
# @DESCRIPTION: |
154 |
-# Function for testing KDE 5. |
155 |
+# Wrapper for cmake-utils_src_test with extra logic for magic handling of dbus |
156 |
+# and virtualx. |
157 |
kde5_src_test() { |
158 |
debug-print-function ${FUNCNAME} "$@" |
159 |
|
160 |
@@ -675,7 +698,9 @@ kde5_src_test() { |
161 |
|
162 |
# @FUNCTION: kde5_src_install |
163 |
# @DESCRIPTION: |
164 |
-# Function for installing KDE 5. |
165 |
+# Wrapper for cmake-utils_src_install with extra logic to avoid compressing |
166 |
+# certain types of files. For example, khelpcenter is not able to read |
167 |
+# compressed handbooks. |
168 |
kde5_src_install() { |
169 |
debug-print-function ${FUNCNAME} "$@" |
170 |
|
171 |
@@ -698,7 +723,7 @@ kde5_src_install() { |
172 |
|
173 |
# @FUNCTION: kde5_pkg_preinst |
174 |
# @DESCRIPTION: |
175 |
-# Function storing icon caches |
176 |
+# Sets up environment variables required in kde5_pkg_postinst. |
177 |
kde5_pkg_preinst() { |
178 |
debug-print-function ${FUNCNAME} "$@" |
179 |
|
180 |
@@ -708,7 +733,7 @@ kde5_pkg_preinst() { |
181 |
|
182 |
# @FUNCTION: kde5_pkg_postinst |
183 |
# @DESCRIPTION: |
184 |
-# Function to rebuild the KDE System Configuration Cache after an application has been installed. |
185 |
+# Updates the various XDG caches (icon, desktop, mime) if necessary. |
186 |
kde5_pkg_postinst() { |
187 |
debug-print-function ${FUNCNAME} "$@" |
188 |
|
189 |
@@ -729,7 +754,7 @@ kde5_pkg_postinst() { |
190 |
|
191 |
# @FUNCTION: kde5_pkg_postrm |
192 |
# @DESCRIPTION: |
193 |
-# Function to rebuild the KDE System Configuration Cache after an application has been removed. |
194 |
+# Updates the various XDG caches (icon, desktop, mime) if necessary. |
195 |
kde5_pkg_postrm() { |
196 |
debug-print-function ${FUNCNAME} "$@" |