1.\" $OpenBSD: pkgpath.7,v 1.5 2017/03/27 10:37:43 fcambus Exp $ 2.\" 3.\" Copyright (c) 2011 Marc Espie <espie@openbsd.org> 4.\" 5.\" Permission to use, copy, modify, and distribute this software for any 6.\" purpose with or without fee is hereby granted, provided that the above 7.\" copyright notice and this permission notice appear in all copies. 8.\" 9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 16.Dd $Mdocdate: March 27 2017 $ 17.Dt PKGPATH 7 18.Os 19.Sh NAME 20.Nm pkgpath 21.Nd ports tree location for a package build 22.Sh DESCRIPTION 23Each location in the ports tree is uniquely identified through a 24.Nm , 25which encodes the directory, flavor and subpackage information 26that allows the build of a package. 27This is not to be confused with 28.Ev PKG_PATH , 29the list of URLs from which 30.Xr pkg_add 1 31retrieves binary packages. 32.Pp 33Every 34.Nm 35conforms to the pattern 36.Ar some/directory[,-sub][,flavor...] . 37.Pp 38The 39.Ar some/directory 40part refers to the directory part, to find under the 41portstree, usually in 42.Pa /usr/ports 43(or 44.Pa /usr/ports/mystuff 45for port developers). 46.Pp 47The 48.Ar ,-sub 49optional part refers to a specific subpackage from a 50multi-package port. 51It can be left blank for non multi-package ports, or to get 52the default subpackage 53(usually 54.Ar -main ) . 55.Pp 56The 57.Ar ,flavor... 58optional part refers to the flavors or pseudo-flavors to use 59when building the package. 60If left blank, it refers to the default flavor. 61An explicit empty flavor can also be specified to make sure to 62get an empty flavor, even if it does not correspond to the default 63flavor. 64.Pp 65Note that 66.Ar -sub 67and 68.Ar flavor 69parts can be specified in any order, as all subpackages start with 70a dash. 71It is an error to ask for several subs at once, e.g.\& 72.Ar some/path,-sub1,-sub2 , 73though it won't always be flagged as a problem. 74.Pp 75For instance: 76.Bl -tag -width small 77.It Ar misc/screen 78A simple directory, default flavor, which happens to be empty. 79.It Ar misc/screen,static 80Same port, 81.Ar static 82flavor. 83.It Ar x11/kde/libs3 84A multi-package port with no subpackage nor flavor, refers to 85.Ar x11/kde/libs3,-main . 86.It Ar net/avahi 87Multi-package port with default flavor. 88Will actually build with FLAVOR="no_gui no_mono no_qt3 no_qt4 bootstrap" 89(all of which are pseudo-flavors), so that only the main package will build. 90.It Ar net/avahi,no_mono,-qt3 91Build avahi with the "no_mono" pseudo-flavor, which will build the 92-main, -qt3, -qt4, -gui, -gtk, -gtk3, and -ui subpackages, and refer to the 93.Ar -qt3 94subpackage. 95.It Ar net/avahi, 96.Ar net/avahi 97with an explicit empty flavor, default subpackage 98.Po 99which happens to be 100.Ar -main 101.Pc . 102.It Ar net/avahi,,-qt4 103.Ar net/avahi 104with an explicit empty flavor, 105.Ar -qt4 106subpackage. 107.El 108.Pp 109The ports tree can iterate over lists of 110.Nm 111through 112.Li SUBDIR="pkgpath1 pkgpath2..." 113or through a full list through 114.Li SUBDIRLIST=file . 115.Pp 116.Xr dpb 1 117also handles 118.Nm 119lists for many options. 120.Sh NORMALISATION AND THE FULLPATH CONVENTION 121When the ports tree handles dependencies, it passes 122.Nm 123from 124.Ev BUILD_DEPENDS , 125.Ev LIB_DEPENDS , 126.Ev RUN_DEPENDS , 127and 128.Ev TEST_DEPENDS 129to the dependent port for normalisation purposes. 130That way, the 131.Nm 132that gets recorded in the package doesn't have any "default" flavor 133or "default" subpackage left: those are always resolved to the correct 134value. 135.Pp 136Likewise, pseudo-flavors vanish from the 137.Nm pkgpath , 138since they only participate in the build process, but do not intervene 139in the built package. 140.Pp 141As a result, such 142.Nm 143are slightly different from the description above, as a flavor left blank 144is the empty flavor (and not the default flavor). 145This is the 146.Qq fullpath convention . 147.Pp 148Tools such as 149.Xr dpb 1 150display fullpath pkgpaths, 151and binary packages store full pkgpaths. 152.Pp 153.Ev SUBDIR 154and 155.Ev SUBDIRLIST 156can be forced to follow the fullpath convention by explicitly passing 157.Li FULLPATH=Yes 158to the corresponding 159.Xr make 1 160invocations. 161.Pp 162Most tools that process binary packages do so. 163.Sh SEE ALSO 164.Xr dpb 1 , 165.Xr bsd.port.mk 5 , 166.Xr library-specs 7 , 167.Xr packages 7 , 168.Xr packages-specs 7 , 169.Xr ports 7 170