>Number:         24654
>Category:       toolchain
>Synopsis:       UPDATING file should refer to build.sh and BUILDING file
>Confidential:   no
>Severity:       non-critical
>Priority:       medium
>Responsible:    toolchain-manager
>State:          open
>Class:          doc-bug
>Submitter-Id:   net
>Arrival-Date:   Wed Mar 03 12:28:00 UTC 2004
>Closed-Date:
>Last-Modified:
>Originator:     Alan Barrett
>Release:        NetBSD 1.6ZK
>Organization:
Not much
>Environment:
NetBSD 1.6ZK
Architecture: i386
Machine: i386
>Description:
The src/UPDATING file does not mention build.sh or the BUILDING file.
I think that it should be changed to encourage the use of build.sh.

>How-To-Repeat:
>Fix:
Apply the following patch.

Index: src/UPDATING
--- UPDATING	23 Feb 2004 22:51:51 -0000	1.107
+++ UPDATING	3 Mar 2004 12:24:11 -0000
@@ -1,9 +1,18 @@
 $NetBSD: UPDATING,v 1.107 2004/02/23 22:51:51 reinoud Exp $
 
-This file is intended to be a brief introduction to the build
-process and a reference on what to do if something doesn't work.
+This file (UPDATING) is intended to be a brief reference to recent
+changes that might cause problems in the build process, and a guide for
+what to do if something doesn't work.
+
+For a more detailed description of the recommended way to build NetBSD
+using build.sh, see the BUILDING file.
+
+Note that much of the advice in this UPDATING file was written before
+build.sh existed.  Nevertheless, the advice here may be useful for
+building on platforms where build.sh does not work, or for resolving or
+working around problems with build.sh.
 
-For a more detailed description see Makefile.
+See also: BUILDING, build.sh, Makefile.
 
 Recent changes:
 ^^^^^^^^^^^^^^^
@@ -507,6 +516,12 @@
 
 Hints for a more successful build:
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+    Use build.sh, but do not use its "expert mode":
+	This will will automatically build the tools in the
+	   correct order, and it will keep the tools and the
+	   new build products from interfering with the running
+	   system.  This will allow you to ignore most of the
+	   other advice in this file.
     Build a new kernel first:
 	This makes sure that any new system calls or features
 	   expected by the new userland will be present.  This
@@ -517,7 +532,9 @@
 	   about one.  It also makes it easier to clean up after
 	   a build.  It's also necessary if you want to use the
 	   same source tree for multiple machines.
-	   To use object directories:
+	   To use object directories with build.sh:
+	    a) invoke build.sh with the "-M" or "-O" options.
+	   To use object directories without using build.sh:
 	    a) cd /usr/src ; make cleandir
 	    b) Add "OBJMACHINE=yes" to /etc/mk.conf
 	    c) Add "MKOBJDIRS=yes" to /etc/mk.conf
@@ -525,20 +542,21 @@
 	   Note that running "make obj" in a directory will create
 	   in obj.$MACHINE directory.
     Build to a DESTDIR:
-	This helps to keep old
-	   installed files (especially libraries) from interfering
-	   with the new build.
-	   To build to a DESTDIR, set the DESTDIR environment
-	   variable before running make build.  It should be set to
-	   the pathname of an initially empty directory.
-	   Problems: you might need to update critical utilities
-		without using DESTDIR since nothing is executed
-		from what is installed in DESTDIR.
-		(See critical utils, below)
+	This helps to keep old installed files (especially libraries)
+	   from interfering with the new build.
+	   To build to a DESTDIR with build.sh, use the "-D" option.
+	   To build to a DESTDIR without using build.sh, set the DESTDIR
+	   environment variable before running make build.  It should be
+	   set to the pathname of an initially empty directory.
+	   Problems: if you do not use build.sh, you might need to
+		update critical utilities without using DESTDIR since
+		nothing is executed from what is installed in DESTDIR.
+		(See critical utils, below.)
     Build often:
 	This keeps critical utilities current enough to not choke
 	on any other part of the source tree that depends on up to
-	date functionality.
+	date functionality.  If you use build.sh, you should not have
+	this problem.
  
 What to do if things don't work:
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>Release-Note:
>Audit-Trail:
>Unformatted: