svn commit: r44288 - head/en_US.ISO8859-1/books/handbook/kernelconfig
Dru Lavigne
dru at FreeBSD.org
Wed Mar 19 16:52:26 UTC 2014
Author: dru
Date: Wed Mar 19 16:52:25 2014
New Revision: 44288
URL: http://svnweb.freebsd.org/changeset/doc/44288
Log:
Finish editorial review of kernel config chapter.
Sponsored by: iXsystems
Modified:
head/en_US.ISO8859-1/books/handbook/kernelconfig/chapter.xml
Modified: head/en_US.ISO8859-1/books/handbook/kernelconfig/chapter.xml
==============================================================================
--- head/en_US.ISO8859-1/books/handbook/kernelconfig/chapter.xml Wed Mar 19 15:55:02 2014 (r44287)
+++ head/en_US.ISO8859-1/books/handbook/kernelconfig/chapter.xml Wed Mar 19 16:52:25 2014 (r44288)
@@ -300,7 +300,15 @@ ath_hal(4) - Atheros Hardw
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
<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
<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
<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
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
<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
</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>
More information about the svn-doc-all
mailing list