From ripper@eskimo.com  Fri Aug  2 13:00:25 2002
Return-Path: <ripper@eskimo.com>
Received: from mx1.FreeBSD.org (mx1.FreeBSD.org [216.136.204.125])
	by hub.freebsd.org (Postfix) with ESMTP id 9362B37B400
	for <FreeBSD-gnats-submit@freebsd.org>; Fri,  2 Aug 2002 13:00:25 -0700 (PDT)
Received: from mx1.eskimo.com (mx1.eskimo.com [204.122.16.48])
	by mx1.FreeBSD.org (Postfix) with ESMTP id 8866F43E42
	for <FreeBSD-gnats-submit@freebsd.org>; Fri,  2 Aug 2002 13:00:23 -0700 (PDT)
	(envelope-from ripper@eskimo.com)
Received: from eskimo.com (ripper@eskimo.com [204.122.16.13])
	by mx1.eskimo.com (8.9.1a/8.8.8) with ESMTP id NAA13625
	for <FreeBSD-gnats-submit@freebsd.org>; Fri, 2 Aug 2002 13:00:11 -0700
Received: (from ripper@localhost)
	by eskimo.com (8.9.1a/8.9.1) id NAA01171;
	Fri, 2 Aug 2002 13:00:11 -0700 (PDT)
Message-Id: <200208022000.NAA01171@eskimo.com>
Date: Fri, 2 Aug 2002 13:00:11 -0700 (PDT)
From: "Ross A. Lippert" <ripper@eskimo.com>
Reply-To: "Ross A. Lippert" <ripper@eskimo.com>
To: FreeBSD-gnats-submit@freebsd.org
Cc:
Subject: confusing directions for kernelconfig chapter
X-Send-Pr-Version: 3.113
X-GNATS-Notify:

>Number:         41270
>Category:       docs
>Synopsis:       [patch] handbook: confusing directions for kernelconfig chapter
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    remko
>State:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Fri Aug 02 13:10:01 PDT 2002
>Closed-Date:    Wed May 28 00:13:03 UTC 2008
>Last-Modified:  Wed May 28 00:13:03 UTC 2008
>Originator:     Ross A. Lippert
>Release:        FreeBSD 4.5-RELEASE i386
>Organization:
>Environment:
System: FreeBSD lipperra-p1.rkv.ad.celera.com 4.5-RELEASE FreeBSD 4.5-RELEASE #2: Fri Apr 26 15:35:00 EDT 2002 ripper@lipperra-p1.celera.com:/usr/src/sys/compile/ROSSBOX i386

>Description:
	There are some grammar and phrasing problems.

	But more importantly, this chapter does not have a very good
	separation of the different issues between a simple kernel
	build and a complicated one, so users who just want to add an
	option end up learning more about make world than they'd want.

	At least, rdm@cfcl.com had trouble with it.

>How-To-Repeat:
	Read it.  Notice how you get told all sorts of stuff to worry
	about followed by a sentence telling you it doesn't apply if
	you aren't updating/making world.

>Fix:

Proposed patch:

Index: en_US.ISO8859-1/books/handbook/kernelconfig/chapter.sgml
===================================================================
RCS file: /home/ncvs/doc/en_US.ISO8859-1/books/handbook/kernelconfig/chapter.sgml,v
retrieving revision 1.78
diff -c -r1.78 chapter.sgml
*** en_US.ISO8859-1/books/handbook/kernelconfig/chapter.sgml	2002/07/01 18:38:17	1.78
--- en_US.ISO8859-1/books/handbook/kernelconfig/chapter.sgml	2002/08/02 19:53:10
***************
*** 136,165 ****
      <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
!       accessible through <filename>/sys</filename>.  There are a number of
        subdirectories here representing different parts of the kernel, but
!       the most important, for our purposes, are
        <filename><replaceable>arch</replaceable>/conf</filename>, where you
!       will edit your custom kernel configuration, and
        <filename>compile</filename>, which is the staging area where your
        kernel will be built.  <replaceable>arch</replaceable> represents
!       either <filename>i386</filename>, <filename>alpha</filename>, or
        <filename>pc98</filename> (an alternative development branch of PC
        hardware, popular in Japan).  Everything inside a particular
        architecture's directory deals with that architecture only; the rest
!       of the code is common to all platforms to which FreeBSD could
!       potentially be ported.  Notice the logical organization of the
!       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 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>.  If you
	have an aversion to <ommand line:</para>
--- 136,168 ----
      <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
!       accessible through <filename>/sys</filename> via a symbolic link.
!       There are a number of
        subdirectories here represen        editor.  If you are just starting out, the only editor available
--- 198,211 ----
  &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>
  
!       <para>Storing your kernel config file directly under
!	<filename>/usr/src</filename> can be a bad idea.  If you are
!	experiencing problems it can be tempting to just delete
!	<filename>/usr/src</filename> and start again.  Five setor o     If you are trying to <link	
          linkend="cutting-edge">sync your source-tree</link> with the
!	latest sources of the FreeBSD project, be sure to check
!	the file 
!         <filename>/usr/src/UPDATING</filename>, before performing any
!	updates.
!         All important issues with updating FreeBSD
!         are written down in this file.
!	<filename>/usr/src/UPDATING</filename> always fits with
!         your version of the FreeBSD sources, and is therefore more accurate
!         for those information than the handbook.</para>
      </note>
  
!     <para>You must now compile the source code for the kernel.  There are two
!       procedures you can use to do this, and the one you will use depends on
!       why you are rebuilding the kernel, and the version of FreeBSD you are
!       running.</para>
! 
!     <itemizedlist>
!       <listitem>
!	<para>If you have installed <emphasis>only</emphasis> the kernel
!	  source code, use procedure 1.</para>
!       </listitem>
! 
!       <listitem>
!	<para>If you are running a FreeBSD version prior to 4.0, and you are
!	  <emphasis>not</emphasis> upgrading to FreeBSD 4.0 or higher using
!	  the <maketarget>make world</maketarget> procedure, use procedure 1.
!         </para>
!       </listitem>
! 
!       <listitem>
!	<para>If you are building a new kernel without updating the source
!	  code (perhaps just to add a new option, such as
!	  <literal>IPFIREWALL</literal>) you can use either procedure.</para>
!       </listitem>
! 
!       <listitem>
!	<para>If you are rebuilding the kernel as part of a
!           <maketarget>make world</maketarget> process, use procedure 2.
!         </para>
!       </listitem>
!     </itemizedlist>
!     
      <procedure>
!       <title>Procedure 1.  Building a kernel the <quote>traditional</quote> way</title>
        
        <step>
	<para>Run &man.config.8; to generate the kernel source code.</para>
	
!	<screen>&prompt.root; <userinput>/usr/sbin/config <replaceable>MYKERNEL</replaceable></userinput></screen>
        </step>
  
        <step>
--- 228,275 ----
        section slowly and carefully.</para>
  
      <note>
!       <para>
!         If you are trying to <link	
          linkend="cutting-edge">sync your source-tree</link> with the
!	latest sources of the FreeBSD project, be sure to check
!	the file 
!         <filename>/usr/src/UPDATING</filename>, before performing any
!	updates.
!         All important issues with updating FreeBSD
!         are written down in this file.
!	<filename>/usr/src/UPDATING</filename> always fits with
!         your version of the FreeBSD source and is more accurate
!         than the information in this handbook.</para>
      </note>
  
!     <indexterm>
!       <primary><command>cvsup</command></primary>
!     </indexterm>
!     <indexterm><primary>anonymous CVS</primary></indexterm>
!     <indexterm><primary>CTM</primary></indexterm>
!     <indexterm>
!       <primary>CVS</primary>
!       <secondary>anonymous</secondary>
!     </indexterm>
! 
!     <para>You must now compile and install the source code for the kernel.
!       There are two ways of doing this.
!       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 do the first.
!       If you are updating/rebuilding your whole system, or upgrading your
!       kernel to a FreeBSD version with a greater major version number
!       (e.g. 3.X to 4.X), then do the second.</para>
! 
! 
      <procedure>
!       <title>Building/Installing the kernel alone</title>
        
        <step>
	<para>Run &man.config.8; to generate the kernel source code.</para>
	
!	<screen>&prompt.root; <userinput>/usr/sbin/config -g <replaceable>MYKERNEL</replaceable></userinput></screen>
        </step>
  
        <step>
***************
*** 303,310 ****
      </procedure>
  
      <procedure>
!       <title>Procedure 2.  Building a kernel the <quote>new</quote>
!	way</title>
        
        <step>
	<para>Change to the <filename>/usr/src</filename> directory.</para>
--- 293,299 ----
      </procedure>
  
      <procedure>
!       <title>Building/Installing as part of a <maketarget>make world</maketarget> process.</title>
        
        <step>
	<para>Change to the <filename>/usr/src</filename> directory.</para>
***************
*** 332,354 ****
          recognize <literal>KERNCONF=</literal>.</para>
      </note>
  
-     <indexterm>
-       <primary><command>cvsup</command></primary>
-     </indexterm>
-     <indexterm><ndexterm><primary>CTM</primary></indexterm>
-     <indexterm>
-       <primary>CVS</primary>
-       <secondary>anonymous</secondary>
-     </indexterm>
- 
-     <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>, <maketarget>make depend</maketarget>,
-       <command>make</command>, <maketarget>make install</maketarget> sequence.
-     </para>
  
      <indexterm>
        <primary><filename>kernel.old</filename></primary>
--- 321,326 ----
***************
*** 356,363 ****
  
      <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
!       reboot to use your kernel.  In case something goes wrong, there are
        some <link linkend="kernelconfig-trouble">troubleshooting</link>
        instructions at the end of this chapter.  Be sure to read the
        section which explains how to recover in case your new kernel <link
--- 328,335 ----
  
      <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>.  On the next boot, your system
!       will boot with the new kernel.  In case something goes wrong, there are
        some <link linkend="kernelconfig-trouble">troubleshooting</link>
        instructions at the end of this chapter.  Be sure to read the
        section which explains how to recover in case your new kernel <link



>Release-Note:
>Audit-Trail:
Responsible-Changed-From-To: gnats-admin->freebsd-doc 
Responsible-Changed-By: keramida 
Responsible-Changed-When: Mon Aug 19 17:01:02 PDT 2002 
Responsible-Changed-Why:  
Doc team stuff. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=41270 
State-Changed-From-To: open->feedback 
State-Changed-By: remko 
State-Changed-When: Mon Dec 26 18:15:39 UTC 2005 
State-Changed-Why:  
Requested feedback from the submitter. 


Responsible-Changed-From-To: freebsd-doc->remko 
Responsible-Changed-By: remko 
Responsible-Changed-When: Mon Dec 26 18:15:39 UTC 2005 
Responsible-Changed-Why:  
I will try to work this out. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=41270 
State-Changed-From-To: feedback->suspended 
State-Changed-By: linimon 
State-Changed-When: Sat Mar 1 20:05:39 UTC 2008 
State-Changed-Why:  
No feedback has been received in quite some time.  Mark this as suspended, 
since it does not seem like it is being worked on. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=41270 
State-Changed-From-To: suspended->closed 
State-Changed-By: gabor 
State-Changed-When: Wed May 28 00:12:03 UTC 2008 
State-Changed-Why:  
This chapter has been completely redesigned since this PR and the issues does 
not seem to be applicable any more. Let's close this issue. 

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