rpm  5.4.15
dependencies
Go to the documentation of this file.
1 /*! \page dependencies Dependencies
2 
3 Dependencies provide a way for a package builder to require other
4 packages or capabilities to be installed before or simultaneously
5 with one another. These can be used to require a python interpretor
6 for a python based application for example. RPM ensures dependencies
7 are satisfied whenever packages are installed, erased, or upgraded.
8 
9 \subsection dependencies_package Requiring Packages
10 
11 To require the packages python and perl, use:
12 
13 \verbatim
14  Requires: python perl
15 \endverbatim
16 
17 in the spec file. Note that "Requires python, perl" would work as well. If you
18 needed to have a very recent version of python but any version of perl,
19 
20 \verbatim
21  Requires: python >= 1.3, perl
22 \endverbatim
23 
24 would do the trick. Again, the ',' in the line is optional. Instead of
25 '>=', you may also use '<', '>', '<=', or '='. Spaces are required
26 around the numeric operator to separate the operator from the package name.
27 
28 The full syntax for specifying a dependency on an epoch, version and release
29 is
30 \verbatim
31  [epoch:]version[-release]
32 \endverbatim
33 where
34 \verbatim
35  epoch (optional) number, with assumed default of 0 if not supplied
36  version (required) can contain any character except '-'
37  release (optional) can contain any character except '-'
38 \endverbatim
39 
40 For example,
41 
42 \verbatim
43  Requires: perl >= 9:5.00502-3
44 \endverbatim
45 
46 specifies
47 
48 \verbatim
49  epoch=9
50  version=5.00502
51  release=3
52 \endverbatim
53 
54 The epoch (if present) is a monotonically increasing integer, neither the
55 version or the release can contain the '-' hyphen character, and the dependency
56 parser does not permit white space within a definition. Unspecified epoch
57 and releases are assumed to be zero, and are interpreted as "providing all"
58 or "requiring any" value.
59 
60 The release tag is usually incremented every time a package is rebuilt for
61 any reason, even if the source code does not change. For example, changes
62 to the specfile, compiler(s) used to build the package, and/or dependency
63 changes should all be tracked by incrementing the release. The version number,
64 on the other hand, is usually set by the developer or upstream maintainer,
65 and should not be casually modified by the packager.
66 
67 Version numbering should be kept simple so that it is easy to determine the
68 version ordering for any set of packages. If the packager needs to separate
69 a release from all other releases that came before it, then the epoch, the
70 most significant part of package ordering, can be changed.
71 
72 The algorithm that RPM uses to determine the version ordering of
73 packages is simple and developers are encouraged not to rely on the
74 details of its working. Developers should keep their numbering scheme
75 simple so any reasonable ordering algorithm would work. The version
76 comparison algorithm is in the routine rpmvercmp() and it is just a segmented
77 strcmp(3). First, the boundaries of the segments are found using
78 isdigit(3)/isalpha(3). Each segment is then compared in order with the
79 right most segment being the least significant. The alphabetical
80 portions are compared using a lexical graphical ascii ordering, the
81 digit segments strip leading zeroes and compare the strlen before
82 doing a strcmp. If both numerical strings are equal, the longer string
83 is larger. Notice that the algorithm has no knowledge of decimal fractions,
84 and perl-5.6 is "older" than perl-5.00503 because the number 6 is less than
85 the number 503.
86 
87 The concept of "newer" used by rpm to determine when a package should be
88 upgraded can be broken if version format changes oddly, such as when the
89 version segments cannot be meaningfully compared.
90 
91 Example of a bad format change: 2.1.7Ax to 19980531
92 \verbatim
93  The date may be the older version, but it is numerically greater
94  2 so it is considered newer :(
95 \endverbatim
96 
97 Example of a bad increment: 2.1.7a to 2.1.7A
98 \verbatim
99  The 'a' (ASCII 97) is compared against 'A' (ASCII 65), making 2.1.7a
100  the newer version.
101 \endverbatim
102 
103 Stick to major.minor.patchlevel using numbers for each if you can.
104 Keeps life simple :-)
105 
106 If a Requires: line needs to include an epoch in the comparison, then
107 the line should be written like
108 
109 \verbatim
110  Requires: somepackage = 23:version
111 \endverbatim
112 
113 You can't continue a "Requires: " line. If you have multiple
114 "Requires: " lines then the package requires all packages mentioned on
115 all of the lines to be installed.
116 
117 \subsection dependencies_prereqs Prereqs
118 
119 Prereqs are different from requires only in that a PreReq is guaranteed
120 to be installed before the package that contains the PreReq. PreReq's
121 are used only to order packages, otherwise PreReq's are exactly the same
122 as a Requires: dependency.
123 
124 \subsection dependencies_virtual Virtual Packages
125 
126 Sometimes you need to make sure the system your package is being installed
127 on has a package which provides a certain capability, even though you don't
128 care what specific package provides it. For example, sendmail won't work
129 properly unless a local delivery agent (lda) is present. You can ensure that
130 one is installed like this:
131 
132 \verbatim
133  Requires: lda
134 \endverbatim
135 
136 This will match either a package called lda (as mentioned above), or any
137 package which contains:
138 
139 \verbatim
140  Provides: lda
141 \endverbatim
142 
143 in its .spec file. No version numbers may be used with virtual packages.
144 
145 Virtual packages are often used to supply file dependencies such as /bin/sh
146 on machines that are only partly managed by rpm. A virtual package with
147 \verbatim
148  Provides: /bin/sh
149 \endverbatim
150 differs from a package that has /bin/sh in the %files list in that the
151 package can be safely removed without removing /bin/sh.
152 
153 \subsection dependencies_automatic Automatic Dependencies
154 
155 To reduce the amount of work required by the package builder, RPM scans
156 the file list of a package when it is being built. Any files in the file
157 list which require shared libraries to work (as determined by ldd) cause
158 that package to require the shared library.
159 
160 For example, if your package contains /bin/vi, RPM will add dependencies
161 for both libtermcap.so.2 and libc.so.5. These are treated as virtual
162 packages, so no version numbers are used.
163 
164 A similar process allows RPM to add Provides information automatically. Any
165 shared library in the file list is examined for its soname (the part of
166 the name which must match for two shared libraries to be considered
167 equivalent) and that soname is automatically provided by the package. For
168 example, the libc-5.3.12 package has provides information added for
169 libm.so.5 and libc.so.5. We expect this automatic dependency generation
170 to eliminate the need for most packages to use explicit Requires: lines.
171 
172 \subsection dependencies_custom Custom Automatic Dependency
173 
174 The automatic dependency programs are found via macro expansion. Thus
175 sites can very the amount of dependency processing that are performed
176 locally, by changing the executable/script which is run. Dependency
177 processing can even be changed on a per-package basis if the macros are
178 defined in the spec file. To allow for maximum configurability the
179 dependency programs are shell scripts which can be duplicated and edited
180 for site specific needs.
181 
182 The macros: %__find_provides, %__find_prereq, %__find_requires,
183 %__find_conflicts, %__find_obsoletes, if they exist, are expanded to
184 the name of a program to exec. For each package, the program receives
185 the glob'ed %files manifest on stdin and returns dependencies on stdout. The
186 discovered dependencies are parsed exactly as if they were found after
187 
188 \verbatim
189  Provides:
190  PreReq:
191  Requires:
192  Conflicts:
193  Obsoletes:
194 \endverbatim
195 tokens in a spec file (i.e. the same parser is used), so items look like
196 (comments added)
197 \verbatim
198  /bin/sh # file existence
199  libc.so.6 # soname existence
200  foo <= 1:2.3-4 # versioned package
201  perl5(Apache) <= 1.2 # versioned namespace
202 \endverbatim
203 
204 The default rpm configuration has only
205  %__find_provides /usr/lib/rpm/find-provides
206  %__find_requires /usr/lib/rpm/find-requires
207 which can be overridden (or even undefined) within a spec file.
208 
209 \subsection dependencies_interpreters Interpreters and Shells
210 
211 Modules for interpreted languages like perl and tcl impose additional
212 dependency requirements on packages. A script written for an interpreter
213 often requires language specific modules to be installed in order to execute
214 correctly. In order to automatically detect language specific modules, each
215 interpreter may have its own find-provides and find-requires. To prevent
216 module name collisions between interpreters, module names are enclosed within
217 parentheses and a conventional interpreter specific identifier is prepended:
218 
219 
220 \verbatim
221  Provides: perl(MIME-Base64), perl(Mail-Header)-1-09
222 
223  Requires: perl(Carp), perl(IO-Wrap) = 4.5
224 \endverbatim
225 
226 
227 The output of a per-interpreter find-requires (notice in this example the
228 first requirement is a package and the rest are language specific modules)
229 
230 \verbatim
231  Mail-Header >= 1.01
232  perl(Carp) >= 3.2
233  perl(IO-Wrap) == 4.5 or perl(IO-Wrap)-4.5
234 \endverbatim
235 
236 the output from find-provides is
237 \verbatim
238  Foo-0.9
239  perl(Widget)-0-1
240 \endverbatim
241 
242 The per-interpreter automatic module detectors will normally be located in
243 \verbatim
244  /usr/lib/rpm/{perl,tcl}/find-{provides,requires}
245 with appropriate per-interpreter hooks into
246 \verbatim
247  /usr/lib/rpm/find-{provides,requires}
248 \endverbatim
249 
250 @todo per-interpreter dependency generators are not located in subdirectories.
251 
252 Notice that shell dependencies will require that all %post et al scriptlets
253 be processed by the find-requires. Since a shell script depends on all the
254 programs which it runs.
255 
256 
257 \subsection dependencies_installing Installing and Erasing Packages with Dependencies
258 
259 For the most part, dependencies should be transparent to the user. However,
260 a few things will change.
261 
262 First, when packages are added or upgraded, all of their dependencies
263 must be satisfied. If they are not, an error message like this appears:
264 
265 \verbatim
266  failed dependencies:
267  libICE.so.6 is needed by somepackage-2.11-1
268  libSM.so.6 is needed by somepackage-2.11-1
269  libc.so.5 is needed by somepackage-2.11-1
270 \endverbatim
271 
272 Similarly, when packages are removed, a check is made to ensure that
273 no installed packages will have their dependency conditions break due to
274 the packages being removed. If you wish to turn off dependency checking for
275 a particular command, use the --nodeps flag.
276 
277 \subsection dependencies_conflicts Conflicts
278 
279 While conflicts were implemented in earlier versions of RPM they never
280 worked properly until RPM 2.3.4 (well, we hope they work properly now
281 anyway).
282 
283 Conflicts allow a package to say it won't work with another package (or
284 virtual package) installed on the system. For example, qmail doesn't work
285 (w/o custom setup) on machines with sendmail installed. The qmail spec file
286 may codify this with a line like:
287 
288 \verbatim
289  Conflicts: sendmail
290 \endverbatim
291 
292 The syntax of the "Conflicts" tag is identical to the syntax of the Requires
293 tag and conflict checking may be overridden by using the --nodeps flag.
294 
295 \subsection dependencies_querying Querying for Dependencies
296 
297 Two new query information selection options are now available. The first,
298 --provides, prints a list of all of the capabilities a package provides.
299 The second, --requires, shows the other packages that a package requires
300 to be installed, along with any version number checking.
301 
302 There are also two new ways to search for packages. Running a query with
303 --whatrequires ITEM queries all of the packages that require ITEM.
304 Similarly, running --whatprovides ITEM queries all of the packages that
305 provide the ITEM virtual package. Note that querying for package that
306 provides "python" will not return anything, as python is a package, not
307 a virtual package.
308 
309 \subsection dependencies_verifying Verifying Dependencies
310 
311 As of RPM 2.2.2, -V (aka --verify) verifies package dependencies
312 by default. You can tell rpm to ignore dependencies during system
313 verification with the --nodeps. If you want RPM to verify just dependencies
314 and not file attributes (including file existence), use the --nofiles
315 flag. Note that "rpm -Va --nofiles --nodeps" will not verify anything at
316 all, nor generate an error message.
317 
318 \subsection dependencies_branching Branching Version
319 
320 It is quite common to need to branch a set of sources in version
321 control. It is not so obvious how those branches should be represented
322 in the package version numbers. Here is one solution.
323 
324 You have a bag of features that are injected into a package in a
325 non-ordered fashion, and you want to have the package
326 name-version-release be able to:
327 
328 \verbatim
329  1) identify the "root version" of the source code.
330  2) identify the handful of features that are in that
331  branch of the package.
332  3) preserve sufficient ordering so that packages upgrade
333  without the use of --oldpackage.
334 \endverbatim
335 
336 A simple (but possibly not adequate) scheme to achieve this is:
337 
338 \verbatim
339  Name: foo
340  Version: VERSION # i.e. the upstream version
341  Release: RELEASE.BRANCH
342 \endverbatim
343 
344 where the release instance is something like YYYMMMDD or some linear
345 record of the number of builds with the current tar file, it is used
346 to preserve ordering when necessary.
347 
348 Another alternative scheme might be:
349 
350 \verbatim
351  Name: foo
352  Epoch: BRANCH
353  Version: VERSION
354  Release: RELEASE
355 \endverbatim
356 
357 \subsection dependencies_build Build dependencies
358 
359 The following dependencies are available at build time. These are
360 similar to the install time version but these apply only during
361 package creation and are specified in the specfile not in the binary
362 package.
363 
364 \verbatim
365  BuildRequires:
366  BuildConflicts:
367  BuildPreReq:
368 \endverbatim
369 
370 */