diff options
Diffstat (limited to 'doc/manual')
| -rw-r--r-- | doc/manual/Makefile.am | 17 | ||||
| -rw-r--r-- | doc/manual/builddependencies | 2 | ||||
| -rw-r--r-- | doc/manual/buildroot | 6 | ||||
| -rw-r--r-- | doc/manual/dependencies | 24 | ||||
| -rw-r--r-- | doc/manual/format | 23 | ||||
| -rw-r--r-- | doc/manual/hregions | 89 | ||||
| -rw-r--r-- | doc/manual/macros | 16 | ||||
| -rw-r--r-- | doc/manual/queryformat | 12 | ||||
| -rw-r--r-- | doc/manual/relocatable | 4 | ||||
| -rw-r--r-- | doc/manual/signatures | 10 | ||||
| -rw-r--r-- | doc/manual/spec | 18 | ||||
| -rw-r--r-- | doc/manual/triggers | 8 | ||||
| -rw-r--r-- | doc/manual/tsort | 159 |
13 files changed, 324 insertions, 64 deletions
diff --git a/doc/manual/Makefile.am b/doc/manual/Makefile.am index 6362e7e3c..b20b807c4 100644 --- a/doc/manual/Makefile.am +++ b/doc/manual/Makefile.am @@ -1,6 +1,17 @@ ## Process this file with automake to produce Makefile.in EXTRA_DIST = \ - builddependencies buildroot dependencies format macros \ - multiplebuilds queryformat spec relocatable signatures triggers - + builddependencies \ + buildroot \ + conditionalbuilds \ + dependencies \ + format \ + hregions \ + macros \ + multiplebuilds \ + queryformat \ + relocatable \ + signatures \ + spec \ + triggers \ + tsort diff --git a/doc/manual/builddependencies b/doc/manual/builddependencies index bc09bcd1a..7c3f3795b 100644 --- a/doc/manual/builddependencies +++ b/doc/manual/builddependencies @@ -1,4 +1,4 @@ -/*! \page builddpendencies How to generate build depedencies +/*! \page builddpendencies Generating buiild dependencies automatically As we start updating packages for the next Red Hat distro, I'd like to see packages start to make use of build dependencies. Basically build diff --git a/doc/manual/buildroot b/doc/manual/buildroot index f31db4764..77b159646 100644 --- a/doc/manual/buildroot +++ b/doc/manual/buildroot @@ -6,7 +6,7 @@ that your package can be built (installed into and packaged from) a user-definable directory. This helps package building by normal users. -<h2>The Spec File</h2> +\subsection buildroot_specfile The Spec File Simply use \verbatim @@ -59,7 +59,7 @@ would be changed to: /usr/bin/fooprog \endverbatim -<h2>Building With a Build Root</h2> +\subsection buildroot_building Building With a Build Root RPM will use the buildroot listed in the spec file as the default buildroot. There are two ways to override this. First, you can @@ -67,7 +67,7 @@ have "buildroot: <dir>" in your rpmrc. Second, you can override the default, and any entry in an rpmrc by using "--buildroot <dir>" on the RPM command line. -<h2>Caveats using Build Roots</h2> +\subsection buildroot_caveats Caveats using Build Roots Care should be taken when using buildroots that the install directory is owned by the correct package. For example the file diff --git a/doc/manual/dependencies b/doc/manual/dependencies index 083b6bc0d..2623d96d9 100644 --- a/doc/manual/dependencies +++ b/doc/manual/dependencies @@ -6,7 +6,7 @@ with one another. These can be used to require a python interpretor for a python based application for example. RPM ensures dependencies are satisfied whenever packages are installed, erased, or upgraded. -<h2>Requiring Packages</h2> +\subsection dependencies_package Requiring Packages To require the packages python and perl, use: @@ -114,14 +114,14 @@ You can't continue a "Requires: " line. If you have multiple "Requires: " lines then the package requires all packages mentioned on all of the lines to be installed. -<h2>Prereqs</h2> +\subsection dependencies_prereqs Prereqs Prereqs are different from requires only in that a PreReq is guaranteed to be installed before the package that contains the PreReq. PreReq's are used only to order packages, otherwise PreReq's are exactly the same as a Requires: dependency. -<h2>Virtual Packages</h2> +\subsection dependencies_virtual Virtual Packages Sometimes you need to make sure the system your package is being installed on has a package which provides a certain capability, even though you don't @@ -150,7 +150,7 @@ on machines that are only partly managed by rpm. A virtual package with differs from a package that has /bin/sh in the %files list in that the package can be safely removed without removing /bin/sh. -<h2>Automatic Dependencies</h2> +\subsection dependencies_automatic Automatic Dependencies To reduce the amount of work required by the package builder, RPM scans the file list of a package when it is being built. Any files in the file @@ -169,7 +169,7 @@ example, the libc-5.3.12 package has provides information added for libm.so.5 and libc.so.5. We expect this automatic dependency generation to eliminate the need for most packages to use explicit Requires: lines. -<h2>Custom Automatic Dependency</h2> +\subsection dependencies_custom Custom Automatic Dependency The automatic dependency programs are found via macro expansion. Thus sites can very the amount of dependnecy processing that are performed @@ -206,7 +206,7 @@ The default rpm configuration has only %__find_requires /usr/lib/rpm/find-requires which can be overridden (or even undefined) within a spec file. -<h2>Interpreters and Shells</h2> +\subsection dependencies_interpreters Interpreters and Shells Modules for interpreted languages like perl and tcl impose additional dependency requirements on packages. A script written for an interpreter @@ -254,7 +254,7 @@ be processed by the find-requires. Since a shell script depends on all the programs which it runs. -<h2>Installing and Erasing Packages with Dependencies</h2> +\subsection dependencies_installing Installing and Erasing Packages with Dependencies For the most part, dependencies should be transparent to the user. However, a few things will change. @@ -274,7 +274,7 @@ no installed packages will have their dependency conditions break due to the packages being removed. If you wish to turn off dependency checking for a particular command, use the --nodeps flag. -<h2>Conflicts</h2> +\subsection dependencies_conflicts Conflicts While conflicts were implemented in earlier versions of RPM they never worked properly until RPM 2.3.4 (well, we hope they work properly now @@ -292,7 +292,7 @@ may codify this with a line like: The syntax of the "Conflicts" tag is identical to the syntax of the Requires tag and conflict checking may be overridden by using the --nodeps flag. -<h2>Querying for Dependencies</h2> +\subsection dependencies_querying Querying for Dependencies Two new query information selection options are now available. The first, --provides, prints a list of all of the capabilities a package provides. @@ -306,7 +306,7 @@ provide the <item> virtual package. Note that querying for package that provides "python" will not return anything, as python is a package, not a virtual package. -<h2>Verifying Dependencies</h2> +\subsection dependencies_verifying Verifying Dependencies As of RPM 2.2.2, -V (aka --verify) verifies package dependencies by default. You can tell rpm to ignore dependencies during system @@ -315,7 +315,7 @@ and not file attributes (including file existence), use the --nofiles flag. Note that "rpm -Va --nofiles --nodeps" will not verify anything at all, nor generate an error message. -<h2>Branching Version</h2> +\subsection dependencies_branching Branching Version It is quite common to need to branch a set of sources in version control. It is not so obvious how those branches should be repesented @@ -354,7 +354,7 @@ Another alternative scheme might be: Release: <release instance> \endverbatim -<h2>Build dependencies</h2> +\subsection dependencies_build Build dependencies The following dependencies are availible at build time. These are similar to the install time version but these apply only during diff --git a/doc/manual/format b/doc/manual/format index 9281add70..5eb494bce 100644 --- a/doc/manual/format +++ b/doc/manual/format @@ -4,9 +4,10 @@ This document describes the RPM file format version 3.0, which is used by RPM versions 2.1 and greater. The format is subject to change, and you should not assume that this document is kept up to date with the latest RPM code. That said, the 3.0 format should not change for -quite a while, and when it does, it will not be 3.0 anymore :-). In -any case, THE PROPER WAY TO ACCESS THESE STRUCTURES IS THROUGH THE RPM -LIBRARY!! +quite a while, and when it does, it will not be 3.0 anymore :-). + +\warning In any case, THE PROPER WAY TO ACCESS THESE STRUCTURES IS THROUGH +THE RPM LIBRARY!! The RPM file format covers both source and binary packages. An RPM package file is divided in 4 logical sections: @@ -14,8 +15,8 @@ package file is divided in 4 logical sections: \verbatim . Lead -- 96 bytes of "magic" and other info . Signature -- collection of "digital signatures" -. Header -- holding area for all the package information -. Payload -- compressed archive of all the files in the package +. Header -- holding area for all the package information (aka "metadata") +. Payload -- compressed archive of the file(s) in the package (aka "payload") \endverbatim All 2 and 4 byte "integer" quantities (int16 and int32) are stored in @@ -23,7 +24,7 @@ network byte order. When data is presented, the first number is the byte number, or address, in hex, followed by the byte values in hex, followed by character "translations" (where appropriate). -<h2>Lead</h2> +\subsection pkgformat_lead Lead The Lead is basically for file(1). All the information contained in the Lead is duplicated or superceded by information in the Header. @@ -94,7 +95,7 @@ is 5, which indicates the new "Header-style" signatures. The remaining 16 bytes (80-95) are currently unused and are reserved for future expansion. -<h2>Signature</h2> +\subsection pkgformat_signature Signature A 3.0 format signature (denoted by signature type 5 in the Lead), uses the same structure as the Header. For historical reasons, this @@ -122,7 +123,7 @@ the size of the PGP key used to sign the package. As of RPM 2.1, all packages carry at least SIZE and MD5 signatures, and the Signature section is padded to a multiple of 8 bytes. -<h2>Header</h2> +\subsection pkgformat_header Header The Header contains all the information about a package: name, version, file list, etc. It uses the same "header structure" as the @@ -131,12 +132,12 @@ tags for the Header would take too much space to list here, and the list grows fairly frequently. For the complete list see lib/rpmlib.h in the RPM sources. -<h2>Payload</h2> +\subsection pkgformat_payload Payload The Payload is currently a gzipped cpio archive. The cpio archive type used is SVR4 with a CRC checksum. -<h2>The Header Structure</h2> +\subsection pkgformat_header_structure The Header Structure The header structure is a little complicated, but actually performs a very simple function. It acts almost like a small database in that it @@ -245,7 +246,7 @@ could start at byte 589, byte that is an improper boundary for an INT32. As a result, 3 null bytes are inserted and the date for the SIZE actually starts at byte 592: "00 09 9b 31", which is 629553). -<h2>Tools</h2> +\subsection pkgformat_tools Tools The tools directory in the RPM sources contains a number of small programs that use the RPM library to pick apart packages. These diff --git a/doc/manual/hregions b/doc/manual/hregions new file mode 100644 index 000000000..91408b349 --- /dev/null +++ b/doc/manual/hregions @@ -0,0 +1,89 @@ +/*! \page hregions Immutable header regions in rpm-4.0.1 and later + +The header data structure has changed in rpm-4.0.[12] to preserve the +original header from a package. The goal is to keep the original +header intact so that metadata can be verified separately from the +payload by the RHN up2date client and by the rpm commmand line verify +mode using signatures saved in the rpm database. I believe the change +is entirely forward and backward compatible, and will not require +any artifacts like changing the version number of packaging or +adding an "rpmlib(...)" tracking dependendency. We'll see ... + +Here's a short description of the change. An rpm header has three sections: +\verbatim + 1) intro (# entries in index, # bytes of data) + 2) index 16 byte entries, one per tag, big endian + 3) data tag values, properly aligned, big endian +\endverbatim + +Representing sections in the header (ignoring the intro) with +\verbatim + A,B,C index entries sorted by tag number + a,b,c variable length entry data + | boundary between index/data +\endverbatim +a header with 3 tag/value pairs (A,a) can be represented something like +\verbatim + ABC|abc +\endverbatim + +The change is to introduce a new tag that keeps track of a contiguous +region (i.e. the original header). Representing the boundaries with +square/angle brackets, an "immutable region" in the header thus becomes +\verbatim + [ABC|abc] +\endverbatim +or more generally (spaces added for clarity) +\verbatim + [ABC> QRS | <abc] qrs +\endverbatim +or with concatenated regions (not implemented yet) +\verbatim + [ABC> [DEF> QRS | <abc] <def] qrs +\endverbatim +or with nested regions (not implemented yet) +\verbatim + [ABC [DEF>> QRS | <<abc] def] qrs +\endverbatim + +\todo Either concatenated/nested regions may be used to implement +a metarpm, aka a package of packages, dunno how, when, or even if, yet. + +What complicates the above is legacy issues, as various versions of rpm +have added/deleted/modified entries in the header freely. Thus, representing +altered tag entries/data with a '.', there is a need to preserve deleted +information something like + +\verbatim + [A.C> QRS XYZ | <a.c] qrs xyz +\endverbatim + +\note This is basically the change that replaces the filename with + a {dirname,basename,dirindex} triple between rpm-3.x and rpm-4.x. + +or + +\verbatim + [AB.> QRS D | <ab.] qrs d +\endverbatim + +\note The header is no longer sorted because of replacing Cc with Dd. + +and yet permit retrieval of the original + +\verbatim + [ABC|abc] +\endverbatim + +region. PITA, really. + +What made header regions trickier yet is the desire to have an implementation +that is both backward and forward compatible. I won't bore you with the +tedious details. + +However, even after doing regressions against supported Red Hat releases, +there's a Great Big Universe of rpm packages out there, and I'm *very* +interested in hearing (as bug reports against rpm at http://bugzilla.redhat.com) +about any and all problems with header regions in rpm-4.0.1. + +*/ diff --git a/doc/manual/macros b/doc/manual/macros index 781ceda70..d296ca1b2 100644 --- a/doc/manual/macros +++ b/doc/manual/macros @@ -10,7 +10,7 @@ lists" (i.e. those read in using %files -f <file>). In addition, macros can be nested, hiding the previous definition for the duration of the expansion of the macro which contains nested macros. -<h2>Defining a Macro</h2> +\subsection macros_defining Defining a Macro To define a macro use: @@ -39,7 +39,7 @@ following shell-like macros are available: At the end of invocation of a parameterized macro, the above macros are (at the moment, silently) discarded. -<h2>Writing a Macro</h2> +\subsection macros_writing Writing a Macro Within the body of a macro, there are several constructs that permit testing for the presence of optional parameters. The simplest construct @@ -57,7 +57,7 @@ deleted). Note the 2nd % needed to escape the arguments to /bin/date. There is currently an 8K limit on the size that this macro can expand to. -<h2>Builtin Macros</h2> +\subsection macros_builtin Builtin Macros There are several builtin macros (with reserved names) that are needed to perform useful operations. The current list is @@ -92,7 +92,7 @@ In addition, rpm itself defines numerous macros. To display the current set, add "%dump" to the beginning of any spec file, process with rpm, and examine the output from stderr. -<h2>Example of a Macro</h2> +\subsection macros_example Example of a Macro Here is an example %patch definition from /usr/lib/rpm/macros: @@ -130,7 +130,7 @@ There are two "private" helper macros: %patch_suffix the gory details of overriding the (default) ".orig" \endverbatim -<h2>Using a Macro</h2> +\subsection macros_using Using a Macro To use a macro, write: @@ -148,7 +148,7 @@ The %{...} form allows you to place the expansion adjacent to other text. The %<name> form, if a parameterized macro, will do argc/argv processing of the rest of the line as described above. -<h2>Command Line Options</h2> +\subsection macros_commandline Command Line Options When the command line option "--define 'macroname value'" allows the user to specify the value that a macro should have during the build. @@ -167,7 +167,7 @@ Note: This works only macros defined in rpm configuration files, not for macros defined in specfiles. You can use %{echo: %{your_macro_here}} if you wish to see the expansion of a macro defined in a spec file. -<h2>Configuration using Macros</h2> +\subsection macros_configuration Configuration using Macros Starting in rpm 3.0, macros rather than rpmrc lines are used to configure rpm. In general, all the rpmrc configuration lines documented in "Maximum RPM" @@ -209,7 +209,7 @@ Here are 2 common FAQ for experienced users of rpm: %_topdir whatever \endverbatim -<h2>Macro Analogues of Autoconf Variables</h2> +\subsection macros_autoconf Macro Analogues of Autoconf Variables Several macro definitions provided by the default rpm macro set have uses in packaging similar to the autoconf variables that are used in building packages: diff --git a/doc/manual/queryformat b/doc/manual/queryformat index 181c1134c..19ef60151 100644 --- a/doc/manual/queryformat +++ b/doc/manual/queryformat @@ -4,7 +4,7 @@ As it is impossible to please everyone with one style of query output, RPM allows you to specify what information should be printed during a query operation and how it should be formatted. -<h2>Tags</h2> +\subsection queryformat_tags Tags All of the information a package contains, apart from signatures and the actual files, is in a part of the package called the header. Each piece @@ -36,7 +36,7 @@ the same reason. A tag can consist of one element or an array of elements. Each element can be a string or number only. -<h2>Query Formats</h2> +\subsection queryformat_format Query Formats A query format is passed to RPM after the --queryformat argument, and normally should be enclosed in single quotes. This query format is then used to print @@ -63,7 +63,7 @@ right align the size to, use: rpm -qa --queryformat "%-30{NAME} %10{SIZE}\n" \endverbatim -<h2>Arrays</h2> +\subsection queryformat_arrays Arrays RPM uses many parallel arrays internally. For example, file sizes and file names are kept as an array of numbers and an array of strings @@ -114,7 +114,7 @@ which will give you the expected output. cdp /usr/man/man1/cdp.1 \endverbatim -<h2>Formatting Tags</h2> +\subsection queryformat_formatting Formatting Tags One of the weaknesses with query formats is that it doesn't recognize that the INSTALLTIME tag (for example) should be printed as a date instead @@ -133,7 +133,7 @@ name after the tag name. Here are some examples: The :shescape may be used on plain strings to get a string which can pass through a single level of shell and give the original string. -<h2>Query Expressions</h2> +\subsection queryformat_expressions Query Expressions Simple conditionals may be evaluated through query expressions. Expressions are delimited by %|...|. The only type of expression currently supported @@ -148,7 +148,7 @@ the SOMETAG tag is present, and "missing" otherwise: Notice that the subformats "present" and "missing" must be inside of curly braces. -<h2>Viewing the Verify Flags</h2> +\subsection queryformat_example Example: Viewing the Verify Flags The follwing example query is run against dev becuase I know %verify is used there. diff --git a/doc/manual/relocatable b/doc/manual/relocatable index ecc503936..c4bdd41ab 100644 --- a/doc/manual/relocatable +++ b/doc/manual/relocatable @@ -6,7 +6,7 @@ may distribute their software to install in "/opt" but you'd like it to install in "/usr/opt". If the vendor were distributing a relocatable RPM package, it would be easy. -<h2>Building a Relocatable Package</h2> +\subsection relcateable_building Building a Relocatable Package Not all software can be "relocatable". Before continuing you should think about how the program works, what files it accesses, what other @@ -35,7 +35,7 @@ into the spec file so that the /usr and /etc directories may be relocated separately when this package is installed. -<h2>Installing Relocatable Packages</h2> +\subsection relcateable_installing Installing Relocatable Packages By default, RPM will install a relocatable package in the prefix directory listed in the spec file. You can override this on the diff --git a/doc/manual/signatures b/doc/manual/signatures index 22f5a78cd..7b4f6dc71 100644 --- a/doc/manual/signatures +++ b/doc/manual/signatures @@ -6,10 +6,10 @@ up and extended, the signature section in the RPM file format has been made easily extensible with new signature types, and packages can have multiple signatures. -<h2>PGP</h2> +\subsection signatures_pgp PGP -RPM's previous usage of PGP was cumbersome, and only supported -1024 bit keys. Both of these problems have been corrected. +Legacy usage of PGP in rpm-2.0 was cumbersome, and only supported +1024 bit keys. Both of these problems have been corrected in rpm-2.1. Whereas previously you needed many rpmrc entries to clue in RPM about keyring locations and such, RPM now behaves as PGP @@ -33,7 +33,7 @@ supply values for %_pgp_path the path to the key ring \endverbatim -<h2>Signature Creation</h2> +\subsection signatures_signing Signing Packages Signature creation is the same as previous releases: just add a --sign to your build command line. You can sign a package @@ -56,7 +56,7 @@ packages, which means that packages built without --sign can be "verified" to some extent. The MD5 signature should catch problems like corrupt packages, faulty downloads, etc. -<h2>Signature Verification</h2> +\subsection signatures_verifying Verifying Package Signatures Package signature verification is the same as previous releases: diff --git a/doc/manual/spec b/doc/manual/spec index fc48ae05a..2a27e48ec 100644 --- a/doc/manual/spec +++ b/doc/manual/spec @@ -19,7 +19,7 @@ definition: %package -n newname \endverbatim -<h2>Summary and Description</h2> +\subsection specfile_summary Summary: and Description: Tags The Summary: tag should be use to give a short (50 char or so) summary of the package. Most package's Description: line should be changed to @@ -66,7 +66,7 @@ are considered "pre-formatted" and will be left alone. Adjacent lines without leading whitespace are considered a single paragraph and may be subject to formatting by glint or another RPM tool. -<h2>Other Tags</h2> +\subsection specfile_url URL: and Packager: Tags Two new tags are "URL:" and "Packager:". "URL:" is a place to put a URL for more information and/or documentation on the software @@ -76,7 +76,7 @@ address of the person who "maintains" the RPM package (which may be different from the person who actually maintains the program the package contains). -<h2>BuildArchitectures</h2> +\subsection specfile_buildarchitectures BuildArchitectures: Tag This tag specifies the arctecture which the resulting binary package will run on. Typically this is a CPU architecture like sparc, @@ -84,7 +84,7 @@ i386. The string 'noarch' is reserved for specifying that the resulting binary package is platform independent. Typical platform independent packages are html, perl, python, java, and ps packages. -<h2>Files Attributes</h2> +\subsection specfile_virtual Virtual File Attribute(s) in %files Section A %ghost tag on a file indicates that this file is not to be included in the package. It is typically used when the attributes of the file @@ -101,14 +101,14 @@ The %config(noreplace) indicates that the file in the package should be installed with extension .rpmnew if there is already a modified file with the same name on the installed machine. --The virtual file attribute token %verify tells `-V/--verify' to ignore +The virtual file attribute token %verify tells `-V/--verify' to ignore certain features on files which may be modified by (say) a postinstall script so that false problems are not displayed during package verification. \verbatim %verify(not size md5 mtime) %{prefix}/bin/javaswarm \endverbatim -<h2>Shell Gobbing of %files</h2> +\subsection specfile_globbing Shell Gobbing of %files Section The usual rules for shell globbing apply. Most special characters can be escaped by prefixing them with a '\'. Spaces are used to separate @@ -136,7 +136,7 @@ easiest to do with a shell script like this: %files -f filelist.rpm \endverbatim -<h2>Fine Adjustment of Automatic Dependencies</h2> +\subsection specfile_automatic Fine Adjustment of Automatic Dependencies Rpm currently supports separate "Autoreq:" and "Autoprov:" tags in a spec file to independently control the running of find-requires and @@ -163,7 +163,7 @@ Similarly there is an Autoprov tag to turn off the automatic provision generation and a Autoreqprov to turn off both the automatic provides and the automatic requires generation. -<h2>nosrc rpms</h2> +\subsection specfile_nosrc NoSource: Tag Files ending in .nosrc.rpm are generally source RPM packages whose spec files have one or more NoSource: or NoPatch: directives in them. Both @@ -186,7 +186,7 @@ The end result of all this, though, is that you can't rebuild ``no-source'' RPM packages using `rpm --rebuild' unless you also have the sources or patches which are not included in the .nosrc.rpm. -<h2>BuildRequires</h2> +\subsection specfile_buildrequires BuildRequires: Tag Build dependencies are identical to install dependencies except: diff --git a/doc/manual/triggers b/doc/manual/triggers index 733332733..6e3ed8945 100644 --- a/doc/manual/triggers +++ b/doc/manual/triggers @@ -7,7 +7,7 @@ of the normal installation scripts (i.e. %pre) which allows one package "triggered package"]) to execute an action when the installation status of another package (the "target" of the trigger) changes. -<h2>A Simple Example</h2> +\subsection triggers_example A Simple Example Say the package "mymailer" needs an /etc/mymailer/mailer symlink which points to the mail transport agent to use. If sendmail is installed, the link should @@ -100,7 +100,7 @@ this case, if any of the targets will remain after the uninstall, the trigger doesn't do anything (as it's probably being triggered by an upgrade). -<h2>Trigger Syntax</h2> +\subsection triggers_syntax Trigger Syntax Trigger specifications are of the form: @@ -123,7 +123,7 @@ Will put a trigger in package 'package' which runs when the installation status of either fileutils > 3.0 or perl < 1.2 is changed. The script will be run through /usr/bin/perl rather then /bin/sh (which is the default). -<h2>An Unusual Case</h2> +\subsection triggers_unusual An Unusual Case There is one other type of trigger available -- %triggerpostun. These are triggers that are run after their target package has been removed; they will @@ -133,7 +133,7 @@ While this type of trigger is almost never useful, they allow a package to fix errors introduced by the %postun of another package (or by an earlier version of that package). -<h2>Order of Script Execution</h2> +\subsection triggers_order Order of Script Execution For reference, here's the order in which scripts are executed on a single package upgrade: diff --git a/doc/manual/tsort b/doc/manual/tsort new file mode 100644 index 000000000..8b2177359 --- /dev/null +++ b/doc/manual/tsort @@ -0,0 +1,159 @@ +/*! \page tsort Package ordering in rpm-4.0.1 and later + +The package ordering algorithm in rpm-4.0.1 has changed. + +\subsection tsort_problem The Problem + +Here's a simple test to illustrate the need for the change (from +bugzilla #12327): + +Assume the minimal 7.0 package manifest in /tmp/list +\verbatim + /mnt/redhat/comps/dist/7.0/sparc/bash-2.04-11.sparc.rpm + /mnt/redhat/comps/dist/7.0.2/sparc/glibc-2.1.94-1.sparc.rpm + /mnt/redhat/comps/dist/7.0/sparc/mktemp-1.5-5.sparc.rpm + /mnt/redhat/comps/dist/7.0/noarch/basesystem-7.0-2.noarch.rpm + /mnt/redhat/comps/dist/7.0/noarch/setup-2.3.4-1.noarch.rpm + /mnt/redhat/comps/dist/7.0/noarch/filesystem-2.0.7-1.noarch.rpm + /mnt/redhat/comps/dist/7.0/sparc/libtermcap-2.0.8-25.sparc.rpm + /mnt/redhat/comps/dist/7.0/noarch/termcap-11.0.1-3.noarch.rpm +\endverbatim + +with database initialization as +\verbatim + mkdir -p /tmp/ROOT/var/lib/rpm + rpm --initdb /tmp/ROOT/var/lib/rpm +\endverbatim + +This command "works" +\verbatim + rpm -Uvh -r /tmp/ROOT `cat /tmp/list` +\endverbatim +while this command +\verbatim + rpm -Uvh -r /tmp/ROOT `tac /tmp/list` +\endverbatim +fails with +\verbatim + loop in prerequisite chain: libtermcap bash libtermcap +\endverbatim + +\note The 2nd upgrade reverse orders the packages in the manifest. + +The problem is that the previous ordering algorithm, basically a very clever +implementation of tsort, was sensitive to initial conditions, and the first +command "happens" to snip a loop, while the second does not. + +\subsection tsort_solution The Solution + +The current ordering algorithm is exactly tsort from Knuth V1, with one further +twist. Since the only way out of a dependency loop is to snip the loop +somewhere, rpm uses hints from Requires: dependencies to distinguish +co-requisite (these are not needed to install, only to use, a package) from +pre-requisite (these are guaranteed to be installed before the package that +includes the dependency) relations. + +There is now syntax in spec files to explicitly specify the source of a +Requires: dependency. If, for example, you use grep in %post, then you +as a packager would normally add +\verbatim + PreReq: grep +\endverbatim +in order to insure that grep was installed before attempted use by the +%postun scriptlet. + +Now the same dependency can be expressed more precisely as +\verbatim + Requires(post): grep +\endverbatim + +For completeness, here's the complete set of tokens that may be +added to Requires: as in the example above: +\verbatim + "interp", RPMSENSE_INTERP + "prereq", RPMSENSE_PREREQ + "preun", RPMSENSE_SCRIPT_PREUN + "pre", RPMSENSE_SCRIPT_PRE + "postun", RPMSENSE_SCRIPT_POSTUN + "post", RPMSENSE_SCRIPT_POST + "rpmlib", RPMSENSE_RPMLIB + "verify", RPMSENSE_SCRIPT_VERIFY +\endverbatim + +Ditto BuildRequires: +\verbatim + "prep", RPMSENSE_SCRIPT_PREP + "build", RPMSENSE_SCRIPT_BUILD + "install", RPMSENSE_SCRIPT_INSTALL + "clean", RPMSENSE_SCRIPT_CLEAN +\endverbatim +but let's not go there (yet). + +For giggles, you can also do stuff like +\verbatim + Requires(pre,post): /bin/sh +\endverbatim + +By marking dependencies more precisely, rpm can distinguish between +an upgrade context (like the use of grep in %post above) and an installed +context (like the autogenerated Requires: in a package that includes a +script with #!/bin/sh), and that permits rpm to differentiate pre-requisites +from co-requisites while doing package ordering. + +Here's what cures the libtermcap <-> bash loop: +\verbatim + Requires(postun): /bin/sh +\endverbatim +which, since the dependency is clearly not useful or necessary in determining +install ordering, is safely ignored. + +\subsection tsort_sideeffects Side Effects + +One of the side effects of changing the package install ordering, is that +there are a handful of new loops that are detected. Here's what I found +looking at supported Red Hat releases: + +\verbatim + ghostscript-fonts ghostscript + /* 7.0 only */ + pango-gtkbeta-devel pango-gtkbeta + XFree86 Mesa + compat-glibc db2 + compat-glibc db1 + pam initscripts + kernel initscripts + initscripts sysklogd + /* 6.2 */ + egcs-c++ libstdc++ + /* 6.1 */ + pilot-link-devel pilot-link + /* 5.2 */ + pam pamconfig +\endverbatim + +Why are there new loops? Because tsort is trying to use all of the +dependency relations for ordering, while the previous tsort ignored all +Requires: from added packages. + +Except for the "well known" libtermcap <-> bash loop (which is just wrong), +all of the other dependencies are simply not needed in an upgrade context +to perform package ordering. Please note that all of the known to cause +loop dependencies listed above are, for now, explicitly ignored when +determining package install ordering. + +\subsection tsort_summary Summary + +So what does this all mean? Basically not much, unless you find yourself +trying to specify dependencies amongst a set of packages correctly and +happen to create a dependency loop. + +And, before you start adding the new-fangled syntax to packages, please +remember that rpm will almost certainly be auto-generating fine-grained +dependencies for %post et al scriptlets pretty soon. Truly, rpm needs to +make packaging easier, not provide Yet More Complicated Syntax in spec files. + +With thanks to Ken Estes for doing the implementation in bash2 that makes +it possible to auto-generate scriptlet dependencies, blame me for the long, +slow deployment. + +*/ |