/[gentoo]/xml/htdocs/doc/en/genkernel.xml
Gentoo

Diff of /xml/htdocs/doc/en/genkernel.xml

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

Revision 1.3 Revision 1.19
1<?xml version='1.0' encoding="UTF-8"?> 1<?xml version='1.0' encoding="UTF-8"?>
2<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/genkernel.xml,v 1.19 2005/07/28 12:40:47 jkt Exp $ -->
2<!DOCTYPE guide SYSTEM "/dtd/guide.dtd"> 3<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
3 4
4<guide link="/doc/en/xml-guide.xml"> 5<guide link="/doc/en/genkernel.xml">
5<title>Gentoo Linux Genkernel Guide</title> 6<title>Gentoo Linux Genkernel Guide</title>
6 7
7<author title="Author"> 8<author title="Author">
8 <mail link="plasmaroo@gentoo.org">Tim Yamin</mail> 9 <mail link="plasmaroo@gentoo.org">Tim Yamin</mail>
9</author> 10</author>
10 11
12<!-- folajimi@speakeasy.net -->
13<author title="Contributor">
14 Jimi Ayodele
15</author>
16
17<!-- thseiler@gmail.com -->
18<author title="NFS Support">
19 Thomas Seiler
20</author>
21
11<abstract> 22<abstract>
12This guide intends to provide a reference of all the functions 23This guide intends to provide a reference of all the functions provided by
13provided by Genkernel. 24genkernel.
14</abstract> 25</abstract>
15 26
27<license/>
28
16<version>1.0</version> 29<version>1.3</version>
17<date>February 15, 2003</date> 30<date>2005-07-24</date>
18 31
19<chapter> 32<chapter>
20<title>Introduction</title> 33<title>Introduction</title>
21<section> 34<section>
22<title>Introduction</title> 35<title>Rationale</title>
23<body>
24
25<p>
26Genkernel is designed to allow users who are not previously used to
27compiling a kernel to use a similar setup to that one that is used on
28the Gentoo LiveCDs which auto-detects your hardware.
29</p>
30
31<p>
32Some users may also be interested in using genkernel for hardware
33which requires initialization and a working kernel before it can be
34booted. Because genkernel also automatically compiles your kernel modules,
35thus allowing hardware which needs to be loaded with module parameters
36to be used.
37</p>
38
39</body> 36<body>
40</section> 37
38<p>
39For users who are not privy to kernel compilation, genkernel is a tool to
40automate this process. It can help you create a kernel image akin to those
41available on Gentoo Installation CDs, which are designed to auto-detect the
42hardware configuration of your system. Some users may also be interested in
43using genkernel for hardware requiring initialization and a working kernel
44before the system starts up. Since genkernel automatically compiles your kernel
45modules, you can use hardware that may require certain module parameters to be
46loaded for proper operation.
47</p>
48
49</body>
41<section> 50</section>
42<title>Is genkernel for me?</title>
43<body>
44 51
45<p>
46Genkernel is often a good choice to those who are unused to compiling
47their own kernel or those who are not certain about their hardware
48configurations.
49</p>
50
51<p>
52Because genkernel is designed to use a generic configuration, it
53should be able to support all of your hardware - however, because all
54the drivers and modules have to be compiled as well, compiling a
55kernel by yourself is often much faster provided you know what you need.
56</p>
57
58<p>
59Genkernel does not however, currently support booting the sytem from
60LVM2/EVMS2 partitions. Users are recommended to use a manually compiled
61kernel for the time being.
62</p>
63
64</body>
65</section> 52<section>
53<title>Target Audience</title>
54<body>
55
56<p>
57If you are either uncertain about how to compile a kernel, or are just
58unfamiliar with your hardware configuration, genkernel is a very handy tool.
59It is designed to take the pain out of the kernel compiling process, and
60supports most hardware by default.
61</p>
62
63<p>
64However, if you know what drivers are required by your system, you may be able
65to further reduce the time taken to compile the kernel. This is possible since
66you can direct genkernel to only build drivers relevant to your hardware.
67Oftentimes, the number of drivers required by your system will be fewer
68(implying a shorter kernel compilation time) than the default configuration
69provides.
70</p>
71
72</body>
66<section> 73</section>
67<title>Getting genkernel</title>
68<body>
69
70<p>
71You can obtain genkernel by simply running <c>emerge genkernel</c>. Don't
72forget to use the <c>-k</c> flag for emerge if you are using binary packages,
73i.e. GRP. Due to the GRP packages having an older version of genkernel, the
74flags are different. As a result, you should consult the <uri
75link="http://www.gentoo.org/doc/en/handbook/handbook-x86.xml?part=1&amp;chap=9">
76Gentoo Handbook</uri> and <path>genkernel --help</path>.
77</p>
78
79</body>
80</section> 74<section>
81<section> 75<title>Installing genkernel</title>
82<title>Supported platforms</title>
83<body> 76<body>
84 77
85<p>
86As of genkernel 3.0.1_beta12; the following platforms should be
87supported: alpha, amd64, parisc, parisc64, ppc, sparc, sparc64, and x86. If
88you believe that there is a bug with the support code, and not with
89genkernel, please file a bug at the <uri
90link="http://bugs.gentoo.org">Gentoo Bugzilla.</uri>
91</p> 78<p>
92 79To obtain genkernel, run <c>emerge genkernel</c> from the command line. If you
80are using the
81<uri link="http://www.gentoo.org/doc/en/handbook/2005.0/hb-install-about.xml#doc_chap2_sect1">
82Gentoo Reference Platform</uri> (GRP), remember to install binary packages by
83passing the <c>-k</c> flag to emerge. Since the GRP is bundled with an older
84version of genkernel, the flags may be different. In any case, consult
85<c>genkernel --help</c> for help on how to use the version of genkernel
86installed on your system.
87</p>
88
93</body> 89</body>
94</section> 90</section>
95</chapter> 91</chapter>
96 92
97<chapter> 93<chapter>
98<title>Genkernel usage</title> 94<title>Working with genkernel</title>
99<section>
100<title>Introduction</title>
101<body>
102
103<p>
104Genkernel is designed to work in three modes:
105</p>
106
107<ul>
108 <li>"all" mode: this builds the kernel and the initrd</li>
109 <li>"kernel" mode: this only builds the kernel image</li>
110 <li>"initrd" mode: this only builds the initrd</li>
111</ul>
112
113<p>
114Most users will only want the "all" mode, which runs the "kernel" mode
115and the "initrd" mode for you. <b>Note</b> that the "kernel" and "initrd"
116modes are currently just aliases for the "all" mode, so they will
117currently give you no special effect.
118</p>
119
120<p>
121Although genkernel is mainly a command to make your life easier when
122you need to compile a kernel, genkernel is also packed full of
123different flags which allow you to customize how your kernel is
124compiled or configured.
125</p>
126
127</body>
128</section> 95<section>
96<title>How to use genkernel</title>
97<body>
98
99<p>
100Although there are several ways to run genkernel, the least-intrusive approach
101is provided by <c>genkernel all</c>. Here, a generic configuration which works
102well for most systems is used. As was mentioned earlier, this approach is not
103without drawbacks; most of the modules created are useless to the average user
104and may increase compile time. Below is an illustration of a more efficient
105approach, achieved by passing certain flags to genkernel as root:
106</p>
107
108<pre caption="Running genkernel (with flags)">
109# genkernel --bootsplash --no-install --no-clean --menuconfig all
110</pre>
111
112<p>
113The above operation causes genkernel to create a bootsplash-enabled kernel
114(<c>--bootsplash</c>) that will have to be manually installed
115(<c>--no-install</c>). While preparing the kernel source tree, genkernel will
116refrain from cleaning out any preexisting object files present in the source
117tree (<c>--no-clean</c>). A menu-driven kernel configuration utility will be
118displayed that allows the user to select which modules will be built for the
119system (<c>--menuconfig</c>).
120</p>
121
122<p>
123There are other flags which alter the result provided by genkernel. For
124instance, replacing <c>--no install</c> with the <c>--install</c> flag allows
125genkernel to automatically install the new kernel in the <path>/boot</path>
126directory. Using the <c>--mountboot</c> flag allows genkernel to mount your
127<path>/boot</path> partition automatically, if necessary.
128</p>
129
130<p>
131Remember, genkernel is designed to make kernel compilation easy and
132stress-free. For this reason, genkernel features several flags to ease the
133kernel compilation effort. For example, there are flags to help with kernel
134configuration, while others affect the actual compilation. Some flags even help
135debug the compilation process. For those interested in further optimization,
136there are flags that affect kernel assembling, packaging and even kernel
137initialization.
138</p>
139
140<p>
141The rest of this chapter examines the functionality of various flags and
142actions available for genkernel. Some of the flags have variants which perform
143a converse operation. The converse variants carry the <b><c>no-</c></b> prefix,
144and their effects are enclosed within the square brackets, [].
145</p>
146
147</body>
129<section> 148</section>
130<title>Genkernel compiler flags</title> 149
150<section>
151<title>Configuration Flags</title>
152<body>
153
154<p>
155The configuration flags listed below exist to help you decide what features
156should be enabled or disabled in the kernel prior to compilation. You can even
157choose whether or not the configuration file created in the process should be
158saved. The following are the primary configuration flags:
159</p>
160
161<ul>
162 <li>
163 <b>--<c>no-</c>menuconfig</b>: Activates <e>[or deactivates]</e> the
164 <c>make menuconfig</c> command (which invokes an interactive, menu-based
165 kernel configuration utility), before building the kernel.
166 </li>
167 <li>
168 <b>--gconfig</b>: Provides a kernel configuration utility which depends
169 on the GTK+ libraries. The advantage of this option is that most users
170 find it easier and clearer to configure the kernel using this tool, since
171 it relies on the X-windowing system. The disadvantage of this option is
172 that you <b>need</b> the X-windowing system to use it, so it will not
173 work on the command line.
174 </li>
175 <li>
176 <b>--xconfig</b>: Provides a kernel configuration utility which depends
177 on the QT libraries. The advantage of this option is that most users find
178 it easier and clearer to configure the kernel using this tool, since it
179 relies on the X-windowing system. The disadvantage of this option is that
180 you <b>need</b> the X-windowing system to use it, so it will not work on
181 the command line.
182 </li>
183 <li>
184 <b>--<c>no-</c>save-config</b>: Saves [or does not save] the kernel
185 configuration to a file in the <path>/etc/kernels/</path> directory for
186 later use.
187 </li>
188</ul>
189
131<body> 190</body>
191</section>
132 192
193<section>
194<title>Compilation Flags</title>
195<body>
196
133<p> 197<p>
134Genkernel supports the following flags which are passed to the 198The following flags usually take effect during the actual compilation:
135relevant applications when your kernel is assembled:
136</p> 199</p>
137 200
138<ul> 201<ul>
139 <li> 202 <li>
140 <b>--kernel-as=<c>someAssembler</c></b>: This specifies an assembler which 203 <b>--kerneldir=<path>/path/to/sources/</path></b>: Specifies an
141 would be used for compiling your kernel. 204 alternative kernel source location, rather than the default
205 <path>/usr/src/linux/</path> location.
142 </li> 206 </li>
143 <li> 207 <li>
144 <b>--kernel-cc=<c>someCompiler</c></b>: This specifies a compiler which 208 <b>--kernel-config=<path>/path/to/config-file</path></b>: Specifies what
145 would be used for compiling your kernel. 209 alternative kernel configuration will be used, rather than the default
210 <path>/path/to/sources/.config</path> file.
146 </li> 211 </li>
147 <li> 212 <li>
148 <b>--kernel-ld=<c>someLinker</c></b>: This specifies a linker which would 213 <b>--module-prefix=<path>/path/to/prefix-directory/</path></b>: Specifies
149 be used for compiling your kernel. 214 a prefix to the directory where kernel modules will be installed (default
215 path is the <path>/lib/modules/</path> directory.)
216 </li>
217</ul>
218
219<ul>
220 <li>
221 <b>--<c>no-</c>clean</b>: Activates <e>[or deactivates]</e> the
222 <c>make clean</c> command before compiling your kernel. The
223 <c>make clean</c> command removes all object files and dependencies from
224 the kernel's source tree.
150 </li> 225 </li>
151 <li> 226 <li>
152 <b>--kernel-make=<c>someMake</c></b>: This specifies an alternate GNU Make 227 <b>--<c>no-</c>mrproper</b>: Activates <e>[or deactivates]</e> the
153 which would be used for compiling your kernel. 228 <c>make mrproper</c> command before kernel compilation. Like the
154 </li> 229 <c>make clean</c> command, <c>make mrproper</c> removes all object files
155</ul> 230 and dependencies from the kernel's source tree. However, any previous
156 231 configuration files (in <path>/path/to/sources/.config</path> or
157<ul> 232 <path>/path/to/sources/.config.old</path>) will <b>also</b> be purged
158 <li> 233 from the kernel's source tree.
159 <b>--utils-as=<c>someAssembler</c></b>: This specifies an assembler which
160 would be used for compiling the support utilities.
161 </li> 234 </li>
162 <li> 235 <li>
163 <b>--utils-cc=<c>someCompiler</c></b>: This specifies a compiler which 236 <b>--oldconfig</b>: Issues the <c>make oldconfig</c> command, which
164 would be used for compiling the support utilities. 237 attempts to collect configuration information for the system's
238 architecture from a generic script in <path>/usr/share/genkernel/</path>.
239 This is a non-interactive process; no user input is entertained. Also, if
240 <c>--oldconfig</c> is used in conjunction with <c>--clean</c>, the latter
241 flag is negated, resulting in the activation of the <c>--no-clean</c>
242 flag.
165 </li> 243 </li>
244</ul>
245
246<ul>
166 <li> 247 <li>
167 <b>--utils-ld=<c>someLinker</c></b>: This specifies a linker which would be 248 <b>--callback="<c>echo hello</c>"</b>: Calls the specified arguments
168 used for compiling the support utilities. 249 (<c>echo hello</c>, in this case) after the kernel and the relevant
250 modules have been built, but before building the initrd image. This may
251 be useful if you want to install external modules in the initrd image by
252 emerging the relevant item(s) with the callback feature, and then
253 redefining a genkernel module group.
169 </li> 254 </li>
255</ul>
256
257<ul>
170 <li> 258 <li>
171 <b>--utils-make=<c>someMake</c></b>: This specifies an alternate GNU Make 259 <b>--<c>no-</c>install</b>: Activates <e>[or deactivates]</e> the
172 which would be used for compiling the support utilities. 260 <c>make install</c> command, which installs your new kernel image,
261 configuration file, initrd image and system map onto your mounted boot
262 partition. Any compiled modules will be installed as well.
173 </li> 263 </li>
174</ul>
175
176<ul>
177 <li> 264 <li>
178 <b>--makeopts=<c>-jJobs</c></b>: This specifies the flags which would be 265 <b>--<c>no-</c>initrdmodules</b>: Refrains from copying any modules to
179 passed to GNU Make when the kernel and utilities are being compiled. 266 the genkernel-created initrd image. This flag is an exception to the rule
267 about the <c>no-</c> prefix; omission of this prefix creates an invalid
268 genkernel flag.
180 </li> 269 </li>
270 <li>
271 <b>--genzimage</b>: Creates the initrd image, prior to the kernel image.
272 (This hack currently applies only to PPC Pegasos systems.)
273 </li>
181</ul> 274</ul>
182 275
183</body> 276</body>
184</section>
185<section> 277</section>
186<title>Genkernel kernel flags</title>
187<body>
188 278
189<p>
190Genkernel supports the following flags, some of which have
191<c>--<b>no-</b>option</c> equivalents that influence
192kernel compilation:
193</p>
194
195<ul>
196 <li>
197 <b>--clean</b>: This runs a <c>make clean</c> before compiling your
198 kernel. This causes all object files and dependencies to be removed.
199 </li>
200 <li>
201 <b>--mrproper</b>: This runs a <c>make mrproper</c> before compiling your
202 kernel. This causes all object files, dependencies <e>and your
203 configuration</e> to be removed.
204 </li>
205</ul>
206
207<ul>
208 <li>
209 <b>--kerneldir=<path>/path/to/sources</path></b>: This specifies an
210 alternative kernel source location, instead of the default location of
211 <path>/usr/src/linux</path>.
212 </li>
213 <li>
214 <b>--kernel-config=<path>/path/to/config-file</path></b>: This specifies an
215 alternative kernel configuration which would be used; rather than the
216 inpersistant <path>/path/to/sources/.config</path> which is used by
217 default.
218 </li>
219</ul>
220
221<ul>
222 <li>
223 <b>--<c>no-</c>bootsplash</b>: This adds <e>or does not add</e> bootsplash
224 support in the initrd which genkernel builds. Not all architectures
225 currently support bootsplash, and a kernel that supports bootsplash is
226 also required.
227 </li>
228 <li>
229 <b>--<c>no-</c>menuconfig</b>: This runs <e>or does not run</e> the kernel
230 menu-based configurator before building your kernel, after <c>make
231 oldconfig</c> has ran.
232 </li>
233</ul>
234
235<ul>
236 <li>
237 <b>--no-initrdmodules</b>: This doesn't copy any modules to the initrd
238 which genkernel creates.
239 </li>
240 <li>
241 <b>--<c>no-</c>install</b>: This installs <e>or does not install</e> your
242 kernel, modules, and initrd one the compilation has finished.
243 </li>
244</ul>
245
246</body>
247</section> 279<section>
280<title>Compiler Flags</title>
281<body>
282
283<p>
284The following flags are supported by genkernel, and are passed to the relevant
285applications while the kernel is being assembled. These flags affect the
286<e>compiler</e> used for the kernel compilation process, albeit at a much lower
287level.
288</p>
289
290<ul>
291 <li>
292 <b>--kernel-cc=<c>someCompiler</c></b>: Specifies the compiler employed
293 during the kernel compilation process.
294 </li>
295 <li>
296 <b>--kernel-ld=<c>someLinker</c></b>: Specifies the linker employed
297 during the kernel compilation process.
298 </li>
299 <li>
300 <b>--kernel-as=<c>someAssembler</c></b>: Specifies the assembler employed
301 during the kernel compilation process.
302 </li>
303 <li>
304 <b>--kernel-make=<c>someMake</c></b>: Specifies an alternative to the
305 <e>GNU make</e> utility employed during the kernel compilation process.
306 </li>
307</ul>
308
309<ul>
310 <li>
311 <b>--utils-cc=<c>someCompiler</c></b>: Specifies the compiler employed
312 during the compilation of support utilities.
313 </li>
314 <li>
315 <b>--utils-ld=<c>someLinker</c></b>: Specifies the linker employed during
316 the compilation of support utilities.
317 </li>
318 <li>
319 <b>--utils-as=<c>someAssembler</c></b>: Specifies the assembler employed
320 during the compilation of support utilities.
321 </li>
322 <li>
323 <b>--utils-make=<c>someMake</c></b>: Specifies an alternative to the
324 <e>GNU make</e> utility employed during the compilation of support
325 utilities.
326 </li>
327</ul>
328
329<ul>
330 <li>
331 <b>--makeopts=<c>-jX</c></b>: Specifies the number of concurrent threads
332 that the make utility can implement while the kernel (and utilities) are
333 being compiled. The variable <b>'X'</b> is a number obtained by adding
334 one (1) to the number of CPUs used by the system. So, for a system with
335 one CPU, the appropriate flag is <c>-j2</c>; a system with two CPUs will
336 use the <c>-j3</c> flag, and so on. <e>(A system with one processor that
337 supports Hyper-Threading&#8482; (HT) Technology can use the</e><c>-j3</c>
338 <e>flag, provided Symmetric Multi-Processing (SMP) support is enabled in
339 the kernel.)</e>
340 </li>
341</ul>
342
343</body>
248<section> 344</section>
249<title>Genkernel miscellaenous flags</title>
250<body>
251 345
252<p>
253Genkernel also supports some miscellaneous flags which do not fit into
254the other two categories:
255</p>
256
257<ul>
258 <li>
259 <b>--arch-override=<c>someArch</c></b>: This flag can be used to override
260 what architecture genkernel thinks you're on, if the auto-detection
261 mechanism fails (please file a bug if it does!) or if you wish to
262 cross-compile a kernel.
263 </li>
264</ul>
265
266<ul>
267 <li>
268 <b>--busybox-config=<path>/path/to/busybox-config</path></b>: This
269 overrides the default busybox configuration with the specifid file
270 </li>
271 <li>
272 <b>--busybox-bin=<path>/path/to/busybox-binary.tar.bz2</path></b>: Using
273 this option means that a busybox binary would not be compiled, and the
274 specified tarball would be used. Note that busybox <e>must</e> be compiled
275 statically!
276 </li>
277</ul>
278
279<ul>
280 <li>
281 <b>--minkernpackage=<path>/output/to/yourkernel.tar.bz2</path></b>: This
282 flag outputs a tarball of the kernel, named as <path>kernel</path> and the
283 initrd named as <path>initrd</path> to the specified file. No path
284 information or modules will be includes in the tarball.
285 </li>
286</ul>
287
288</body>
289</section> 346<section>
347<title>Debugging Flags</title>
348<body>
349
350<p>
351The use debugging flags during the kernel compilation process controls the
352amount of information reported, as well as the presentation of said data.
353</p>
354
355<ul>
356 <li>
357 <b>--debuglevel=<c>verblevel</c></b>: Controls the level of
358 verbosity for information provided by genkernel. The variable
359 <c>verblevel</c> is an integer between 0 and 5. The level '0' represents
360 minimal output, while '5' provides as much information as possible about
361 genkernel's activities during the kernel compilation process.
362 </li>
363 <li>
364 <b>--debugfile=<path>/path/to/outputfile</path></b>: Ignores the value
365 set by the <c>--debuglevel</c> argument, and sends <b>all</b> debugging
366 data produced by genkernel to the specified output file, which is located
367 at <path>/var/log/genkernel.log</path> by default.
368 </li>
369 <li>
370 <b>--no-color</b>: Activates [or deactivates] colored output of debugging
371 information (reported by genkernel) using escape sequences.
372 </li>
373</ul>
374
375</body>
290<section> 376</section>
291<title>Running genkernel</title>
292<body>
293 377
294<p>
295All that is needed to run genkernel is just genkernel with the
296necessary flags as root. For example:
297</p>
298
299<pre caption="Running genkernel">
300# genkernel --menuconfig --no-clean --no-install --bootsplash
301<comment>(Would produce a kernel, asking you what how to configure it
302to your desire, leaving alone any compiled object files, enabling
303bootsplash support but not installing anything.)</comment>
304</pre>
305
306<p>
307If you want genkernel to install your kernel as well, you must ensure
308that your <path>/boot</path> partition is mounted:
309</p>
310
311<pre caption="Mounting your /boot">
312<comment>(If /boot is a valid entry in /etc/fstab:)</comment>
313# mount /boot
314<comment>(... otherwise for IDE disks:)</comment>
315# mount /dev/hda1 /boot
316<comment>(... and for SCSI disks:)</comment>
317# mount /dev/sda1 /boot
318</pre>
319
320</body>
321</section> 378<section>
379<title>Initialization Flags</title>
380<body>
381
382<p>
383The flags here are used to create certain effects during system startup. Some
384of these flags are primarily for aesthetics, while others may be essential for
385enabling certain features on the system.
386</p>
387
388<ul>
389 <li>
390 <b>--<c>no-</c>bootsplash</b>: Activates <e>[or deactivates]</e> support
391 for <uri link="http://www.bootsplash.org/">bootsplash</uri> in the
392 genkernel-built initrd image. The bootsplash feature is supported on a
393 limited number of architectures, and a kernel that supports bootsplash
394 is also required.
395 </li>
396 <li>
397 <b>--<c>no-</c>gensplash</b>: Activates <e>[or deactivates]</e> support
398 for <uri link="http://dev.gentoo.org/~spock/projects/gensplash/">gensplash</uri>
399 support in the genkernel-built initrd image. The gensplash utility is
400 intended to be a replacement for bootsplash, and is designed for use with
401 2.6.x series kernels. To override the default theme used by gensplash,
402 use <b>--gensplash=<c>PreferredTheme</c></b> (where <c>PreferredTheme</c>
403 is the title of one of the directories inside the
404 <path>/etc/splash/</path> directory.
405 </li>
406 <li>
407 <b>--gensplash-res=<c>PreferredResolution</c></b>: This flag allows you
408 to select which splash screen resolutions will be supported in the initrd
409 during the start-up of the system. This is useful for two reasons: First,
410 you are able to select only the splash screen resolution(s) relevant to
411 your system. Second, you avoid the unnecessary increase in the disk space
412 required by initrd (since the initrd does not have to support resolutions
413 that are irrelevant for your system configuration.) However, you may want
414 to omit this flag if the kernel is being compiled for an Installation CD;
415 this allows gensplash support for all possible resolutions.
416 </li>
417 <li>
418 <b>--do-keymap-auto</b>: Force keymap selection during the boot
419 sequence.
420 </li>
421 <li>
422 <b>--lvm2</b>: Includes support for storage using via <uri
423 link="http://sources.redhat.com/lvm2/">Logical Volume Management</uri>
424 (LVM2) from <e>static</e> binaries, if available to the system. Relevant
425 (static) LVM2 binaries are compiled if they are unavailable. Be sure to
426 install the lvm2 package on your system with <c>emerge lvm2</c> before
427 enabling this flag, and review the <uri
428 link="http://www.gentoo.org/doc/en/lvm2.xml">Gentoo LVM2
429 Installation</uri> guide.
430 </li>
431 <li>
432 <b>--evms2</b>: Includes support for storage using the <uri
433 link="http://evms.sourceforge.net/">Enterprise Volume Management
434 System</uri> (EVMS2), if available. Be sure to install the evms package
435 on your system with <c>USE=static emerge evms2</c> before using this
436 (genkernel) flag. <e>(Omitting the </e><c>USE=static</c> <e>flag during
437 package installation will fail to include the necessary static binaries.)
438 </e>
439 </li>
440 <li>
441 <b>--dmraid</b>: Includes support for <uri
442 link="http://people.redhat.com/~heinzm/sw/dmraid/readme">DMRAID</uri>;
443 the utility which creates RAID mappings using the kernel device-mapper
444 subsystem. DMRAID discovers, activates, deactivates and displays
445 properties of software RAID sets (ATARAID, for example) and contained
446 DOS partitions.
447 </li>
448 <li>
449 <b>--linuxrc=/path/to/your/linuxrc</b>: Specifies a user-created
450 <e>linuxrc</e> &#8212; a script that is initialized during the start-up
451 stage of the kernel, prior to the actual boot process. (A default linuxrc
452 script should be in the <path>/usr/share/genkernel/</path> directory.)
453 This script allows you to boot into a small, modularized kernel and load
454 the drivers that are needed (as modules) by the system.
455 </li>
456 <li>
457 <b>--cachedir=/path/to/alt/dir/</b>: Overrides the default cache location
458 used while compiling the kernel.
459 </li>
460 <li>
461 <b>--tempdir=/path/to/new/tempdir/</b>: Specifies the location of the
462 temporary directory used by genkernel while compiling the kernel.
463 </li>
464 <li>
465 <b>--unionfs</b>: Includes support for the <uri
466 link="http://www.fsl.cs.sunysb.edu/project-unionfs.html">Unification File
467 System</uri> in the initrd image.
468 </li>
469</ul>
470
471</body>
322<section> 472</section>
323<title>Setting up genkernel to work with your bootloader</title> 473
474<section>
475<title>Miscellaneous Flags</title>
476<body>
477
478<p>
479The assortment of flags listed below are supported by genkernel, but do not fit
480neatly into any of the other categories:
481</p>
482
483<ul>
484 <li>
485 <b>--mountboot</b>: Detects whether or not the <path>/boot/</path>
486 directory needs to be mounted on a separate partition. It will check
487 <path>/etc/fstab</path> script for instructions on how to mount the boot
488 partition on a file system (if needed).
489 </li>
490 <li>
491 <b>--kernname=<c>NickName</c></b>: Allows you to modify the name of the
492 kernel and initrd images in the <path>/boot/</path> directory, so that
493 the images produced are kernel-<c>NickName</c>-version and
494 initramfs-<c>NickName</c>-version.
495 </li>
496</ul>
497
324<body> 498</body>
499</section>
325 500
501
502<section>
503<title>Possible Actions</title>
504<body>
505
506<p>
507An action tells genkernel what to build. Currently, the following actions are
508supported:
326<p> 509</p>
510
511<ul>
512 <li><c>initrd</c>: Only builds the initrd image</li>
513 <li><c>bzImage</c>: Only builds the kernel image</li>
514 <li><c>kernel</c>: Only builds the kernel image and modules</li>
515 <li><c>all</c>: Builds all stages &#8212; the initrd, kernel image and
516 modules.</li>
517</ul>
518
519<p>
520The last action, <c>all</c>, is recommended for most users since it builds the
521stages required for a functional kernel. Remember, an <e>action</e> simply
522tells genkernel what to <e>build</e>, not <e>install</e>.
523</p>
524
525</body>
526</section>
527
528
529<section>
530<title>Bootloader Configuration</title>
531<body>
532
533<p>
327To set up genkernel to work with your bootloader, three or four changes are 534To set up genkernel to work with your bootloader, three or four changes should
328required to your bootloader configuration. 535to the bootloader's configuration file:
329</p> 536</p>
330 537
331<ol> 538<ol>
332 <li> 539 <li>
333 Add <c>root=/dev/ram0</c> and <c>init=/linuxrc</c> to the 540 Add <c>root=/dev/ram0</c> and <c>init=/linuxrc</c> to the kernel
334 kernel parameters passed to the kernel image. 541 parameters passed to the kernel image.
335 </li> 542 </li>
336 <li> 543 <li>
337 Add <c>real_root=/dev/hda3</c>, for example, to the kernel parameters 544 Add <c>real_root=/dev/hda3</c>, for example, to the kernel parameters
338 passed to the kernel image if <path>/dev/hda3</path> contains your root 545 passed to the kernel image, if <path>/dev/hda3</path> contains your root
339 partition. 546 partition.
340 </li> 547 </li>
341 <li> 548 <li>
342 If you are using bootsplash, add a suitable modeline such as 549 If you are using bootsplash, add a suitable mode line such as
343 <c>vga=0x317</c> to the parameters passed to the kernel and also add 550 <c>vga=0x317</c> to the parameters passed to the kernel and also add
344 <c>splash=verbose</c> or <c>splash=silent</c> depending on the verboseness 551 <c>splash=verbose</c> or <c>splash=silent</c> depending on the
345 you require from your bootsplash. 552 verboseness you require from your bootloader.
346 </li> 553 </li>
347 <li> 554 <li>
348 Add the initrd according to how your bootloader requires it: see the <uri 555 Add the initrd information as required by the bootloader. Consult the
349 link="http://www.gentoo.org/doc/en/handbook/handbook-x86.xml?part=1&amp;chap=9">Gentoo 556 <uri link="/doc/en/handbook/handbook-x86.xml?part=1&amp;chap=10">
350 Handbook</uri> for details on how you would do it for your bootloader. 557 Bootloader Configuration Chapter</uri> of the Gentoo Handbook for details
558 on how to make your bootloader initrd-aware.
351 </li> 559 </li>
352</ol> 560</ol>
353 561
354</body> 562</body>
355</section> 563</section>
564
356</chapter> 565</chapter>
357 566
358<chapter> 567<chapter>
359<title>Porting genkernel</title> 568<title>Configuration Options</title>
360<section>
361<title>Introduction</title>
362<body>
363 569
364<p>
365Provided your architecture has all the required libraries and utilties
366which genkernel requires, which includes but it not limited to a
367working kernel for your architecture, working compiler suite, GNU
368Make, and a working busybox distribution, you're all set to go!
369</p>
370
371<p>
372For each architecture, genkernel uses
373<path>/usr/share/genkernel/archName</path> for configuration files for
374that architecture.
375</p>
376
377</body>
378</section> 570<section>
571<title>Editing /etc/genkernel.conf</title>
572<body>
573
574<p>
575Passing flags to genkernel from the command line can be cumbersome, especially
576if you have about a dozen flags:
577</p>
578
579<pre caption="Running genkernel (overloaded with flags)">
580# genkernel --debuglevel=5 --no-color --no-mrproper --clean --gensplash\
581--kerneldir=/path/to/alternate/kernel/sources --install --menuconfig --udev\
582--kernel-config=/path/to/preferred/configfile --save-config --mountboot all
583</pre>
584
585<p>Fortunately, there is a configuration file where most of the basic options
586can be set (or changed) as necessary. What follows is a rundown of the more
587relevant options:
588</p>
589
590<ul>
591 <li>
592 <b>MENUCONFIG=<c>[yes|no]</c></b>: This option is equivalent to the
593 <c>--menuconfig</c> flag used by genkernel, which in turn uses the
594 <c>make menuconfig</c> command to invoke a command-line based kernel
595 configuration utility. To invoke the utility automatically during kernel
596 configuration via this script, set this option to 'yes' here; otherwise,
597 choose 'no'.
598 </li>
599 <li>
600 <b>CLEAN=<c>[yes|no]</c></b>: Setting this option to 'yes' is equivalent
601 to the <c>--clean</c> flag used by genkernel, and invokes the
602 <c>make clean</c> command to remove all object files and dependencies
603 from the kernel's source tree. Setting this option to 'no' creates a
604 cascade effect &#8212; it is equivalent to genkernel's <c>--no-clean</c>
605 flag, which disables the <c>make clean</c> command and implies
606 genkernel's <c>--no-mrproper</c> flag &#8212; essentially nullifying the
607 <c>make mrproper</c> command.
608 </li>
609 <li>
610 <b>MRPROPER=<c>[yes|no]</c></b>: Setting this option to 'yes' is
611 equivalent to <c>--mrproper</c> flag used by genkernel, and invokes the
612 <c>make mrproper</c> command, which purges the kernel source tree of any
613 configuration files. Selecting 'no' here is equivalent to genkernel's
614 <c>--no-mrproper</c> flag, which disables the <c>make mrproper</c>
615 command.
616 </li>
617 <li>
618 <b>MOUNTBOOT=<c>[yes|no]</c></b>: Setting this option to 'yes' is
619 equivalent to the <c>--mountboot</c> flag, and automatically mounts the
620 <path>/boot/</path> directory (if needed) at compile time. If the
621 <path>/boot/</path> directory is on a separate partition, consider
622 enabling this option; it will make for one less (essential) step to
623 remember later.
624 </li>
625 <li>
626 <b>SAVE_CONFIG=<c>[yes|no]</c></b>: After configuring the kernel, the
627 selected options are stored as <path>.config</path> in the kernel source
628 tree. This script may be overwritten during the next kernel compilation,
629 or even purged from the kernel source tree. Choosing 'yes' here is
630 equivalent to the <c>--save-config</c> flag, and stores all options
631 selected during kernel configuration as a script in the
632 <path>/etc/kernels/</path> directory. Choosing 'no' preserves the
633 <e>status quo</e>.
634 </li>
635 <li>
636 <b>USECOLOR=<c>[yes|no]</c></b>: Setting this option to 'yes' is
637 equivalent to the <c>--color</c> flag, which colors genkernel's output
638 to ease debugging (when needed.)
639 </li>
640 <li>
641 <b>DEBUGLEVEL=<c>[0|1|2|3|4|5]</c></b>: This option is for adjusting the
642 verbosity of the output produced by genkernel &#8212; setting this option
643 to '0' with <c>--debuglevel=0</c> will suppress all output produced by
644 genkernel; setting this option to '5' with <c>--debuglevel=5</c>
645 provides the user with all output produced by genkernel.
646 </li>
647</ul>
648
649<p>
650By choosing the appropriate options in <path>/etc/genkernel.conf</path>, you
651can halve the number of flags passed to genkernel from the command line:
652</p>
653
654<pre caption="Running genkernel (with flags), after employing genkernel.conf">
655# genkernel --gensplash --kerneldir=/path/to/alternate/kernel/sources --udev\
656--kernel-config=/path/to/preferred/configfile --install all
657</pre>
658
659<p>
660Identical results are obtained from both approaches, but the latter has most of
661the options stored in a script that can be modified at a later date.
662</p>
663
664</body>
379<section> 665</section>
380<title>How the system bootstrapping works</title>
381<body>
382 666
383<ol>
384 <li>
385 The bootloader loads the genkernel image, built to the specification of the
386 configuration files in the genkernel directories as well as the initrd
387 which is prepared by genkernel.
388 </li>
389 <li>
390 The kernel boots up, allocates a small amount of RAM in which busybox is
391 initialized, which probes the system with the modules in the modules_load
392 list for the architecture.
393 </li>
394 <li>
395 Once done, and providing that the <c>real_root</c> parameter which is the
396 root boot device as busybox sees things is found, the system is booted from
397 the device.
398 </li>
399</ol>
400
401</body>
402</section>
403<section>
404<title>The configuration files</title>
405<body>
406
407<ul>
408 <li>
409 <path>busy-config</path>: This is the configuration which is used to build
410 busybox for your architecture.
411 </li>
412 <li>
413 <path>config.sh</path>: This is a shell script which sets various internal
414 genkernel variables. See one of the <path>config.sh</path> files for an
415 example.
416 </li>
417 <li>
418 <path>modules_load</path>: This is a file containing a space-delimited list
419 of modules which are loaded for SCSI, FireWire, ATARAID and PCMCIA support.
420 If none are available for your platform, leave the fields blank. See one of
421 the <path>modules_load</path> files for an example.
422 </li>
423</ul>
424
425<ul>
426 <li>
427 <path>kernel-config</path>: A default kernel configuration used for any
428 kernel version.
429 </li>
430 <li>
431 <path>kernel-config-2.4</path>: A default kernel configuration used for 2.4
432 series kernels.
433 </li>
434 <li>
435 <path>kernel-config-2.6</path>: A default kernel configuration used for 2.6
436 series kernels.
437 </li>
438</ul>
439
440</body>
441</section>
442</chapter> 667</chapter>
668
669<chapter>
670<title>Network-Booting with genkernel</title>
671
672<section>
673<title>Network Booting from an Installation CD</title>
674<body>
675
676<p>
677The genkernel utility can build kernel and initrd images that provide support
678for network booting, or <e>netboot</e>ing . With any luck, you should be able
679to netboot any recent computer into the environment provided by the
680Installation CD.
681</p>
682
683<p>
684The magic lies in genkernel's linuxrc script: it will try to <e>netmount</e>
685the Installation CD using NFS. From there, <e>the init scripts</e> of the
686Installation CD can take over, as if the CD was present locally.
687</p>
688
689</body>
690</section>
691
692<section>
693<title>Building Kernel and Initrd Images with Support for Netbooting</title>
694<body>
695
696<p>
697To enable support for netbooting, include the following options while
698configuring the kernel:
699</p>
700
701<warn>
702Support for netbooting with genkernel is experimental and may contain bugs.
703</warn>
704
705<p>
706First, the kernel image must include the drivers for your Network Interface
707Cards (NIC). Normally, drivers for such devices will be compiled as modules.
708However, it is essential (for netbooting) that you such drivers compiled
709directly into the kernel image and <b>not</b> as modules.
710</p>
711
712<pre caption="Configuring a 2.6.x series kernel to support your NIC driver">
713Device Drivers --->
714 Networking Support --->
715 Ethernet (10 or 100Mbit) --->
716 [*] Ethernet (10 or 100Mbit)
717 &lt;*&gt; the driver for your network card
718<comment>(Be sure to select &lt;*&gt; and not &lt;m&gt;)</comment>
719</pre>
720
721<p>
722Secondly, we suggest that you enable <c>IP: kernel level
723autoconfiguration</c> and the <c>IP: DHCP support</c> options. This avoids an
724unnecessary layer of complexity since the IP address and the NFS path to the
725Installation CD can be configured on a DHCP server. Of course, this means the
726kernel command line will remain constant for any machine &#8212; which is very
727important for <e>etherbooting</e>.
728</p>
729
730<pre caption="Configuring a 2.6.x series kernel to support DHCP">
731Device Drivers --->
732 Networking Support --->
733 Networking options
734 [*] TCP/IP networking--->
735 [*] IP: kernel level autoconfiguration
736 [*] IP: DHCP support
737<comment>(These options tell the kernel to send a DHCP request at bootup.)</comment>
738</pre>
739
740<p>
741Additionally, you should enable SquashFS because most modern Gentoo
742Installation CDs require it. Support for SquashFS is not included with the
743generic kernel source tree. To enable SquashFS, apply the necessary patches to
744the generic kernel source or install <c>gentoo-sources</c>.
745</p>
746
747<pre caption="Configuring the kernel to support SquashFS">
748File systems--->
749 Miscellaneous filesystems --->
750 [*] SquashFS 2.X - Squashed file system support
751</pre>
752
753<p>
754Once the compilation process is completed, create a compressed <e>tarball</e>
755(tar.gz) that contains the kernel's modules. This step is only necessary if
756your kernel version does not match the kernel image version on the Installation
757CD.
758</p>
759
760<pre caption="Creating a compressed tarball containing the kernel modules">
761<comment># Create a tar.gz containing all the modules</comment>
762cd /
763tar -cf /tmp/modules-X.Y.Z.tar.gz /lib/modules/X.Y.Z/
764</pre>
765
766<p>
767Depending on your network boot mechanism, you will need to do some of the
768following steps:
769</p>
770
771<pre caption="Creating a boot image">
772<comment># Create a etherboot image</comment>
773emerge mknbi
774cd /boot
775mkelf-linux -params="root=/dev/ram0 init=/linuxrc ip=dhcp" kernel... initrd... > etherboot.img
776
777<comment># Create a OpenBoot / SPARC64 TFTP image</comment>
778emerge sparc-utils
779cd /boot
780elftoaout kernel... -o kernel.aout
781piggyback64 kernel.aout System.map-... initrd-...
782mv kernel.aout openboot.img <comment># This is the boot image</comment>
783
784<comment># PXE does not need any more steps, the kernel and initrd can be used as is</comment>
785</pre>
786
787<p>
788Finally, copy this kernel to your TFTP server. The details are
789architecture-dependent and are beyond the scope of this guide. Please refer to
790the documentation for your platform.
791</p>
792
793</body>
794</section>
795
796<section>
797<title>NFS Setup</title>
798<body>
799
800<p>
801To setup a NFS share that contains the Installation CD, use the loop device to
802mount the ISO image and then copy the contents of the CD into the NFS share. As
803a nice extra, genkernel's initrd scripts will extract all tar.gz files located
804in the <path>/nfs/livecd/add/</path> directory. All you have to do here is copy
805the <c>modules-X.Y.Z.tar.gz</c> archive to the <path>/nfs/livecd/add/</path>
806directory.
807</p>
808
809<pre caption="Preparing the NFS share">
810<comment># This assumes that /nfs/livecd is a exported NFS share</comment>
811mount /mnt/cdrom /tmp/gentoo-livecd.iso -o loop
812cp -p /mnt/cdrom /nfs/livecd
813umount /mnt/cdrom
814
815<comment># Copy the modules.tar.gz into /add</comment>
816mkdir /nfs/livecd/add
817cp /tmp/modules-X.Y.Z.tar.gz /nfs/livecd/add
818</pre>
819
820</body>
821</section>
822
823<section>
824<title>DHCP Setup</title>
825<body>
826
827<p>
828The netboot images will ask your DHCP server for an IP as well as a
829root-path parameter. Both can be specified per host using a MAC
830address to identify machines:
831</p>
832
833<pre caption="Sample client dhcpd.conf setup">
834...
835
836host netbootableMachine {
837 hardware ethernet 11:22:33:44:55:66;
838 fixed-address 192.168.1.10;
839 option root-path "192.168.1.2:/nfs/livecd";
840}
841<comment># Here, 192.168.1.2 is the NFS server
842# While 192.168.1.10 will be the IP address of the netbooted machine</comment>
843...
844</pre>
845
846</body>
847</section>
848
849<section>
850<title>Netbooting Instructions</title>
851<body>
852
853<p>
854Netbooting itself is again very platform-specific. The important part
855is to specify the <c>ip=dhcp</c> and <c>init=/linuxrc</c> parameters
856on the kernel command line, as this will bring up the
857network interface and tell the initrd scripts to mount the Installation CD via
858NFS. Here are some platform-specific tips:
859</p>
860
861<pre caption="Netbooting Instructions">
862<comment># Etherboot - insert the etherboot disk into the drive and reboot
863# The kernel command line was specified when the image was constructed</comment>
864
865<comment># Sparc64 - Hit Stop-A at the boot prompt </comment>
866ok boot net ip=dhcp init=/linuxrc
867
868<comment># PXE - Setup pxelinux (part of syslinux), then create a pxelinux.cfg/default along the lines of:</comment>
869
870DEFAULT gentoo
871TIMEOUT 40
872PROMPT 1
873
874LABEL gentoo
875 KERNEL kernel-X.Y.Z
876 APPEND initrd=initrd-X.Y.Z root=/dev/ram0 init=/linuxrc ip=dhcp
877</pre>
878
879</body>
880</section>
881
882</chapter>
883
884<chapter>
885<title>Conclusion</title>
886
887<section>
888<title>To Automate or not to Automate?</title>
889<body>
890
891<p>
892The purpose of genkernel is to provide an (easier) alternative to the
893time-tested approach to kernel compilation. As always, you are free to decide
894on whether or not you want to automate the kernel compilation process.
895</p>
896
897</body>
898</section>
899
900</chapter>
901
443</guide> 902</guide>

Legend:
Removed from v.1.3  
changed lines
  Added in v.1.19

  ViewVC Help
Powered by ViewVC 1.1.20