Bug 24083
| Summary: | change layout and content of kernel building so it's easier to understand | ||
|---|---|---|---|
| Product: | Documentation | Reporter: | dan <dan> |
| Component: | Books & Articles | Assignee: | freebsd-doc (Nobody) <doc> |
| Status: | Closed FIXED | ||
| Severity: | Affects Only Me | ||
| Priority: | Normal | ||
| Version: | Latest | ||
| Hardware: | Any | ||
| OS: | Any | ||
Responsible Changed From-To: gnats-admin->freebsd-doc Misfiled State Changed From-To: open->closed Dan tells me to kill this. |
Submitter-Id: current-users Originator: Dan Langille Organization: The FreeBSD Diary Confidential: no Synopsis: We've seen a great deal of confused kernel builders over the past week. This should fix that. Severity: non-critical Priority: low Category: docs Release: FreeBSD 4.1-STABLE i386 Class: change-request Environment: Description: People are getting confused over kernel building. They are using buildkernel when they should be using config -r MYKERNEL. Hopefully the addition of sub-sections and slightly more detail will fix this. I admit to not building the HTML How-To-Repeat: Fix: --- chapter.sgml.original Fri Jan 5 17:57:36 2001 +++ chapter.sgml Fri Jan 5 19:05:48 2001 @@ -57,7 +57,15 @@ <sect1 id="kernelconfig-building"> <title>Building and Installing a Custom Kernel</title> + <para>There are two methods for building a new kernel. Which method + you use depends on whether or not you are doing a build world. If + you don't know what a "build world" you can safely ignore that method. + If you are just modifying your kernel, then you want the standard + method. The steps for each method are quite different and will + be outlined below.</para> + <sect1 id="kernelconfig-building"> + <title>Directory structure</title> <para>First, let us take a quick tour of the kernel build directory. All directories mentioned will be relative to the main <filename>/usr/src/sys</filename> directory, which is also @@ -77,17 +85,30 @@ directory structure, with each supported device, filesystem, and option in its own subdirectory.</para> - <note> - <para>If there is <emphasis>not</emphasis> a - <filename>/usr/src/sys</filename> directory on your system, then - the kernel source has not been been installed. The easiest way to - do this is by running <command>/stand/sysinstall</command> as - <username>root</username>, choosing <literal>Configure</literal>, - then <literal>Distributions</literal>, then - <literal>src</literal>, then <literal>sys</literal>.</para> - </note> - - <para>Next, move to the + <sect1 id="kernelconfig-building"> + <title>Obtaining the kernel source</title> + <para>If there is <emphasis>not</emphasis> a + <filename>/usr/src/sys</filename> directory on your system, then + the kernel source has not been been installed. The easiest way to + do this is by running <command>/stand/sysinstall</command> as + <username>root</username>, choosing <literal>Configure</literal>, + then <literal>Distributions</literal>, then + <literal>src</literal>, then <literal>sys</literal>.</para> + + <sect1 id="kernelconfig-building"> + <title>Modifying the kernel configuration file</title> + <para>The installed kernel sources include the configuration file for + the GENERIC kernel. This file is named, oddly enough, + <filename>GENERIC</filename>. Do not modify this file. By convention, + the kernel configuration file name is all upper case. Also included + with the kernel source is LINT. This file contains all the + kernel configuration options which are possible. Most options have + a description of what the option is for and any dependencies. Like + <filename>GENERIC</filename>, this file should not be modified.</para> + + <para>The first step is configuring your kernel is the creation of your + kernel configuration file. We will use <filename>GENERIC</filename> + as the starting point. Move to the <filename><replaceable>arch</replaceable>/conf</filename> directory and copy the <filename>GENERIC</filename> configuration file to the name you want to give your kernel. For example:</para> @@ -95,7 +116,7 @@ <screen>&prompt.root; <userinput>cd /usr/src/sys/i386/conf</userinput> &prompt.root; <userinput>cp GENERIC MYKERNEL</userinput></screen> - <para>Traditionally, this name is in all capital letters and, if you + <para>As mentioned above, this name is in all capital letters and, if you are maintaining multiple FreeBSD machines with different hardware, it is a good idea to name it after your machine's hostname. We will call it <filename>MYKERNEL</filename> for the purpose of this @@ -138,12 +159,14 @@ for those information than the handbook.</para> </note> - <para>When you are finished, type the following to compile and install - your kernel if you are using FreeBSD prior FreeBSD 4.0 and don't - want to upgrade to FreeBSD 4.0 or higher with this step, - or if you are using a release-version of FreeBSD and your - <filename>/usr/src/</filename> directory only contains the - <filename>sys/</filename> sub-directory.</para> + <sect1 id="kernelconfig-building"> + <title>Compiling your kernel</title> + <para>This section contains the default kernel compilation instructions. + If you are upgrading from -RELEASE to -STABLE, using FreeBSD 4.0 or + above, then the instructions on this section are for you. If you are + using before FreeBSD 4.0 and are not upgrading to FreeBSD 4.0 or above, + then this section is for you. Otherwise you should read the instructions + from the next section to see if they apply to your situation.</para> <note> <para>If you are trying to upgrade your kernel from an older version @@ -160,6 +183,8 @@ &prompt.root; <userinput>make</userinput> &prompt.root; <userinput>make install</userinput></screen> + <sect1 id="kernelconfig-building"> + <title>Alternative compilation instructions</title> <para>If you have just upgraded to a newer version of 4.X or higher (ie from 3.X to 4-STABLE, or even from 4-STABLE to a later version of 4-STABLE), make sure you have <link @@ -173,9 +198,10 @@ <para>If you have <emphasis>not</emphasis> upgraded your source tree in any way (you have not run <application>CVSup</application>, <application>CTM</application>, or used - <application>anoncvs</application>), then you should use the - <command>config</command>, <command>make depend</command>, - <command>make</command>, <command>make install</command> sequence.</para> + <application>anoncvs</application>), then you should use the instructions + from the previous section. However, if all you did was install + the kernel source using cvsup, then the instructions in the previous + section should be used.</para> <warning> <para>If you have upgraded your sources since your last kernel @@ -188,6 +214,8 @@ sources!</emphasis></para> </warning> + <sect1 id="kernelconfig-building"> + <title>Kernel installation</title> <para>The new kernel will be copied to the root directory as <filename>/kernel</filename> and the old kernel will be moved to <filename>/kernel.old</filename>. Now, shutdown the system and