1 |
dsd 08/10/31 22:01:32 |
2 |
|
3 |
Modified: linux-info.eclass |
4 |
Log: |
5 |
Add documentation from Fabio Rossi in bug #217562 |
6 |
|
7 |
Revision Changes Path |
8 |
1.56 eclass/linux-info.eclass |
9 |
|
10 |
file : http://sources.gentoo.org/viewcvs.py/gentoo-x86/eclass/linux-info.eclass?rev=1.56&view=markup |
11 |
plain: http://sources.gentoo.org/viewcvs.py/gentoo-x86/eclass/linux-info.eclass?rev=1.56&content-type=text/plain |
12 |
diff : http://sources.gentoo.org/viewcvs.py/gentoo-x86/eclass/linux-info.eclass?r1=1.55&r2=1.56 |
13 |
|
14 |
Index: linux-info.eclass |
15 |
=================================================================== |
16 |
RCS file: /var/cvsroot/gentoo-x86/eclass/linux-info.eclass,v |
17 |
retrieving revision 1.55 |
18 |
retrieving revision 1.56 |
19 |
diff -u -r1.55 -r1.56 |
20 |
--- linux-info.eclass 21 Mar 2008 11:11:27 -0000 1.55 |
21 |
+++ linux-info.eclass 31 Oct 2008 22:01:32 -0000 1.56 |
22 |
@@ -1,53 +1,93 @@ |
23 |
# Copyright 1999-2006 Gentoo Foundation |
24 |
# Distributed under the terms of the GNU General Public License v2 |
25 |
-# $Header: /var/cvsroot/gentoo-x86/eclass/linux-info.eclass,v 1.55 2008/03/21 11:11:27 dsd Exp $ |
26 |
-# |
27 |
-# Description: This eclass is used as a central eclass for accessing kernel |
28 |
-# related information for sources already installed. |
29 |
-# It is vital for linux-mod to function correctly, and is split |
30 |
-# out so that any ebuild behaviour "templates" are abstracted out |
31 |
-# using additional eclasses. |
32 |
+# $Header: /var/cvsroot/gentoo-x86/eclass/linux-info.eclass,v 1.56 2008/10/31 22:01:32 dsd Exp $ |
33 |
# |
34 |
# Original author: John Mylchreest <johnm@g.o> |
35 |
# Maintainer: kernel-misc@g.o |
36 |
# |
37 |
# Please direct your bugs to the current eclass maintainer :) |
38 |
|
39 |
+# @ECLASS: linux-info.eclass |
40 |
+# @MAINTAINER: |
41 |
+# kernel-misc@g.o |
42 |
+# @BLURB: eclass used for accessing kernel related information |
43 |
+# @DESCRIPTION: |
44 |
+# This eclass is used as a central eclass for accessing kernel |
45 |
+# related information for sources already installed. |
46 |
+# It is vital for linux-mod.eclass to function correctly, and is split |
47 |
+# out so that any ebuild behaviour "templates" are abstracted out |
48 |
+# using additional eclasses. |
49 |
+ |
50 |
# A Couple of env vars are available to effect usage of this eclass |
51 |
# These are as follows: |
52 |
+ |
53 |
+# @ECLASS-VARIABLE: KERNEL_DIR |
54 |
+# @DESCRIPTION: |
55 |
+# A string containing the directory of the target kernel sources. The default value is |
56 |
+# "/usr/src/linux" |
57 |
+ |
58 |
+# @ECLASS-VARIABLE: CONFIG_CHECK |
59 |
+# @DESCRIPTION: |
60 |
+# A string containing a list of .config options to check for before |
61 |
+# proceeding with the install. |
62 |
+# |
63 |
+# e.g.: CONFIG_CHECK="MTRR" |
64 |
+# |
65 |
+# You can also check that an option doesn't exist by |
66 |
+# prepending it with an exclamation mark (!). |
67 |
+# |
68 |
+# e.g.: CONFIG_CHECK="!MTRR" |
69 |
+# |
70 |
+# To simply warn about a missing option, prepend a '~'. |
71 |
+ |
72 |
+# @ECLASS-VARIABLE: ERROR_<CFG> |
73 |
+# @DESCRIPTION: |
74 |
+# A string containing the error message to display when the check against CONFIG_CHECK |
75 |
+# fails. <CFG> should reference the appropriate option used in CONFIG_CHECK. |
76 |
# |
77 |
-# Env Var Option Description |
78 |
-# KERNEL_DIR <string> The directory containing kernel the target kernel |
79 |
-# sources. |
80 |
-# CONFIG_CHECK <string> a list of .config options to check for before |
81 |
-# proceeding with the install. ie: CONFIG_CHECK="MTRR" |
82 |
-# You can also check that an option doesn't exist by |
83 |
-# prepending it with an exclamation mark (!). |
84 |
-# ie: CONFIG_CHECK="!MTRR" |
85 |
-# To simply warn about a missing option, prepend a '~'. |
86 |
-# ERROR_CFG <string> The error message to display when the above check |
87 |
-# fails. <CFG> should reference the appropriate option |
88 |
-# as above. ie: ERROR_MTRR="MTRR exists in the .config |
89 |
-# but shouldn't!!" |
90 |
-# KBUILD_OUTPUT <string> This is passed on commandline, or can be set from |
91 |
-# the kernel makefile. This contains the directory |
92 |
-# which is to be used as the kernel object directory. |
93 |
+# e.g.: ERROR_MTRR="MTRR exists in the .config but shouldn't!!" |
94 |
+ |
95 |
+# @ECLASS-VARIABLE: KBUILD_OUTPUT |
96 |
+# @DESCRIPTION: |
97 |
+# A string passed on commandline, or set from the kernel makefile. It contains the directory |
98 |
+# which is to be used as the kernel object directory. |
99 |
|
100 |
# There are also a couple of variables which are set by this, and shouldn't be |
101 |
# set by hand. These are as follows: |
102 |
-# |
103 |
-# Env Var Option Description |
104 |
-# KV_FULL <string> The full kernel version. ie: 2.6.9-gentoo-johnm-r1 |
105 |
-# KV_MAJOR <integer> The kernel major version. ie: 2 |
106 |
-# KV_MINOR <integer> The kernel minor version. ie: 6 |
107 |
-# KV_PATCH <integer> The kernel patch version. ie: 9 |
108 |
-# KV_EXTRA <string> The kernel EXTRAVERSION. ie: -gentoo |
109 |
-# KV_LOCAL <string> The kernel LOCALVERSION concatenation. ie: -johnm |
110 |
-# KV_DIR <string> The kernel source directory, will be null if |
111 |
-# KERNEL_DIR is invalid. |
112 |
-# KV_OUT_DIR <string> The kernel object directory. will be KV_DIR unless |
113 |
-# koutput is used. This should be used for referencing |
114 |
-# .config. |
115 |
+ |
116 |
+# @ECLASS-VARIABLE: KV_FULL |
117 |
+# @DESCRIPTION: |
118 |
+# A read-only variable. It's a string containing the full kernel version. ie: 2.6.9-gentoo-johnm-r1 |
119 |
+ |
120 |
+# @ECLASS-VARIABLE: KV_MAJOR |
121 |
+# @DESCRIPTION: |
122 |
+# A read-only variable. It's an integer containing the kernel major version. ie: 2 |
123 |
+ |
124 |
+# @ECLASS-VARIABLE: KV_MINOR |
125 |
+# @DESCRIPTION: |
126 |
+# A read-only variable. It's an integer containing the kernel minor version. ie: 6 |
127 |
+ |
128 |
+# @ECLASS-VARIABLE: KV_PATCH |
129 |
+# @DESCRIPTION: |
130 |
+# A read-only variable. It's an integer containing the kernel patch version. ie: 9 |
131 |
+ |
132 |
+# @ECLASS-VARIABLE: KV_EXTRA |
133 |
+# @DESCRIPTION: |
134 |
+# A read-only variable. It's a string containing the kernel EXTRAVERSION. ie: -gentoo |
135 |
+ |
136 |
+# @ECLASS-VARIABLE: KV_LOCAL |
137 |
+# @DESCRIPTION: |
138 |
+# A read-only variable. It's a string containing the kernel LOCALVERSION concatenation. ie: -johnm |
139 |
+ |
140 |
+# @ECLASS-VARIABLE: KV_DIR |
141 |
+# @DESCRIPTION: |
142 |
+# A read-only variable. It's a string containing the kernel source directory, will be null if |
143 |
+# KERNEL_DIR is invalid. |
144 |
+ |
145 |
+# @ECLASS-VARIABLE: KV_OUT_DIR |
146 |
+# @DESCRIPTION: |
147 |
+# A read-only variable. It's a string containing the kernel object directory, will be KV_DIR unless |
148 |
+# KBUILD_OUTPUT is used. This should be used for referencing .config. |
149 |
|
150 |
# And to ensure all the weirdness with crosscompile |
151 |
inherit toolchain-funcs versionator |
152 |
@@ -101,9 +141,11 @@ |
153 |
# File Functions |
154 |
# --------------------------------------- |
155 |
|
156 |
-# getfilevar accepts 2 vars as follows: |
157 |
-# getfilevar <VARIABLE> <CONFIGFILE> |
158 |
- |
159 |
+# @FUNCTION: getfilevar |
160 |
+# @USAGE: variable configfile |
161 |
+# @RETURN: the value of the variable |
162 |
+# @DESCRIPTION: |
163 |
+# It detects the value of the variable defined in the file configfile |
164 |
getfilevar() { |
165 |
local ERROR workingdir basefname basedname myARCH="${ARCH}" |
166 |
ERROR=0 |
167 |
@@ -132,10 +174,18 @@ |
168 |
} |
169 |
|
170 |
|
171 |
+# @FUNCTION: linux_config_exists |
172 |
+# @RETURN: true or false |
173 |
+# @DESCRIPTION: |
174 |
+# It returns true if .config exists otherwise false |
175 |
linux_config_exists() { |
176 |
[ -s "${KV_OUT_DIR}/.config" ] |
177 |
} |
178 |
|
179 |
+# @FUNCTION: require_configured_kernel |
180 |
+# @DESCRIPTION: |
181 |
+# This function verifies that the current kernel is configured (it checks against the existence of .config) |
182 |
+# otherwise it dies. |
183 |
require_configured_kernel() { |
184 |
if ! linux_config_exists; then |
185 |
qeerror "Could not find a usable .config in the kernel source directory." |
186 |
@@ -146,6 +196,11 @@ |
187 |
fi |
188 |
} |
189 |
|
190 |
+# @FUNCTION: linux_chkconfig_present |
191 |
+# @USAGE: option |
192 |
+# @RETURN: true or false |
193 |
+# @DESCRIPTION: |
194 |
+# It checks that CONFIG_<option>=y or CONFIG_<option>=n is present in the current kernel .config |
195 |
linux_chkconfig_present() { |
196 |
local RESULT |
197 |
require_configured_kernel |
198 |
@@ -153,6 +208,11 @@ |
199 |
[ "${RESULT}" = "m" -o "${RESULT}" = "y" ] && return 0 || return 1 |
200 |
} |
201 |
|
202 |
+# @FUNCTION: linux_chkconfig_module |
203 |
+# @USAGE: option |
204 |
+# @RETURN: true or false |
205 |
+# @DESCRIPTION: |
206 |
+# It checks that CONFIG_<option>=m is present in the current kernel .config |
207 |
linux_chkconfig_module() { |
208 |
local RESULT |
209 |
require_configured_kernel |
210 |
@@ -160,6 +220,11 @@ |
211 |
[ "${RESULT}" = "m" ] && return 0 || return 1 |
212 |
} |
213 |
|
214 |
+# @FUNCTION: linux_chkconfig_builtin |
215 |
+# @USAGE: option |
216 |
+# @RETURN: true or false |
217 |
+# @DESCRIPTION: |
218 |
+# It checks that CONFIG_<option>=y is present in the current kernel .config |
219 |
linux_chkconfig_builtin() { |
220 |
local RESULT |
221 |
require_configured_kernel |
222 |
@@ -167,6 +232,11 @@ |
223 |
[ "${RESULT}" = "y" ] && return 0 || return 1 |
224 |
} |
225 |
|
226 |
+# @FUNCTION: linux_chkconfig_string |
227 |
+# @USAGE: option |
228 |
+# @RETURN: CONFIG_<option> |
229 |
+# @DESCRIPTION: |
230 |
+# It prints the CONFIG_<option> value of the current kernel .config (it requires a configured kernel). |
231 |
linux_chkconfig_string() { |
232 |
require_configured_kernel |
233 |
getfilevar "CONFIG_${1}" "${KV_OUT_DIR}/.config" |
234 |
@@ -175,15 +245,22 @@ |
235 |
# Versioning Functions |
236 |
# --------------------------------------- |
237 |
|
238 |
-# kernel_is returns true when the version is the same as the passed version |
239 |
+# @FUNCTION: kernel_is |
240 |
+# @USAGE: [-lt -gt -le -ge -eq] major_number [minor_number patch_number] |
241 |
+# @RETURN: true or false |
242 |
+# @DESCRIPTION: |
243 |
+# It returns true when the current kernel version satisfies the comparison against the passed version. |
244 |
+# -eq is the default comparison. |
245 |
# |
246 |
+# @CODE |
247 |
# For Example where KV = 2.6.9 |
248 |
-# kernel_is 2 4 returns false |
249 |
-# kernel_is 2 returns true |
250 |
-# kernel_is 2 6 returns true |
251 |
-# kernel_is 2 6 8 returns false |
252 |
-# kernel_is 2 6 9 returns true |
253 |
-# |
254 |
+# kernel_is 2 4 returns false |
255 |
+# kernel_is 2 returns true |
256 |
+# kernel_is 2 6 returns true |
257 |
+# kernel_is 2 6 8 returns false |
258 |
+# kernel_is 2 6 9 returns true |
259 |
+# @CODE |
260 |
+ |
261 |
# got the jist yet? |
262 |
|
263 |
kernel_is() { |
264 |
@@ -234,6 +311,16 @@ |
265 |
echo ${x} |
266 |
} |
267 |
|
268 |
+# @FUNCTION: get_version |
269 |
+# @DESCRIPTION: |
270 |
+# It gets the version of the kernel inside KERNEL_DIR and populates the KV_FULL variable |
271 |
+# (if KV_FULL is already set it does nothing). |
272 |
+# |
273 |
+# The kernel version variables (KV_MAJOR, KV_MINOR, KV_PATCH, KV_EXTRA and KV_LOCAL) are also set. |
274 |
+# |
275 |
+# The KV_DIR is set using the KERNEL_DIR env var, the KV_DIR_OUT is set using a valid |
276 |
+# KBUILD_OUTPUT (in a decreasing priority list, we look for the env var, makefile var or the |
277 |
+# symlink /lib/modules/${KV_MAJOR}.${KV_MINOR}.${KV_PATCH}${KV_EXTRA}/build). |
278 |
get_version() { |
279 |
local kbuild_output |
280 |
|
281 |
@@ -338,6 +425,10 @@ |
282 |
return 0 |
283 |
} |
284 |
|
285 |
+# @FUNCTION: get_running_version |
286 |
+# @DESCRIPTION: |
287 |
+# It gets the version of the current running kernel and the result is the same as get_version() if the |
288 |
+# function can find the sources. |
289 |
get_running_version() { |
290 |
KV_FULL=$(uname -r) |
291 |
|
292 |
@@ -366,6 +457,9 @@ |
293 |
# ebuild check functions |
294 |
# --------------------------------------- |
295 |
|
296 |
+# @FUNCTION: check_kernel_built |
297 |
+# @DESCRIPTION: |
298 |
+# This function verifies that the current kernel sources have been already prepared otherwise it dies. |
299 |
check_kernel_built() { |
300 |
# if we haven't determined the version yet, we need to |
301 |
require_configured_kernel |
302 |
@@ -386,6 +480,9 @@ |
303 |
fi |
304 |
} |
305 |
|
306 |
+# @FUNCTION: check_modules_supported |
307 |
+# @DESCRIPTION: |
308 |
+# This function verifies that the current kernel support modules (it checks CONFIG_MODULES=y) otherwise it dies. |
309 |
check_modules_supported() { |
310 |
# if we haven't determined the version yet, we need too. |
311 |
require_configured_kernel |
312 |
@@ -400,6 +497,10 @@ |
313 |
fi |
314 |
} |
315 |
|
316 |
+# @FUNCTION: check_extra_config |
317 |
+# @DESCRIPTION: |
318 |
+# It checks the kernel config options specified by CONFIG_CHECK. It dies only when a required config option (i.e. |
319 |
+# the prefix ~ is not used) doesn't satisfy the directive. |
320 |
check_extra_config() { |
321 |
local config negate die error reworkmodulenames |
322 |
local soft_errors_count=0 hard_errors_count=0 config_required=0 |
323 |
@@ -590,7 +691,10 @@ |
324 |
################################ |
325 |
# Default pkg_setup |
326 |
# Also used when inheriting linux-mod to force a get_version call |
327 |
- |
328 |
+# @FUNCTION: linux-info_pkg_setup |
329 |
+# @DESCRIPTION: |
330 |
+# Force a get_version() call when inherited from linux-mod.eclass and then check if the kernel is configured |
331 |
+# to support the options specified in CONFIG_CHECK (if not null) |
332 |
linux-info_pkg_setup() { |
333 |
get_version || die "Unable to calculate Linux Kernel version" |