share/man/man7/pkgpath.7

   1 .\" $OpenBSD: pkgpath.7,v 1.2 2013/01/09 11:52:52 espie 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: January 9 2013 $
  17 .Dt PKGPATH 7
  18 .Os
  19 .Sh NAME
  20 .Nm pkgpath
  21 .Nd ports tree location for a package build
  22 .Sh DESCRIPTION
  23 Each location in the ports tree is uniquely identified through a
  24 .Nm ,
  25 which encodes the directory, flavor and subpackage information
  26 that allows the build of a package.
  27 This is not to be confused with
  28 .Ev PKG_PATH ,
  29 the list of URLs from which
  30 .Xr pkg_add 1
  31 retrieves binary packages.
  32 .Pp
  33 Every
  34 .Nm
  35 conforms to the pattern
  36 .Ar some/directory[,-sub][,flavor...] .
  37 .Pp
  38 The
  39 .Ar some/directory
  40 part refers to the directory part, to find under the
  41 portstree, usually in
  42 .Pa /usr/ports
  43 (or
  44 .Pa /usr/port/mystuff
  45 for port developers).
  46 .Pp
  47 The
  48 .Ar ,-sub
  49 optional part refers to a specific subpackage from a
  50 multi-package port.
  51 It can be left blank for non multi-package ports, or to get
  52 the default subpackage
  53 (usually
  54 .Ar -main ) .
  55 .Pp
  56 The
  57 .Ar ,flavor...
  58 optional part refers to the flavors or pseudo-flavors to use
  59 when building the package.
  60 If left blank, it refers to the default flavor.
  61 An explicit empty flavor can also be specified to make sure to
  62 get an empty flavor, even if it does not correspond to the default
  63 flavor.
  64 .Pp
  65 Note that
  66 .Ar -sub
  67 and
  68 .Ar flavor
  69 parts can be specified in any order, as all subpackages start with
  70 a dash.
  71 It is an error to ask for several subs at once, e.g.\&
  72 .Ar some/path,-sub1,-sub2 ,
  73 though it won't always be flagged as a problem.
  74 .Pp
  75 For instance:
  76 .Bl -tag -width small
  77 .It Ar misc/screen
  78 A simple directory, default flavor, which happens to be empty.
  79 .It Ar misc/screen,static
  80 Same port,
  81 .Ar static
  82 flavor.
  83 .It Ar x11/kde/libs3
  84 A multi-package port with no subpackage nor flavor, refers to
  85 .Ar x11/kde/libs3,-main .
  86 .It Ar net/avahi
  87 Multi-package port with default flavor.
  88 Will 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
  91 Build 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
  94 subpackage.
  95 .It Ar net/avahi,
  96 .Ar net/avahi
  97 with an explicit empty flavor, default subpackage
  98 .Po
  99 which happens to be
 100 .Ar -main
 101 .Pc .
 102 .It Ar net/avahi,,-qt4
 103 .Ar net/avahi
 104 with an explicit empty flavor,
 105 .Ar -main
 106 subpackage.
 107 .El
 108 .Pp
 109 The ports tree can iterate over lists of
 110 .Nm
 111 through
 112 .Li SUBDIR="pkgpath1 pkgpath2..."
 113 or through a full list through
 114 .Li SUBDIRLIST=file .
 115 .Pp
 116 .Xr dpb 1
 117 also handles
 118 .Nm
 119 lists for many options.
 120 .Sh NORMALISATION AND THE FULLPATH CONVENTION
 121 When the ports tree handles dependencies, it passes
 122 .Nm
 123 from
 124 .Ev BUILD_DEPENDS ,
 125 .Ev LIB_DEPENDS ,
 126 .Ev RUN_DEPENDS ,
 127 and
 128 .Ev REGRESS_DEPENDS
 129 to the dependent port for normalisation purposes.
 130 That way, the
 131 .Nm
 132 that gets recorded in the package doesn't have any "default" flavor
 133 or "default" subpackage left: those are always resolved to the correct
 134 value.
 135 .Pp
 136 Likewise, pseudo-flavors vanish from the
 137 .Nm pkgpath ,
 138 since they only participate in the build process, but do not intervene
 139 in the built package.
 140 .Pp
 141 As a result, such
 142 .Nm
 143 are slightly different from the description above, as a flavor left blank
 144 is the empty flavor (and not the default flavor).
 145 This is the
 146 .Qq fullpath convention .
 147 .Pp
 148 Tools such as
 149 .Xr dpb 1
 150 display fullpath pkgpaths,
 151 and binary packages store full pkgpaths.
 152 .Pp
 153 .Ev SUBDIR
 154 and
 155 .Ev SUBDIRLIST
 156 can be forced to follow the fullpath convention by explicitly passing
 157 .Li FULLPATH=Yes
 158 to the corresponding
 159 .Xr make 1
 160 invocations.
 161 .Pp
 162 Most 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