From ec6cc5260a388ba3554ba7bd95253536c7423b94 Mon Sep 17 00:00:00 2001
From: espie <espie@openbsd.org>
Date: Sat, 11 Nov 2023 10:12:08 +0000
Subject: [PATCH] document UNLINKED/BUILD_UNLINKED

---
 share/man/man5/bsd.port.mk.5 | 33 ++++++++++++++++++++++++++++++---
 1 file changed, 30 insertions(+), 3 deletions(-)

diff --git a/share/man/man5/bsd.port.mk.5 b/share/man/man5/bsd.port.mk.5
index c745b3640d7..8b6edd6515b 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.642 2023/11/10 19:46:52 ajacoutot Exp $
+.\" $OpenBSD: bsd.port.mk.5,v 1.643 2023/11/11 10:12:08 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 10 2023 $
+.Dd $Mdocdate: November 11 2023 $
 .Dt BSD.PORT.MK 5
 .Os
 .Sh NAME
@@ -1231,6 +1231,12 @@ Define only for broken ports, set to reason the port is broken.
 See also
 .Ev NO_IGNORE ,
 .Ev TRY_BROKEN .
+.It Ev BUILD_UNLINKED
+User settings.
+List of tags that shouldn't be
+.Ev IGNORE Ns d
+even though the ports are currently
+.Ev UNLINKED .
 .It Ev BUILD_USER
 User to switch to when using
 .Ev PORTS_PRIVSEP ,
@@ -2194,6 +2200,7 @@ If non-empty, most common targets that do something (e.g.,
 will be ignored.
 See also
 .Ev BATCH ,
+.Ev BUILD_UNLINKED ,
 .Ev BROKEN ,
 .Ev FETCH_MANUALLY ,
 .Ev IGNORE_IS_FATAL ,
@@ -2202,7 +2209,8 @@ See also
 .Ev IS_INTERACTIVE ,
 .Ev NOT_FOR_ARCHS ,
 .Ev NO_IGNORE ,
-.Ev ONLY_FOR_ARCHS .
+.Ev ONLY_FOR_ARCHS ,
+.Ev UNLINKED .
 .It Ev IGNORE_IS_FATAL
 User settings.
 If set to
@@ -3570,6 +3578,22 @@ User settings.
 If set, expands to a command that will release a lock.
 This lock will reside in
 .Pa ${LOCKDIR} .
+.It Ev UNLINKED
+Some ports should not be built by default for various reasons:
+not fully integrated into the system yet, bootstrap-specific
+ports, flavors that conflict badly with the default installation,
+but these ports should still be indexed by tools like
+.Pa sqlports
+for consistency.
+Instead, set
+.Ev UNLINKED
+to a
+.Sq tag
+that will make the port
+.Ev IGNORE Ns d
+unless
+.Ev BUILD_UNLINKED
+contains that specific tag.
 .It Ev UNMESSAGE
 File recorded in the package and displayed during deinstallation.
 Defaults to ${PKGDIR}/UNMESSAGE if this file exists.
@@ -4660,6 +4684,9 @@ a given build dependency (and corresponding WANTLIB for a given SUBPACKAGE).
 See
 .Cm print-package-args Pq Cm lib-depends-args
 for details.
+.It "Not built because unlinked (<tag>)"
+Confere
+.Ev UNLINKED .
 .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,
-- 
2.20.1