From owner-freebsd-doc  Tue Dec 25 22:10:10 2001
Delivered-To: freebsd-doc@freebsd.org
Received: from freefall.freebsd.org (freefall.FreeBSD.org [216.136.204.21])
	by hub.freebsd.org (Postfix) with ESMTP id 7866937B41E
	for <freebsd-doc@freebsd.org>; Tue, 25 Dec 2001 22:10:02 -0800 (PST)
Received: (from gnats@localhost)
	by freefall.freebsd.org (8.11.6/8.11.6) id fBQ6A2r88561;
	Tue, 25 Dec 2001 22:10:02 -0800 (PST)
	(envelope-from gnats)
Received: from guru.mired.org (okc-65-31-201-166.mmcable.com [65.31.201.166])
	by hub.freebsd.org (Postfix) with SMTP id D608437B417
	for <FreeBSD-gnats-submit@freebsd.org>; Tue, 25 Dec 2001 22:09:02 -0800 (PST)
Received: (qmail 47688 invoked by uid 100); 26 Dec 2001 06:09:01 -0000
Message-Id: <20011226060901.47687.qmail@guru.mired.org>
Date: 26 Dec 2001 06:09:01 -0000
From: Mike Meyer <mwm@mired.org>
Reply-To: Mike Meyer <mwm@mired.org>
To: FreeBSD-gnats-submit@freebsd.org
X-Send-Pr-Version: 3.113
Subject: docs/33184: The handbook is missing a critical step in the upgrade process
Sender: owner-freebsd-doc@FreeBSD.ORG
Precedence: bulk
List-ID: <freebsd-doc.FreeBSD.ORG>
List-Archive: <http://docs.freebsd.org/mail/> (Web Archive)
List-Help: <mailto:majordomo@FreeBSD.ORG?subject=help> (List Instructions)
List-Subscribe: <mailto:majordomo@FreeBSD.ORG?subject=subscribe%20freebsd-doc>
List-Unsubscribe: <mailto:majordomo@FreeBSD.ORG?subject=unsubscribe%20freebsd-doc>
X-Loop: FreeBSD.org


>Number:         33184
>Category:       docs
>Synopsis:       The handbook is missing a critical step in the upgrade process
>Confidential:   no
>Severity:       critical
>Priority:       medium
>Responsible:    freebsd-doc
>State:          open
>Quarter:        
>Keywords:       
>Date-Required:
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Tue Dec 25 22:10:01 PST 2001
>Closed-Date:
>Last-Modified:
>Originator:     Mike Meyer
>Release:        FreeBSD 4.4-STABLE i386
>Organization:
Meyer Consulting
>Environment:
System: FreeBSD guru.mired.org 4.4-STABLE FreeBSD 4.4-STABLE #7: Fri Nov 23 03:32:45 CST 2001 mwm@guru.mired.org:/usr/src/sys/compile/ATHLON i386


>Description:

The handbook description of building a new kernel fails to point out
that you can't safely do a "make buildkernel" after updating your
system sources until *after* you've done a "make buildworld".

>How-To-Repeat:

Read the handbook section on building a kernel, and note that the
discussion of "make buildkernel" doesn't mention this requirement at
all.

>Fix:

The attached patch corrects this oversight.

--- handbook/cutting-edge/chapter.sgml.orig	Tue Dec 25 23:50:00 2001
+++ handbook/cutting-edge/chapter.sgml	Wed Dec 26 00:04:36 2001
@@ -870,7 +870,8 @@
 
 	<screen>&prompt.root; <userinput>make <replaceable>target</replaceable></userinput></screen>
 
-	<para>Beginning with version 2.2.5 of &os; (actually, it was
+	<para id="make-buildworld">Beginning with version 2.2.5 of &os;
+	  (actually, it was
 	  first created on the &os.current; branch, and then retrofitted to
 	  &os.stable; midway between 2.2.2 and 2.2.5) the
 	  <maketarget>world</maketarget> target has been split in
@@ -971,7 +972,10 @@
 
       <para>If you are upgrading to &os; 4.0 or above then the standard
 	kernel build procedure (as described in <xref linkend="kernelconfig">)
-	is deprecated.  Instead, you should run these commands.</para>
+	is deprecated.  Instead, you should run these commands
+	<emphasis>after</emphasis> you have <link
+        linkend="make-buildworld">built the world with
+        <maketarget>buildworld</maketarget></link>.</para> 
 
       <screen>&prompt.root; <userinput>cd /usr/src</userinput>
 &prompt.root; <userinput>make buildkernel</userinput>

>Release-Note:
>Audit-Trail:
>Unformatted:

To Unsubscribe: send mail to majordomo@FreeBSD.org
with "unsubscribe freebsd-doc" in the body of the message