/[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.23 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.23 2005/08/18 11:33:54 neysx 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
19 Thomas Seiler 19 Thomas Seiler
20</author> 20</author>
21 21
22<abstract> 22<abstract>
23This guide intends to provide a reference of all the functions provided by 23This guide intends to provide a reference of all the functions provided by
24genkernel. 24genkernel.
25</abstract> 25</abstract>
26 26
27<license/> 27<license/>
28 28
29<version>1.4.1</version> 29<version>1.4.3</version>
30<date>2005-08-11</date> 30<date>2005-12-16</date>
31 31
32<chapter> 32<chapter>
33<title>Introduction</title> 33<title>Introduction</title>
34<section> 34<section>
35<title>Rationale</title> 35<title>Rationale</title>
75<body> 75<body>
76 76
77<p> 77<p>
78To obtain genkernel, run <c>emerge genkernel</c> from the command line. If you 78To obtain genkernel, run <c>emerge genkernel</c> from the command line. If you
79are using the <uri 79are using the <uri
80link="/doc/en/handbook/2005.0/hb-install-about.xml#doc_chap2_sect1"> Gentoo 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 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 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 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 84--help</c> for help on how to use the version of genkernel installed on your
85system. 85system.
86</p> 86</p>
87 87
88</body> 88</body>
89</section> 89</section>
90</chapter> 90</chapter>
91 91
92<chapter> 92<chapter>
143and their effects are enclosed within the square brackets, []. 143and their effects are enclosed within the square brackets, [].
144</p> 144</p>
145 145
146</body> 146</body>
147</section> 147</section>
148
149<section> 148<section>
150<title>Configuration Flags</title> 149<title>Configuration Flags</title>
151<body> 150<body>
152 151
153<p> 152<p>
178 on the X-windowing system. The disadvantage of this option is that you 177 on the X-windowing system. The disadvantage of this option is that you
179 <b>need</b> the X-windowing system to use it, so it will not work on the 178 <b>need</b> the X-windowing system to use it, so it will not work on the
180 command line. 179 command line.
181 </li> 180 </li>
182 <li> 181 <li>
183 <b>--<c>no-</c>save-config</b>: Saves [or does not save] the kernel 182 <b>--<c>no-</c>save-config</b>: Saves <e>[or does not save]</e> the kernel
184 configuration to a file in the <path>/etc/kernels/</path> directory for 183 configuration to a file in the <path>/etc/kernels/</path> directory for
185 later use. 184 later use.
186 </li> 185 </li>
187</ul> 186</ul>
188 187
327 that the make utility can implement while the kernel (and utilities) are 326 that the make utility can implement while the kernel (and utilities) are
328 being compiled. The variable <b>'X'</b> is a number obtained by adding one 327 being compiled. The variable <b>'X'</b> is a number obtained by adding one
329 (1) to the number of CPUs used by the system. So, for a system with one 328 (1) to the number of CPUs used by the system. So, for a system with one
330 CPU, the appropriate flag is <c>-j2</c>; a system with two CPUs will use 329 CPU, the appropriate flag is <c>-j2</c>; a system with two CPUs will use
331 the <c>-j3</c> flag, and so on. <e>(A system with one processor that 330 the <c>-j3</c> flag, and so on. <e>(A system with one processor that
332 supports Hyper-Threading (HT) Technology can use the</e><c>-j3</c> 331 supports Hyper-Threading&trade; (HT) Technology can use the
333 <e>flag, provided Symmetric Multi-Processing (SMP) support is enabled in 332 </e><c>-j3</c><e> flag, provided Symmetric Multi-Processing (SMP) support is
334 the kernel.)</e> 333 enabled in the kernel.)</e>
335 </li> 334 </li>
336</ul> 335</ul>
337 336
338</body> 337</body>
339</section> 338</section>
340<section> 339<section>
341<title>Debugging Flags</title> 340<title>Debugging Flags</title>
342<body> 341<body>
343 342
344<p> 343<p>
345The use debugging flags during the kernel compilation process controls the 344The use of debugging flags during the kernel compilation process controls the
346amount of information reported, as well as the presentation of said data. 345amount of information reported, as well as the presentation of said data.
347</p> 346</p>
348 347
349<ul> 348<ul>
350 <li> 349 <li>
359 by the <c>--debuglevel</c> argument, and sends <b>all</b> debugging data 358 by the <c>--debuglevel</c> argument, and sends <b>all</b> debugging data
360 produced by genkernel to the specified output file, which is located at 359 produced by genkernel to the specified output file, which is located at
361 <path>/var/log/genkernel.log</path> by default. 360 <path>/var/log/genkernel.log</path> by default.
362 </li> 361 </li>
363 <li> 362 <li>
364 <b>--no-color</b>: Activates [or deactivates] colored output of debugging 363 <b>--no-color</b>: Activates <e>[or deactivates]</e> colored output of
365 information (reported by genkernel) using escape sequences. 364 debugging information (reported by genkernel) using escape sequences.
366 </li> 365 </li>
367</ul> 366</ul>
368 367
369</body> 368</body>
370</section> 369</section>
424 <li> 423 <li>
425 <b>--evms2</b>: Includes support for storage using the <uri 424 <b>--evms2</b>: Includes support for storage using the <uri
426 link="http://evms.sourceforge.net/">Enterprise Volume Management 425 link="http://evms.sourceforge.net/">Enterprise Volume Management
427 System</uri> (EVMS2), if available. Be sure to install the evms package on 426 System</uri> (EVMS2), if available. Be sure to install the evms package on
428 your system with <c>USE=static emerge evms2</c> before using this 427 your system with <c>USE=static emerge evms2</c> before using this
429 (genkernel) flag. <e>(Omitting the </e><c>USE=static</c> <e>flag during 428 (genkernel) flag. <e>(Omitting the </e><c>USE=static</c><e> flag during
430 package installation will fail to include the necessary static binaries.) 429 package installation will fail to include the necessary static
431 </e> 430 binaries.)</e>
432 </li> 431 </li>
433 <li> 432 <li>
434 <b>--dmraid</b>: Includes support for <uri 433 <b>--dmraid</b>: Includes support for <uri
435 link="http://people.redhat.com/~heinzm/sw/dmraid/readme">DMRAID</uri>; the 434 link="http://people.redhat.com/~heinzm/sw/dmraid/readme">DMRAID</uri>; the
436 utility which creates RAID mappings using the kernel device-mapper 435 utility which creates RAID mappings using the kernel device-mapper
437 subsystem. DMRAID discovers, activates, deactivates and displays properties 436 subsystem. DMRAID discovers, activates, deactivates and displays properties
438 of software RAID sets (ATARAID, for example) and contained DOS partitions. 437 of software RAID sets (ATARAID, for example) and contained DOS partitions.
439 </li> 438 </li>
440 <li> 439 <li>
441 <b>--linuxrc=/path/to/your/linuxrc</b>: Specifies a user-created 440 <b>--linuxrc=/path/to/your/linuxrc</b>: Specifies a user-created
442 <e>linuxrc</e> a script that is initialized during the start-up stage of 441 <e>linuxrc</e> &mdash; a script that is initialized during the start-up
443 the kernel, prior to the actual boot process. (A default linuxrc script 442 stage of the kernel, prior to the actual boot process. (A default linuxrc
444 should be in the <path>/usr/share/genkernel/</path> directory.) This script 443 script should be in the <path>/usr/share/genkernel/</path> directory.) This
445 allows you to boot into a small, modularized kernel and load the drivers 444 script allows you to boot into a small, modularized kernel and load the
446 that are needed (as modules) by the system. 445 drivers that are needed (as modules) by the system.
447 </li> 446 </li>
448 <li> 447 <li>
449 <b>--cachedir=/path/to/alt/dir/</b>: Overrides the default cache location 448 <b>--cachedir=/path/to/alt/dir/</b>: Overrides the default cache location
450 used while compiling the kernel. 449 used while compiling the kernel.
451 </li> 450 </li>
499 498
500<ul> 499<ul>
501 <li><c>initrd</c>: Only builds the initrd image</li> 500 <li><c>initrd</c>: Only builds the initrd image</li>
502 <li><c>bzImage</c>: Only builds the kernel image</li> 501 <li><c>bzImage</c>: Only builds the kernel image</li>
503 <li><c>kernel</c>: Only builds the kernel image and modules</li> 502 <li><c>kernel</c>: Only builds the kernel image and modules</li>
503 <li>
504 <li><c>all</c>: Builds all stages the initrd, kernel image and modules.</li> 504 <c>all</c>: Builds all stages &mdash; the initrd, kernel image and modules.
505 </li>
505</ul> 506</ul>
506 507
507<p> 508<p>
508The last action, <c>all</c>, is recommended for most users since it builds the 509The last action, <c>all</c>, is recommended for most users since it builds the
509stages required for a functional kernel. Remember, an <e>action</e> simply 510stages required for a functional kernel. Remember, an <e>action</e> simply
537 <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
538 you require from your bootloader. 539 you require from your bootloader.
539 </li> 540 </li>
540 <li> 541 <li>
541 Add the initrd information as required by the bootloader. Consult the <uri 542 Add the initrd information as required by the bootloader. Consult the <uri
542 link="/doc/en/handbook/handbook-x86.xml?part=1&amp;chap=10"> Bootloader 543 link="/doc/en/handbook/handbook-x86.xml?part=1&amp;chap=10">Bootloader
543 Configuration Chapter</uri> of the Gentoo Handbook for details on how to 544 Configuration Chapter</uri> of the Gentoo Handbook for details on how to
544 make your bootloader initrd-aware. 545 make your bootloader initrd-aware.
545 </li> 546 </li>
546</ol> 547</ol>
547 548
585 the <c>--clean</c> flag used by genkernel, and invokes the <c>make 586 the <c>--clean</c> flag used by genkernel, and invokes the <c>make
586 clean</c> command to remove all object files and dependencies from the 587 clean</c> command to remove all object files and dependencies from the
587 kernel's source tree. Setting this option to 'no' creates a cascade effect 588 kernel's source tree. Setting this option to 'no' creates a cascade effect
588 &#8212; it is equivalent to genkernel's <c>--no-clean</c> flag, which 589 &#8212; it is equivalent to genkernel's <c>--no-clean</c> flag, which
589 disables the <c>make clean</c> command and implies genkernel's 590 disables the <c>make clean</c> command and implies genkernel's
590 <c>--no-mrproper</c> flag &#8212; essentially nullifying the <c>make 591 <c>--no-mrproper</c> flag &mdash; essentially nullifying the <c>make
591 mrproper</c> command. 592 mrproper</c> command.
592 </li> 593 </li>
593 <li> 594 <li>
594 <b>MRPROPER=<c>[yes|no]</c></b>: Setting this option to 'yes' is equivalent 595 <b>MRPROPER=<c>[yes|no]</c></b>: Setting this option to 'yes' is equivalent
595 to <c>--mrproper</c> flag used by genkernel, and invokes the <c>make 596 to <c>--mrproper</c> flag used by genkernel, and invokes the <c>make
618 to the <c>--color</c> flag, which colors genkernel's output to ease 619 to the <c>--color</c> flag, which colors genkernel's output to ease
619 debugging (when needed.) 620 debugging (when needed.)
620 </li> 621 </li>
621 <li> 622 <li>
622 <b>DEBUGLEVEL=<c>[0|1|2|3|4|5]</c></b>: This option is for adjusting the 623 <b>DEBUGLEVEL=<c>[0|1|2|3|4|5]</c></b>: This option is for adjusting the
623 verbosity of the output produced by genkernel setting this option to '0' 624 verbosity of the output produced by genkernel &mdash; setting this option to
624 with <c>--debuglevel=0</c> will suppress all output produced by genkernel; 625 '0' with <c>--debuglevel=0</c> will suppress all output produced by
625 setting this option to '5' with <c>--debuglevel=5</c> provides the user 626 genkernel; setting this option to '5' with <c>--debuglevel=5</c> provides
626 with all output produced by genkernel. 627 the user with all output produced by genkernel.
627 </li> 628 </li>
628</ul> 629</ul>
629 630
630<p> 631<p>
631By choosing the appropriate options in <path>/etc/genkernel.conf</path>, you 632By choosing the appropriate options in <path>/etc/genkernel.conf</path>, you
632can halve the number of flags passed to genkernel from the command line: 633can halve the number of flags passed to genkernel from the command line:
633</p> 634</p>
634 635
635<pre caption="Running genkernel (with flags), after employing genkernel.conf"> 636<pre caption="Running genkernel (with flags), after employing genkernel.conf">
636# <i>genkernel --gensplash --kerneldir=/path/to/alternate/kernel/sources \ 637# <i>genkernel --gensplash --kerneldir=/path/to/alternate/kernel/sources \
637--kernel-config=/path/to/preferred/configfile --install all</i> 638--kernel-config=/path/to/preferred/configfile --install all</i>
638</pre> 639</pre>
639 640
640<p> 641<p>
641Identical results are obtained from both approaches, but the latter has most of 642Identical results are obtained from both approaches, but the latter has most of
652<title>Network Booting from an Installation CD</title> 653<title>Network Booting from an Installation CD</title>
653<body> 654<body>
654 655
655<p> 656<p>
656The genkernel utility can build kernel and initrd images that provide support 657The genkernel utility can build kernel and initrd images that provide support
657for network booting, or <e>netboot</e>ing . With any luck, you should be able 658for network booting, or <e>netboot</e>ing. With any luck, you should be able
658to netboot any recent computer into the environment provided by the 659to netboot any recent computer into the environment provided by the
659Installation CD. 660Installation CD.
660</p> 661</p>
661 662
662<p> 663<p>
688</p> 689</p>
689 690
690<pre caption="Configuring a 2.6.x series kernel to support your NIC driver"> 691<pre caption="Configuring a 2.6.x series kernel to support your NIC driver">
691Device Drivers ---> 692Device Drivers --->
692 Networking Support ---> 693 Networking Support --->
693 Ethernet (10 or 100Mbit) ---> 694 Ethernet (10 or 100Mbit) --->
694 [*] Ethernet (10 or 100Mbit) 695 [*] Ethernet (10 or 100Mbit)
695 &lt;*&gt; the driver for your network card 696 &lt;*&gt; the driver for your network card
696<comment>(Be sure to select &lt;*&gt; and not &lt;M&gt;)</comment> 697<comment>(Be sure to select &lt;*&gt; and not &lt;M&gt;)</comment>
697</pre> 698</pre>
698 699
699<p> 700<p>
700Secondly, we suggest that you enable <c>IP: kernel level autoconfiguration</c> 701Secondly, we suggest that you enable <c>IP: kernel level autoconfiguration</c>
701and the <c>IP: DHCP support</c> options. This avoids an unnecessary layer of 702and the <c>IP: DHCP support</c> options. This avoids an unnecessary layer of
702complexity since the IP address and the NFS path to the Installation CD can be 703complexity since the IP address and the NFS path to the Installation CD can be
703configured on a DHCP server. Of course, this means the kernel command line 704configured on a DHCP server. Of course, this means the kernel command line
704will remain constant for any machine which is very important for 705will remain constant for any machine &mdash; which is very important for
705<e>etherbooting</e>. 706<e>etherbooting</e>.
706</p> 707</p>
707 708
708<pre caption="Configuring a 2.6.x series kernel to support DHCP"> 709<pre caption="Configuring a 2.6.x series kernel to support DHCP">
709Device Drivers ---> 710Device Drivers --->
710 Networking Support ---> 711 Networking Support --->
711 Networking options 712 Networking options
712 [*] TCP/IP networking---> 713 [*] TCP/IP networking--->
713 [*] IP: kernel level autoconfiguration 714 [*] IP: kernel level autoconfiguration
714 [*] IP: DHCP support 715 [*] IP: DHCP support
715<comment>(These options tell the kernel to send a DHCP request at bootup.)</comment> 716<comment>(These options tell the kernel to send a DHCP request at bootup.)</comment>
716</pre> 717</pre>
721generic kernel source tree. To enable SquashFS, apply the necessary patches to 722generic kernel source tree. To enable SquashFS, apply the necessary patches to
722the generic kernel source or install <c>gentoo-sources</c>. 723the generic kernel source or install <c>gentoo-sources</c>.
723</p> 724</p>
724 725
725<pre caption="Configuring the kernel to support SquashFS"> 726<pre caption="Configuring the kernel to support SquashFS">
726File systems---> 727File systems--->
727 Miscellaneous filesystems ---> 728 Miscellaneous filesystems --->
728 [*] SquashFS 2.X - Squashed file system support 729 [*] SquashFS 2.X - Squashed file system support
729</pre> 730</pre>
730 731
731<p> 732<p>
736</p> 737</p>
737 738
738<pre caption="Creating a compressed tarball containing the kernel modules"> 739<pre caption="Creating a compressed tarball containing the kernel modules">
739<comment>(Create a tar.gz containing all the modules)</comment> 740<comment>(Create a tar.gz containing all the modules)</comment>
740# <i>cd /</i> 741# <i>cd /</i>
741# <i> tar -cf /tmp/modules-X.Y.Z.tar.gz /lib/modules/X.Y.Z/</i> 742# <i>tar -cf /tmp/modules-X.Y.Z.tar.gz /lib/modules/X.Y.Z/</i>
742</pre> 743</pre>
743 744
744<p> 745<p>
745Depending on your network boot mechanism, you will need to do some of the 746Depending on your network boot mechanism, you will need to do some of the
746following steps: 747following steps:
783directory. 784directory.
784</p> 785</p>
785 786
786<pre caption="Preparing the NFS share"> 787<pre caption="Preparing the NFS share">
787<comment>(This assumes that /nfs/livecd is a exported NFS share)</comment> 788<comment>(This assumes that /nfs/livecd is a exported NFS share)</comment>
788# <i>mount /mnt/cdrom /tmp/gentoo-livecd.iso -o loop</i> 789# <i>mount /tmp/gentoo-livecd.iso /mnt/cdrom -o loop</i>
789# <i>cp -p /mnt/cdrom /nfs/livecd</i> 790# <i>cp -p /mnt/cdrom /nfs/livecd</i>
790# <i>umount /mnt/cdrom</i> 791# <i>umount /mnt/cdrom</i>
791 792
792<comment>(Copy the modules.tar.gz into /add)</comment> 793<comment>(Copy the modules.tar.gz into /add)</comment>
793# <i>mkdir /nfs/livecd/add</i> 794# <i>mkdir /nfs/livecd/add</i>
800<title>DHCP Setup</title> 801<title>DHCP Setup</title>
801<body> 802<body>
802 803
803<p> 804<p>
804The netboot images will ask your DHCP server for an IP as well as a root-path 805The netboot images will ask your DHCP server for an IP as well as a root-path
805parameter. Both can be specified per host using a MAC address to identify 806parameter. Both can be specified per host using a MAC address to identify
806machines: 807machines:
807</p> 808</p>
808 809
809<pre caption="Sample client dhcpd.conf setup"> 810<pre caption="Sample client dhcpd.conf setup">
810... 811...
856</section> 857</section>
857</chapter> 858</chapter>
858 859
859<chapter> 860<chapter>
860<title>Conclusion</title> 861<title>Conclusion</title>
861
862<section> 862<section>
863<title>To Automate or not to Automate?</title> 863<title>To Automate or not to Automate?</title>
864<body> 864<body>
865 865
866<p> 866<p>

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

  ViewVC Help
Powered by ViewVC 1.1.20