##
##  rpmtool.pod -- RPM Auxiliary Tool (Manual Page)
##  Copyright (c) 2000-2002 Cable & Wireless Deutschland GmbH
##  Copyright (c) 2000-2002 The OpenPKG Project <http://www.openpkg.org/>
##  Copyright (c) 2000-2002 Ralf S. Engelschall <rse@engelschall.com>
##
##  Permission to use, copy, modify, and distribute this software for
##  any purpose with or without fee is hereby granted, provided that
##  the above copyright notice and this permission notice appear in all
##  copies.
##
##  THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
##  WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
##  MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
##  IN NO EVENT SHALL THE AUTHORS AND COPYRIGHT HOLDERS AND THEIR
##  CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
##  SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
##  LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
##  USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
##  ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
##  OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
##  OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
##  SUCH DAMAGE.
##

=pod

=head1 NAME

B<rpmtool> - RPM Auxiliary Tool

=head1 SYNOPSIS

B<rpmtool>
I<command>
[I<command-options>]

=head1 DESCRIPTION

This is an auxiliary tool to the RedHat Package Manager (RPM). It
provides additional functionality for use in RPM I<spec> files while
building packages. The following I<command>s are available:

=over 4

=item B<platform> 

This command outputs a unique platform id in the format
"<architecture>-<system><release>". For instance, the output on a
FreeBSD platform can be "i386-freebsd4.2", the output on a Linux
platform can be "i686-linux2.2.16", the output on a Solaris platform can
be "sun4u-sunos5.8", etc.

Example:

 case `rpmtool platform`; in
     *-freebsd[34].* ) ... ;;
     *-sunos5.[678]  ) ... ;;
     *-linux2.[24].* ) ... ;;
 esac

=item B<flags> [B<-m>] [B<-c>] [B<-O>] I<tool>

This command outputs additional flags for make (B<-m>) or compiler (B<-c>) for
use with the program I<tool>. For B<-m> it provides only standard flags which
always can be used. In conjunction with B<-O> (optimization), it also provides
reasonable job control for use on multi-processor platforms (for instance it
outputs "-j4" on an SMP system with 2 CPUs if GNU make or BSD pmake is used).
For B<-c> it provides only standard flags which always can be used. In
conjunction with B<-O> it provides also optimization flags (for instance it
outputs "-O2 -pipe" for GNU C/C++ compiler).

Example:

 CC="$CC" CFLAGS=`rpmtool -c -O $CC` ./configure ...

=item B<files> [B<-v>] [B<-o> I<outfile>] [B<-r> I<build-root>] [I<entry> ...]

This is a dynamic variant of the RPM C<%files> section, i.e., it
dynamically creates the contents of the C<%files> section for use with
the C<%files -f> command. For this the file list entries are read from
the command line (or from stdin if no arguments are given or a single
argument C<-> is given) and written to stdout (if no B<-o> option is
given or its I<outfile> argument is C<->) or to I<outfile>.

The trick of this approach is to be able to use additional features in
the file list which RPM does not provide. The following features are
provided:

=over 4

=item B<Trailing Tags>

RPM requires that all tags (like C<%attr(...)> or C<%dir>) preceed the
path in a file list entry. This sometimes leads to ugly and unreadable
file lists, because all paths cannot be left-aligned. With rpmtool(1)
tags in the input file list can be at leading and trailing positions.
The output file list will nevertheless have all tags in leading
positions for RPM.

=item B<Syntactical Set Pattern>

RPM supports simple wildcard patterns like C</path/*> or C</path/[a-z]>,
etc. Sometimes it is convienient, to also have (in addition to character
sets) string sets like C</path/{foo,bar,quux}>. rpmtool(1) provides this
by syntactically (without checking the filesystem) expanding those
string sets.

=item B<Overriding Entries>

This is the most important feature and the reason why shtool(1)'s
B<files> command was implemented. Although RPM allows one to specify a
directory in a file list and then implicitly expands this recursively
into its contents, it unfortunately does not allow one to later
explcitly override particular entries (usually if an individual
C<%attr(...)> tag is required). rpmtool(1) now supports overriding
entries, i.e., if a path occurs multiple times, only the last occurance
is kept.

=item B<Negation Tag>

This provides an additional tag C<%not> which can be used to explicitly
exclude a previously implicitly added entry.

=back

Example:

 %install
   :
 rpmtool files -o files -r$RPM_BUILD_ROOT \
     '%defattr(-,foo,foo)' \
     '%{prefix}' \
     '%attr(1755,root,foo) %{prefix}/bin/bar' \
     '%not %dir {%{prefix},%{prefix}/*,%{prefix}/man/*}' \
     '%not %{prefix}/info/dir'

 %files -f files

=item B<user> [B<-a>] [B<-r>] [B<-p> I<passwd>] [B<-n> I<realname>] [B<-d> I<homedir>] [B<-s> I<shell>] [B<-u> I<min-uid>] I<username>

This adds (B<-a>) or removes (B<-r>) the user I<username> in the system database.

=item B<group> [B<-a>] [B<-r>] [B<-g> I<min-gid>] I<groupname> [I<username> ...]

This adds (B<-a>) or removes (B<-r>) the group I<groupname> in the system database.

=item B<msg> [B<-b>]

This displays the contents of F<stdin> as a boxed message. If option
B<-b> is given it additionally beeps once before displaying the box.

=back

=head1 HISTORY

This tool was created in November 2000 for use in OpenPKG, the
cross-platform RPM-based Unix software packaging facility.

=head1 AUTHOR

 Ralf S. Engelschall
 rse@engelschall.com
 www.engelschall.com

=cut

