Date: Fri, 4 Oct 2013 17:29:34 +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: r42827 - in head/en_US.ISO8859-1/books/handbook: bsdinstall kernelconfig Message-ID: <201310041729.r94HTYYp025321@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
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@pci0:3:0:0: class=0x020000 card=0x058a1014 chip=0x1014168c rev=0x01 hdr=0x00 + <programlisting><command>pciconf <option>-lv</option></command> + ath0@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>
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201310041729.r94HTYYp025321>