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

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

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

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

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

  ViewVC Help
Powered by ViewVC 1.1.20