add DIAGNOSTICS, for easy grepping thru logs.

as discussed with jmc@, put the section in exposition order.
(we're not even a driver anyways)
sthen@ likes it.

1 files changed, 149 insertions, 2 deletions

diff --git a/share/man/man5/bsd.port.mk.5 b/share/man/man5/bsd.port.mk.5
index 56630461456..0d76707d572 100644
--- a/share/man/man5/bsd.port.mk.5
+++ b/share/man/man5/bsd.port.mk.5
@@ -1,4 +1,4 @@
-.\" $OpenBSD: bsd.port.mk.5,v 1.328 2012/01/29 11:32:36 espie Exp $
+.\" $OpenBSD: bsd.port.mk.5,v 1.329 2012/02/17 07:37:40 espie Exp $
 .\"
 .\" Copyright (c) 2000-2008 Marc Espie
 .\"
@@ -24,7 +24,7 @@
 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: January 29 2012 $
+.Dd $Mdocdate: February 17 2012 $
 .Dt BSD.PORT.MK 5
 .Os
 .Sh NAME
@@ -2729,6 +2729,153 @@ GNU-configure would always try to use bison otherwise, which leads to
 unreproducible builds.
 Set to bison if needed.
 .El
+.Sh DIAGNOSTICS
+Note that some of these messages are actually emitted by some other external
+commands, but grouped here for convenience: easier to look for in
+.Xr dpb 1 Ns 's
+logs.
+.Bl -diag
+.It "Error: change in plist between ..."
+Error message comes from
+.Xr register-plist 1 .
+.It "Error: duplicate item in packing-list"
+Error message comes from
+.Xr pkg_create 1 ,
+and will result from incorrect packing-lists, such as including several
+fragments with the same file, or having incorrect
+.Ev PKG_ARGS-sub .
+.It "Error: Libraries in packing-lists...and libraries from installed packages don't match"
+The ports tree and the installed packages are out-of-sync.
+Mixing library information from both sources might produce packages that can't
+be installed elsewhere.
+Cleanest fix is to update the out-of-date source (e.g., update the ports tree,
+or build and install new packages).
+Developers may use
+.Ev PKG_CREATE_NO_CHECKS
+instead, assuming they understand the implications.
+See print-package-args (wantlib-args) for details.
+.It "Fatal: can't flavor a SUBDIR"
+A dependency mentions top_subdir,flavor.
+Flavor would then be ignored, as it is only applied to individual ports.
+.It "Fatal: can't subpackage a SUBDIR"
+A dependency mentions top_subdir,-sub.
+Subpackage would then be ignored, as it is only applied to individual ports.
+.It "Fatal: flavor should never start with a digit"
+This would utterly confuse
+.Xr pkg_add 1 .
+See
+.Xr packages-specs 7 .
+.It "Fatal: inclusion of <file> from <file>"
+.Pa bsd.port.mk
+or
+.Pa bsd.port.subdir.mk
+has been included from a
+.Ev MODULE
+or from
+.Pa Makefile.inc ,
+resulting in a double inclusion.
+This would lead to weird results, such as
+.Ev PKG_ARGS
+being defined twice.
+.It "Fatal: SUBPACKAGES should always begin with -: <offending list>"
+That is the only way to differentiate between
+.Ev FLAVOR
+and
+.Ev SUBPACKAGE
+in
+.Xr pkgpath 7
+specifications.
+.It "Fatal: the licencing info for <pkgname> is incomplete..."
+Every port must have explicit defines of all
+.Ev PERMIT_*
+values.
+.It "Fatal: Use 'env FLAVOR=flavor make' instead"
+Arguments specified after
+.Xr make 1
+are hardcoded for all recursive sub-makes, and very difficult to override.
+Thus,
+.Ev FLAVOR
+must be specified in the environment instead.
+.It "Fatal: Use 'env SUBPACKAGE=-sub make' instead"
+Arguments specified after
+.Xr make 1
+are hardcoded for all recursive sub-makes, and very difficult to override.
+Thus,
+.Ev SUBPACKAGE
+must be specified in the environment instead.
+.It "ldconfig: <dir>: No such file or directory"
+Usually produced by
+.Xr pkg_add 1
+running
+.Xr ldconfig 8 .
+Some tools such as GNU libtool will add directories living under
+.Pa ${WRKINST}
+to the shared library path during the
+.Ar fake
+stage.
+Of course,
+.Xr ldconfig 8
+will later complain after the directory no longer exists.
+The bogus tool should be fixed to conform to
+.Ox
+usage.
+.It LIB_DEPENDS spec not needed
+There doesn't seem to be any WANTLIB to match the given LIB_DEPENDS.
+Thus, the LIB_DEPENDS won't turn into a @depends line in the created package.
+This is most often because of confusion between LIB_DEPENDS and RUN_DEPENDS:
+RUN_DEPENDS is needed for dlopen'd libraries.
+Might be intentional sometimes, if some compile flavors create static binaries,
+for instance.
+See print-package-args (lib-depends-args) for details.
+.It "Warning: FULLPKGNAME-sub defined but not FULLPKGPATH-sub"
+.Ev FULLPKGNAME-sub
+has been explicitly defined by the port, instead of relying on the default,
+but no value of
+.Ev FULLPKGPATH-sub
+has been given.
+This is often an error.
+.It "Warning: symlink(s) point to non existent file."
+Error message comes from
+.Xr pkg_create 1 .
+The symlink resides in the fake area, under
+.Pa ${WRKINST} .
+This is only a warning because the symlink may point to a run-time dependency,
+which obviously won't exist under
+.Pa ${WRKINST}
+at the time
+.Li make package
+is run.
+.It "Warning: option @no-default-conflict with no @conflict"
+Error message comes from
+.Xr pkg_create 1 .
+Most packages that waive "default-conflict" will have explicit conflict markers
+instead.
+Otherwise, the package will only conflict with the exact same version, with
+some possible
+.Ev REVISION
+bumps.
+Any other version or
+.Ev FLAVOR
+won't conflict.
+This is generally an error, apart from very few ports like
+.Pa devel/autoconf/*
+and
+.Pa devel/automake/* .
+.It "groff produced empty result for <manpage>..."
+Error message comes from
+.Xr pkg_create 1 .
+Manpages are automatically formatted with
+.Xr groff 1
+if
+.Ev USE_GROFF
+is set.
+The above message denotes an actual problem while formatting the page,
+which should be addressed.
+In the meantime,
+.Xr pkg_create 1
+still produces a package, but leaves the manpage unformatted, in the hope
+that something will be able to make sense of it.
+.El
 .Sh FILES
 .Bl -tag -width files/md5
 .It Pa ../Makefile.inc