1 |
dsd 08/10/31 22:24:55 |
2 |
|
3 |
Modified: linux-mod.eclass |
4 |
Log: |
5 |
add some fantastic documentation from Fabio Rossi in bug #217560 |
6 |
|
7 |
Revision Changes Path |
8 |
1.86 eclass/linux-mod.eclass |
9 |
|
10 |
file : http://sources.gentoo.org/viewcvs.py/gentoo-x86/eclass/linux-mod.eclass?rev=1.86&view=markup |
11 |
plain: http://sources.gentoo.org/viewcvs.py/gentoo-x86/eclass/linux-mod.eclass?rev=1.86&content-type=text/plain |
12 |
diff : http://sources.gentoo.org/viewcvs.py/gentoo-x86/eclass/linux-mod.eclass?r1=1.85&r2=1.86 |
13 |
|
14 |
Index: linux-mod.eclass |
15 |
=================================================================== |
16 |
RCS file: /var/cvsroot/gentoo-x86/eclass/linux-mod.eclass,v |
17 |
retrieving revision 1.85 |
18 |
retrieving revision 1.86 |
19 |
diff -u -r1.85 -r1.86 |
20 |
--- linux-mod.eclass 31 Oct 2008 21:25:56 -0000 1.85 |
21 |
+++ linux-mod.eclass 31 Oct 2008 22:24:55 -0000 1.86 |
22 |
@@ -1,47 +1,60 @@ |
23 |
# Copyright 1999-2004 Gentoo Foundation |
24 |
# Distributed under the terms of the GNU General Public License v2 |
25 |
-# $Header: /var/cvsroot/gentoo-x86/eclass/linux-mod.eclass,v 1.85 2008/10/31 21:25:56 dsd Exp $ |
26 |
+# $Header: /var/cvsroot/gentoo-x86/eclass/linux-mod.eclass,v 1.86 2008/10/31 22:24:55 dsd Exp $ |
27 |
|
28 |
-# Description: This eclass is used to interface with linux-info in such a way |
29 |
-# to provide the functionality required and initial functions |
30 |
-# required to install external modules against a kernel source |
31 |
-# tree. |
32 |
-# |
33 |
# Author(s): John Mylchreest <johnm@g.o>, |
34 |
# Stefan Schweizer <genstef@g.o> |
35 |
# Maintainer: kernel-misc@g.o |
36 |
# |
37 |
# Please direct your bugs to the current eclass maintainer :) |
38 |
|
39 |
+# @ECLASS: linux-mod.eclass |
40 |
+# @MAINTAINER: |
41 |
+# kernel-misc@g.o |
42 |
+# @BLURB: It provides the functionality required to install external modules against a kernel source tree. |
43 |
+# @DESCRIPTION: |
44 |
+# This eclass is used to interface with linux-info.eclass in such a way |
45 |
+# to provide the functionality and initial functions |
46 |
+# required to install external modules against a kernel source |
47 |
+# tree. |
48 |
+ |
49 |
# A Couple of env vars are available to effect usage of this eclass |
50 |
# These are as follows: |
51 |
-# |
52 |
-# Env Var Option Default Description |
53 |
-# KERNEL_DIR <string> /usr/src/linux The directory containing kernel |
54 |
-# the target kernel sources. |
55 |
-# ECONF_PARAMS <string> The parameters to pass to econf. |
56 |
-# If this is not set, then econf |
57 |
-# isn't run. |
58 |
-# BUILD_PARAMS <string> The parameters to pass to emake. |
59 |
-# BUILD_TARGETS <string> clean modules The build targets to pass to |
60 |
-# make. |
61 |
-# MODULE_NAMES <string> This is the modules which are |
62 |
-# to be built automatically using |
63 |
-# the default pkg_compile/install. |
64 |
-# They are explained properly |
65 |
-# below. It will only make |
66 |
-# BUILD_TARGETS once in any |
67 |
-# directory. |
68 |
|
69 |
-# MODULE_NAMES - Detailed Overview |
70 |
+# @ECLASS-VARIABLE: KERNEL_DIR |
71 |
+# @DESCRIPTION: |
72 |
+# A string containing the directory of the target kernel sources. The default value is |
73 |
+# "/usr/src/linux" |
74 |
+ |
75 |
+# @ECLASS-VARIABLE: ECONF_PARAMS |
76 |
+# @DESCRIPTION: |
77 |
+# It's a string containing the parameters to pass to econf. |
78 |
+# If this is not set, then econf isn't run. |
79 |
+ |
80 |
+# @ECLASS-VARIABLE: BUILD_PARAMS |
81 |
+# @DESCRIPTION: |
82 |
+# It's a string with the parameters to pass to emake. |
83 |
+ |
84 |
+# @ECLASS-VARIABLE: BUILD_TARGETS |
85 |
+# @DESCRIPTION: |
86 |
+# It's a string with the build targets to pass to make. The default value is "clean modules" |
87 |
+ |
88 |
+# @ECLASS-VARIABLE: MODULE_NAMES |
89 |
+# @DESCRIPTION: |
90 |
+# It's a string containing the modules to be built automatically using the default |
91 |
+# src_compile/src_install. It will only make ${BUILD_TARGETS} once in any directory. |
92 |
+ |
93 |
# |
94 |
# The structure of each MODULE_NAMES entry is as follows: |
95 |
-# modulename(libdir:srcdir:objdir) |
96 |
# |
97 |
-# modulename = name of the module file excluding the .ko |
98 |
-# libdir = place in system modules directory where module is installed: |
99 |
-# srcdir = place for ebuild to cd to before running make |
100 |
-# objdir = place the .ko and objects are located after make runs |
101 |
+# modulename(libdir:srcdir:objdir) |
102 |
+# |
103 |
+# where: |
104 |
+# |
105 |
+# modulename = name of the module file excluding the .ko |
106 |
+# libdir = place in system modules directory where module is installed: |
107 |
+# srcdir = place for ebuild to cd to before running make |
108 |
+# objdir = place the .ko and objects are located after make runs |
109 |
# |
110 |
# To get an idea of how these variables are used, here's a few lines |
111 |
# of code from around line 540 in this eclass: |
112 |
@@ -51,47 +64,67 @@ |
113 |
# insinto /lib/modules/${KV_FULL}/${libdir} |
114 |
# doins ${modulename}.${KV_OBJ} || die "doins ${modulename}.${KV_OBJ} failed" |
115 |
# |
116 |
-# for example: |
117 |
-# MODULE_NAMES="module_pci(pci:${S}/pci:${S}) module_usb(usb:${S}/usb:${S})" |
118 |
+# For example: |
119 |
+# MODULE_NAMES="module_pci(pci:${S}/pci:${S}) module_usb(usb:${S}/usb:${S})" |
120 |
# |
121 |
# what this would do is |
122 |
-# cd ${S}/pci |
123 |
-# make ${BUILD_PARAMS} ${BUILD_TARGETS} |
124 |
-# cd ${S} |
125 |
-# insinto /lib/modules/${KV_FULL}/pci |
126 |
-# doins module_pci.${KV_OBJ} |
127 |
-# |
128 |
-# cd ${S}/usb |
129 |
-# make ${BUILD_PARAMS} ${BUILD_TARGETS} |
130 |
-# cd ${S} |
131 |
-# insinto /lib/modules/${KV_FULL}/usb |
132 |
-# doins module_usb.${KV_OBJ} |
133 |
-# |
134 |
-# if the srcdir isnt specified, it assumes ${S} |
135 |
-# if the libdir isnt specified, it assumes misc. |
136 |
-# if the objdir isnt specified, it assumes srcdir |
137 |
+# |
138 |
+# cd "${S}"/pci |
139 |
+# make ${BUILD_PARAMS} ${BUILD_TARGETS} |
140 |
+# cd "${S}" |
141 |
+# insinto /lib/modules/${KV_FULL}/pci |
142 |
+# doins module_pci.${KV_OBJ} |
143 |
+# |
144 |
+# cd "${S}"/usb |
145 |
+# make ${BUILD_PARAMS} ${BUILD_TARGETS} |
146 |
+# cd "${S}" |
147 |
+# insinto /lib/modules/${KV_FULL}/usb |
148 |
+# doins module_usb.${KV_OBJ} |
149 |
|
150 |
# There is also support for automated modprobe.d/modules.d(2.4) file generation. |
151 |
# This can be explicitly enabled by setting any of the following variables. |
152 |
+ |
153 |
+# @ECLASS-VARIABLE: MODULESD_<modulename>_ENABLED |
154 |
+# @DESCRIPTION: |
155 |
+# This is used to disable the modprobe.d/modules.d file generation otherwise the file will be |
156 |
+# always generated (unless no MODULESD_<modulename>_* variable is provided). Set to "no" to disable |
157 |
+# the generation of the file and the installation of the documentation. |
158 |
+ |
159 |
+# @ECLASS-VARIABLE: MODULESD_<modulename>_EXAMPLES |
160 |
+# @DESCRIPTION: |
161 |
+# This is a bash array containing a list of examples which should |
162 |
+# be used. If you want us to try and take a guess set this to "guess". |
163 |
+# |
164 |
+# For each array_component it's added an options line in the modprobe.d/modules.d file |
165 |
+# |
166 |
+# options array_component |
167 |
+# |
168 |
+# where array_component is "<modulename> options" (see modprobe.conf(5)) |
169 |
+ |
170 |
+# @ECLASS-VARIABLE: MODULESD_<modulename>_ALIASES |
171 |
+# @DESCRIPTION: |
172 |
+# This is a bash array containing a list of associated aliases. |
173 |
+# |
174 |
+# For each array_component it's added an alias line in the modprobe.d/modules.d file |
175 |
# |
176 |
+# alias array_component |
177 |
# |
178 |
-# MODULESD_${modulename}_ENABLED This enables the modules.d file |
179 |
-# generation even if we dont |
180 |
-# specify any additional info. |
181 |
-# MODULESD_${modulename}_EXAMPLES This is a bash array containing |
182 |
-# a list of examples which should |
183 |
-# be used. If you want us to try and |
184 |
-# take a guess. Set this to "guess" |
185 |
-# MODULESD_${modulename}_ALIASES This is a bash array containing |
186 |
-# a list of associated aliases. |
187 |
-# MODULESD_${modulename}_ADDITIONS This is a bash array containing |
188 |
-# A list of additional things to |
189 |
-# add to the bottom of the file. |
190 |
-# This can be absolutely anything. |
191 |
-# Each entry is a new line. |
192 |
-# MODULES_${modulename}_DOCS This is a string list which contains |
193 |
-# the full path to any associated |
194 |
-# documents for $modulename |
195 |
+# where array_component is "wildcard <modulename>" (see modprobe.conf(5)) |
196 |
+ |
197 |
+# @ECLASS-VARIABLE: MODULESD_<modulename>_ADDITIONS |
198 |
+# @DESCRIPTION: |
199 |
+# This is a bash array containing a list of additional things to |
200 |
+# add to the bottom of the file. This can be absolutely anything. |
201 |
+# Each entry is a new line. |
202 |
+ |
203 |
+# @ECLASS-VARIABLE: MODULESD_<modulename>_DOCS |
204 |
+# @DESCRIPTION: |
205 |
+# This is a string list which contains the full path to any associated |
206 |
+# documents for <modulename>. These files are installed in the live tree. |
207 |
+ |
208 |
+# @ECLASS-VARIABLE: KV_OBJ |
209 |
+# @DESCRIPTION: |
210 |
+# It's a read-only variable. It contains the extension of the kernel modules. |
211 |
|
212 |
# The order of these is important as both of linux-info and eutils contain |
213 |
# set_arch_to_kernel and set_arch_to_portage functions and the ones in eutils |
214 |
@@ -150,6 +183,10 @@ |
215 |
fi |
216 |
} |
217 |
|
218 |
+# @FUNCTION: use_m |
219 |
+# @RETURN: true or false |
220 |
+# @DESCRIPTION: |
221 |
+# It checks if the kernel version is greater than 2.6.5. |
222 |
use_m() { |
223 |
debug-print-function ${FUNCNAME} $* |
224 |
|
225 |
@@ -162,6 +199,10 @@ |
226 |
return 0 || return 1 |
227 |
} |
228 |
|
229 |
+# @FUNCTION: convert_to_m |
230 |
+# @USAGE: /path/to/the/file |
231 |
+# @DESCRIPTION: |
232 |
+# It converts a file (e.g. a makefile) to use M= instead of SUBDIRS= |
233 |
convert_to_m() { |
234 |
debug-print-function ${FUNCNAME} $* |
235 |
|
236 |
@@ -175,6 +216,11 @@ |
237 |
fi |
238 |
} |
239 |
|
240 |
+# internal function |
241 |
+# |
242 |
+# FUNCTION: update_depmod |
243 |
+# DESCRIPTION: |
244 |
+# It updates the modules.dep file for the current kernel. |
245 |
update_depmod() { |
246 |
debug-print-function ${FUNCNAME} $* |
247 |
|
248 |
@@ -195,6 +241,11 @@ |
249 |
fi |
250 |
} |
251 |
|
252 |
+# internal function |
253 |
+# |
254 |
+# FUNCTION: update_modules |
255 |
+# DESCRIPTION: |
256 |
+# It calls the update-modules utility. |
257 |
update_modules() { |
258 |
debug-print-function ${FUNCNAME} $* |
259 |
|
260 |
@@ -211,6 +262,11 @@ |
261 |
fi |
262 |
} |
263 |
|
264 |
+# internal function |
265 |
+# |
266 |
+# FUNCTION: move_old_moduledb |
267 |
+# DESCRIPTION: |
268 |
+# It updates the location of the database used by the module-rebuild utility. |
269 |
move_old_moduledb() { |
270 |
debug-print-function ${FUNCNAME} $* |
271 |
|
272 |
@@ -226,6 +282,11 @@ |
273 |
fi |
274 |
} |
275 |
|
276 |
+# internal function |
277 |
+# |
278 |
+# FUNCTION: update_moduledb |
279 |
+# DESCRIPTION: |
280 |
+# It adds the package to the /var/lib/module-rebuild/moduledb database used by the module-rebuild utility. |
281 |
update_moduledb() { |
282 |
debug-print-function ${FUNCNAME} $* |
283 |
|
284 |
@@ -243,6 +304,12 @@ |
285 |
fi |
286 |
} |
287 |
|
288 |
+# internal function |
289 |
+# |
290 |
+# FUNCTION: remove_moduledb |
291 |
+# DESCRIPTION: |
292 |
+# It removes the package from the /var/lib/module-rebuild/moduledb database used by |
293 |
+# the module-rebuild utility. |
294 |
remove_moduledb() { |
295 |
debug-print-function ${FUNCNAME} $* |
296 |
|
297 |
@@ -255,6 +322,9 @@ |
298 |
fi |
299 |
} |
300 |
|
301 |
+# @FUNCTION: set_kvobj |
302 |
+# @DESCRIPTION: |
303 |
+# It sets the KV_OBJ variable. |
304 |
set_kvobj() { |
305 |
debug-print-function ${FUNCNAME} $* |
306 |
|
307 |
@@ -289,12 +359,21 @@ |
308 |
echo "${kernel_cc}" |
309 |
} |
310 |
|
311 |
+# internal function |
312 |
+# |
313 |
+# FUNCTION: |
314 |
+# USAGE: /path/to/the/modulename_without_extension |
315 |
+# RETURN: A file in /etc/modules.d/ (kernel < 2.6) or /etc/modprobe.d/ (kernel >= 2.6) |
316 |
+# DESCRIPTION: |
317 |
+# This function will generate and install the neccessary modprobe.d/modules.d file from the |
318 |
+# information contained in the modules exported parms. |
319 |
+# (see the variables MODULESD_<modulename>_ENABLED, MODULESD_<modulename>_EXAMPLES, |
320 |
+# MODULESD_<modulename>_ALIASES, MODULESD_<modulename>_ADDITION and MODULESD_<modulename>_DOCS). |
321 |
+# |
322 |
+# At the end the documentation specified with MODULESD_<modulename>_DOCS is installed. |
323 |
generate_modulesd() { |
324 |
debug-print-function ${FUNCNAME} $* |
325 |
|
326 |
- # This function will generate the neccessary modules.d file from the |
327 |
- # information contained in the modules exported parms |
328 |
- |
329 |
local currm_path currm currm_t t myIFS myVAR |
330 |
local module_docs module_enabled module_aliases \ |
331 |
module_additions module_examples module_modinfo module_opts |
332 |
@@ -437,6 +516,13 @@ |
333 |
return 0 |
334 |
} |
335 |
|
336 |
+# internal function |
337 |
+# |
338 |
+# FUNCTION: find_module_params |
339 |
+# USAGE: A string "NAME(LIBDIR:SRCDIR:OBJDIR)" |
340 |
+# RETURN: The string "modulename:NAME libdir:LIBDIR srcdir:SRCDIR objdir:OBJDIR" |
341 |
+# DESCRIPTION: |
342 |
+# Analyze the specification NAME(LIBDIR:SRCDIR:OBJDIR) of one module as described in MODULE_NAMES. |
343 |
find_module_params() { |
344 |
debug-print-function ${FUNCNAME} $* |
345 |
|
346 |
@@ -482,6 +568,11 @@ |
347 |
# default ebuild functions |
348 |
# -------------------------------- |
349 |
|
350 |
+# @FUNCTION: linux-mod_pkg_setup |
351 |
+# @DESCRIPTION: |
352 |
+# It checks the CONFIG_CHECK options (see linux-info.eclass(5)), verifies that the kernel is |
353 |
+# configured, verifies that the sources are prepared, verifies that the modules support is builtin |
354 |
+# in the kernel and sets the object extension KV_OBJ. |
355 |
linux-mod_pkg_setup() { |
356 |
debug-print-function ${FUNCNAME} $* |
357 |
|
358 |
@@ -506,6 +597,14 @@ |
359 |
done |
360 |
} |
361 |
|
362 |
+# @FUNCTION: linux-mod_src_compile |
363 |
+# @DESCRIPTION: |
364 |
+# It compiles all the modules specified in MODULE_NAMES. For each module the econf command is |
365 |
+# executed only if ECONF_PARAMS is defined, the name of the target is specified by BUILD_TARGETS |
366 |
+# while the options are in BUILD_PARAMS (all the modules share these variables). The compilation |
367 |
+# happens inside ${srcdir}. |
368 |
+# |
369 |
+# Look at the description of these variables for more details. |
370 |
linux-mod_src_compile() { |
371 |
debug-print-function ${FUNCNAME} $* |
372 |
|
373 |
@@ -558,6 +657,17 @@ |
374 |
ABI="${myABI}" |
375 |
} |
376 |
|
377 |
+# @FUNCTION: linux-mod_src_install |
378 |
+# @DESCRIPTION: |
379 |
+# It install the modules specified in MODULES_NAME. The modules should be inside the ${objdir} |
380 |
+# directory and they are installed inside /lib/modules/${KV_FULL}/${libdir}. |
381 |
+# |
382 |
+# The modprobe.d/modules.d configuration file is automatically generated if the |
383 |
+# MODULESD_<modulename>_* variables are defined. The only way to stop this process is by |
384 |
+# setting MODULESD_<modulename>_ENABLED=no. At the end the documentation specified via |
385 |
+# MODULESD_<modulename>_DOCS is also installed. |
386 |
+# |
387 |
+# Look at the description of these variables for more details. |
388 |
linux-mod_src_install() { |
389 |
debug-print-function ${FUNCNAME} $* |
390 |
|
391 |
@@ -585,6 +695,9 @@ |
392 |
done |
393 |
} |
394 |
|
395 |
+# @FUNCTION: linux-mod_pkg_preinst |
396 |
+# @DESCRIPTION: |
397 |
+# It checks what to do after having merged the package. |
398 |
linux-mod_pkg_preinst() { |
399 |
debug-print-function ${FUNCNAME} $* |
400 |
|
401 |
@@ -593,6 +706,11 @@ |
402 |
[ -d "${D}lib/modules" ] && UPDATE_MODULEDB=true || UPDATE_MODULEDB=false |
403 |
} |
404 |
|
405 |
+# @FUNCTION: linux-mod_pkg_postinst |
406 |
+# @DESCRIPTION: |
407 |
+# It executes /sbin/depmod and adds the package to the /var/lib/module-rebuild/moduledb |
408 |
+# database (if ${D}/lib/modules is created) and it runs /sbin/update-modules |
409 |
+# (if ${D}/etc/modules.d is created). |
410 |
linux-mod_pkg_postinst() { |
411 |
debug-print-function ${FUNCNAME} $* |
412 |
|
413 |
@@ -601,6 +719,10 @@ |
414 |
${UPDATE_MODULEDB} && update_moduledb; |
415 |
} |
416 |
|
417 |
+# @FUNCTION: linux-mod_pkg_postrm |
418 |
+# @DESCRIPTION: |
419 |
+# It removes the package from the /var/lib/module-rebuild/moduledb database but it doens't |
420 |
+# call /sbin/depmod and /sbin/update-modules because the modules are still installed. |
421 |
linux-mod_pkg_postrm() { |
422 |
debug-print-function ${FUNCNAME} $* |
423 |
remove_moduledb; |