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

Legend:
Removed from v.1.16  
changed lines
  Added in v.1.17

  ViewVC Help
Powered by ViewVC 1.1.20