OpenPKG Specs / file revision

 ##

 ##  rpmtool.pod -- OpenPKG RPM Auxiliary Tool (Manual Page)

 ##

 ##  Copyright (c) 2000-2012 OpenPKG GmbH <http://openpkg.com/>

 ##

 ##  This software is property of the OpenPKG GmbH, DE MUC HRB 160208.

 ##  All rights reserved. Licenses which grant limited permission to use,

 ##  copy, modify and distribute this software are available from the

 ##  OpenPKG GmbH.

 ##

 ##  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<mflags> [B<-O>] I<tool>

 This command outputs additional flags for make(1) for

 use with the program I<tool>. 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).

 Example:

  make `rpmtool mflags -O make`

 =item B<cflags> [B<-O>] I<tool>

 This command outputs additional flags for cc(1) for use with the program

 I<tool>. It provides only standard flags which always can be used.

 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 cflags -O $CC` ./configure ...

 =item B<cppflags> [B<-p> I<prefix>] [[C<+|->I<subdir> ...]

 This command output cpp(1) C<-I> options for the OpenPKG instance

 I<prefix>. It optionally can prefix or suffix with one or more I<subdir>

 related options, too. If I<subdir> is prefixed with C<+> (or not

 prefixed at all), the generated option is appended. If I<subdir> is

 prefixed with C<-> the generated option is prepended.

 Example:

  rpmtool cppflags -p /foo bar -baz +quux

 =item B<ldflags> [B<-p> I<prefix>] [[C<+|->I<subdir> ...]

 This command output ld(1) C<-L> options for the OpenPKG instance

 I<prefix>. It optionally can prefix or suffix with one or more I<subdir>

 related options, too. If I<subdir> is prefixed with C<+> (or not

 prefixed at all), the generated option is appended. If I<subdir> is

 prefixed with C<-> the generated option is prepended.

 Example:

  rpmtool ldflags -p /foo bar -baz +quux

 =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(8)

 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 convenient, to also have (in addition to character

 sets) string sets like C</path/{foo,bar,quux}>. rpmtool(8) 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(8) 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<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