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