Add support for BROKEN_ON_PLATFORM and BROKEN_EXCEPT_ON_PLATFORM, as per

discussion on tech-pkg.

BROKEN_ON_PLATFORM and NOT_FOR_PLATFORM are the same, except that
(now) BROKEN_ON_PLATFORM sets PKG_FAIL_REASON and NOT_FOR_PLATFORM
sets PKG_SKIP_REASON. BROKEN_EXCEPT_FOR_PLATFORM and ONLY_FOR_PLATFORM
correspond in the same way.

The idea is that going forward we will distinguish unbuildable
packages that theoretically ought to be fixed (these are BROKEN) from
packages where it doesn't make sense to build (these are NOT_FOR)...
examples of the former include most non-64-bit-clean packges; examples
of the latter include OS-specific language bindings.

A general review of the uses of NOT_FOR_PLATFORM and ONLY_FOR_PLATFORM
(converting many of them to BROKEN...) is coming up.

Similarly, a general review of the uses of PKG_FAIL_REASON and
PKG_SKIP_REASON is coming up.

For this to become useful, pbulk needs to be taught to report failing
and skipped packages differently - the idea is that failing packages
should be reported up front and skipped packages don't need to be. This
has not been done yet, but one set of things at a time...

1 files changed, 23 insertions, 10 deletions

diff --git a/mk/help/notonly.help b/mk/help/notonly.help
index 36440616615..bb5337f670a 100644
--- a/mk/help/notonly.help
+++ b/mk/help/notonly.help
@@ -1,22 +1,35 @@
-# $NetBSD: notonly.help,v 1.2 2007/09/12 09:59:44 rillig Exp $
+# $NetBSD: notonly.help,v 1.3 2015/01/01 06:06:06 dholland Exp $
 
 # === Package-settable variables ===
 #
+# BROKEN_ON_PLATFORM
+#	A list of platforms on which this package doesn't build or
+#	builds but doesn't run.
+#
 # NOT_FOR_PLATFORM
-#	A list of platforms (for which this package either doesn't build
-#	or isn't useful to have.
+#	A list of platforms for which this package isn't useful to
+#	have and doesn't make sense to attempt to build.
+#
 #
+# BROKEN_EXCEPT_ON_PLATFORM
+#	If a package only builds and runs on some platforms, they
+#	should be listed here. This variable should only be used if
+#	you are sure that the package won't work on other platforms.
+#	It is almost always better to use BROKEN_ON_PLATFORM.
 #
 # ONLY_FOR_PLATFORM
-#	If a package only builds on some platforms, they should be
-#	listed here. This variable should only be used if you are sure
-#	that the package won't work on other platforms. It is almost
-#	always better to use NOT_FOR_PLATFORM.
+#	If a package only makes sense on a fixed set of platforms
+#	(often exactly one), they should be listed here. This variable
+#	should only be used if you are sure that the package doesn't
+#	make sense on other platforms. For ordinary cases it is almost
+#	always better to use NOT_FOR_PLATFORM, and if the package merely
+#	doesn't work, use BROKEN_ON_PLATFORM.
 #
 # Platforms are triples of OPSYS, OS_VERSION and MACHINE_ARCH, separated
 # by dashes. Each of the components may be the wildcard "*".
 #
-# Whenever you use these variables in a package Makefile, add a comment
-# nearby _why_ you are restricting the list of platforms. Otherwise
-# these restrictions may be quickly removed by other developers.
+# Whenever you use these variables in a package Makefile, add a
+# comment nearby explaining _why_ you are restricting the list of
+# platforms. Otherwise these restrictions may be quickly removed by
+# other developers.
 #