xref: /openbsd-src/share/man/man7/packages-specs.7 (revision a28daedfc357b214be5c701aa8ba8adb29a7f1c2)
1.\" $OpenBSD: packages-specs.7,v 1.10 2008/07/15 11:10:51 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: July 15 2008 $
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.
121The
122.Ar directory,[-multi],[flavor...]
123part of the dependency is always used to obtain the default dependency for
124the given package (the package that will be built and installed if no package
125is found).
126The corresponding package name is also used as a package specification,
127after removing any version and flavor requirements.
128.Pp
129An explicit specification such as
130.Qq ghostscript-*
131may be used to ask for any version of package ghostscript,
132or a more specific version number may be required, such as
133.Qq png-1.0.7 .
134Version numbers may also include ranges, separated by commas, so for
135instance,
136.Qq foo->=1.3
137would match any foo with version at least 1.3, and
138.Qq foo->=1.3,<=1.5
139would match any version of foo between 1.3 and 1.5, inclusive.
140.Pp
141If the flavor specification is left blank, any flavor will do.
142Note that most default package names don't contain flavor specification,
143which means that any flavor will do.
144For instance, in
145.Bd -literal -offset indent
146LIB_DEPENDS=aa.1.2::graphics/aalib
147.Ed
148.Pp
149both
150.Qq aalib-1.2
151and
152.Qq aalib-1.2-no_x11
153will do.
154To restrict the specification to packages that match flavor
155.Sq f ,
156append
157.Sq -f .
158To restrict the specification to packages that do not match flavor
159.Sq f ,
160append
161.Sq -!f .
162In the preceding case, one may use
163.Bd -literal -offset indent
164LIB_DEPENDS=aa.1.2:aalib-*-!no_x11:graphics/aalib
165.Ed
166.Pp
167to ensure the no_x11 flavor is not picked.
168.Sh DEPENDENCIES RESOLUTION
169Several packages may be specified for a dependency:
170.Qq foo-*|bar-*
171will match either any version of package foo, or any version of package bar.
172In the general case, each package holds a tree of dependencies.
173Resolution occurs at
174.Xr pkg_add 1
175time, and all dependencies are tracked only as far as needed.
176.Pp
177For instance, if package
178.Qq foo-1.0
179depends on either
180.Qq bar-*
181or
182.Qq fuzz-* ,
183and
184.Qq bar-2.0
185depends
186on
187.Qq toughluck-* ,
188.Xr pkg_add 1
189will first check whether
190.Qq bar-*
191or
192.Qq fuzz-*
193is installed.
194If either is there, the
195.Qq toughluck-*
196dependency will never be examined.
197It would only be used in the case where neither
198.Qq bar-*
199nor
200.Qq fuzz-*
201are present, thus
202.Xr pkg_add 1
203would decide to bring in
204.Qq bar-2.0 ,
205and so would check on
206.Qq toughluck-* .
207.Sh SEE ALSO
208.Xr pkg_add 1 ,
209.Xr bsd.port.mk 5 ,
210.Xr library-specs 7 ,
211.Xr packages 7 ,
212.Xr ports 7
213.Sh HISTORY
214Support for these package specifications first appeared in
215.Ox 2.9 .
216