new documentation: pkgpath.7

tweaks by jmc@, krw@ approves.
(to be linked to other pages that will need tweaking)

3 files changed, 174 insertions, 4 deletions

diff --git a/share/man/man7/Makefile b/share/man/man7/Makefile
index fea8dfde683..84c96c73870 100644
--- a/share/man/man7/Makefile
+++ b/share/man/man7/Makefile
@@ -1,4 +1,4 @@
-#	$OpenBSD: Makefile,v 1.20 2011/09/18 10:38:57 schwarze Exp $
+#	$OpenBSD: Makefile,v 1.21 2011/11/21 12:00:57 espie Exp $
 #	$NetBSD: Makefile,v 1.6 1994/12/22 10:50:05 cgd Exp $
 
 # missing: term.7
@@ -6,7 +6,7 @@
 MAN=	ascii.7 eqn.7 environ.7 glob.7 hier.7 hostname.7 intro.7 kgdb.7 \
 	library-specs.7 mailaddr.7 \
 	man.7 mandoc_char.7 mdoc.7 mirroring-ports.7 \
-	operator.7 packages.7 packages-specs.7 ports.7 roff.7 \
+	operator.7 packages.7 packages-specs.7 pkgpath.7 ports.7 roff.7 \
 	script.7 securelevel.7 tbl.7
 MLINKS=	mdoc.7 mandoc.7 mirroring-ports.7 mirror-maker.7
 
diff --git a/share/man/man7/packages-specs.7 b/share/man/man7/packages-specs.7
index f6ad54f8d2b..307f6b9df2a 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.20 2011/01/13 12:00:37 landry Exp $
+.\" $OpenBSD: packages-specs.7,v 1.21 2011/11/21 12:00:57 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: January 13 2011 $
+.Dd $Mdocdate: November 21 2011 $
 .Dt PACKAGES-SPECS 7
 .Os
 .Sh NAME
@@ -311,6 +311,7 @@ and so would check on
 .Xr bsd.port.mk 5 ,
 .Xr library-specs 7 ,
 .Xr packages 7 ,
+.Xr pkgpath 7 ,
 .Xr ports 7
 .Sh HISTORY
 Support for a more complex form of those package specifications first
diff --git a/share/man/man7/pkgpath.7 b/share/man/man7/pkgpath.7
new file mode 100644
index 00000000000..c051b1acf40
--- /dev/null
+++ b/share/man/man7/pkgpath.7
@@ -0,0 +1,169 @@
+.\" $OpenBSD: pkgpath.7,v 1.1 2011/11/21 12:00:57 espie Exp $
+.\"
+.\" Copyright (c) 2011 Marc Espie <espie@openbsd.org>
+.\"
+.\" Permission to use, copy, modify, and distribute this software for any
+.\" purpose with or without fee is hereby granted, provided that the above
+.\" copyright notice and this permission notice appear in all copies.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+.Dd $Mdocdate: November 21 2011 $
+.Dt PKGPATH 7
+.Os
+.Sh NAME
+.Nm pkgpath
+.Nd ports tree location for a package build
+.Sh DESCRIPTION
+Each location in the ports tree is uniquely identified through a
+.Nm ,
+which encodes the directory, flavor and subpackage information
+that allows the build of a package.
+This is not to be confused with
+.Ev PKG_PATH ,
+the list of URLs from which
+.Xr pkg_add 1
+retrieves binary packages.
+.Pp
+Every
+.Nm
+conforms to the pattern
+.Ar some/directory[,-sub][,flavor...] .
+.Pp
+The
+.Ar some/directory
+part refers to the directory part, to find under the
+portstree, usually in
+.Pa /usr/ports
+(or
+.Pa /usr/port/mystuff
+for port developers).
+.Pp
+The
+.Ar ,-sub
+optional part refers to a specific subpackage from a
+multi-package port.
+It can be left blank for non multi-package ports, or to get
+the default subpackage
+(usually
+.Ar -main ) .
+.Pp
+The
+.Ar ,flavor...
+optional part refers to the flavors or pseudo-flavors to use
+when building the package.
+If left blank, it refers to the default flavor.
+An explicit empty flavor can also be specified to make sure to
+get an empty flavor, even if it does not correspond to the default
+flavor.
+.Pp
+Note that
+.Ar -sub
+and
+.Ar -flavor
+parts can be specified in any order, as all subpackages start with
+a dash.
+It is an error to ask for several subs at once, e.g.\&
+.Ar some/path,-sub1,-sub2 ,
+though it won't always be flagged as a problem.
+.Pp
+For instance:
+.Bl -tag -width small
+.It Ar misc/screen
+A simple directory, default flavor, which happens to be empty.
+.It Ar misc/screen,static
+Same port,
+.Ar static
+flavor.
+.It Ar x11/kde/libs3
+A multi-package port with no subpackage nor flavor, refers to
+.Ar x11/kde/libs3,-main .
+.It Ar net/avahi
+Multi-package port with default flavor.
+Will actually build with FLAVOR="no_gui no_mono no_qt3 no_qt4 bootstrap"
+(all of which are pseudo-flavors), so that only the main package will build.
+.It Ar net/avahi,no_mono,-qt3
+Build avahi with the "no_mono" pseudo-flavor, which will build the
+-main, -qt3, qt4, -gui, -gtk, -gtk3, and -ui subpackages, and refer to the
+.Ar -qt3
+subpackage.
+.It Ar net/avahi,
+.Ar net/avahi
+with an explicit empty flavor, default subpackage
+.Po
+which happens to be
+.Ar -main
+.Pc .
+.It Ar net/avahi,,-qt4
+.Ar net/avahi
+with an explicit empty flavor,
+.Ar -main
+subpackage.
+.El
+.Pp
+The ports tree can iterate over lists of
+.Nm
+through
+.Li SUBDIR="pkgpath1 pkgpath2..."
+or through a full list through
+.Li SUBDIRLIST=file .
+.Pp
+.Xr dpb 1
+also handles
+.Nm
+lists for many options.
+.Sh NORMALISATION AND THE FULLPATH CONVENTION
+When the ports tree handles dependencies, it passes
+.Nm
+from
+.Ev BUILD_DEPENDS ,
+.Ev LIB_DEPENDS ,
+.Ev RUN_DEPENDS ,
+and
+.Ev REGRESS_DEPENDS
+to the dependent port for normalisation purposes.
+That way, the
+.Nm
+that gets recorded in the package doesn't have any "default" flavor
+or "default" subpackage left: those are always resolved to the correct
+value.
+.Pp
+Likewise, pseudo-flavors vanish from the
+.Nm pkgpath ,
+since they only participate in the build process, but do not intervene
+in the built package.
+.Pp
+As a result, such
+.Nm
+are slightly different from the description above, as a flavor left blank
+is the empty flavor (and not the default flavor).
+This is the
+.Qq fullpath convention .
+.Pp
+Tools such as
+.Xr dpb 1
+display fullpath pkgpaths,
+and binary packages store full pkgpaths.
+.Pp
+.Ev SUBDIR
+and
+.Ev SUBDIRLIST
+can be forced to follow the fullpath convention by explicitly passing
+.Li FULLPATH=Yes
+to the corresponding
+.Xr make 1
+invocations.
+.Pp
+Most tools that process binary packages do so.
+.Sh SEE ALSO
+.Xr dpb 1 ,
+.Xr bsd.port.mk 5 ,
+.Xr library-specs 7 ,
+.Xr packages 7 ,
+.Xr packages-specs 7 ,
+.Xr ports 7