1.\" $OpenBSD: packages-specs.7,v 1.17 2010/11/26 07:46:31 espie Exp $ 2.\" 3.\" Copyright (c) 2001 Marc Espie 4.\" 5.\" All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR 17.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 18.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 19.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, 20.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 21.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 22.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 23.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 24.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 25.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 26.\" 27.Dd $Mdocdate: November 26 2010 $ 28.Dt PACKAGES-SPECS 7 29.Os 30.Sh NAME 31.Nm packages-specs 32.Nd binary package names specifications 33.Sh DESCRIPTION 34Each package has a name consisting of at most three parts: 35.Bd -literal -offset indent 36stem-version[-flavors] 37.Ed 38.Pp 39The 40.Ar stem 41part identifies the package. 42It may contain some dashes, but its form is mostly conventional. 43For instance, japanese packages usually 44start with a 45.Sq ja 46prefix, e.g., 47.Qq ja-kterm-6.2.0 . 48.Pp 49The 50.Ar version 51part starts at the first digit that follows a 52.Sq - , 53and goes on up to the following 54.Sq - , 55or to the end of the package name, if no flavor modifier is present. 56All packages must have a version number. 57Normally, the version number directly matches the original software 58distribution version number, or release date. 59In case there are substantial changes in the 60.Ox 61package, a patch level marker should be appended, e.g., 62.Sq p0 , 63.Sq p1 ... 64For example, assuming that the screen package for release 2.8 was 65named 66.Qq screen-2.9.8 67and that an important security patch led to a newer package, 68the new package would be called 69.Qq screen-2.9.8p0 . 70Obviously, these specific markers are reserved for 71.Ox 72purposes. 73See 74.Ev REVISION 75in 76.Xr bsd.port.mk 5 . 77.Pp 78In some rare cases, version numbering changes completely upstream. 79A version style marker, of the form 80.Sq v0 , 81.Sq v1 ... 82can be appended to the version number (after the patch level) 83to denote the new numbering scheme. 84See 85.Ev EPOCH 86in 87.Xr bsd.port.mk 5 . 88.Pp 89Flavored packages will also contain a list of flavors after the version 90identifier, in a canonical order determined by 91.Ev FLAVORS 92in the corresponding port's 93.Pa Makefile . 94For instance, kterm has an xaw3d flavor: 95.Qq ja-kterm-xaw3d . 96.Pp 97Note that, to uniquely identify the version part, no flavor shall ever 98start with a digit. 99Usually, flavored packages are slightly different versions of the same 100package that offer very similar functionalities. 101.Sh CONFLICTS 102Most conflicts between packages are handled on a package name basis. 103Unless the packages have been specially prepared, it is 104normally not possible to install two packages with the same 105.Ar stem . 106.Pp 107Note that the 108.Ar stem 109ends at the 110.Ar version 111part. 112So, for instance, 113.Qq kdelibs-1.1.2 114and 115.Qq kdelibs-2.1.1 116conflict. 117But 118.Qq openldap-2.0.7 119and 120.Qq openldap-client-2.0.7 121don't. 122Neither do 123.Qq qt-1.45 124and 125.Qq qt2-3.0 . 126.Sh DEPENDENCIES 127Packages may depend on other packages, as specified by their port's 128Makefile, in a 129.Ev BUILD_DEPENDS , 130.Ev LIB_DEPENDS , 131.Ev REGRESS_DEPENDS 132or 133.Ev RUN_DEPENDS . 134All those conform to 135.Bd -literal -offset indent 136[pkgspec:]directory,[-multi],[flavor...] 137.Ed 138.Pp 139The 140.Ar directory,[-multi],[flavor...] 141part of the dependency is always used to obtain the default dependency for 142the given package (the package that will be built and installed if no package 143is found). 144The corresponding package name is also used as a package specification, 145after removing any version and flavor requirements. 146.Pp 147Without a 148.Sq pkgspec: 149part, by default, any package with the right stem will do: in effect, 150the pkgspec used is 151.Sq stem-* . 152.Pp 153In 154.Ox 4.9 , 155the dependent port may override this default, and set 156.Ev PKGSPEC 157to achieve a more restrictive default, for instance, 158.Pa databases/db/v3 159sets the default to 160.Qq PKGSPEC = db->=3,<4 161to avoid collision with 162.Pa databases/db/v4 . 163Be extra cautious with this functionality: this tweaks the depends line for 164any including package, thus usually requiring a version bump, and is in 165general only required for very messy cases where several incompatible versions 166of the same software coexist as packages with the same stem. 167.Pp 168An explicit specification such as 169.Qq png-1.0.7 . 170may be used to ask for a more specific version number. 171Version numbers may also include ranges, separated by commas, so for 172instance, 173.Qq foo->=1.3 174would match any foo with version at least 1.3, and 175.Qq foo->=1.3,<=1.5 176would match any version of foo between 1.3 and 1.5, inclusive. 177.Pp 178As a convenience, the ports tree recognizes a specification that starts 179with STEM, and will replace this with the correct stem, which can be useful 180for embarrassingly long package names. 181.Pp 182As another convenience, the ports tree recognizes constructs like 183.Qq graphics/png>=1.2.0 184and transforms it into 185.Qq STEM->=1.2.0:graphics/png . 186More specifically, package paths never contain <, >, or =, and those 187characters trigger the transform. 188.Pp 189If the flavor specification is left blank, any flavor will do. 190Note that most default package names don't contain flavor specification, 191which means that any flavor will do 192For instance, in 193.Bd -literal -offset indent 194LIB_DEPENDS = graphics/aalib 195.Ed 196.Pp 197both 198.Qq aalib-1.2 199and 200.Qq aalib-1.2-no_x11 201will do. 202To restrict the specification to packages that match flavor 203.Sq f , 204append 205.Sq -f . 206To restrict the specification to packages that do not match flavor 207.Sq f , 208append 209.Sq -!f . 210In the preceding case, one may use 211.Bd -literal -offset indent 212LIB_DEPENDS = aalib-*-!no_x11:graphics/aalib 213.Ed 214.Pp 215to ensure the no_x11 flavor is not picked. 216.Sh DEPENDENCIES RESOLUTION 217Several packages may be specified for a dependency: 218.Qq foo-*|bar-* 219will match either any version of package foo, or any version of package bar. 220In the general case, each package holds a tree of dependencies. 221Resolution occurs at 222.Xr pkg_add 1 223time, and all dependencies are tracked only as far as needed. 224.Pp 225For instance, if package 226.Qq foo-1.0 227depends on either 228.Qq bar-* 229or 230.Qq fuzz-* , 231and 232.Qq bar-2.0 233depends 234on 235.Qq toughluck-* , 236.Xr pkg_add 1 237will first check whether 238.Qq bar-* 239or 240.Qq fuzz-* 241is installed. 242If either is there, the 243.Qq toughluck-* 244dependency will never be examined. 245It would only be used in the case where neither 246.Qq bar-* 247nor 248.Qq fuzz-* 249are present, thus 250.Xr pkg_add 1 251would decide to bring in 252.Qq bar-2.0 , 253and so would check on 254.Qq toughluck-* . 255.Sh SEE ALSO 256.Xr pkg_add 1 , 257.Xr bsd.port.mk 5 , 258.Xr library-specs 7 , 259.Xr packages 7 , 260.Xr ports 7 261.Sh HISTORY 262Support for a more complex form of those package specifications first 263appeared in 264.Ox 2.9 . 265The current simplified form was introduced in 266.Ox 4.9 . 267