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

CVS patchset: 3262
CVS date: 1999/09/07 15:46:53

4 files changed, 142 insertions, 3 deletions

diff --git a/doc/manual/Makefile.am b/doc/manual/Makefile.am
index edef14e09..b1164fc11 100644
--- a/doc/manual/Makefile.am
+++ b/doc/manual/Makefile.am
@@ -2,5 +2,5 @@
 
 EXTRA_DIST	= \
 	dependencies macros queryformat spec buildroot format \
-	relocatable signatures triggers
+	multiplebuilds relocatable signatures triggers
 
diff --git a/doc/manual/macros b/doc/manual/macros
index 4fcbfd14f..cd8ea3eb1 100644
--- a/doc/manual/macros
+++ b/doc/manual/macros
@@ -133,3 +133,82 @@ or
 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.  We will try to support
+users who accidentally type the leading % but this should not be
+relied upon.
+
+Evaluating a macro can be difficult outside of an rpm execution context. If
+you wish to see the expanded value of a macro, you may use
+	"--eval '<macro expression>'"
+that will read rpm config files and print the macro expansion on stdout.
+
+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.
+ 
+RPM 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"
+have been converted to macros, usually with a leading underscore, and the
+same name that was used in rpmrc files. In some cases, there is no leading
+underscore. Those macros existed in rpm-2.5.x and the underscore is omitted
+in order to preserve the meaning and usage of macros that are defined during
+spec file parsing.
+
+Here's an example to illustrate configuration using macros:
+
+   Old way:
+	In /etc/rpmrc and/or ~/.rpmrc you put
+		something:      some_value
+
+   New way:
+	In /etc/rpm/macros and/or ~/.rpmmacros
+		%_something     some_value
+
+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
+
+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:
+
+    %_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
+
diff --git a/doc/manual/multiplebuilds b/doc/manual/multiplebuilds
new file mode 100644
index 000000000..3557b2459
--- /dev/null
+++ b/doc/manual/multiplebuilds
@@ -0,0 +1,41 @@
+(From Ken Estes <kestes@staff.mail.com>)
+
+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
+        /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.
diff --git a/doc/manual/spec b/doc/manual/spec
index 0b3d465ef..1ee780ed6 100644
--- a/doc/manual/spec
+++ b/doc/manual/spec
@@ -58,8 +58,8 @@ address of the person who "maintains" the RPM package (which may be
 different from the person who actually maintains the program the
 package contains).
 
-Files attributes
----------------
+Files Attributes
+----------------
 
 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
@@ -76,3 +76,22 @@ The %config(noreplace) indicates that the file in the package should
 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 by putting
+
+	Autoreq: 0 
+
+in your spec file. Any and all requirements should be added manually using the
+
+	Requires: depend1, ..., dependN
+
+in this case.