Date: Wed, 19 Mar 2014 16:52:25 +0000 (UTC) From: Dru Lavigne <dru@FreeBSD.org> To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r44288 - head/en_US.ISO8859-1/books/handbook/kernelconfig Message-ID: <201403191652.s2JGqPC1034440@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
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>
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201403191652.s2JGqPC1034440>