Bug 4451 - Patches to improve documentation of RPM
Summary: Patches to improve documentation of RPM
Keywords:
Status: CLOSED CURRENTRELEASE
Alias: None
Product: Red Hat Linux
Classification: Retired
Component: rpm
Version: 6.0
Hardware: i386
OS: Linux
low
low
Target Milestone: ---
Assignee: Jeff Johnson
QA Contact:
URL:
Whiteboard:
Depends On:
Blocks:
TreeView+ depends on / blocked
 
Reported: 1999-08-10 01:35 UTC by kestes
Modified: 2008-05-01 15:37 UTC (History)
0 users

Fixed In Version:
Doc Type: Bug Fix
Doc Text:
Clone Of:
Environment:
Last Closed: 1999-09-07 16:24:59 UTC
Embargoed:


Attachments (Terms of Use)

Description kestes 1999-08-10 01:35:40 UTC
These patches were made against the latest rpm sources
from CVS if they do not fit let me know and I will
rewrite them.  If my documentation is vauge it is only
because I do not understand the feature so I am inviting
you to please explain it to me


diff -u ./buildroot /devel/kestes/vendorc/rpm/docs/buildroot
--- ./buildroot	Mon Jul 19 18:13:12 1999
+++ /devel/kestes/vendorc/rpm/docs/buildroot	Tue Jan 19
15:53:12 1999
@@ -64,3 +64,52 @@
 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.
+
+Warnings of 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 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 buildmaster to ensure that all packages install
unique files.
+Explicit use of %files can help make the build master 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 -u ./dependencies
/devel/kestes/vendorc/rpm/docs/dependencies
--- ./dependencies	Mon Jul 19 18:13:12 1999
+++ /devel/kestes/vendorc/rpm/docs/dependencies	Mon Aug  9
21:08:121999
@@ -39,7 +39,28 @@

 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.
+all of the lines to be installed. Max line length is
probably 8K.
+
+
+To specify incompatible epocs and versions and relases in
the spec
+file the corrrect syntax is
+
+	Requires: pkg >= 2:0-0
+
+with the comparison on epoch:version-release with
+	epoch = 2
+	version = 0
+	release = 0
+
+
+Prereqs
+-------
+
+Prerequs are not equivelant to 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
+packages prereqs are required to be installed on the
machine in a
+different invocatoin of RPM then the one installing the
package.


 Virtual Packages
@@ -115,6 +136,10 @@
 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
 -------------------------------------------------
diff -u ./macros /devel/kestes/vendorc/rpm/docs/macros
--- ./macros	Mon Jul 19 18:13:12 1999
+++ /devel/kestes/vendorc/rpm/docs/macros	Mon Aug  9
20:53:38 1999
@@ -18,17 +18,19 @@

 %define <name>[(opts)] <body>

-All whitespace surrounding <body> is removed.  Name may be
composed
-of alphanumeric characters, and the character `_' and must
be at least
-3 characters in length. A macro without an (opts) field is
"simple" in that
-only recursive macro expansion is performed. A
parameterized macro contains
-an (opts) field. The opts (i.e. string between parantheses)
is passed
-exactly as is to getopts(3) for argc/argv processing at the
beginning of
-a macro invocation.  While a parameterized macro is being
expanded, the
+All whitespace surrounding <body> is removed.  Name may be
composed of
+alphanumeric characters, and the character `_' and must be
at least 3
+characters in length. In rpm-3.x, '-' is not valid in macro
+names. Change to something like an underscore.  A macro
without an
+(opts) field is "simple" in that only recursive macro
expansion is
+performed. A parameterized macro contains an (opts) field.
The opts
+(i.e. string between parantheses) is passed exactly as is
to
+getopts(3) for argc/argv processing at the beginning of a
macro
+invocation.  While a parameterized macro is being expanded,
the
 following shell-like macros are available:

 	%0	the name of the macro being invoked
-	%*	all arguments (unlike shell, not including any
processed flags)
+	%*	all arguments
 	%#	the number of arguments
 	%{-f}	if present at invocation, the flag f itself
 	%{-f*}	if present at invocation, the argument to flag f
@@ -133,3 +135,73 @@
 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.
+
+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.
+Note lack of leading % for the macro name.  It we will try
to support
+users who accidentally type the leading % but this should
not be
+relied upon.
+
+Debugging an incorrect macro expansion is difficult.
There's also a
+command like option to make this easier.  Run
+ "--eval '<macro expression>'" that will read all config
files and
+then expand <macro expression> to stdout.  Does this work
with specfiles?
+
+New Macro Format
+----------------
+
+With one glaring exeception (rpmrc files) almost everything
in "Maximum RPM"
+is relevant. And, if you understand that configuration has
changed mostly
+according to the following scheme
+
+Here are 2 common FAQ for experienced users of rpm:
+
+1) --rcfile works differently.
+
+Old way:	rpm --rcfile whatever
+New way:	rpm --rcfile /usr/lib/rpm/rpmrc:whatever
+
+2) topdir (and other rpmrc configurables) work differently.
+
+Old way:
+	~/.rpmrc contains
+		topdir:		whatever
+
+New way:
+	/usr/lib/rpm/rpmrc contains
+		macrofiles:	/usr/lib/rpm/macros: ... :~/.rpmmacros
+	~/.rpmmacros contains
+		%_topdir	whatever
+
+
+	Old: in /etc/rpmrc and/or ~/.rpmrc you put
+		something: 	some_value
+
+	New: in /etc/rpm/macros and/or ~/.rpmmacros
+		%_something	some_value
+
+then almost everything applies.
+
+(Note: there are exceptions mostly in trying to maintain
compatibility
+with rpm-2.5.x macro names.)
+
+BTW, rpm-3.0.2 (and for future) has the autoconf analogues
of
+bindir, libdir, etc:
+	%_prefix                /usr
+	%_exec_prefix           %{_prefix}
+	%_bindir                %{_exec_prefix}/bin
+	%_sbindir               %{_exec_prefix}/sbin
+	%_libexecdir            %{_exec_prefix}/libexec
+	%_datadir               %{_prefix}/share
+	%_sysconfdir            %{_prefix}/etc
+	%_sharedstatedir        %{_prefix}/com
+	%_localstatedir         %{_prefix}/var
+	%_libdir                %{_exec_prefix}/lib
+	%_includedir            %{_prefix}/include
+	%_oldincludedir         /usr/include
+	%_infodir               %{_prefix}/include
+	%_mandir                %{_prefix}/man
+
Only in /devel/kestes/vendorc/rpm/docs/: multiplebuilds
Only in /devel/kestes/vendorc/rpm/docs/: multiplebuilds~
diff -u ./queryformat
/devel/kestes/vendorc/rpm/docs/queryformat
--- ./queryformat	Mon Jul 19 18:13:12 1999
+++ /devel/kestes/vendorc/rpm/docs/queryformat	Wed Dec 30
10:15:20 1998
@@ -48,7 +48,7 @@
 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 wish to print enclosed in
curly braces
+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:

Only in /devel/kestes/vendorc/rpm/docs/: scripts
Only in /devel/kestes/vendorc/rpm/docs/: scripts~
diff -u ./spec /devel/kestes/vendorc/rpm/docs/spec
--- ./spec	Mon Jul 19 18:13:12 1999
+++ /devel/kestes/vendorc/rpm/docs/spec	Mon Aug  9 20:59:34
1999
@@ -76,3 +76,20 @@
 be installed with extension .rpmnew if there is already a
file by
 the same name on the installed machine.

+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
+find-provides. A common problem occurs when packaging a
large third
+party binary which has interfaces to other third party
libraries you
+do not own.  RPM will require all the third party libraries
be
+installed on the target machine even though their intended
use was
+optional.  To rectify the situation you may turn off
requirements when
+building the package buy putting
+
+	Autoreq: 0
+
+in your spec file. You will have to add another line of the
actual
+library requirements using the standard "Requires:" for the
RPM to
+accuratly reflect its real requirements.



I call this file multiplebuilds
--------------------------------





It is possible to run several RPM builds on the same machine
using
separate RPM databases.  On my build machine I have several
build
areas which all run builds at the same time.  The builds do
not
interfere with each other.  Each build behaves as if it was
running on
its own machine and no build area knows about the RPM
database which
actually configures the machine.


1) First setup a "topdir" in a prefix other then where RPM
is
installed.  You will need to make the directories.  They
need to be
writable by the account which will do the building,
typically they
are owned by the buildmaster account and set to permissions
755.

	BUILD RPMS SOURCES SPECS SRPMS


2) Next you will need to decide where the database files
live.  I suggest
putting them in a separate directory under "topdir".  I call
my
directory DB and it has the same owner and permissions as
the other
directories.

3) Each separate build area needs a rpmrc.  This will need
to specify
the new topdir and dbpath.  If you will be building the same
packages
in different work areas you will also need to specify a
tmppath into
the topdir.  I suggest either making tmppath be the same as
the BUILD
directory or adding another directory called BUILDROOT for
it in the
topdir.

4) keeping track of the correct rpmrc for each build area
can be
difficult.  To make my life easier I make a small shell
script with the
topdir hard coded inside:


	#!/bin/sh

	/usr/local/bin/rpm --rcfile /topdir/rpmrc "$@"
	exit $?


I call the shell script rpm and it lives in the topdir.
Each time I
wish to use a particular build area I just ensure that the
build area
is first in my path so that when I run "rpm" I get the
regular rpm
binary but I am using the local build areas rpmrc.




Help me write something inteligent about the running of
scripts on the target machine


%pre checks exit status and a package can not be installed
unless its
%pre secton exits with a return code of 0.  This can be used
to
prevent a package from being installed if hardware
dependencies or
dependencies managed by other package managers are not met.



So the order is

	install new package
	uninstall old package

The sequence of scripts run (including triggers) for a
package upgrade
(new is new package, old is old package, any is any other
package
which has triggered attached to the package being upgraded)

# install section
        new-%pre
        all new files are installed
        new-%post
        any-%triggerin
        new-%triggerin

# uninstall section
        old-%triggerun
        any-%triggerun
        old-%preun
        all old files are removed
        old-%postun
        old-%triggerpostun
        any-%triggerpostun


If a preinstall script exits 1, the install *of that
package*
is aborted. However, if rpm is also installing other
packages that have
the failed package as a Prereq: or a Requires:, installation
of them
will *not* abort.

 This is unfortunate, as it means that you cannot safely do:
	rpm -i local-setup.rpm local-package1.rpm local2.rpm ....
where local-setup.rpm is something that checks basic setup
for sanity
and everything else depends on that basic local setup to be
good. You
have to have your scripts, procedures, or whatever do this
in two steps.


discribe %include

Comment 1 Jeff Johnson 1999-08-10 14:22:59 UTC
Ken, can you reply to this message with patches attached? Fishing
a patch out of html is the pits ...

Thanks. And thanks for the patch.

Comment 2 Jeff Johnson 1999-09-07 16:24:59 UTC
Added (although your scripts suggestions were too raw for now).
Thanks for the work.


Note You need to log in before you can comment on or make changes to this bug.