From pepper@reppep.com  Tue Jun 25 15:34:32 2002
Return-Path: <pepper@reppep.com>
Received: from guest.reppep.com (guest.reppep.com [64.81.19.110])
	by hub.freebsd.org (Postfix) with ESMTP id 46E4737B401
	for <FreeBSD-gnats-submit@freebsd.org>; Tue, 25 Jun 2002 15:34:31 -0700 (PDT)
Received: by guest.reppep.com (Postfix, from userid 501)
	id F3B8FA827; Tue, 25 Jun 2002 18:34:40 -0400 (EDT)
Message-Id: <20020625223440.F3B8FA827@guest.reppep.com>
Date: Tue, 25 Jun 2002 18:34:40 -0400 (EDT)
From: Chris Pepper <pepper@rockefeller.edu>
Reply-To: Chris Pepper <pepper@rockefeller.edu>
To: FreeBSD-gnats-submit@freebsd.org
Cc:
Subject: handbook/cutting-edge/chapter.sgml: various fixes
X-Send-Pr-Version: 3.113
X-GNATS-Notify:

>Number:         39858
>Category:       docs
>Synopsis:       handbook/cutting-edge/chapter.sgml: various fixes
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    keramida
>State:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Tue Jun 25 15:40:03 PDT 2002
>Closed-Date:    Mon Jul 15 18:32:28 PDT 2002
>Last-Modified:  Mon Jul 15 18:32:28 PDT 2002
>Originator:     Chris Pepper
>Release:        FreeBSD 4.6-STABLE i386
>Organization:
>Environment:
System: FreeBSD guest.reppep.com 4.6-STABLE FreeBSD 4.6-STABLE #0: Tue Jun 25 14:38:05 EDT 2002 root@guest.reppep.com:/usr/obj/usr/src/sys/REPPEP i386


	
>Description:
	Removed some inline tabs and trailing whitespace.
	The docs suggest dropping to single-user before doing anything, but point out this can be deferred until the actual installation phase. Inserted a reminder on when to go single, if deferring.
	Clarified when "adjkerntz -i" is required -- it seemed to cause some trouble once when I ran it unnecessarily.
	Removed suggestion re: "make -j 4" on single-CPU systems. This has been confirmed on -questions to cause a slowdown, rather than faster building.
>How-To-Repeat:
	
>Fix:

	

--- chapter.sgml.diff begins here ---
Index: chapter.sgml
===================================================================
RCS file: /home/ncvs/doc/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.sgml,v
retrieving revision 1.127
diff -u -r1.127 chapter.sgml
--- chapter.sgml	2002/06/23 21:13:50	1.127
+++ chapter.sgml	2002/06/25 21:28:30
@@ -746,7 +746,7 @@
 	from the obvious benefit of making things go slightly faster,
 	reinstalling the system will touch a lot of important system
 	files, all the standard system binaries, libraries, include files
-	and so on.  Changing these on a  running system (particularly if
+	and so on.  Changing these on a running system (particularly if
 	you have active users on the system at the time) is asking for
 	trouble.</para>
 
@@ -754,7 +754,9 @@
       <para>Another method is to compile the system in multi-user mode, and
         then drop into single user mode for the installation.  If you would
         like to do it this way, simply hold off on the following steps until
-        the build has completed.</para>
+        the builds have completed; drop to single-user mode before using
+        <maketarget>installkernel</maketarget> or
+        <maketarget>installworld</maketarget>.</para>
 
       <para>As the superuser, you can execute</para>
 
@@ -778,7 +780,9 @@
 
 
         <note>
-          <para>If your CMOS clock is set to local time and not to GMT,
+          <para>If your CMOS clock is set to local time and not to GMT
+            (if the output of the <command>date</command> doesn't show the
+            correct time and zone),
             you may also need to run the following command:</para>
 <screen>&prompt.root; <userinput>adjkerntz -i</userinput></screen>
 
@@ -830,9 +834,9 @@
 	  when the process has finished.</para>
 
 	<screen>&prompt.root; <userinput>script /var/tmp/mw.out</userinput>
-Script started, output file is /var/tmp/mw.out	 
+Script started, output file is /var/tmp/mw.out
 &prompt.root; <userinput>make TARGET</userinput>
-<emphasis>&hellip; compile, compile, compile &hellip;</emphasis>	  
+<emphasis>&hellip; compile, compile, compile &hellip;</emphasis>
 &prompt.root; <userinput>exit</userinput>
 Script done, &hellip;</screen>
 
@@ -944,18 +948,8 @@
  
         <para>It is now possible to specify a <option>-j</option> option to
           <command>make</command> which will cause it to spawn several
-          simultaneous processes.  This is most useful on multi-CPU machines.
-          However, since much of the compiling process is IO bound rather
-          than CPU bound it is also useful on single CPU machines.</para>
+          simultaneous processes.  This is most useful on multi-CPU machines.</para>
 
-	<para>On a typical single-CPU machine you would run:</para>
-	  
-	  <screen>&prompt.root; <userinput>make -j4 buildworld</userinput></screen>
-
-	<para>&man.make.1; will then have up to 4 processes running at any one
-	  time.  Empirical evidence posted to the mailing lists shows this
-	  generally gives the best performance benefit.</para>
-
 	<para>If you have a multi-CPU machine and you are using an SMP
 	  configured kernel try values between 6 and 10 and see how they speed
 	  things up.</para>
@@ -1000,7 +994,7 @@
 	system back to single user mode.  This is a good test that the new
 	system works properly.  After booting from
 	<filename>GENERIC</filename> and verifying that your system works you
-	can then build a new kernel based on your normal kernel	configuration
+	can then build a new kernel based on your normal kernel configuration
 	file.</para>
 
       <para>If you are upgrading to &os; 4.0 or above then the old
@@ -1008,12 +1002,22 @@
 	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> 
+        <maketarget>buildworld</maketarget></link>.</para>
 
+      <note>
+	<para>If you are building in multi-user mode, you'll need to drop to
+	  single user mode before using <command>make
+	  installkernel</command>; details are in <xref linkend="makeworld-singleuser">.</para>
+      </note>
+
       <screen>&prompt.root; <userinput>cd /usr/src</userinput>
 &prompt.root; <userinput>make buildkernel</userinput>
 &prompt.root; <userinput>make installkernel</userinput></screen>
@@ -1045,7 +1049,7 @@
 &prompt.root; <userinput>make installworld</userinput></screen>
 
       <note>
-	<para>If you specified variables on the	  <command>make
+	<para>If you specified variables on the <command>make
 	    buildworld</command> command line, you must specify the same
 	  variables in the <command>make installworld</command> command
 	  line.  This does not necessarily hold true for other options;
@@ -1601,9 +1605,7 @@
 	      
 	      <listitem>
 		<para>Pass the <option>-j&lt;n&gt;</option> option to &man.make.1; to
-		  run multiple processes in parallel.  This usually helps 
-		  regardless of whether you have a single or a multi processor
-		  machine.</para>
+		  run multiple processes in parallel.</para>
 	      </listitem>
 	      
 	      <listitem><para>The filesystem holding
--- chapter.sgml.diff ends here ---
>Release-Note:
>Audit-Trail:

From: Martin Heinen <martin@sumuk.de>
To: Chris Pepper <pepper@rockefeller.edu>
Cc: FreeBSD-gnats-submit@FreeBSD.ORG
Subject: Re: docs/39858: handbook/cutting-edge/chapter.sgml: various fixes
Date: Wed, 26 Jun 2002 09:24:42 +0200

 On Tue, Jun 25, 2002 at 06:34:40PM -0400, Chris Pepper wrote:
 > 
 > >Number:         39858
 > >Category:       docs
 > >Synopsis:       handbook/cutting-edge/chapter.sgml: various fixes
 
 >  	      <listitem>
 >  		<para>Pass the <option>-j&lt;n&gt;</option> option to &man.make.1; to
 > -		  run multiple processes in parallel.  This usually helps 
 > -		  regardless of whether you have a single or a multi processor
 > -		  machine.</para>
 > +		  run multiple processes in parallel.</para>
 >  	      </listitem>
 
 While we're here, we should replace &lt;/&gt; with <replaceable>.
 
 -- 
 Marxpitn
State-Changed-From-To: open->patched 
State-Changed-By: keramida 
State-Changed-When: Sun Jul 14 20:22:12 PDT 2002 
State-Changed-Why:  
I've extracted parts of the diff in this PR and committed them. 
Thanks for submitting this :) 


Responsible-Changed-From-To: freebsd-doc->keramida 
Responsible-Changed-By: keramida 
Responsible-Changed-When: Sun Jul 14 20:22:12 PDT 2002 
Responsible-Changed-Why:  

http://www.freebsd.org/cgi/query-pr.cgi?pr=39858 
State-Changed-From-To: patched->closed 
State-Changed-By: trhodes 
State-Changed-When: Mon Jul 15 18:31:11 PDT 2002 
State-Changed-Why:  
I rewrote the only part of this patch which was not applied.  My patch 
adds a note about the use of chflags(1) and installkernel.  Thanks for the 
submission! 

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