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

Legend:
Removed from v.1.15  
changed lines
  Added in v.1.27

  ViewVC Help
Powered by ViewVC 1.1.20