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