Date: Mon, 8 Jan 2001 23:44:42 +1300 (NZDT) From: dan@freebsddiary.org To: FreeBSD-gnats-submit@freebsd.org Subject: docs/24148: improve kernel building description Message-ID: <200101081044.f08AigF48967@xeon.unixathome.org>
next in thread | raw e-mail | index | archive | help
>Number: 24148
>Category: docs
>Synopsis: current instructions for kernel building are not clear in some areas
>Confidential: no
>Severity: non-critical
>Priority: low
>Responsible: freebsd-doc
>State: open
>Quarter:
>Keywords:
>Date-Required:
>Class: doc-bug
>Submitter-Id: current-users
>Arrival-Date: Mon Jan 08 02:50:03 PST 2001
>Closed-Date:
>Last-Modified:
>Originator: Dan Langille
>Release: FreeBSD 4.2-STABLE i386
>Organization:
The FreeBSD Diary
>Environment:
>Description:
We're seeing lots of people getting confused about config -r and make buildkernel. This should help.
>How-To-Repeat:
>Fix:
Patch supplied:
--- 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
>Release-Note:
>Audit-Trail:
>Unformatted:
To Unsubscribe: send mail to majordomo@FreeBSD.org
with "unsubscribe freebsd-doc" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?200101081044.f08AigF48967>