Initial revision

CVS patchset: 795
CVS date: 1996/07/12 02:31:16

5 files changed, 368 insertions, 0 deletions

diff --git a/docs/dependencies b/docs/dependencies
new file mode 100644
index 000000000..6973bec51
--- /dev/null
+++ b/docs/dependencies
@@ -0,0 +1,110 @@
+DEPENDENCIES
+============
+
+Dependencies provide a way for a package builder to require other
+packages or capabilities to be installed before or simultaneously
+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.
+
+Requiring Packages
+------------------
+
+To require packages, use:
+
+	Requires: python perl
+
+in the spec file. Note that "Requires python, perl" would work as well. If you
+needed to have a very recent version of python but any version of perl,
+
+	Requires: python >= 1.3, perl
+
+would do the trick. Again, the ',' in the line is optional.  Instead of
+'>=', you may also use '<', '>', '<=', or '='.
+
+RPM uses an internal algorithm to determine version number orderings which
+works correctly most of the time. For example, it will know that
+1.9a is older then 1.9b. However, it will also be later then 1.9 which
+may or may not be correct as some programmers use letters in version numbers
+to indicate beta versions. 
+
+To work around this, you may specify a serial number for a package like this:
+
+	Serial: 23
+
+If a Requires: line should be comparing the given number with a serial number
+instead of a version number, you would do this:
+
+	Requires: somepackage =S 23
+
+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
+care what specific package provides it. For example, sendmail won't work
+properly unless a local delivery agent (lda) is present. You can ensure that
+one is installed like this:
+
+	Requires: lda
+
+This will match either a package called lda (as mentioned above), or any
+package which contains:
+
+	Provides: lda
+
+in its .spec file. No version numbers may be used with virtual packages.
+
+Automatic Dependencies
+----------------------
+
+To reduct 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
+list which require shared libraries to work (as determined by ldd) cause
+that package to require the shared library.
+
+For example, if your package contains /bin/vi, RPM will add dependencies 
+for both libtermcap.so.2 and libc.so.5. These are treated as virtual
+packages, so no version numbers are used.
+
+A similar process allows RPM to add Provides information automatically. Any
+shared library in the file list is examined for its soname (the part of
+the name which must match for two shared libraries to be considered
+equivalent) and that soname is automatically provided by the package. For
+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.
+
+Installing and Erasing Packages with Dependencies
+-------------------------------------------------
+
+For the most part, dependencies should be transparent to the user. However,
+a few things will change.
+
+First, when packages are added or upgraded, all of their dependencies
+must be satisfied. If they are not, an error message like this appears:
+
+    failed dependencies:
+	    libICE.so.6  is needed by somepackage-2.11-1
+	    libSM.so.6  is needed by somepackage-2.11-1
+	    libc.so.5  is needed by somepackage-2.11-1
+
+Similarly, when packages are removed, a check is made to ensure that 
+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.
+
+Querying with Dependencies
+--------------------------
+
+Two new query information selection options are now available. The first, 
+--provides, prints a list of all of the capabilities a package provides. 
+The second, --requires, shows the other packages that a package requires
+to be installed, along with any version number checking.
+
+There are also two new ways to search for packages. Running a query with 
+--whatrequires <item> queries all of the packages that require <item>. 
+Similarly, running --whatprovides <item> queries all of the packages that 
+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.
diff --git a/docs/queryformat b/docs/queryformat
new file mode 100644
index 000000000..af21437e4
--- /dev/null
+++ b/docs/queryformat
@@ -0,0 +1,93 @@
+QUERY FORMATS
+=============
+
+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.
+
+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
+of information in the header has a tag associated with it which allows
+RPM to to tell the difference between the name and description of a
+package.
+
+To get a list of all of the tags your version of RPM knows about, run the
+command 'rpm --querytags'. It will print out a list like (but much longer
+then) this:
+
+    RPMTAG_NAME
+    RPMTAG_VERSION
+    RPMTAG_RELEASE
+    RPMTAG_SERIAL
+    RPMTAG_SUMMARY
+    RPMTAG_DESCRIPTION
+    RPMTAG_BUILDTIME
+    RPMTAG_BUILDHOST
+    RPMTAG_INSTALLTIME
+    RPMTAG_SIZE
+
+As all of these tags begin with RPMTAG_, you may omit it from query format
+specifiers and it will be omitted from the rest of this documentation for
+the same reason.
+
+A tag can consist of one element or an array of elements. Each element can
+be a string or number only.
+
+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
+the information section of a query. This means that when both -i and 
+--queryformat are used in a command, the -i is essentially ignored.
+
+The query format is similar to a C style printf string, which the printf(2)
+man page provides a good introduction to. However, as RPM already knows the
+type of data that is being printed, you must omit the type specifier. In
+its place put the tag name you with to print enclosed in curly braces
+({}). For example, the following RPM command prints the names and sizes
+of all of the packages installed on a system:
+
+    rpm -qa --queryformat "%{NAME} %{SIZE}\n"
+
+If you want to use printf formatters, they go between the % and {. To
+change the above command to print the NAME in the first 30 bytes and
+right align the size to, use:
+
+    rpm -qa --queryformat "%-30{NAME} %10{SIZE}\n"
+
+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
+respectively, with the first element in the size array corresponding
+to the first element in the name array. 
+
+To iterate over a set of parallel arrays, enclose the format to be used
+to print each item in the array within square brackets ([]). For example,
+to print all of the files and their sizes in the slang-devel package
+followed by their sizes, with one file per line, use this command:
+
+    rpm -q --queryformat "[%-50{FILENAMES} %10{FILESIZES}\n]" slang-devel
+
+Note that since the trailing newline is inside of the square brackets, one
+newline is printed for each filename.
+
+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
+of as a number. To compensate, you can specify one of a few different
+formats to use when printing tags by placing a colon followed the formatting 
+name after the tag name. Here are some examples:
+
+    rpm -q --queryformat "%{NAME} %{INSTALLTIME:date}\n" fileutils
+    rpm -q --queryformat "[%{FILEMODES:perms} %{FILENAMES}\n]" rpm
+    rpm -q --queryformat \
+	"[%{REQUIRENAME} %{REQUIREFLAGS:depflags} %{REQUIREVERSION}\n]" \
+	vlock
diff --git a/docs/relocatable b/docs/relocatable
new file mode 100644
index 000000000..d6a8bc9d1
--- /dev/null
+++ b/docs/relocatable
@@ -0,0 +1,36 @@
+RELOCATABLE PACKAGES
+====================
+
+Relocatable packages are a way to give the user a little control
+over the installation location of a package.  For example, a vendor
+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.
+
+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
+programs access *it* (and expect it to be in a certain place), etc.
+If you determine that the location of the package doesn't matter,
+then it can probably be built as "relocatable".
+
+All you need to do to build a relocatable package is put:
+
+  Prefix: <dir>
+
+in your spec file.  The "<dir>" will usually be something like "/usr",
+"/usr/local", or "/opt".  Every file in your %files list must start
+with that prefix.  For example, if you have "Prefix: /usr" and your
+%files list contains "/etc/foo.conf", the build will fail.
+
+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
+RPM install command line with "--prefix <dir>".  For example, if
+the package in question were going to be installed in "/opt" but
+you don't have enough disk space there (and it is a relocatable
+package), you could install it "--prefix /usr/opt".
diff --git a/docs/signatures b/docs/signatures
new file mode 100644
index 000000000..503b0f6d8
--- /dev/null
+++ b/docs/signatures
@@ -0,0 +1,70 @@
+New RPM Signatures
+==================
+
+The 2.1 release of RPM had a few improvements in the area of
+digital package signatures.  The usage of PGP has been cleaned
+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.
+
+PGP
+---
+
+RPM's previous usage of PGP was cumbersome, and only supported
+1024 bit keys.  Both of these problems have been corrected.
+
+Whereas previously you needed many rpmrc entries to clue in
+RPM about keyring locations and such, RPM now behaves as PGP
+users would expect.  The PGPPATH environment variable can be
+used to specify keyring locations.  You can also use a
+"pgp_path:" line in your rpmrc to specify a different value
+for RPM to use for PGPPATH.  If neither of these are used PGP
+uses its default ($HOME/.pgp).
+
+If you just want to verify packages, you do not need any entries
+in your rpmrc (except possibly "pgp_path:").  The minimal rpmrc
+entries to use PGP for package building are:
+
+signature: pgp
+pgp_name: <name to uniquely select the key to use for signing>
+
+Signature Creation
+------------------
+
+Signature creation is the same as previous releases: just add
+a --sign to your build command line.  You can sign a package
+after the package is built with:
+
+rpm --resign <package>
+
+Using --resign removes any previous signature in the package.
+To *add* a signature to a package, leaving all existing
+signatures use:
+
+rpm --addsign <package>
+
+RPM always creates MD5 and SIZE signatures when it build
+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.
+
+Signature Verification
+----------------------
+
+Package signature verification is the same as previous releases:
+
+rpm -K <package>
+
+RPM will verify evey signature in the package, which may include
+more than one PGP signature.  The output indicates what types of
+signatures are being checked.  If any checks fail you'll see a
+"NOT OK" message, and you should be worried.
+
+If you have a package with PGP signatures, but don't have PGP
+installed, but still want to verify it as much as possible, you
+can do:
+
+rpm -K --nopgp <package>
+
+That will cause RPM to skip any PGP signatures, but still check
+any others (currently only MD5 and SIZE).
diff --git a/docs/spec b/docs/spec
new file mode 100644
index 000000000..d65619682
--- /dev/null
+++ b/docs/spec
@@ -0,0 +1,59 @@
+SPEC FILE ADDITIONS
+===================
+
+A few additions have been made to the spec file format.
+
+Summary and Description
+-----------------------
+
+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
+a Summary: line.  The Description: tag is still supported but should
+be changed to a "%description" entry similar to %package and %files.
+At some point in the future support will be removed for "Description:".
+As an example, this spec file fragment:
+
+  Description: Screen drawing library
+  Name: screenlib
+  Version: 1.0
+
+  %package devel
+  Description: Screen drawing library headers and static libs
+
+might be changed to:
+
+  Summary: Screen drawing library
+  Name: screenlib
+  Version: 1.0
+
+  %description
+  The screen drawing library
+  is a handy development tool
+
+  %package devel
+  Summary: Screen drawing library headers and static libs
+
+  %description devel
+  This package contains all of the
+  headers and the static libraries for
+  screenlib.
+
+  You'll only need this package if you
+  are doing development.
+
+The description is free form text, but there are two things to note.
+The first regards reformating.  Lines that begin with white space
+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.
+
+Other 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
+contained in the package.  Some future RPM package tool may make use
+of this.  The Packager: tag is meant to contain the name and email
+address of the person who "maintains" the RPM package (which may be
+different from the person who actually maintains the program the
+package contains).