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