document package-specs

2 files changed, 31 insertions, 6 deletions

diff --git a/share/man/man5/bsd.port.mk.5 b/share/man/man5/bsd.port.mk.5
index 1cfb4795692..e7325c3aa68 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.271 2010/11/14 11:18:30 espie Exp $
+.\" $OpenBSD: bsd.port.mk.5,v 1.272 2010/11/26 07:46:31 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 14 2010 $
+.Dd $Mdocdate: November 26 2010 $
 .Dt BSD.PORT.MK 5
 .Os
 .Sh NAME
@@ -1669,6 +1669,15 @@ of ${PKGNAME}${SUBPACKAGE} is not appropriate.
 .It Ev PKGPATH
 Path to the current port's directory, relative to ${PORTSDIR}.
 Read-only.
+.It Ev PKGSPEC
+default package spec for using this port as a dependency.
+Defaults to
+.Sq stem-* ,
+derived from the
+.Ev FULLPKGNAME.
+Do not override without very good reasons,
+namely software that coexist as different incompatible versions with the
+same stem, e.g., already a mess.
 .It Ev PLIST_DB
 User settings.
 Directory used to save generated packing-lists, as persistent information.
@@ -2759,7 +2768,8 @@ The following variables are subpackage dependent:
 .Ev MESSAGE ,
 .Ev UNMESSAGE ,
 .Ev DESCR ,
-.Ev PLIST .
+.Ev PLIST ,
+.Ev PKSPEC .
 .Pp
 The usual non-MULTI_PACKAGES variables are simply used as default values
 for all subpackages.
diff --git a/share/man/man7/packages-specs.7 b/share/man/man7/packages-specs.7
index fc0e1670ab7..17420e79b59 100644
--- a/share/man/man7/packages-specs.7
+++ b/share/man/man7/packages-specs.7
@@ -1,4 +1,4 @@
-.\" $OpenBSD: packages-specs.7,v 1.16 2010/11/20 10:05:05 espie Exp $
+.\" $OpenBSD: packages-specs.7,v 1.17 2010/11/26 07:46:31 espie Exp $
 .\"
 .\" Copyright (c) 2001 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 20 2010 $
+.Dd $Mdocdate: November 26 2010 $
 .Dt PACKAGES-SPECS 7
 .Os
 .Sh NAME
@@ -146,10 +146,25 @@ after removing any version and flavor requirements.
 .Pp
 Without a
 .Sq pkgspec:
-part, any package with the right stem will do: in effect,
+part, by default, any package with the right stem will do: in effect,
 the pkgspec used is
 .Sq stem-* .
 .Pp
+In
+.Ox 4.9 ,
+the dependent port may override this default, and set
+.Ev PKGSPEC
+to achieve a more restrictive default, for instance,
+.Pa databases/db/v3
+sets the default to 
+.Qq PKGSPEC = db->=3,<4
+to avoid collision with 
+.Pa databases/db/v4 .
+Be extra cautious with this functionality: this tweaks the depends line for
+any including package, thus usually requiring a version bump, and is in
+general only required for very messy cases where several incompatible versions 
+of the same software coexist as packages with the same stem.
+.Pp
 An explicit specification such as
 .Qq png-1.0.7 .
 may be used to ask for a more specific version number.