##
##  openpkg.pod -- OpenPKG maintainance utility (frontend 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<openpkg> - B<OpenPKG> maintainance utility

=head1 VERSION

openpkg-tool @version@

=head1 SYNOPSIS

B<openpkg> 
B<index> 
[B<-r> I<resource>] 
[B<-p> I<platform>]
[B<-C> I<cache.db>] 
[B<-o> I<index.rdf>] 
[B<-c>] 
[B<-i>] 
I<dir> ...

B<openpkg> 
B<build> 
[B<-R> I<rpm>]
[B<-r> I<repository>]
[B<-f> I<index.rdf>]
[B<-u>] 
[B<-U>] 
[B<-z>]
[B<-Z>]
[B<-i>]
[B<-q>]
[B<-P> I<priv-cmd>]
[B<-N> I<non-priv-cmd>]
[B<-p> I<platform>]
[B<-D>I<var>=I<val> ...]
[B<-E> I<name> ...]
([B<-a>] [B<-A>] | I<patternlist>)

=head1 DESCRIPTION

B<openpkg> is a frontend utility for maintaining an B<OpenPKG> instance.
It currenty provides indexing of RPM files (B<openpkg index>) and
automated recursive from-scratch installation and updating of existing
RPM packages (B<openpkg build>).

=head1 COMMANDS

=head2 OPENPKG INDEX

B<openpkg-index> creates an XML/RDF based resource index for RPM
F<.spec> files in a source tree or from an RPM package repository. The
index holds enough information to support an automated build process by
B<openpkg build>.

The following command line options exist:

=over 4

=item B<-r> I<resource>

The name of the resource stored in the index. The default is
"C<OpenPKG-CURRENT/Source/>".

=item B<-p> I<platform>

B<openpkg index> adds a platform attribute for binary RPMs. The
attribute is built as I<%{arch}>C<->I<platform>C<->I<%{os}> where
I<%{arch}> and I<%{os}> are taken from the RPM header and I<platform> is
the value of the B<-p> option. The default value is "C<unkown>". This
must be used to distinguish between platforms that support the same
Architecture and OS name like various Linux distributions.

=item B<-C> I<cache.db>

Cache all F<.spec> files into this Berkeley-DB file when indexing source
RPMs. The cache is refreshed automatically when the source RPMs are more
recent than the cache entry.

=item B<-o> I<index.rdf>

Name of the output XML/RDF file, default is to write to F<stdout>.

=item B<-c>

Compress output with C<bzip2>. Use the B<-o> option to specify a F<.bz2>
suffix.

=item B<-i>

The specified directories are RPM repositories. Build index over
all F<.rpm> files in these directories and all subdirectories.
If a subdirectory already contains a C<00INDEX.rdf> or C<00INDEX.rdf.*>
file then skip scanning the subdirectory, instead add a reference
to the index file into the new index.

Without this option the directories are source trees with a subdirectory
per package and a I<package>C<.spec> file inside each subdirectory.

=back

=head2 OPENPKG BUILD

B<openpkg build> writes a shell script to standard output that installs
or upgrades software packages including all dependencies. Packages that
are upgraded automatically trigger rebuilds of all packages that depend
on the upgraded package ("reverse dependencies"). The dependency
information is read from an index generated by B<openpkg index>.

The following command line options exist:

=over 4

=item B<-R> I<rpm>

Specify a path to the installed B<OpenPKG> C<rpm> executable. Several
other internal paths are deduced from the I<rpm> path, so this should be
something like I<%{l_prefix}>C</bin/rpm>.

=item B<-r> I<repository>

Specify a path to an RPM repository, this can be a URL or a directory
path. The name of the package file is appended to this path.
The default is to use a URL pointing to the B<OpenPKG> FTP server.

=item B<-f> I<index.rdf>

Specify a path to the primary XML/RDF index, this can be a URL or a
file path. If the index contains references to aother indexes these are
included automatically. The default is to use a URL pointing to the
B<OpenPKG> FTP server for the B<OpenPKG> release you are using.

=item B<-u>

The generated script will ignore binary RPMs that are stored on
your system. Instead it will either fetch binary RPMs or rebuild
from source RPMs fetched from the repository.

=item B<-U>

The generated script will try to upgrade all selected packages
including their dependencies to the most recent version.

=item B<-z>

The generated script will rebuild all selected packages
including their dependencies even when the most recent version
is already installed.

=item B<-Z>

B<openpkg build> ignores a installed packages, the
script will rebuild all selected packages from scratch. 
Note that this doesn't work together with the B<-a> option.

=item B<-i>

The generated script will ignore errors. However, if a build
phase fails the install phase is still skipped.

=item B<-q>

Ignore all reverse dependencies.
I<ATTENTION: this might break already installed packages!>

=item B<-P> I<priv-cmd>

Command prefix to use for install commands that require elevated
privileges. The most common tool for this is sudo(1).

=item B<-N> I<non-priv-cmd>

Command prefix to use for install commands that do not require elevated
privileges. The most common tool for this is sudo(1).

=item B<-p> I<platform>

The platform string that is matched against the index for binary
packages. Default is to use the I<%{_target_platform}> variable.

=item B<-D>I<var>=I<val>

Specify configuration options for all selected packages. This can be
either B<-D>C<with_>I<xxx>C<=>I<yyy> or just B<-D>C<with_>I<xxx>, the
latter is equivalent to a B<-D>C<with_>I<xxx>C<=>C<yes>. The parameters
are matched against selected packages that are already installed. If
they do indicate a change the package is rebuild. There can be multiple
B<-D> options.

=item B<-E> I<name>

Ignore a package with the specified I<name>. This can be used to avoid
upgrading to a broken package in the repository. There can be multiple
B<-E> options.

=item B<-a>

Select all installed packages. Do not specify a pattern list together
with the B<-a> option.

=item B<-A>

Select all packages in the repository. Do not specify a pattern list together
with the B<-a> option.

=back

=head1 CONFIGURATION

B<openpkg build> reads the configuration file I<$HOME/.openpkg/build>.
The file lists default options, one option per line and section tags
of the form C<[>I<prefix>C<]>. Options following such a tag are only
evaluated if the selected RPM path matches the prefix so that you can
define default options for multiple B<OpenPKG> hierarchies.

=head1 CAVEATS

Parallel execution of B<openpkg build> causes undefined effects.

=head1 SEE ALSO

rpm(1), sudo(1)

=head1 HISTORY

The B<openpkg index> and B<openpkg build> command
was invented in November 2002 by I<Michael van Elst>
E<lt>mlelstv@dev.de.cw.netE<gt> under contract with I<Cable & Wireless
Germany> E<lt>http://www.cw.com/deE<gt> for use inside the B<OpenPKG>
project E<lt>http://www.openpkg.org/E<gt>.

=head1 AUTHORS

 Michael van Elst
 mlelstv@dev.de.cw.net

=cut