* Add comments on all the directory build/install ordering goo.

* Beef up that goo so that for each ".WAIT group" all of the install targets
  in the previous group have completed before starting the `all', `depend'
  or `dependall' targets.

tools/Makefile

@@ -1,4 +1,4 @@
-#	$NetBSD: Makefile,v 1.35 2002/02/11 07:21:41 pk Exp $
+#	$NetBSD: Makefile,v 1.36 2002/02/18 15:35:53 pk Exp $
 
 # XXX Note: NO_DBSYM is a stopgap temporary variable for use
 # with the development of non-NetBSD hosting support.  This will go away.
@@ -54,18 +54,44 @@ all-${dir} depend-${dir} dependall-${dir} install-${dir}:
 .include <bsd.subdir.mk>
 .include <bsd.obj.mk>
 
-# For each .WAIT point, make sure the previous target is installed before
+# For each .WAIT point, make sure the previous targets are installed before
 # building a dependent target.
+#
+# We use the "internal" targets and dependencies generated by <bsd.subdir.mk>
+# to achieve this. These targets look like:
+#	subdir-all:	all-dir1     [.WAIT] all-dir2     etc..
+#	subdir-install:	install-dir1 [.WAIT] install-dir2 etc..
+# and so on for each element in ${TARGETS}, with .WAIT sources inserted at
+# places corresponding to the .WAITs in our $SUBDIR variable.
+#
+# In this Makefile we want additional depencies of the `all-dirN',
+# `depend-dirN' and `dependall-dirN' targets in the Nth ".WAIT group" on all
+# of the `install-dir[N-1]' targets in the previous ".WAIT group".
+#
+# Also, since we're now mixing `install' with `all' and `depend' targets
+# an order relationship between those in each individual subdirectory
+# must be established.
+#
 _dep:=
-_last:=
+_group:=
 .for d in ${SUBDIR}
 _this:=		${d}
 .if ${_this} == ".WAIT"
-_dep:=		${_dep} install-${_last}
-.ORDER: depend-${_last} all-${_last} dependall-${_last} install-${_last}
+
+# setup dependency to apply to all/depend targets in the next group
+_dep:=		${_group:S/^/install-/}
+_group:=
+
 .else
-_last:=		${d}
+
+# build the current ".WAIT group"
+_group:=	${_group} ${d}
+# order depend/all/install targets for ${d} subdir.  Note the additional
+# .WAIT to achieve "closure" of the predecessor/successor relationships.
+.ORDER: depend-${d} all-${d} dependall-${d} .WAIT install-${d}
+# make all/depend-${d} dependent on all install targets in the previous group
 depend-${d} all-${d} dependall-${d}: ${_dep}
+
 .endif
 .endfor