From 144038e68277b58980453f1e2a5fe44a1b7e508d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ralf=20Cors=C3=A9pius?= Date: Sat, 6 Oct 2007 08:53:11 +0200 Subject: s,\\subsection,\\section, --- doc/manual/buildroot | 6 +++--- doc/manual/dependencies | 24 ++++++++++++------------ doc/manual/format | 12 ++++++------ doc/manual/macros | 16 ++++++++-------- doc/manual/queryformat | 12 ++++++------ doc/manual/relocatable | 4 ++-- doc/manual/signatures | 6 +++--- doc/manual/spec | 16 ++++++++-------- doc/manual/triggers | 8 ++++---- doc/manual/tsort | 8 ++++---- 10 files changed, 56 insertions(+), 56 deletions(-) diff --git a/doc/manual/buildroot b/doc/manual/buildroot index a36914202..3bf0b05e7 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. -\subsection buildroot_specfile The Spec File +\section buildroot_specfile The Spec File Simply use \verbatim @@ -59,7 +59,7 @@ would be changed to: /usr/bin/fooprog \endverbatim -\subsection buildroot_building Building With a Build Root +\section 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: " in your rpmrc. Second, you can override the default, and any entry in an rpmrc by using "--buildroot " on the RPM command line. -\subsection buildroot_caveats Caveats using Build Roots +\section 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 b8d362b7e..36e7192ee 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. -\subsection dependencies_package Requiring Packages +\section 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. -\subsection dependencies_prereqs Prereqs +\section 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. -\subsection dependencies_virtual Virtual Packages +\section 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. -\subsection dependencies_automatic Automatic Dependencies +\section 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. -\subsection dependencies_custom Custom Automatic Dependency +\section dependencies_custom Custom Automatic Dependency The automatic dependency programs are found via macro expansion. Thus sites can very the amount of dependency 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. -\subsection dependencies_interpreters Interpreters and Shells +\section 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. -\subsection dependencies_installing Installing and Erasing Packages with Dependencies +\section 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. -\subsection dependencies_conflicts Conflicts +\section 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. -\subsection dependencies_querying Querying for Dependencies +\section 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 \ virtual package. Note that querying for package that provides "python" will not return anything, as python is a package, not a virtual package. -\subsection dependencies_verifying Verifying Dependencies +\section 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. -\subsection dependencies_branching Branching Version +\section 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 represented @@ -354,7 +354,7 @@ Another alternative scheme might be: Release: \endverbatim -\subsection dependencies_build Build dependencies +\section dependencies_build Build dependencies The following dependencies are available 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 5eb494bce..521387ba7 100644 --- a/doc/manual/format +++ b/doc/manual/format @@ -24,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). -\subsection pkgformat_lead Lead +\section 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. @@ -95,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. -\subsection pkgformat_signature Signature +\section 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 @@ -123,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. -\subsection pkgformat_header Header +\section 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 @@ -132,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. -\subsection pkgformat_payload Payload +\section pkgformat_payload Payload The Payload is currently a gzipped cpio archive. The cpio archive type used is SVR4 with a CRC checksum. -\subsection pkgformat_header_structure The Header Structure +\section 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 @@ -246,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). -\subsection pkgformat_tools Tools +\section 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/macros b/doc/manual/macros index 239b4b463..fea9bf38f 100644 --- a/doc/manual/macros +++ b/doc/manual/macros @@ -10,7 +10,7 @@ lists" (i.e. those read in using %files -f \). In addition, macros can be nested, hiding the previous definition for the duration of the expansion of the macro which contains nested macros. -\subsection macros_defining Defining a Macro +\section 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. -\subsection macros_writing Writing a Macro +\section 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. -\subsection macros_builtin Builtin Macros +\section 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. -\subsection macros_example Example of a Macro +\section 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 -\subsection macros_using Using a Macro +\section macros_using Using a Macro To use a macro, write: @@ -172,7 +172,7 @@ replaced by the first argument to the macro, but only if the macro is invoked as "%mymacro 5". Invoking as "%{mymacro} 5" will not work as desired in this case. -\subsection macros_commandline Command Line Options +\section 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. @@ -191,7 +191,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. -\subsection macros_configuration Configuration using Macros +\section 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" @@ -233,7 +233,7 @@ Here are 2 common FAQ for experienced users of rpm: %_topdir whatever \endverbatim -\subsection macros_autoconf Macro Analogues of Autoconf Variables +\section 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 b6f6e2511..9b2ce6cd6 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. -\subsection queryformat_tags Tags +\section 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. -\subsection queryformat_format Query Formats +\section 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 -\subsection queryformat_arrays Arrays +\section 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 -\subsection queryformat_formatting Formatting Tags +\section 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. -\subsection queryformat_expressions Query Expressions +\section 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. -\subsection queryformat_example Example: Viewing the Verify Flags +\section queryformat_example Example: Viewing the Verify Flags The following example query is run against dev because I know %verify is used there. diff --git a/doc/manual/relocatable b/doc/manual/relocatable index d0700724f..d73d0ce32 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. -\subsection relocatable_building Building a Relocatable Package +\section relocatable_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. -\subsection relocatable_installing Installing Relocatable Packages +\section relocatable_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 9cad9aabf..fffb9857b 100644 --- a/doc/manual/signatures +++ b/doc/manual/signatures @@ -6,7 +6,7 @@ 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. -\subsection signatures_pgp PGP +\section signatures_pgp PGP 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. @@ -33,7 +33,7 @@ supply values for %_pgp_path the path to the key ring \endverbatim -\subsection signatures_signing Signing Packages +\section 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. -\subsection signatures_verifying Verifying Package Signatures +\section 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 98616f324..762f57067 100644 --- a/doc/manual/spec +++ b/doc/manual/spec @@ -19,7 +19,7 @@ definition: %package -n newname \endverbatim -\subsection specfile_summary Summary: and Description: Tags +\section 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. -\subsection specfile_url URL: and Packager: Tags +\section 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). -\subsection specfile_buildarchitectures BuildArchitectures: Tag +\section specfile_buildarchitectures BuildArchitectures: Tag This tag specifies the architecture 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. -\subsection specfile_virtual Virtual File Attribute(s) in %files Section +\section 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 @@ -108,7 +108,7 @@ script so that false problems are not displayed during package verification. %verify(not size md5 mtime) %{prefix}/bin/javaswarm \endverbatim -\subsection specfile_globbing Shell Globbing of %files Section +\section specfile_globbing Shell Globbing 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 -\subsection specfile_automatic Fine Adjustment of Automatic Dependencies +\section 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. -\subsection specfile_nosrc NoSource: Tag +\section 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. -\subsection specfile_buildrequires BuildRequires: Tag +\section specfile_buildrequires BuildRequires: Tag Build dependencies are identical to install dependencies except: diff --git a/doc/manual/triggers b/doc/manual/triggers index 2349bc3fb..7bbad07ea 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. -\subsection triggers_example A Simple Example +\section 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). -\subsection triggers_syntax Trigger Syntax +\section 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). -\subsection triggers_unusual An Unusual Case +\section 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). -\subsection triggers_order Order of Script Execution +\section 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 index 8b2177359..e2f634f5a 100644 --- a/doc/manual/tsort +++ b/doc/manual/tsort @@ -2,7 +2,7 @@ The package ordering algorithm in rpm-4.0.1 has changed. -\subsection tsort_problem The Problem +\section tsort_problem The Problem Here's a simple test to illustrate the need for the change (from bugzilla #12327): @@ -44,7 +44,7 @@ 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 +\section 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 @@ -107,7 +107,7 @@ Here's what cures the libtermcap <-> bash loop: which, since the dependency is clearly not useful or necessary in determining install ordering, is safely ignored. -\subsection tsort_sideeffects Side Effects +\section 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 @@ -141,7 +141,7 @@ 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 +\section 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 -- cgit v1.2.3