os/doc
3
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Finish editorial review of kernel config chapter.

Browse source 
Sponsored by: iXsystems
This commit is contained in:
Dru Lavigne 2014-03-19 16:52:25 +00:00
parent 18a88c6710
commit 045622bc49
Notes: svn2git 2020-12-08 03:00:23 +00:00 
svn path=/head/; revision=44288
1 changed files with 64 additions and 97 deletions
Download patch file Download diff file Expand all files Collapse all files

161
en_US.ISO8859-1/books/handbook/kernelconfig/chapter.xml
View file

@ -300,7 +300,15 @@ ath_hal(4) - Atheros Hardware Access Layer (HAL)</programlisting>
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>
<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>
<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
@ -1163,28 +1171,9 @@ device fwe # Ethernet over FireWire (non-standard!)</programl
<sect1 xml: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>/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>
<para>Once the edits to the custom configuration file have been
saved, the source code for the
kernel can be compiled using the following steps:</para>
<procedure>
<title>Building a Kernel</title>
@ -1193,13 +1182,8 @@ device fwe # Ethernet over FireWire (non-standard!)</programl
<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>/usr/src</filename>:</para>
<para>Change to this directory:</para>
<screen>&prompt.root; <userinput>cd /usr/src</userinput></screen>
</step>
@ -1208,100 +1192,88 @@ device fwe # Ethernet over FireWire (non-standard!)</programl
<para>Compile the new kernel by specifying the name of the
custom kernel configuration file:</para>
<screen>&prompt.root; <userinput>make buildkernel KERNCONF=MYKERNEL</userinput></screen>
<screen>&prompt.root; <userinput>make buildkernel KERNCONF=<replaceable>MYKERNEL</replaceable></userinput></screen>
</step>
<step>
<para>Install the new kernel:</para>
<para>Install the new kernel associated with the specified
kernel configuration file. This command will copy the new kernel to
<filename>/boot/kernel/kernel</filename> and save the old kernel
to <filename>/boot/kernel.old/kernel</filename>:</para>
<screen>&prompt.root; <userinput>make installkernel KERNCONF=MYKERNEL</userinput></screen>
<screen>&prompt.root; <userinput>make installkernel KERNCONF=<replaceable>MYKERNEL</replaceable></userinput></screen>
</step>
<step>
<para>Shutdown the system and reboot into the new kernel.
If something goes wrong, refer to <xref
linkend="kernelconfig-noboot"/>.</para>
</step>
</procedure>
<tip>
<para>By default, when a custom kernel is compiled,
<emphasis>all</emphasis> kernel modules are rebuilt as well.
all kernel modules are rebuilt.
To update a kernel faster or to build only custom modules,
edit <filename>/etc/make.conf</filename> before starting to
build the kernel:</para>
build the kernel.</para>
<programlisting>MODULES_OVERRIDE = linux acpi sound/sound sound/driver/ds1 ntfs</programlisting>
<para>For example, this variable specifies the list of modules to build
instead of using the default of building all modules:</para>
<para>This variable specifies the list of modules to build
instead the default of building of all of them.</para>
<programlisting>MODULES_OVERRIDE = linux acpi ntfs</programlisting>
<para>Alternately, this variable lists which modules to
exclude from the build process:</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>
<para>Additional variables are available.
Refer to &man.make.conf.5; for details.</para>
<indexterm>
<primary><filename>/boot/kernel.old</filename></primary>
</indexterm>
<para>The new kernel will be copied to <filename>/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>/boot</filename>. Third party or
custom modules can be placed in <filename>/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 xml:id="kernelconfig-trouble">
<title>If Something Goes Wrong</title>
<para>There are four categories of trouble that can occur when
building a custom kernel. They are:</para>
building a custom kernel:</para>
<variablelist>
<varlistentry>
<term><command>config</command> fails:</term>
<term><command>config</command> fails</term>
<listitem>
<para>If &man.config.8; fails, it is probably a simple
error. Fortunately, &man.config.8; will print the line
number that it had trouble with. For example, for
this message:</para>
<para>If <command>config</command> fails, it will print the line
number that is incorrect. As an example, for
the following message, make sure that line 17 is typed correctly by
comparing it to
<filename>GENERIC</filename> or <filename>NOTES</filename>:</para>
<screen>config: line 17: syntax error</screen>
<para>Make sure the keyword on line 17 is typed correctly by
comparing it to the
<filename>GENERIC</filename> kernel or another
reference.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><command>make</command> fails:</term>
<term><command>make</command> fails</term>
<listitem>
<para>If <command>make</command> fails, it usually signals
an error in the kernel description which is not severe
enough for &man.config.8; to catch. Review the
configuration, and if you still cannot resolve the
problem, send an email to the &a.questions; with the
kernel configuration.</para>
<para>If <command>make</command> fails, it is usually due to
an error in the kernel configuration file which is not severe
enough for <command>config</command> to catch. Review the
configuration, and if the problem is not apparent,
send an email to the &a.questions; which contains the
kernel configuration file.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>The kernel does not boot:<anchor xml:id="kernelconfig-noboot"/></term>
<term>The kernel does not boot<anchor xml:id="kernelconfig-noboot"/></term>
<listitem>
<para>If the new kernel does not boot, or fails to recognize
<para>If the new kernel does not boot or fails to recognize
devices, do not panic! Fortunately, &os; has an excellent
mechanism for recovering from incompatible kernels.
Simply choose the kernel to boot from at the &os; boot
@ -1310,9 +1282,7 @@ device fwe # Ethernet over FireWire (non-standard!)</programl
prompt</quote> option. At the prompt, type
<command>boot
kernel.old</command>, or
the name of any other kernel that will boot properly.
When reconfiguring a kernel, it is always a good idea to
keep a kernel that is known to work on hand.</para>
the name of any other kernel that is known to boot properly.</para>
<para>After booting with a good kernel, check over the
configuration file and try to build it again. One helpful
@ -1323,16 +1293,14 @@ device fwe # Ethernet over FireWire (non-standard!)</programl
<note>
<para>When troubleshooting a kernel, make sure to keep
<filename>GENERIC</filename>, or some other kernel that
is known to work, on hand as a different name that will
not get erased on the next build. Do not rely on
<filename>kernel.old</filename> because when installing
a new kernel, <filename>kernel.old</filename> is
overwritten with the last installed kernel which may
be non-functional. As soon as possible, move the
working kernel to the proper <filename>/boot/kernel</filename>
location or commands such as &man.ps.1; may not work
properly. To do this, simply rename the directory
a copy of <filename>GENERIC</filename>, or some other kernel that
is known to work, as a different name that will
not get erased on the next build. This is important
because every time
a new kernel is installed, <filename>kernel.old</filename> is
overwritten with the last installed kernel, which may or
may not be bootable. As soon as possible, move the
working kernel by renaming the directory
containing the good kernel:</para>
<screen>&prompt.root; <userinput>mv /boot/kernel /boot/kernel.bad</userinput>
@ -1343,18 +1311,17 @@ device fwe # Ethernet over FireWire (non-standard!)</programl
</varlistentry>
<varlistentry>
<term>The kernel works, but &man.ps.1; does not work
any more:</term>
<term>The kernel works, but &man.ps.1; does not</term>
<listitem>
<para>If the kernel version differs from the one that the
system utilities have been built with, for example, a
-CURRENT kernel on a -RELEASE, many system status commands
kernel built from -CURRENT sources is installed on a -RELEASE system, many system status commands
like &man.ps.1; and &man.vmstat.8; will not work. To fix
this, <link linkend="makeworld">recompile and install a
world</link> built with the same version of the
source tree as the kernel. This is one reason why it is
not a good idea to use a different version of the kernel
source tree as the kernel. It is
never a good idea to use a different version of the kernel
than the rest of the operating system.</para>
</listitem>
</varlistentry>