1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/openpkg/rpmtool.pod Tue Jan 06 23:40:39 2009 +0100
1.3 @@ -0,0 +1,190 @@
1.4 +##
1.5 +## rpmtool.pod -- OpenPKG RPM Auxiliary Tool (Manual Page)
1.6 +## Copyright (c) 2000-2007 OpenPKG Foundation e.V. <http://openpkg.net/>
1.7 +## Copyright (c) 2000-2007 Ralf S. Engelschall <http://engelschall.com/>
1.8 +##
1.9 +## Permission to use, copy, modify, and distribute this software for
1.10 +## any purpose with or without fee is hereby granted, provided that
1.11 +## the above copyright notice and this permission notice appear in all
1.12 +## copies.
1.13 +##
1.14 +## THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
1.15 +## WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
1.16 +## MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
1.17 +## IN NO EVENT SHALL THE AUTHORS AND COPYRIGHT HOLDERS AND THEIR
1.18 +## CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
1.19 +## SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
1.20 +## LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
1.21 +## USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
1.22 +## ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
1.23 +## OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
1.24 +## OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
1.25 +## SUCH DAMAGE.
1.26 +##
1.27 +
1.28 +=pod
1.29 +
1.30 +=head1 NAME
1.31 +
1.32 +B<rpmtool> - RPM Auxiliary Tool
1.33 +
1.34 +=head1 SYNOPSIS
1.35 +
1.36 +B<rpmtool>
1.37 +I<command>
1.38 +[I<command-options>]
1.39 +
1.40 +=head1 DESCRIPTION
1.41 +
1.42 +This is an auxiliary tool to the RedHat Package Manager (RPM). It
1.43 +provides additional functionality for use in RPM I<spec> files while
1.44 +building packages. The following I<command>s are available:
1.45 +
1.46 +=over 4
1.47 +
1.48 +=item B<platform>
1.49 +
1.50 +This command outputs a unique platform id in the format
1.51 +"<architecture>-<system><release>". For instance, the output on a
1.52 +FreeBSD platform can be "i386-freebsd4.2", the output on a Linux
1.53 +platform can be "i686-linux2.2.16", the output on a Solaris platform can
1.54 +be "sun4u-sunos5.8", etc.
1.55 +
1.56 +Example:
1.57 +
1.58 + case `rpmtool platform`; in
1.59 + *-freebsd[34].* ) ... ;;
1.60 + *-sunos5.[678] ) ... ;;
1.61 + *-linux2.[24].* ) ... ;;
1.62 + esac
1.63 +
1.64 +=item B<mflags> [B<-O>] I<tool>
1.65 +
1.66 +This command outputs additional flags for make(1) for
1.67 +use with the program I<tool>. It provides only standard flags which
1.68 +always can be used. In conjunction with B<-O> (optimization), it also provides
1.69 +reasonable job control for use on multi-processor platforms (for instance it
1.70 +outputs "-j4" on an SMP system with 2 CPUs if GNU make or BSD pmake is used).
1.71 +
1.72 +Example:
1.73 +
1.74 + make `rpmtool mflags -O make`
1.75 +
1.76 +=item B<cflags> [B<-O>] I<tool>
1.77 +
1.78 +This command outputs additional flags for cc(1) for use with the program
1.79 +I<tool>. It provides only standard flags which always can be used.
1.80 +conjunction with B<-O> it provides also optimization flags (for instance
1.81 +it outputs "-O2 -pipe" for GNU C/C++ compiler).
1.82 +
1.83 +Example:
1.84 +
1.85 + CC="$CC" CFLAGS=`rpmtool cflags -O $CC` ./configure ...
1.86 +
1.87 +=item B<cppflags> [B<-p> I<prefix>] [[C<+|->I<subdir> ...]
1.88 +
1.89 +This command output cpp(1) C<-I> options for the OpenPKG instance
1.90 +I<prefix>. It optionally can prefix or suffix with one or more I<subdir>
1.91 +related options, too. If I<subdir> is prefixed with C<+> (or not
1.92 +prefixed at all), the generated option is appended. If I<subdir> is
1.93 +prefixed with C<-> the generated option is prepended.
1.94 +
1.95 +Example:
1.96 +
1.97 + rpmtool cppflags -p /foo bar -baz +quux
1.98 +
1.99 +=item B<ldflags> [B<-p> I<prefix>] [[C<+|->I<subdir> ...]
1.100 +
1.101 +This command output ld(1) C<-L> options for the OpenPKG instance
1.102 +I<prefix>. It optionally can prefix or suffix with one or more I<subdir>
1.103 +related options, too. If I<subdir> is prefixed with C<+> (or not
1.104 +prefixed at all), the generated option is appended. If I<subdir> is
1.105 +prefixed with C<-> the generated option is prepended.
1.106 +
1.107 +Example:
1.108 +
1.109 + rpmtool ldflags -p /foo bar -baz +quux
1.110 +
1.111 +=item B<files> [B<-v>] [B<-o> I<outfile>] [B<-r> I<build-root>] [I<entry> ...]
1.112 +
1.113 +This is a dynamic variant of the RPM C<%files> section, i.e., it
1.114 +dynamically creates the contents of the C<%files> section for use with
1.115 +the C<%files -f> command. For this the file list entries are read from
1.116 +the command line (or from stdin if no arguments are given or a single
1.117 +argument C<-> is given) and written to stdout (if no B<-o> option is
1.118 +given or its I<outfile> argument is C<->) or to I<outfile>.
1.119 +
1.120 +The trick of this approach is to be able to use additional features in
1.121 +the file list which RPM does not provide. The following features are
1.122 +provided:
1.123 +
1.124 +=over 4
1.125 +
1.126 +=item B<Trailing Tags>
1.127 +
1.128 +RPM requires that all tags (like C<%attr(...)> or C<%dir>) preceed the
1.129 +path in a file list entry. This sometimes leads to ugly and unreadable
1.130 +file lists, because all paths cannot be left-aligned. With rpmtool(8)
1.131 +tags in the input file list can be at leading and trailing positions.
1.132 +The output file list will nevertheless have all tags in leading
1.133 +positions for RPM.
1.134 +
1.135 +=item B<Syntactical Set Pattern>
1.136 +
1.137 +RPM supports simple wildcard patterns like C</path/*> or C</path/[a-z]>,
1.138 +etc. Sometimes it is convenient, to also have (in addition to character
1.139 +sets) string sets like C</path/{foo,bar,quux}>. rpmtool(8) provides this
1.140 +by syntactically (without checking the filesystem) expanding those
1.141 +string sets.
1.142 +
1.143 +=item B<Overriding Entries>
1.144 +
1.145 +This is the most important feature and the reason why shtool(1)'s
1.146 +B<files> command was implemented. Although RPM allows one to specify a
1.147 +directory in a file list and then implicitly expands this recursively
1.148 +into its contents, it unfortunately does not allow one to later
1.149 +explcitly override particular entries (usually if an individual
1.150 +C<%attr(...)> tag is required). rpmtool(8) now supports overriding
1.151 +entries, i.e., if a path occurs multiple times, only the last occurance
1.152 +is kept.
1.153 +
1.154 +=item B<Negation Tag>
1.155 +
1.156 +This provides an additional tag C<%not> which can be used to explicitly
1.157 +exclude a previously implicitly added entry.
1.158 +
1.159 +=back
1.160 +
1.161 +Example:
1.162 +
1.163 + %install
1.164 + :
1.165 + rpmtool files -o files -r$RPM_BUILD_ROOT \
1.166 + '%defattr(-,foo,foo)' \
1.167 + '%{prefix}' \
1.168 + '%attr(1755,root,foo) %{prefix}/bin/bar' \
1.169 + '%not %dir {%{prefix},%{prefix}/*,%{prefix}/man/*}' \
1.170 + '%not %{prefix}/info/dir'
1.171 +
1.172 + %files -f files
1.173 +
1.174 +=item B<msg> [B<-b>]
1.175 +
1.176 +This displays the contents of F<stdin> as a boxed message. If option
1.177 +B<-b> is given it additionally beeps once before displaying the box.
1.178 +
1.179 +=back
1.180 +
1.181 +=head1 HISTORY
1.182 +
1.183 +This tool was created in November 2000 for use in OpenPKG, the
1.184 +cross-platform RPM-based Unix software packaging facility.
1.185 +
1.186 +=head1 AUTHOR
1.187 +
1.188 + Ralf S. Engelschall
1.189 + rse@engelschall.com
1.190 + www.engelschall.com
1.191 +
1.192 +=cut
1.193 +
