From dan@xeon.unixathome.org  Mon Jan  8 02:44:01 2001
Return-Path: <dan@xeon.unixathome.org>
Received: from xeon.unixathome.org (ns1.unixathome.org [203.79.82.27])
	by hub.freebsd.org (Postfix) with ESMTP id 8C2A637B6A7
	for <FreeBSD-gnats-submit@freebsd.org>; Mon,  8 Jan 2001 02:43:57 -0800 (PST)
Received: (from dan@localhost)
	by xeon.unixathome.org (8.11.1/8.11.1) id f08AigF48967;
	Mon, 8 Jan 2001 23:44:42 +1300 (NZDT)
	(envelope-from dan)
Message-Id: <200101081044.f08AigF48967@xeon.unixathome.org>
Date: Mon, 8 Jan 2001 23:44:42 +1300 (NZDT)
From: dan@freebsddiary.org
Sender: dan@xeon.unixathome.org
Reply-To: dan@freebsddiary.org
To: FreeBSD-gnats-submit@freebsd.org
Subject: improve kernel building description
X-Send-Pr-Version: 3.2

>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:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Mon Jan 08 02:50:03 PST 2001
>Closed-Date:    Thu Jan 18 01:48:45 PST 2001
>Last-Modified:  Thu Jan 18 01:49:03 PST 2001
>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:

From: "Dan Langille" <dan@langille.org>
To: freebsd-gnats-submit@FreeBSD.org
Cc: dan@freebsddiary.org
Subject: Re: docs/24148: current instructions for kernel building are not clear in some areas
Date: Thu, 11 Jan 2001 19:32:50 +1300

 BTW: please, someone [with more technical knowledge than I have] 
 read this carefully.  I think it's correct and will lead to less hassles for 
 novices.
 
 thanks
 
 --
 Dan Langille
 The FreeBSD Diary - http://freebsddiary.org/
        FreshPorts - http://freshports.org/
      NZ Broadband - http://unixathome.org/broadband/
 
State-Changed-From-To: open->closed 
State-Changed-By: asmodai 
State-Changed-When: Thu Jan 18 01:48:45 PST 2001 
State-Changed-Why:  
At originator's request. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=24148 
>Unformatted:
