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

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1.16 - (show annotations) (download) (as text)
Sun Jun 26 23:50:57 2005 UTC (9 years, 5 months ago) by vanquirius
Branch: MAIN
Changes since 1.15: +6 -6 lines
File MIME type: application/xml
livecd->installation cd; fix typos

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 $ -->
3 <!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
4
5 <guide link="/doc/en/genkernel.xml">
6 <title>Gentoo Linux Genkernel Guide</title>
7
8 <author title="Author">
9 <mail link="plasmaroo@gentoo.org">Tim Yamin</mail>
10 </author>
11
12 <abstract>
13 This guide intends to provide a reference of all the functions
14 provided by genkernel.
15 </abstract>
16
17 <license/>
18
19 <version>1.1.2.3</version>
20 <date>2005-06-26</date>
21
22 <chapter>
23 <title>Introduction</title>
24 <section>
25 <title>Introduction</title>
26 <body>
27
28 <p>
29 Genkernel is designed to allow users who are not previously used to
30 compiling a kernel to use a similar setup to that one that is used on
31 the Gentoo Installation CDs which auto-detects your hardware.
32 </p>
33
34 <p>
35 Some users may also be interested in using genkernel for hardware
36 which requires initialization and a working kernel before it can be
37 booted. Because genkernel also automatically compiles your kernel modules,
38 thus allowing hardware which needs to be loaded with module parameters
39 to be used.
40 </p>
41
42 </body>
43 </section>
44 <section>
45 <title>Is genkernel for me?</title>
46 <body>
47
48 <p>
49 Genkernel is often a good choice to those who are unused to compiling
50 their own kernel or those who are not certain about their hardware
51 configurations.
52 </p>
53
54 <p>
55 Because genkernel is designed to use a generic configuration, it
56 should be able to support all of your hardware - however, because all
57 the drivers and modules have to be compiled as well, compiling a
58 kernel by yourself is often much faster provided you know what you need.
59 </p>
60
61 <p>
62 Genkernel does not however, currently support booting the sytem from
63 LVM2/EVMS2 partitions. Users are recommended to use a manually compiled
64 kernel for the time being.
65 </p>
66
67 </body>
68 </section>
69 <section>
70 <title>Getting genkernel</title>
71 <body>
72
73 <p>
74 You can obtain genkernel by simply running <c>emerge genkernel</c>. Don't
75 forget to use the <c>-k</c> flag for emerge if you are using binary packages,
76 i.e. GRP. Due to the GRP packages having an older version of genkernel, the
77 flags are different. As a result, you should consult the <uri
78 link="/doc/en/handbook/handbook-x86.xml?part=1&amp;chap=10">
79 Gentoo Handbook</uri> and <path>genkernel --help</path>.
80 </p>
81
82 </body>
83 </section>
84 <section>
85 <title>Supported platforms</title>
86 <body>
87
88 <p>
89 As of genkernel 3.0.2, the following platforms should be
90 supported: alpha, amd64, parisc, parisc64, ppc, ppc64, sparc, sparc64, and x86.
91 </p>
92
93 </body>
94 </section>
95 </chapter>
96
97 <chapter>
98 <title>Genkernel usage</title>
99 <section>
100 <title>Introduction</title>
101 <body>
102
103 <p>
104 Genkernel 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>
114 Most users will only want the "all" mode, which runs the "kernel" mode
115 and the "initrd" mode for you. <b>Note</b> that the "kernel" and "initrd"
116 modes are currently just aliases for the "all" mode, so they will
117 currently give you no special effect.
118 </p>
119
120 <p>
121 Although genkernel is mainly a command to make your life easier when
122 you need to compile a kernel, genkernel is also packed full of
123 different flags which allow you to customize how your kernel is
124 compiled or configured.
125 </p>
126
127 </body>
128 </section>
129 <section>
130 <title>Genkernel compiler flags</title>
131 <body>
132
133 <p>
134 Genkernel supports the following flags which are passed to the
135 relevant 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>
185 <section>
186 <title>Genkernel kernel flags</title>
187 <body>
188
189 <p>
190 Genkernel supports the following flags, some of which have
191 <c>--<b>no-</b>option</c> equivalents that influence
192 kernel compilation:
193 </p>
194
195 <ul>
196 <li>
197 <b>--callback="echo Hello"</b>: This routine calls the specified
198 arguments after the kernel and the relevant modules have been built; but
199 before the initrd has been built. This is useful where you might want
200 external modules installed to the initrd by emerging the relevant item
201 using the callback and then redefining a genkernel module group.
202 </li>
203 <li>
204 <b>--<c>no-</c>clean</b>: This runs <e>or does not
205 run</e> <c>make clean</c> before compiling your kernel. This
206 causes all object files and dependencies to be removed.
207 </li>
208 <li>
209 <b>--<c>no-</c>mrproper</b>: This runs <e>or does not
210 run</e> <c>make mrproper</c> before compiling your kernel. This
211 causes all object files, dependencies <b>and your
212 configuration</b> to be removed.
213 </li>
214 </ul>
215
216 <ul>
217 <li>
218 <b>--kerneldir=<path>/path/to/sources</path></b>: This specifies an
219 alternative kernel source location, instead of the default location of
220 <path>/usr/src/linux</path>.
221 </li>
222 <li>
223 <b>--kernel-config=<path>/path/to/config-file</path></b>: This specifies an
224 alternative kernel configuration which would be used; rather than the
225 non-persistent <path>/path/to/sources/.config</path> which is used by
226 default.
227 </li>
228 </ul>
229
230 <ul>
231 <li>
232 <b>--<c>no-</c>bootsplash</b>: This adds <e>or does not add</e> bootsplash
233 support in the initrd which genkernel builds. Not all architectures
234 currently support bootsplash, and a kernel that supports bootsplash is
235 also required.
236 </li>
237 <li>
238 <b>--<c>no-</c>menuconfig</b>: This runs <e>or does not run</e> the kernel
239 menu-based configurator before building your kernel, after <c>make
240 oldconfig</c> has run.
241 </li>
242 </ul>
243
244 <ul>
245 <li>
246 <b>--no-initrdmodules</b>: This doesn't copy any modules to the initrd
247 which genkernel creates.
248 </li>
249 <li>
250 <b>--<c>no-</c>install</b>: This installs <e>or does not install</e> your
251 kernel, modules, and initrd once the compilation has finished.
252 </li>
253 </ul>
254
255 </body>
256 </section>
257 <section>
258 <title>Genkernel miscellaneous flags</title>
259 <body>
260
261 <p>
262 Genkernel also supports some miscellaneous flags which do not fit into
263 the 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>
299 <section>
300 <title>Running genkernel</title>
301 <body>
302
303 <p>
304 All that is needed to run genkernel is just genkernel with the
305 necessary 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
311 to your desire, leaving alone any compiled object files, enabling
312 bootsplash support but not installing anything.)</comment>
313 </pre>
314
315 <p>
316 If you want genkernel to install your kernel as well, you must ensure
317 that your <path>/boot</path> partition is mounted - recent genkernels
318 would 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>
333 <section>
334 <title>Setting up genkernel to work with your bootloader</title>
335 <body>
336
337 <p>
338 To set up genkernel to work with your bootloader, three or four changes are
339 required to your bootloader configuration.
340 </p>
341
342 <ol>
343 <li>
344 Add <c>root=/dev/ram0</c> and <c>init=/linuxrc</c> to the
345 kernel parameters passed to the kernel image.
346 </li>
347 <li>
348 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
350 partition.
351 </li>
352 <li>
353 If you are using bootsplash, add a suitable modeline such as
354 <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
356 you require from your bootsplash.
357 </li>
358 <li>
359 Add the initrd according to how your bootloader requires it: see the <uri
360 link="/doc/en/handbook/handbook-x86.xml?part=1&amp;chap=10">Gentoo
361 Handbook</uri> for details on how you would do it for your bootloader.
362 </li>
363 </ol>
364
365 </body>
366 </section>
367 <section>
368 <title>Kernel Configuration Files</title>
369 <body>
370
371 <p>
372 Genkernel will save your kernel config in <path>/etc/kernels</path> and use that
373 config whenever you issue <c>genkernel</c> again. If you want to start off again
374 with the defaults, rename the file in <path>/etc/kernels</path>. Genkernel will
375 then 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>
382
383 <chapter>
384 <title>Porting genkernel</title>
385 <section>
386 <title>Introduction</title>
387 <body>
388
389 <p>
390 Provided your architecture has all the required libraries and utilties
391 which genkernel requires, which includes but it is not limited to a
392 working kernel for your architecture, working compiler suite, GNU
393 make, and a working busybox distribution, you're all set to go!
394 </p>
395
396 <p>
397 For each architecture, genkernel uses
398 <path>/usr/share/genkernel/$archName</path> for configuration files for
399 that architecture.
400 </p>
401
402 </body>
403 </section>
404 <section>
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>
427 </section>
428 <section>
429 <title>The configuration files</title>
430 <body>
431
432 <ul>
433 <li>
434 <path>busy-config</path>: This is the configuration which is used to build
435 busybox for your architecture.
436 </li>
437 <li>
438 <path>config.sh</path>: This is a shell script which sets various internal
439 genkernel variables. See one of the <path>config.sh</path> files for an
440 example.
441 </li>
442 <li>
443 <path>modules_load</path>: This is a file containing a space-delimited list
444 of modules which are loaded for SCSI, FireWire, ATARAID and PCMCIA support.
445 If none are available for your platform, leave the fields blank. See one of
446 the <path>modules_load</path> files for an example.
447 </li>
448 </ul>
449
450 <ul>
451 <li>
452 <path>kernel-config</path>: A default kernel configuration used for any
453 kernel version.
454 </li>
455 <li>
456 <path>kernel-config-2.4</path>: A default kernel configuration used for 2.4
457 series kernels.
458 </li>
459 <li>
460 <path>kernel-config-2.6</path>: A default kernel configuration used for 2.6
461 series kernels.
462 </li>
463 </ul>
464
465 </body>
466 </section>
467 </chapter>
468 </guide>

  ViewVC Help
Powered by ViewVC 1.1.20