1.\" $OpenBSD: packages-specs.7,v 1.25 2014/10/27 22:45:30 gsoares 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: October 27 2014 $ 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, whichever comes first. 56.Pp 57It is followed by the (possibly empty) 58.Op - Ns Ar flavors 59part. 60.Pp 61Thus, version numbers should always start with a digit and cannot contain 62a 63.Sq - , 64whereas flavors should never start with a digit. 65.Pp 66All packages must have a version number. 67Normally, the version number directly matches the original software 68distribution version number, or release date. 69In case there are substantial changes in the 70.Ox 71package, a patch level marker should be appended, e.g., 72.Sq p0 , 73.Sq p1 ... 74For example, assuming that the screen package for release 2.8 was 75named 76.Qq screen-2.9.8 77and that an important security patch led to a newer package, 78the new package would be called 79.Qq screen-2.9.8p0 . 80Obviously, these specific markers are reserved for 81.Ox 82purposes. 83See 84.Ev REVISION 85in 86.Xr bsd.port.mk 5 . 87.Pp 88Version comparison is done using the dewey notation with a few specific rules. 89.Bl -bullet 90.It 91The version number is cut into separate parts on each dot 92.Sq \&. . 93Therefore, replace other upstream separators such as 94.Sq _ 95or 96.Sq - 97with dots. 98.It 99Comparison checks each part in turn, the first part that differs yields 100a comparison result. 101.It 102If parts are numbers they are compared numerically. 103.It 104Parts can also be numbers with an optional letter appended. 105The numbers are compared numerically, and in case of equality, the letter 106makes the difference. 107.It 108Other parts are compared alphabetically. 109.It 110The last part may contain an extra suffix matching 111.Ar rc[N] , 112.Ar beta[N] , 113.Ar pre[N] , 114or 115.Ar pl[N] , 116with 117.Ar N 118an optional number. 119These correspond to traditional notations for 120.Sq release candidate , 121.Sq beta version , 122.Sq pre-release , 123.Sq patch-level , 124and are ordered accordingly, e.g., 125.Ar beta 126is oldest, 127.Ar rc 128and 129.Ar pre 130are next (and non-comparable to one another), 131then normal version, and finally 132.Ar pl . 133.Bl -dash 134.It 135"foo-1.01" is equal to "foo-1.1", which can lead to surprises.. 136.It 137"foo-1.001" is older than "foo-1.002", which in turns is older than "foo-1.0010" 138.It 139"foo-1.0rc2" is not comparable to "foo-1.0pre3" 140.It 141"bar-1.0beta3" is older than "bar-1.0rc1" 142.It 143"baz-1.0" is older than "baz-1.0pl1" 144.El 145.El 146.Pp 147In some rare cases, version numbering changes completely upstream. 148A version style marker, of the form 149.Sq v0 , 150.Sq v1 ... 151can be appended to the version number (after the patch level) 152to denote the new numbering scheme. 153See 154.Ev EPOCH 155in 156.Xr bsd.port.mk 5 . 157.Pp 158Flavored packages will also contain a list of flavors after the version 159identifier, in a canonical order determined by 160.Ev FLAVORS 161in the corresponding port's 162.Pa Makefile . 163For instance, kterm has an xaw3d flavor: 164.Qq ja-kterm-xaw3d . 165.Pp 166Note that, to uniquely identify the version part, no flavor shall ever 167start with a digit. 168Usually, flavored packages are slightly different versions of the same 169package that offer very similar functionalities. 170.Sh CONFLICTS 171Most conflicts between packages are handled on a package name basis. 172Unless the packages have been specially prepared, it is 173normally not possible to install two packages with the same 174.Ar stem . 175.Pp 176Note that the 177.Ar stem 178ends at the 179.Ar version 180part. 181So, for instance, 182.Qq kdelibs-1.1.2 183and 184.Qq kdelibs-2.1.1 185conflict. 186But 187.Qq openldap-2.0.7 188and 189.Qq openldap-client-2.0.7 190don't. 191Neither do 192.Qq qt-1.45 193and 194.Qq qt2-3.0 . 195.Sh DEPENDENCIES 196Packages may depend on other packages, as specified by their port's 197Makefile, in a 198.Ev BUILD_DEPENDS , 199.Ev LIB_DEPENDS , 200.Ev TEST_DEPENDS 201or 202.Ev RUN_DEPENDS . 203All those conform to 204.Bd -literal -offset indent 205[pkgspec:]pkgpath 206.Ed 207.Pp 208The 209.Xr pkgpath 7 210part of the dependency is always used to obtain the default dependency for 211the given package (the package that will be built and installed if no package 212is found). 213The corresponding package name is also used as a package specification, 214after removing any version and flavor requirements. 215.Pp 216Without a 217.Sq pkgspec: 218part, by default, any package with the right stem will do: in effect, 219the pkgspec used is 220.Sq stem-* . 221.Pp 222In 223.Ox 4.9 , 224the dependent port may override this default, and set 225.Ev PKGSPEC 226to achieve a more restrictive default, for instance, 227.Pa databases/db/v3 228sets the default to 229.Qq PKGSPEC = db->=3,<4 230to avoid collision with 231.Pa databases/db/v4 . 232Be extra cautious with this functionality: this tweaks the depends line for 233any including package, thus usually requiring a version bump, and is in 234general only required for very messy cases where several incompatible versions 235of the same software coexist as packages with the same stem. 236.Pp 237An explicit specification such as 238.Qq png-1.0.7 . 239may be used to ask for a more specific version number. 240Version numbers may also include ranges, separated by commas, so for 241instance, 242.Qq foo->=1.3 243would match any foo with version at least 1.3, and 244.Qq foo->=1.3,<=1.5 245would match any version of foo between 1.3 and 1.5, inclusive. 246.Pp 247As a convenience, the ports tree recognizes a specification that starts 248with STEM, and will replace this with the correct stem, which can be useful 249for embarrassingly long package names. 250.Pp 251As another convenience, the ports tree recognizes constructs like 252.Qq graphics/png>=1.2.0 253and transforms it into 254.Qq STEM->=1.2.0:graphics/png . 255More specifically, package paths never contain <, >, or =, and those 256characters trigger the transform. 257.Pp 258If the flavor specification is left blank, any flavor will do. 259Note that most default package names don't contain flavor specification, 260which means that any flavor will do 261For instance, in 262.Bd -literal -offset indent 263LIB_DEPENDS = graphics/aalib 264.Ed 265.Pp 266both 267.Qq aalib-1.2 268and 269.Qq aalib-1.2-no_x11 270will do. 271To restrict the specification to packages that match flavor 272.Sq f , 273append 274.Sq -f . 275To restrict the specification to packages that do not match flavor 276.Sq f , 277append 278.Sq -!f . 279In the preceding case, one may use 280.Bd -literal -offset indent 281LIB_DEPENDS = aalib-*-!no_x11:graphics/aalib 282.Ed 283.Pp 284to ensure the no_x11 flavor is not picked. 285.Sh DEPENDENCIES RESOLUTION 286Several packages may be specified for a dependency: 287.Qq foo-*|bar-* 288will match either any version of package foo, or any version of package bar. 289In the general case, each package holds a tree of dependencies. 290Resolution occurs at 291.Xr pkg_add 1 292time, and all dependencies are tracked only as far as needed. 293.Pp 294For instance, if package 295.Qq foo-1.0 296depends on either 297.Qq bar-* 298or 299.Qq fuzz-* , 300and 301.Qq bar-2.0 302depends 303on 304.Qq toughluck-* , 305.Xr pkg_add 1 306will first check whether 307.Qq bar-* 308or 309.Qq fuzz-* 310is installed. 311If either is there, the 312.Qq toughluck-* 313dependency will never be examined. 314It would only be used in the case where neither 315.Qq bar-* 316nor 317.Qq fuzz-* 318are present, thus 319.Xr pkg_add 1 320would decide to bring in 321.Qq bar-2.0 , 322and so would check on 323.Qq toughluck-* . 324.Sh SEE ALSO 325.Xr pkg_add 1 , 326.Xr bsd.port.mk 5 , 327.Xr library-specs 7 , 328.Xr packages 7 , 329.Xr pkgpath 7 , 330.Xr ports 7 331.Sh HISTORY 332Support for a more complex form of those package specifications first 333appeared in 334.Ox 2.9 . 335The current simplified form was introduced in 336.Ox 4.9 . 337