1.\" $OpenBSD: packages-specs.7,v 1.12 2010/07/04 18:54:41 jmc 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: July 4 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. 73.Pp 74In some rare cases, version numbering changes completely upstream. 75A version style marker, of the form 76.Sq v0 , 77.Sq v1 ... 78can be appended to the version number (after the patch level) 79to denote the new numbering scheme. 80.Pp 81Flavored packages will also contain a list of flavors after the version 82identifier, in a canonical order determined by 83.Ev FLAVORS 84in the corresponding port's 85.Pa Makefile . 86For instance, kterm has an xaw3d flavor: 87.Qq ja-kterm-xaw3d . 88.Pp 89Note that, to uniquely identify the version part, no flavor shall ever 90start with a digit. 91Usually, flavored packages are slightly different versions of the same 92package that offer very similar functionalities. 93.Sh CONFLICTS 94Most conflicts between packages are handled on a package name basis. 95Unless the packages have been specially prepared, it is 96normally not possible to install two packages with the same 97.Ar stem . 98.Pp 99Note that the 100.Ar stem 101ends at the 102.Ar version 103part. 104So, for instance, 105.Qq kdelibs-1.1.2 106and 107.Qq kdelibs-2.1.1 108conflict. 109But 110.Qq openldap-2.0.7 111and 112.Qq openldap-client-2.0.7 113don't. 114Neither do 115.Qq qt-1.45 116and 117.Qq qt2-3.0 . 118.Sh DEPENDENCIES 119Packages may depend on other packages, as specified by their port's 120Makefile, in a 121.Ev BUILD_DEPENDS , 122.Ev LIB_DEPENDS , 123.Ev REGRESS_DEPENDS 124or 125.Ev RUN_DEPENDS . 126All those conform to 127.Bd -literal -offset indent 128[legacy]:[pkgspec]:directory,[-multi],[flavor...] 129.Ed 130.Pp 131The 132.Ar [legacy] 133part of the dependency corresponds to older semantics that have been 134deprecated. 135.Pp 136The 137.Ar directory,[-multi],[flavor...] 138part of the dependency is always used to obtain the default dependency for 139the given package (the package that will be built and installed if no package 140is found). 141The corresponding package name is also used as a package specification, 142after removing any version and flavor requirements. 143.Pp 144If the 145.Sq pkgspec 146part is left empty, any package with the right stem will do: in effect, 147the pkgspec used is 148.Sq stem-* . 149.Pp 150An explicit specification such as 151.Qq ghostscript-* 152may be used to ask for any version of package ghostscript, 153or a more specific version number may be required, such as 154.Qq png-1.0.7 . 155Version numbers may also include ranges, separated by commas, so for 156instance, 157.Qq foo->=1.3 158would match any foo with version at least 1.3, and 159.Qq foo->=1.3,<=1.5 160would match any version of foo between 1.3 and 1.5, inclusive. 161.Pp 162If the flavor specification is left blank, any flavor will do. 163Note that most default package names don't contain flavor specification, 164which means that any flavor will do. 165For instance, in 166.Bd -literal -offset indent 167LIB_DEPENDS=::graphics/aalib 168.Ed 169.Pp 170both 171.Qq aalib-1.2 172and 173.Qq aalib-1.2-no_x11 174will do. 175To restrict the specification to packages that match flavor 176.Sq f , 177append 178.Sq -f . 179To restrict the specification to packages that do not match flavor 180.Sq f , 181append 182.Sq -!f . 183In the preceding case, one may use 184.Bd -literal -offset indent 185LIB_DEPENDS=:aalib-*-!no_x11:graphics/aalib 186.Ed 187.Pp 188to ensure the no_x11 flavor is not picked. 189.Sh DEPENDENCIES RESOLUTION 190Several packages may be specified for a dependency: 191.Qq foo-*|bar-* 192will match either any version of package foo, or any version of package bar. 193In the general case, each package holds a tree of dependencies. 194Resolution occurs at 195.Xr pkg_add 1 196time, and all dependencies are tracked only as far as needed. 197.Pp 198For instance, if package 199.Qq foo-1.0 200depends on either 201.Qq bar-* 202or 203.Qq fuzz-* , 204and 205.Qq bar-2.0 206depends 207on 208.Qq toughluck-* , 209.Xr pkg_add 1 210will first check whether 211.Qq bar-* 212or 213.Qq fuzz-* 214is installed. 215If either is there, the 216.Qq toughluck-* 217dependency will never be examined. 218It would only be used in the case where neither 219.Qq bar-* 220nor 221.Qq fuzz-* 222are present, thus 223.Xr pkg_add 1 224would decide to bring in 225.Qq bar-2.0 , 226and so would check on 227.Qq toughluck-* . 228.Sh SEE ALSO 229.Xr pkg_add 1 , 230.Xr bsd.port.mk 5 , 231.Xr library-specs 7 , 232.Xr packages 7 , 233.Xr ports 7 234.Sh HISTORY 235Support for these package specifications first appeared in 236.Ox 2.9 . 237