[src/trunk]: src Correct BUGS in BUILDING.mdoc now that most ports are USE_NE...

[sommerfeld <sommerfeld%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/92ff0f3c1bda
branches:  trunk
changeset: 526372:92ff0f3c1bda
user:      sommerfeld <sommerfeld%NetBSD.org@localhost>
date:      Thu May 02 22:13:30 2002 +0000

description:
Correct BUGS in BUILDING.mdoc now that most ports are USE_NEW_TOOLCHAIN

Obsolete NBUILDJOBS; build.sh just passes -jN through to make(1),
which inherits it cooperatively through the build tree.  Fix
documentation so that it's shown to be deprecated.

If you use build -jN, please save full build logs so that errors due
to missing dependancies can be analyzed and corrected.

diffstat:

 BUILDING.mdoc |  56 +++++++++++++++++++++++++++++++++-----------------------
 Makefile      |  22 +++++++---------------
 UPDATING      |   5 ++++-
 build.sh      |  12 ++++++------
 etc/Makefile  |  12 +++---------
 5 files changed, 53 insertions(+), 54 deletions(-)

diffs (285 lines):

diff -r 1f6d6c8db719 -r 92ff0f3c1bda BUILDING.mdoc
--- a/BUILDING.mdoc     Thu May 02 22:01:46 2002 +0000
+++ b/BUILDING.mdoc     Thu May 02 22:13:30 2002 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: BUILDING.mdoc,v 1.15 2002/03/14 18:33:05 thorpej Exp $
+.\"    $NetBSD: BUILDING.mdoc,v 1.16 2002/05/02 22:13:30 sommerfeld Exp $
 .\"
 .\" Copyright (c) 2001 The NetBSD Foundation, Inc.
 .\" All rights reserved.
@@ -516,17 +516,11 @@
 .DFLTy
 .
 .It Sy NBUILDJOBS
-If set, specifies the number of parallel
-.Xr make 1
-processes that should be run simultaneously.  This can speed up builds
-on SMP machines, or machines with much more CPU power than I/O
-availability.  This should be used
-.Em instead
-of the
+Now obsolete.  Use the 
 .Xr make 1
 option
 .Sy -j ,
-in order to ensure proper ordering of build components.
+instead (see below)
 .DFLTu
 .
 .It Sy NOCLEANDIR
@@ -587,6 +581,16 @@
 .
 .Bl -tag -width "var=value"
 .
+.It Sy -j Em njob
+Run up to
+.Em njob
+.Xr make 1 
+subjobs in parallel.
+Makefiles should use .WAIT or have explicit dependancies 
+as necessary to enforce build ordering.
+If you see build failures with -j, please save complete build logs 
+so the failures can be analyzed.
+.
 .It Sy -m Em dir
 Specify the default directory for searching for system Makefile
 segments, mainly the
@@ -664,11 +668,8 @@
 .Dq make depend
 immediately followed by a
 .Dq make all .
-This combined target recurses as an atomic unit, so that the
-.Dq make depend
-phase can participate in
-.Sy make -j
-parallelism.
+This improves cache locality of the build since both passes read the source
+files in their entirety.
 .
 .It Sy includes
 Build and install system header files.  Typically needed before any
@@ -803,14 +804,12 @@
 no release sets are placed in ${RELEASEDIR}.
 .
 .It Sy -j Em njob
-Set the value of
-.Sy NBUILDJOBS
-to
-.Em njob .
-This provides similar functionality to the familiar
-.Dq make -j ,
-but preserves the ordering of the top level
-.Dq make build .
+Passed through to 
+.Xr make 1 .
+Makefiles should use .WAIT or have explicit dependancies 
+as necessary to enforce build ordering.
+If you see build failures with -j, please save complete build logs 
+so the failures can be analyzed.
 .
 .It Sy -m Em mach
 Set the value of
@@ -945,6 +944,17 @@
 .Sy PATH ,
 or called with an absolute path.
 .
+.Sh OBSOLETE VARIABLES
+.
+.Bl -tag -width "NBUILDJOBS"
+.
+.It Sy NBUILDJOBS
+Now obsolete.  Use the 
+.Xr make 1
+option
+.Sy -j ,
+instead.
+.El
 .Sh SEE ALSO
 .Xr make 1 ,
 .Xr hier 7 ,
@@ -963,6 +973,6 @@
 .
 .Sh BUGS
 .
-Many platforms are not yet using the
+A few platforms are not yet using the
 .Sy USE_NEW_TOOLCHAIN
 system.
diff -r 1f6d6c8db719 -r 92ff0f3c1bda Makefile
--- a/Makefile  Thu May 02 22:01:46 2002 +0000
+++ b/Makefile  Thu May 02 22:13:30 2002 +0000
@@ -1,4 +1,4 @@
-#      $NetBSD: Makefile,v 1.172 2002/05/02 16:36:21 bjh21 Exp $
+#      $NetBSD: Makefile,v 1.173 2002/05/02 22:13:30 sommerfeld Exp $
 
 # This is the top-level makefile for building NetBSD. For an outline of
 # how to build a snapshot or release, as well as other release engineering
@@ -23,8 +23,6 @@
 #      an appropriate point in a build.
 #   MKSHARE, if set to `no', will prevent building and installing
 #      anything in /usr/share.
-#   NBUILDJOBS is the number of jobs to start in parallel during a
-#      `make build'. It defaults to 1.
 #   UPDATE, if defined, will avoid a `make cleandir' at the start of
 #     `make build', as well as having the effects listed in
 #     /usr/share/mk/bsd.README.
@@ -79,15 +77,6 @@
 .endfor
 .endif
 
-.if defined(NBUILDJOBS)
-.if !target(.BEGIN)
-.BEGIN:
-       @echo 'NBUILDJOBS is currently broken; see PR toolchain/14837.'
-       @false
-.endif
-#_J=           -j${NBUILDJOBS}
-.endif
-
 _SUBDIR=       tools lib include gnu bin games libexec sbin usr.bin
 _SUBDIR+=      usr.sbin share sys etc distrib regress
 
@@ -158,7 +147,7 @@
 .else
        @printf "Build started at: " && date
 .for tgt in ${BUILDTARGETS}
-       @(cd ${.CURDIR} && ${MAKE} ${_J} ${tgt})
+       @(cd ${.CURDIR} && ${MAKE} ${tgt})
 .endfor
        @printf "Build finished at: " && date
 .endif
@@ -182,6 +171,9 @@
        @echo '*** This platform is not yet verified to work with the new toolchain,'
        @echo '*** and may result in a failed build or corrupt binaries!'
 .endif
+.if defined(NBUILDJOBS)
+       @echo '*** WARNING: NBUILDJOBS is obsolete; use -j directly instead!'
+.endif
 
 do-distrib-dirs:
 .if !defined(DESTDIR) || ${DESTDIR} == ""
@@ -193,13 +185,13 @@
 .for dir in tools lib/csu lib gnu/lib
 do-${dir:S/\//-/}:
 .for targ in dependall install
-       (cd ${.CURDIR}/${dir} && ${MAKE} ${_J} ${targ})
+       (cd ${.CURDIR}/${dir} && ${MAKE} ${targ})
 .endfor
 .endfor
 
 do-build:
 .for targ in dependall install
-       (cd ${.CURDIR} && ${MAKE} ${_J} ${targ} BUILD_tools=no BUILD_lib=no)
+       (cd ${.CURDIR} && ${MAKE} ${targ} BUILD_tools=no BUILD_lib=no)
 .endfor
 
 # Speedup stubs for some subtrees that don't need to run these rules.
diff -r 1f6d6c8db719 -r 92ff0f3c1bda UPDATING
--- a/UPDATING  Thu May 02 22:01:46 2002 +0000
+++ b/UPDATING  Thu May 02 22:13:30 2002 +0000
@@ -1,4 +1,4 @@
-$NetBSD: UPDATING,v 1.59 2002/04/29 08:36:20 lukem Exp $
+$NetBSD: UPDATING,v 1.60 2002/05/02 22:13:30 sommerfeld 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.
@@ -9,6 +9,9 @@
 ^^^^^^^^^^^^^^^
 
 20020426:
+       NBUILDJOBS obsoleted in favor of just using -j.
+
+20020426:
        etc/postinstall added, which performs various checks for 
        configuration file updates and changes, and can fix most of
        the problems identified.
diff -r 1f6d6c8db719 -r 92ff0f3c1bda build.sh
--- a/build.sh  Thu May 02 22:01:46 2002 +0000
+++ b/build.sh  Thu May 02 22:13:30 2002 +0000
@@ -1,5 +1,5 @@
 #! /bin/sh
-#  $NetBSD: build.sh,v 1.56 2002/04/18 01:38:11 tv Exp $
+#  $NetBSD: build.sh,v 1.57 2002/05/02 22:13:31 sommerfeld Exp $
 #
 # Top level build wrapper, for a system containing no tools.
 #
@@ -90,7 +90,7 @@
        echo "    -b: build nbmake and nbmake wrapper script, if needed"
        echo "    -D: set DESTDIR to dest"
        echo "    -d: build a full distribution into DESTDIR (including etc files)"
-       echo "    -j: set NBUILDJOBS to njob"
+       echo "    -j: Run up to njob jobs in parallel; see make(1)"
        echo "    -m: set MACHINE to mach (not required if NetBSD native)"
        echo "    -n: show commands that would be executed, but do not execute them"
        echo "    -O: set obj root directory to obj (sets a MAKEOBJDIR pattern)"
@@ -151,7 +151,7 @@
        -d)     buildtarget=distribution;;
 
        -j)     eval $optargcmd
-               MAKEFLAGS="$MAKEFLAGS NBUILDJOBS=$OPTARG"; export MAKEFLAGS;;
+               parallel="-j $OPTARG";;
 
        # -m overrides MACHINE_ARCH unless "-a" is specified
        -m)     eval $optargcmd
@@ -367,7 +367,7 @@
 eval cat <<EOF $makewrapout
 #! /bin/sh
 # Set proper variables to allow easy "make" building of a NetBSD subtree.
-# Generated from:  \$NetBSD: build.sh,v 1.56 2002/04/18 01:38:11 tv Exp $
+# Generated from:  \$NetBSD: build.sh,v 1.57 2002/05/02 22:13:31 sommerfeld Exp $
 #
 
 EOF
@@ -384,10 +384,10 @@
 $runcmd chmod +x "$makewrapper"
 
 if $do_buildsystem; then
-       ${runcmd-exec} "$makewrapper" $buildtarget
+       ${runcmd-exec} "$makewrapper" $parallel $buildtarget
 elif $do_buildonlytools; then
        if [ "$MKOBJDIRS" != "no" ]; then
-               $runcmd "$makewrapper" obj-tools || exit 1
+               $runcmd "$makewrapper" $parallel obj-tools || exit 1
        fi
        $runcmd cd tools
        if [ "$UPDATE" = "" ]; then
diff -r 1f6d6c8db719 -r 92ff0f3c1bda etc/Makefile
--- a/etc/Makefile      Thu May 02 22:01:46 2002 +0000
+++ b/etc/Makefile      Thu May 02 22:13:30 2002 +0000
@@ -1,4 +1,4 @@
-#      $NetBSD: Makefile,v 1.217 2002/05/02 15:09:40 lukem Exp $
+#      $NetBSD: Makefile,v 1.218 2002/05/02 22:13:31 sommerfeld Exp $
 #      from: @(#)Makefile      8.7 (Berkeley) 5/25/95
 
 # Environment variables without default values:
@@ -72,12 +72,6 @@
 .include "etc.${MACHINE}/Makefile.inc"
 .endif
 
-# Use multiple jobs for kernel builds, if NBUILDJOBS set.
-# (Taken from src/Makefile.)
-.if defined(NBUILDJOBS)
-_J= -j${NBUILDJOBS}
-.endif
-
 # -rw-r--r--
 BINOWN= root
 BINGRP= wheel
@@ -271,7 +265,7 @@
        ${INSTALL_SYMLINK} -o root -g wheel -m 755 usr/src/sys ${DESTDIR}/sys
 
 release snapshot: check_DESTDIR check_RELEASEDIR .WAIT \
-    distribution snap_pre snap_md_pre snap_kern snap_md_post
+    distribution .WAIT snap_pre snap_md_pre .WAIT snap_kern .WAIT snap_md_post
        (cd ../distrib/sets; ${MAKE} sets)
        ${MAKESUMS} -t ${RELEASEDIR}/binary/kernel '*.gz'
 
@@ -348,7 +342,7 @@
 .if !defined(UPDATE)
        cd ${KERNOBJDIR}/${configfile:C/.*\///} && ${MAKE} distclean
 .endif
-       cd ${KERNOBJDIR}/${configfile:C/.*\///} && ${MAKE} depend && ${MAKE} ${_J}
+       cd ${KERNOBJDIR}/${configfile:C/.*\///} && ${MAKE} depend && ${MAKE}
 .endfor # build kernels
 .endif # KERNELS_DONE                                                  # }
 .for configfile in ${KERNEL_SETS}