From b6bfef11bed20f62a82ac14f2cdc7069fb2a8648 Mon Sep 17 00:00:00 2001
From: Marc Espie <espie@cvs.openbsd.org>
Date: Fri, 25 Nov 2011 10:12:27 +0000
Subject: document a few more odds and ends

---
 share/man/man5/bsd.port.mk.5 | 74 +++++++++++++++++++++++++++++++++++++-------
 1 file changed, 63 insertions(+), 11 deletions(-)

diff --git a/share/man/man5/bsd.port.mk.5 b/share/man/man5/bsd.port.mk.5
index ca6809a86a1..b1849a20764 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.304 2011/11/22 16:21:50 sthen Exp $
+.\" $OpenBSD: bsd.port.mk.5,v 1.305 2011/11/25 10:12:26 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: November 22 2011 $
+.Dd $Mdocdate: November 25 2011 $
 .Dt BSD.PORT.MK 5
 .Os
 .Sh NAME
@@ -134,6 +134,18 @@ Verify the ports mentioned in
 by checking the corresponding packages are actually installed,
 and install the missing ports by recursing through the ports tree.
 Invoked right after creating the working directory.
+.It Ar check-register
+Introspection target.
+Verifies from the ports tree, without building anything, that the current
+subpackage will register okay
+.Po
+see
+.Ev PLIST_DB
+.Pc .
+.It Ar check-register-all
+Applies
+.Ar check-register
+to all subpackages of the current port.
 .It Ar checkpatch
 Debugging version of the
 .Ar patch
@@ -1129,13 +1141,23 @@ For instance:
 ERRORS+="Fatal: Missing comment"
 \&.endif
 .Ed
+Porter can add to
+.Ev ERRORS ,
+for instance to flag erroneous combinations of
+.Ev FLAVORS
+(but see
+.Ev ONLY_FOR_ARCHS
+.Ev NOT_FOR_ARCHS
+and
+.Ev BROKEN
+for other common issues).
 .It Ev EXTRACT_CASES
 In the normal extraction stage (when
 .Ev EXTRACT_ONLY
 is not empty), this is the contents of a case statement, used to extract files.
 Fragments are automatically appended to extract tar, xz and zip
-archives, so that the default case is equivalent to the following shell
-fragment:
+archives, so that the default case is more or less equivalent to the
+following shell fragment:
 .Bd -literal
 set -e
 cd ${WRKDIR}
@@ -1195,7 +1217,7 @@ FETCH_MANUALLY= "You must fetch foo-1.0.tgz"
 FETCH_MANUALLY+="from http://www.fubar.com/ manually,"
 FETCH_MANUALLY+="after reading and agreeing to the license."
 .Ed
-Automatically sets
+Behaves like
 .Ev IS_INTERACTIVE
 if some distribution files are missing.
 .It Ev FETCH_PACKAGES
@@ -1365,7 +1387,8 @@ Defaults to
 If set, points to a directory common for all instances of concurrent ports
 builds.
 .It Ev LOCK_CMD
-Expands to a command that will acquire a lock.
+Expands to a command that will acquire a lock, namely
+.Xr dolock 1 .
 See also
 .Xr ports 7 .
 .It Ev LOCK_VERBOSE
@@ -1450,7 +1473,7 @@ File recorded in the package and displayed during installation.
 Defaults to ${PKGDIR}/MESSAGE if this file exists.
 Leave empty if no message is needed.
 .It Ev MISSING_FILES
-if
+When
 .Ev FETCH_MANUALLY
 is set,
 .Ev MISSING_FILES
@@ -1631,8 +1654,8 @@ In the normal distpatch stage (when
 is not empty), this is the contents of a case statement, used to apply
 distribution patches.
 Fragments are automatically appended to handle gzip'ed and bzip'ed
-patches, so that the default case is equivalent to the following shell
-fragment:
+patches, so that the default case is more or less equivalent to the following
+shell fragment:
 .Bd -literal
 set -e
 cd ${FULLDISTDIR}
@@ -1723,6 +1746,22 @@ For mips64 and pic libraries, see
 Path to
 .Xr pkg_create 1
 command, with possible options.
+.It Ev PKG_CREATE_NO_CHECKS
+Porters switch.
+Set to
+.Sq Yes
+to avoid checking the ports tree when solving
+.Ev WANTLIB
+.Po
+see
+.Ar wantlib-args
+.Pc .
+May result in bogus packages that mix
+.Cm @depends
+lines obtained from
+the ports tree with
+.Cm @wantlib
+lines that come from the installed system.
 .It Ev PKG_DBDIR
 Path to package installation records.
 Defaults to
@@ -1806,13 +1845,21 @@ same stem, e.g., already a mess.
 .It Ev PLIST_DB
 User settings.
 Directory used to save generated packing-lists, as persistent information.
-Packing-lists are processed by a script, register-plist, which complains
-when packing-lists change without a REVISION bump.
+Packing-lists are processed by a script,
+.Xr register-plist 1 ,
+which complains when packing-lists change without a
+.Ev REVISION
+bump.
+It also knows enough about package version numbers when something in the
+package or its dependencies goes backward, thus catching
+.Ev EPOCH
+issues.
 This directory is never cleaned during normal operation.
 .Sq make clean=plist
 should only ever be used during debugging by port maintainers.
 Defaults to
 .Pa ${PORTSDIR}/plist/${MACHINE_ARCH} .
+If set to empty, will not register anything: very much unsafe.
 .It Ev PREFERRED_CIPHERS
 List of cryptographic ciphers to use, in order of preference.
 Default is
@@ -1974,6 +2021,11 @@ which default to
 and
 .Sq check
 respectively.
+.It Ev README_NAME
+User settings.
+Path to the template used to generate a readme html file.
+Defaults to
+.Pa ${TEMPLATES}/README.port .
 .It Ev REORDER_DEPENDENCIES
 Points to a list of files that specify inter-dependencies for
 .Xr make 1 .
-- 
cgit v1.2.3