suggested changes to docs from Ken Estes (#4451).

CVS patchset: 3263
CVS date: 1999/09/07 16:24:20

diff --git a/doc/manual/buildroot b/doc/manual/buildroot
index ec40c52..7c9facd 100644 (file)
--- a/doc/manual/buildroot
+++ b/doc/manual/buildroot
@@ -64,3 +64,50 @@ buildroot.  There are two ways to override this.  First, you can
 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.
+
+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
+
+       /usr/lib/perl5/site_perl/MD5.pm
+
+is installed by the package perl-MD5.  If we were to use a buildroot
+and specified 
+
+       %files  
+       /usr/lib/perl5/site_perl
+
+we would end up with the directory /usr/lib/perl5/site_perl being
+owned by the library package. This directory is in fact used by ALL
+perl libriares and should be owned by the package for perl not any of
+its libraries. It is important that the %files command specifies all
+the known directories explicitly. So this would be preferable:
+
+       /usr/lib/perl5/site_perl/*
+
+Since we only want the files and directories that the package perl-MD5
+installed into /usr/lib/perl5/site_perl/ to be owned by the package.
+The directory /usr/lib/perl5/site_perl/ is created when perl is
+installed.
+
+If we were to use the bad %files line shown above, then when the MD5
+package is removed, RPM will try to remove each of the perl-MD5 files and
+then try to remove the dir itself. If there's still files in the
+site_perl directory (e.g. from other packages) then the Unix rmdir(2)
+will fail and you will get a non-zero return code from RPM. If the
+rmdir succeds then you will no longer have a site_perl directory on
+your machine even though this directory was created when Perl was
+installed.
+
+The other common problem is that two packages could install two files
+with the the same name into the same directory. This would lead to
+other collision problems when removing the file. Care should be taken
+by the packager to ensure that all packages install unique files.
+Explicit use of %files can help make the packager aware of potential
+problems before they happen. When you try to install a package which
+contains file names already used by other packages on the system then
+RPM will warn you of the problem and give a fatal error. This error can
+be overriden with --force and the installed file will be replaced by the
+new file and when the new package is removed the file will be removed as well.

diff --git a/doc/manual/dependencies b/doc/manual/dependencies
index 62c1adc..4f5b3f3 100644 (file)
--- a/doc/manual/dependencies
+++ b/doc/manual/dependencies
@@ -28,18 +28,36 @@ works correctly most of the time. For example, it will know that
 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:
+To work around this, you may specify an epoch number for a package like this:
 
-       Serial: 23
+       Epoch: 23
 
-If a Requires: line should be comparing the given number with a serial number
-instead of a version number, you would do this:
+If a Requires: line needs to include an epoch in the comparison, then
+the line should be written like
 
-       Requires: somepackage =S 23
+       Requires: somepackage = 23:version
 
 You can't continue a "Requires: " line. If you have multiple
-"Requires: " lines then the package requires all pacakges mentioned on
-all lines to be installed. Max line length is probably 8K.
+"Requires: " lines then the package requires all packages mentioned on
+all of the lines to be installed. Max line length is probably 8K.
+
+The full syntax for specifying a dependency on an epoch, version and release
+is
+       [epoch:]version[-release]
+where
+       epoch   (optional) number, with assumed default of 0 if not supplied
+       version (required) can contain any character except '-'
+       release (optional) can contain any character except '-'
+
+Prereqs
+-------
+
+Prereqs are slightly different than requires. If multiple packages are
+given on a single command line, then RPM will rearrange the package
+order to ensure that the installation order obeys the requirements. A
+package's prereqs are guaranteed to be installed on the machine before
+the package itself is installed. Otherwise prereqs are identical to
+requires.
 
 
 Virtual Packages
@@ -60,10 +78,16 @@ package which contains:
 
 in its .spec file. No version numbers may be used with virtual packages.
 
+Virtual packages are often used to supply file dependencies such as /bin/sh
+on machines that are only partly managed by rpm. A virtual package with
+       Provides: /bin/sh
+differs from a package that has /bin/sh in the %files list in that the
+package can be safely removed without removing /bin/sh.
+
 Automatic Dependencies
 ----------------------
 
-To reduct the amount of work required by the package builder, RPM scans
+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
 list which require shared libraries to work (as determined by ldd) cause
 that package to require the shared library.
@@ -109,12 +133,16 @@ the output from find-provides is
        Foo-0.9
        perl(Widget)-0-1
 
-
 The per-interpreter automatic module detectors will normally be located in
        /usr/lib/rpm/{perl,tcl}/find-{provides,requires}
 with appropriate per-interpreter hooks into
        /usr/lib/rpm/find-{provides,requires}
 
+Notice that shell dependencies will require that all executable programs be
+tracked by the dependency processing system. Since a shell script depends on
+all the programs which it runs. In this way executables are much like shared
+libraries for shell scripts.
+
 
 Installing and Erasing Packages with Dependencies
 -------------------------------------------------