svn commit: r42827 - in head/en_US.ISO8859-1/books/handbook: bsdinstall kernelconfig
Dru Lavigne
dru at FreeBSD.org
Fri Oct 4 17:29:34 UTC 2013
Author: dru
Date: Fri Oct 4 17:29:34 2013
New Revision: 42827
URL: http://svnweb.freebsd.org/changeset/doc/42827
Log:
This patch does the following:
- comments author names
- incorporates "9.4. Kernel Drivers, Subsystems, and Modules" into "9.2. Why Build a Custom Kernel?"
- fixes reference to 9.4 in bsdinstall chapter
- puts the configuration file section before the building the kernel section
- makes it clearer how to get src and cp the needed config file
- general wordsmithing to make the first half of this chapter less confusing
Approved by: gjb (mentor)
Modified:
head/en_US.ISO8859-1/books/handbook/bsdinstall/chapter.xml
head/en_US.ISO8859-1/books/handbook/kernelconfig/chapter.xml
Modified: head/en_US.ISO8859-1/books/handbook/bsdinstall/chapter.xml
==============================================================================
--- head/en_US.ISO8859-1/books/handbook/bsdinstall/chapter.xml Fri Oct 4 15:14:58 2013 (r42826)
+++ head/en_US.ISO8859-1/books/handbook/bsdinstall/chapter.xml Fri Oct 4 17:29:34 2013 (r42827)
@@ -936,7 +936,7 @@ Trying to mount root from cd9660:/dev/is
<para>Check the probe results carefully to make sure that &os;
found all the devices you expected. If a device was not
found, then it will not be listed. <link
- linkend="kernelconfig-modules">Kernel modules</link> allows
+ linkend="kernelconfig-custom-kernel">Kernel modules</link> allows
you to add in support for devices which are not in the
<filename>GENERIC</filename> kernel.</para>
Modified: head/en_US.ISO8859-1/books/handbook/kernelconfig/chapter.xml
==============================================================================
--- head/en_US.ISO8859-1/books/handbook/kernelconfig/chapter.xml Fri Oct 4 15:14:58 2013 (r42826)
+++ head/en_US.ISO8859-1/books/handbook/kernelconfig/chapter.xml Fri Oct 4 17:29:34 2013 (r42827)
@@ -7,22 +7,20 @@
<chapter id="kernelconfig">
<chapterinfo>
- <authorgroup>
+<!-- <authorgroup>
<author>
<firstname>Jim</firstname>
<surname>Mock</surname>
- <contrib>Updated and restructured by </contrib>
- <!-- Mar 2000 -->
+ <contrib>Updated and restructured in Mar 2000 by </contrib>
</author>
</authorgroup>
<authorgroup>
<author>
<firstname>Jake</firstname>
<surname>Hamby</surname>
- <contrib>Originally contributed by </contrib>
- <!-- 6 Oct 1995 -->
+ <contrib>Originally contributed 6 Oct 1995 by </contrib>
</author>
- </authorgroup>
+ </authorgroup>-->
</chapterinfo>
<title>Configuring the FreeBSD Kernel</title>
@@ -49,6 +47,10 @@
</listitem>
<listitem>
+ <para>How to take a hardware inventory.</para>
+ </listitem>
+
+ <listitem>
<para>How to customize a kernel configuration file.</para>
</listitem>
@@ -73,10 +75,10 @@
<sect1 id="kernelconfig-custom-kernel">
<title>Why Build a Custom Kernel?</title>
- <para>Traditionally, &os; used a <quote>monolithic</quote> kernel.
+ <para>Traditionally, &os; used a monolithic kernel.
The kernel was one large program, supported a fixed list of
devices, and in order to change the kernel's behavior, one had
- to compile a new kernel, and then reboot into the new
+ to compile and then reboot into a new
kernel.</para>
<para>Today, most of the functionality in the &os; kernel is
@@ -87,10 +89,10 @@
a modular kernel.</para>
<para>Occasionally, it is still necessary to perform static kernel
- configuration. This may be because the functionality is so tied
+ configuration. Sometimes the needed functionality is so tied
to the kernel that it can not be made dynamically loadable.
Some security environments prevent the loading and unloading of
- kernel modules, and require that only needed functionality is
+ kernel modules and require that only needed functionality is
statically compiled into the kernel.</para>
<para>Building a custom kernel is often a rite of passage for
@@ -120,45 +122,69 @@
</listitem>
<listitem>
- <para>Additional hardware support. A custom kernel can add in
+ <para>Additional hardware support. A custom kernel can add
support for devices which are not present in the
<filename>GENERIC</filename> kernel.</para>
</listitem>
</itemizedlist>
+
+ <para>Before building a custom kernel, consider the reason for
+ doing so. If there is a need for specific hardware support,
+ it may already exist as a module.</para>
+
+ <para>Kernel modules exist in <filename
+ class="directory">/boot/kernel</filename> and may be
+ dynamically loaded into the running kernel using
+ &man.kldload.8;. Most kernel drivers have a
+ loadable module and manual page. For example, the &man.ath.4;
+ wireless Ethernet driver has the following information in its
+ manual page:</para>
+
+ <programlisting>Alternatively, to load the driver as a module at boot time, place the
+following line in &man.loader.conf.5;:
+
+ if_ath_load="YES"</programlisting>
+
+ <para>Adding <literal>if_ath_load="YES"</literal> to
+ <filename>/boot/loader.conf</filename> will load this
+ module dynamically at boot time.</para>
+
+ <para>In some cases, there is no associated module in <filename
+ class="directory">/boot/kernel</filename>. This is
+ mostly true for certain subsystems.</para>
</sect1>
<sect1 id="kernelconfig-devices">
<sect1info>
- <authorgroup>
+ <!--<authorgroup>
<author>
<firstname>Tom</firstname>
<surname>Rhodes</surname>
<contrib>Written by </contrib>
</author>
- </authorgroup>
+ </authorgroup>-->
</sect1info>
<title>Finding the System Hardware</title>
- <para>Before venturing into kernel configuration, it would be
- wise to get an inventory of the machine's hardware. In cases
- where &os; is not the primary operating system, the inventory
- list can be created by viewing the current operating system
- configuration. For example, µsoft;'s
+ <para>Before editing the kernel configuration file, it is recommended
+ to perform an inventory of the machine's hardware. On a dual-boot
+ system, the inventory
+ can be created from the other operating system.
+ For example, µsoft;'s
<application>Device Manager</application> contains information
about installed devices.</para>
<note>
<para>Some versions of µsoft.windows; have a
- <application>System</application> icon which will display a
- screen where <application>Device Manager</application> may
- be accessed.</para>
+ <application>System</application> icon which can be used to
+ access <application>Device Manager</application>.</para>
</note>
- <para>If another operating system does not exist on the machine,
- the administrator must find this information out manually. One
- method is using &man.dmesg.8; and &man.man.1;. Most device
- drivers on &os; have a manual page, listing supported hardware.
- During the boot probe, found hardware will be listed. For
+ <para>If &os; is the only installed operating system,
+ use &man.dmesg.8; to determine the hardware that was found and
+ listed during the boot probe. Most device
+ drivers on &os; have a manual page which lists the hardware supported by that driver.
+ For
example, the following lines indicate that the &man.psm.4;
driver found a mouse:</para>
@@ -167,32 +193,29 @@ psm0: [GIANT-LOCKED]
psm0: [ITHREAD]
psm0: model Generic PS/2 mouse, device ID 0</programlisting>
- <para>This driver will need to be included in the custom kernel
- configuration file or loaded using &man.loader.conf.5;.</para>
+ <para>Since this hardware exists, this driver should not be removed from a custom kernel
+ configuration file.</para>
- <para>On occasion, the data from <command>dmesg</command> will
- only show system messages instead of the boot probe output. In
- these situations, the output may be obtained by reading
+ <para>If the output of <command>dmesg</command> does not display
+ the results of the boot probe output, instead read the contents of
<filename>/var/run/dmesg.boot</filename>.</para>
- <para>Another method for finding hardware is to use
- &man.pciconf.8; which provides more verbose output. For
+ <para>Another tool for finding hardware is
+ &man.pciconf.8;, which provides more verbose output. For
example:</para>
- <programlisting>ath0 at pci0:3:0:0: class=0x020000 card=0x058a1014 chip=0x1014168c rev=0x01 hdr=0x00
+ <programlisting><command>pciconf <option>-lv</option></command>
+ ath0 at pci0:3:0:0: class=0x020000 card=0x058a1014 chip=0x1014168c rev=0x01 hdr=0x00
vendor = 'Atheros Communications Inc.'
device = 'AR5212 Atheros AR5212 802.11abg wireless'
class = network
subclass = ethernet</programlisting>
- <para>This output, obtained by using
- <command>pciconf <option>-lv</option></command>, shows that the
+ <para>This output shows that the
<devicename>ath</devicename> driver located a wireless Ethernet
- device. Type <command>man
- <replaceable>ath</replaceable></command> to read
- &man.ath.4;.</para>
+ device.</para>
- <para>The <option>-k</option> flag, when passed to &man.man.1;
+ <para>The <option>-k</option> flag of &man.man.1;
can be used to provide useful information. For example, to
display a list of manual pages which contain the specified
word:</para>
@@ -202,253 +225,85 @@ psm0: model Generic PS/2 mouse, device I
<programlisting>ath(4) - Atheros IEEE 802.11 wireless network driver
ath_hal(4) - Atheros Hardware Access Layer (HAL)</programlisting>
- <para>Armed with a hardware inventory list, the process of
- building a custom kernel should appear less daunting.</para>
+ <para>Once the hardware inventory list is created, refer to it
+ to ensure that installed hardware is not removed as you edit the custom
+ kernel configuration file.</para>
</sect1>
- <sect1 id="kernelconfig-modules">
- <title>Kernel Drivers, Subsystems, and Modules</title>
-
- <indexterm>
- <primary>kernel</primary>
- <secondary>drivers / modules / subsystems</secondary>
- </indexterm>
-
- <para>Before building a custom kernel, consider the reason for
- doing so. If there is a need for specific hardware support,
- it may already exist as a module.</para>
-
- <para>Kernel modules exist in <filename
- class="directory">/boot/kernel</filename> and may be
- dynamically loaded into the running kernel using
- &man.kldload.8;. Most, if not all kernel drivers have a
- loadable module and manual page. For example, the &man.ath.4;
- wireless Ethernet driver has the following information in its
- manual page:</para>
-
- <programlisting>Alternatively, to load the driver as a module at boot time, place the
-following line in &man.loader.conf.5;:
-
- if_ath_load="YES"</programlisting>
-
- <para>Adding <literal>if_ath_load="YES"</literal> to
- <filename>/boot/loader.conf</filename> will enable loading this
- module dynamically at boot time.</para>
-
- <para>In some cases, there is no associated module. This is
- mostly true for certain subsystems. One way to tell if a driver
- is available is to check for the module itself.</para>
-
- <warning>
- <para>It is easy to remove support for a device or option and
- end up with a broken kernel. For example, if the &man.ata.4;
- driver is removed from the kernel configuration file, a system
- using <acronym>ATA</acronym> disk drivers may not boot. When
- in doubt, just leave support in the kernel.</para>
- </warning>
- </sect1>
-
- <sect1 id="kernelconfig-building">
- <title>Building and Installing a Custom Kernel</title>
-
- <indexterm>
- <primary>kernel</primary>
- <secondary>building / installing</secondary>
- </indexterm>
+ <sect1 id="kernelconfig-config">
+ <sect1info>
+<!-- <authorgroup>
+ <author>
+ <firstname>Joel</firstname>
+ <surname>Dahl</surname>
+ <contrib>Updated by </contrib>
+ </author>
+ </authorgroup>-->
+ </sect1info>
+ <title>The Configuration File</title>
- <note>
- <para>It is required to have the full &os; source tree installed
- to build the kernel.</para>
- </note>
+ <para>In order to create a custom kernel configuration file and
+ build a custom kernel, the full &os; source tree must first be installed.</para>
- <para>The kernel build is located at <filename
- class="directory">/usr/src/sys</filename>. It contains a
- number of subdirectories representing different parts of the
- kernel. These include <filename
- class="directory"><replaceable>arch</replaceable>/conf</filename>,
- which contains the kernel configuration file, and
- <filename class="directory">compile</filename>, which is the
- staging area where the kernel will be built.
- <replaceable>arch</replaceable> contains subdirectories for each
- supported architecture: <filename
- class="directory">i386</filename>, <filename
+ <para>If <filename class="directory">/usr/src/</filename> does
+ not exist or it is empty, source has not been installed.
+ Source can be installed using
+ <application>svn</application>, which is described in <xref
+ linkend="svn"/>, or by installing the
+ <literal>src</literal> distribution using &man.sysinstall.8;. This
+ distribution can be selected by navigating to the
+ <literal>Configuration</literal> and then to the
+ <literal>Distributions</literal> menu within &man.sysinstall.8;.</para>
+
+ <para>Once source is installed, review the contents of <filename
+ class="directory">/usr/src/sys</filename>. This directory contains a
+ number of subdirectories, including those which represent the following
+ supported architectures: <filename
class="directory">amd64</filename>, <filename
+ class="directory">i386</filename>, <filename
class="directory">ia64</filename>, <filename
- class="directory">powerpc</filename>, <filename
- class="directory">sparc64</filename>, and <filename
- class="directory">pc98</filename>. Everything inside a
+ class="directory">pc98</filename>, <filename
+ class="directory">powerpc</filename>, and <filename
+ class="directory">sparc64</filename>. Everything inside a
particular architecture's directory deals with that architecture
only and the rest of the code is machine independent code common
- to all platforms. Notice the logical organization of the
- directory structure, with each supported device, file system,
- and option in its own subdirectory.</para>
-
- <para>The examples in this chapter assume the i386 architecture.
- If the system has a different architecture, change the path
- names accordingly.</para>
-
- <note>
- <para>If <filename class="directory">/usr/src/</filename> does
- not exist or it is empty, source has not been installed. The
- easiest way to install source is to use
- <application>svn</application> as described in <xref
- linkend="svn"/>. One should also create a symlink to
- <filename class="directory">/usr/src/sys/</filename>:</para>
-
- <screen>&prompt.root; <userinput>ln -s /usr/src/sys /sys</userinput></screen>
- </note>
-
- <para>Next, <application>cd</application> to <filename
- class="directory"><replaceable>arch</replaceable>/conf</filename>
- and copy the <filename>GENERIC</filename> configuration file to
- the name of the custom kernel. For example:</para>
-
- <screen>&prompt.root; <userinput>cd /usr/src/sys/<replaceable>i386</replaceable>/conf</userinput>
-&prompt.root; <userinput>cp GENERIC <replaceable>MYKERNEL</replaceable></userinput></screen>
-
- <para>Traditionally, this name is in all capital letters. When
+ to all platforms. Each supported architecture has a <filename
+ class="directory">conf</filename> subdirectory
+ which contains the <filename>GENERIC</filename> kernel
+ configuration file for that architecture.</para>
+
+ <para>Do not make edits to <filename>GENERIC</filename>. Instead,
+ copy the file to a different name and make edits to the copy.
+ The convention is to use a name with all capital letters. When
maintaining multiple &os; machines with different hardware, it
is a good idea to name it after the machine's hostname. This
- example uses
- <filename><replaceable>MYKERNEL</replaceable></filename>.</para>
+ example creates a custom configuration file for the
+ <literal>amd64</literal> architecture:</para>
+
+ <screen>&prompt.root; <userinput>cd /usr/src/sys/<replaceable>amd64</replaceable>/conf</userinput>
+&prompt.root; <userinput>cp GENERIC <replaceable>MYKERNEL</replaceable></userinput></screen>
<tip>
<para>When finished customizing the kernel configuration file,
save a backup copy to a location outside of <filename
- class="directory">/usr/src</filename>. Do not edit
- <filename>GENERIC</filename> directly.</para>
+ class="directory">/usr/src</filename>.</para>
<para>Alternately, keep the kernel configuration file elsewhere
- and create a symbolic link to the file in <filename
- class="directory"><replaceable>i386</replaceable></filename>.</para>
+ and create a symbolic link to the file:</para>
- <para>For example:</para>
-
- <screen>&prompt.root; <userinput>cd /usr/src/sys/<replaceable>i386</replaceable>/conf</userinput>
+ <screen>&prompt.root; <userinput>cd /usr/src/sys/<replaceable>amd64</replaceable>/conf</userinput>
&prompt.root; <userinput>mkdir /root/kernels</userinput>
&prompt.root; <userinput>cp GENERIC /root/kernels/<replaceable>MYKERNEL</replaceable></userinput>
&prompt.root; <userinput>ln -s /root/kernels/<replaceable>MYKERNEL</replaceable></userinput></screen>
</tip>
- <para>Edit
- <filename><replaceable>MYKERNEL</replaceable></filename>
- with a text editor. The default editor is
- <application>vi</application>, whose usage is covered well in
- many books in the <link
- linkend="bibliography">bibliography</link>. An easier editor
+ <para>The configuration file
+ <filename><replaceable>MYKERNEL</replaceable></filename> can now be customized
+ with any ASCII text editor. The default editor is
+ <application>vi</application>, though an easier editor
for beginners, called <application>ee</application>, is also
- available. Feel free to change the comment lines at the top to
- reflect the configuration or the changes made to differentiate
- it from <filename>GENERIC</filename>.</para>
-
- <para>If the <filename>GENERIC</filename> configuration file seems
- overwhelming, follow the descriptions in the <link
- linkend="kernelconfig-config">Configuration File</link>
- section slowly and carefully.</para>
-
- <note>
- <para>After <link linkend="svn">syncing the source tree</link>
- with the latest sources, <emphasis>always</emphasis> read
- <filename class="directory">/usr/src/UPDATING</filename>
- before performing any update steps. This file describes any
- important issues or areas requiring special attention within
- the updated source code.
- <filename>/usr/src/UPDATING</filename> always matches
- the version of the &os; source and contains more up-to-date
- information than this Handbook.</para>
- </note>
-
- <para>After saving the edits, compile the source code for the
- kernel.</para>
-
- <procedure>
- <title>Building a Kernel</title>
-
- <note>
- <para>It is required to have the full &os; source tree
- installed to build the kernel.</para>
- </note>
-
- <step>
- <para><command>cd</command> to <filename
- class="directory">/usr/src</filename>:</para>
-
- <screen>&prompt.root; <userinput>cd /usr/src</userinput></screen>
- </step>
-
- <step>
- <para>Compile the new kernel by specifying the name of the
- custom kernel configuration file:</para>
-
- <screen>&prompt.root; <userinput>make buildkernel KERNCONF=<replaceable>MYKERNEL</replaceable></userinput></screen>
- </step>
-
- <step>
- <para>Install the new kernel:</para>
-
- <screen>&prompt.root; <userinput>make installkernel KERNCONF=<replaceable>MYKERNEL</replaceable></userinput></screen>
- </step>
- </procedure>
-
- <tip>
- <para>By default, when a custom kernel is compiled,
- <emphasis>all</emphasis> kernel modules are rebuilt as well.
- To update a kernel faster or to build only custom modules,
- edit <filename>/etc/make.conf</filename> before starting to
- build the kernel:</para>
-
- <programlisting>MODULES_OVERRIDE = linux acpi sound/sound sound/driver/ds1 ntfs</programlisting>
-
- <para>This variable specifies the list of modules to build
- instead the default of building of all of them.</para>
-
- <programlisting>WITHOUT_MODULES = linux acpi sound ntfs</programlisting>
-
- <para>This variable sets up a list of top level modules to
- exclude from the build process. For other available
- variables, refer to &man.make.conf.5;.</para>
- </tip>
-
- <indexterm>
- <primary><filename
- class="directory">/boot/kernel.old</filename></primary>
- </indexterm>
-
- <para>The new kernel will be copied to <filename
- class="directory">/boot/kernel</filename> as
- <filename>/boot/kernel/kernel</filename> and the old kernel
- will be moved to <filename>/boot/kernel.old/kernel</filename>.
- Now, shutdown the system and reboot into the new kernel.
- If something goes wrong, refer to the <link
- linkend="kernelconfig-trouble">troubleshooting</link>
- instructions and the section which explains how to
- recover when the new kernel <link
- linkend="kernelconfig-noboot">does not boot</link>.</para>
-
- <note>
- <para>Other files relating to the boot process, such as the boot
- &man.loader.8; and configuration, are stored in <filename
- class="directory">/boot</filename>. Third party or
- custom modules can be placed in <filename
- class="directory">/boot/kernel</filename>, although users
- should be aware that keeping modules in sync with the compiled
- kernel is very important. Modules not intended to run with
- the compiled kernel may result in instability.</para>
- </note>
- </sect1>
-
- <sect1 id="kernelconfig-config">
- <sect1info>
- <authorgroup>
- <author>
- <firstname>Joel</firstname>
- <surname>Dahl</surname>
- <contrib>Updated by </contrib>
- </author>
- </authorgroup>
- </sect1info>
- <title>The Configuration File</title>
-
+ installed with &os;.</para>
+
<indexterm>
<primary>kernel</primary>
<secondary>NOTES</secondary>
@@ -459,14 +314,18 @@ following line in &man.loader.conf.5;:
<secondary>configuration file</secondary>
</indexterm>
- <para>The general format of a configuration file is quite simple.
- Each line contains a keyword and one or more arguments. For
- simplicity, most lines only contain one argument. Anything
- following a <literal>#</literal> is considered a comment and
- ignored. The following sections describe each keyword, in
- the order they are listed in <filename>GENERIC</filename>.
- For an exhaustive list of architecture dependent options and
- devices, refer to <filename>NOTES</filename> in the same
+ <para>The format of the kernel configuration file is simple.
+ Each line contains a keyword that represents a device or
+ subsystem, an argument, and a brief description. Any text
+ after a <literal>#</literal> is considered a comment and
+ ignored. To remove kernel support for a device or subsystem,
+ put a <literal>#</literal> at the beginning of the line
+ representing that device or subsystem. Do not add or remove a
+ <literal>#</literal> for any line that you do not understand.</para>
+
+ <para>In addition to the brief descriptions provided in this file, additional
+ descriptions are contained in
+ <filename>NOTES</filename>, which can be found in the same
directory as <filename>GENERIC</filename> for that architecture.
For architecture independent options, refer to
<filename>/usr/src/sys/conf/NOTES</filename>.</para>
@@ -490,60 +349,18 @@ options IPDIVERT</programlisting
<para>Using this method, the local configuration file expresses
local differences from a <filename>GENERIC</filename>
kernel. As upgrades are performed, new features added to
- <filename>GENERIC</filename> will be also be added to the local
+ <filename>GENERIC</filename> will also be added to the local
kernel unless they are specifically prevented using
<literal>nooptions</literal> or <literal>nodevice</literal>.
A comprehensive list of configuration directives and their
descriptions may be found in &man.config.5;.</para>
- <para>The remainder of this chapter addresses the contents of a
- typical configuration file and the role various options and
- devices play.</para>
-
<note>
<para>To build a file which contains all available options,
run the following command as <username>root</username>:</para>
<screen>&prompt.root; <userinput>cd /usr/src/sys/<replaceable>i386</replaceable>/conf && make LINT</userinput></screen>
</note>
- <indexterm>
- <primary>kernel</primary>
- <secondary>configuration file</secondary>
- </indexterm>
-
- <para>The following is an example of the
- <filename>GENERIC</filename> kernel configuration file with
- various additional comments where needed for clarity. This
- example should match the copy in
- <filename>/usr/src/sys/<replaceable>i386</replaceable>/conf/GENERIC</filename>
- fairly closely.</para>
-
- <indexterm>
- <primary>kernel options</primary>
- <secondary>machine</secondary>
- </indexterm>
-
- <programlisting>machine i386</programlisting>
-
- <para>This is the machine architecture. It must be either
- <literal>amd64</literal>, <literal>i386</literal>,
- <literal>ia64</literal>, <literal>pc98</literal>,
- <literal>powerpc</literal>, or
- <literal>sparc64</literal>.</para>
-
- <indexterm>
- <primary>kernel options</primary>
- <secondary>cpu</secondary>
- </indexterm>
- <programlisting>cpu I486_CPU
-cpu I586_CPU
-cpu I686_CPU</programlisting>
-
- <para>This option specifies the type of CPU. It is fine to have
- multiple instances of the CPU entries, but for a custom kernel
- it is best to specify the CPU. To determine the CPU type,
- review the boot messages in
- <filename>/var/run/dmesg.boot</filename>.</para>
<indexterm>
<primary>kernel options</primary>
@@ -558,19 +375,6 @@ cpu I686_CPU</programlisting>
The value in the <literal>ident</literal> string will
print when the kernel boots.</para>
- <programlisting>#To statically compile in device wiring instead of /boot/device.hints
-#hints "GENERIC.hints" # Default places to look for devices.</programlisting>
-
- <para>&man.device.hints.5; is used to configure options for device
- drivers. The default location is
- <filename>/boot/device.hints</filename>. The
- <literal>hints</literal> option compiles these hints statically
- into the kernel so that there is no need to create
- <filename>/boot/device.hints</filename>.</para>
-
- <!-- XXX: Add a comment here that explains when compiling hints into
- the kernel is a good idea and why. -->
-
<programlisting>makeoptions DEBUG=-g # Build kernel with gdb(1) debug symbols</programlisting>
<para>This option enables debugging information when passed to
@@ -580,12 +384,6 @@ cpu I686_CPU</programlisting>
<para>The default system scheduler for &os;. Keep this.</para>
- <programlisting>options PREEMPTION # Enable kernel thread preemption</programlisting>
-
- <para>Allows kernel threads to be preempted by higher priority
- threads. This helps with interactivity and allows interrupt
- threads to run sooner rather than waiting.</para>
-
<programlisting>options INET # InterNETworking</programlisting>
<para>Networking support. This is mandatory as most programs
@@ -1370,6 +1168,112 @@ device fwe # Ethernet
</sect2>
</sect1>
+ <sect1 id="kernelconfig-building">
+ <title>Building and Installing a Custom Kernel</title>
+
+ <para>After saving the edits, compile the source code for the
+ kernel.</para>
+
+ <note>
+ <para>After <link linkend="svn">syncing the source tree</link>
+ with the latest sources, <emphasis>always</emphasis> read
+ <filename class="directory">/usr/src/UPDATING</filename>
+ before performing any update steps. This file describes any
+ important issues or areas requiring special attention within
+ the updated source code.
+ <filename>/usr/src/UPDATING</filename> always matches
+ the version of the &os; source and contains more up-to-date
+ information than this Handbook.</para>
+ </note>
+
+ <warning>
+ <para>It is easy to remove support for a device or option and
+ end up with a broken kernel. For example, if the &man.ata.4;
+ driver is removed from the kernel configuration file, a system
+ using <acronym>ATA</acronym> disk drivers may not boot. When
+ in doubt, just leave support in the kernel.</para>
+ </warning>
+
+ <procedure>
+ <title>Building a Kernel</title>
+ <indexterm>
+ <primary>kernel</primary>
+ <secondary>building / installing</secondary>
+ </indexterm>
+
+ <note>
+ <para>It is required to have the full &os; source tree
+ installed to build the kernel.</para>
+ </note>
+
+ <step>
+ <para><command>cd</command> to <filename
+ class="directory">/usr/src</filename>:</para>
+
+ <screen>&prompt.root; <userinput>cd /usr/src</userinput></screen>
+ </step>
+
+ <step>
+ <para>Compile the new kernel by specifying the name of the
+ custom kernel configuration file:</para>
+
+ <screen>&prompt.root; <userinput>make buildkernel KERNCONF=<replaceable>MYKERNEL</replaceable></userinput></screen>
+ </step>
+
+ <step>
+ <para>Install the new kernel:</para>
+
+ <screen>&prompt.root; <userinput>make installkernel KERNCONF=<replaceable>MYKERNEL</replaceable></userinput></screen>
+ </step>
+ </procedure>
+
+ <tip>
+ <para>By default, when a custom kernel is compiled,
+ <emphasis>all</emphasis> kernel modules are rebuilt as well.
+ To update a kernel faster or to build only custom modules,
+ edit <filename>/etc/make.conf</filename> before starting to
+ build the kernel:</para>
+
+ <programlisting>MODULES_OVERRIDE = linux acpi sound/sound sound/driver/ds1 ntfs</programlisting>
+
+ <para>This variable specifies the list of modules to build
+ instead the default of building of all of them.</para>
+
+ <programlisting>WITHOUT_MODULES = linux acpi sound ntfs</programlisting>
+
+ <para>This variable sets up a list of top level modules to
+ exclude from the build process. For other available
+ variables, refer to &man.make.conf.5;.</para>
+ </tip>
+
+ <indexterm>
+ <primary><filename
+ class="directory">/boot/kernel.old</filename></primary>
+ </indexterm>
+
+ <para>The new kernel will be copied to <filename
+ class="directory">/boot/kernel</filename> as
+ <filename>/boot/kernel/kernel</filename> and the old kernel
+ will be moved to <filename>/boot/kernel.old/kernel</filename>.
+ Now, shutdown the system and reboot into the new kernel.
+ If something goes wrong, refer to the <link
+ linkend="kernelconfig-trouble">troubleshooting</link>
+ instructions and the section which explains how to
+ recover when the new kernel <link
+ linkend="kernelconfig-noboot">does not boot</link>.</para>
+
+ <note>
+ <para>Other files relating to the boot process, such as the boot
+ &man.loader.8; and configuration, are stored in <filename
+ class="directory">/boot</filename>. Third party or
+ custom modules can be placed in <filename
+ class="directory">/boot/kernel</filename>, although users
+ should be aware that keeping modules in sync with the compiled
+ kernel is very important. Modules not intended to run with
+ the compiled kernel may result in instability.</para>
+ </note>
+ </sect1>
+
<sect1 id="kernelconfig-trouble">
<title>If Something Goes Wrong</title>
More information about the svn-doc-head
mailing list