##
##  openpkg.pod -- OpenPKG Maintenance Tool (manual page)
##  Copyright (c) 2000-2003 The OpenPKG Project <http://www.openpkg.org/>
##  Copyright (c) 2000-2003 Ralf S. Engelschall <rse@engelschall.com>
##  Copyright (c) 2000-2003 Cable & Wireless <http://www.cw.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 build> - B<OpenPKG> Maintenance Tool (Building)

=head1 VERSION

openpkg build XX-VERSION-XX

=head1 SYNOPSIS

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<-s>]
[B<-S>]
[B<-M>]
[B<-L>]
[B<-W>]
[B<-X>]
[B<-K>]
[B<-e>]
[B<-b>]
[B<-B>]
[B<-G>]
[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<-H> I<name> ...]
([B<-a>] [B<-A>] | I<patternlist>)

=head1 DESCRIPTION

The B<openpkg build> tool provides automated recursive from-scratch
installation and updating of existing RPM packages (B<openpkg build>).
It 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>.

Packages are selected by providing a list of name patterns. Each
pattern is either a package name or a prefix followed by a '*'
character. Additionally you can append a discrimination prefix separated
by a comma that matches against the full name-version-revision
string.

=head1 OPTIONS

The following command line options exist:

=over 4

=item B<-R> I<rpm>

Specify a path to the installed B<OpenPKG> C<rpm> command. Several
other internal paths are deduced from the I<rpm> path, so this should be
something like "I<%{l_prefix}>C</bin/openpkg 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 other 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 all 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<-s>

Print a status map instead of the install script. The map consists
of 3 columns: "old", "tag" and "new". "old" shows the installed
version of a package or just the package name if no package of
that name is installed and "new" shows the repository version
of a package if it is considered for installation. "tag" has the
following possible values:

=over 4

=item OK

The installed package is suitable and will not be touched.

=item ADD

There is no installed package yet.

=item UPGRADE

The installed package is outdated and requires an update.

=item DEPEND

The installed package needs rebuilding because one of its
dependencies is rebuilt.

=item MISMATCH

The installed package needs rebuilding because it was build
with different parameters.

=item CONFLICT

The required new package cannot be installed because it
conflicts with some already installed package.

=item UNDEF

The package has an invalid or ambiguous dependency.

=back

=item B<-S>

Similar to B<-s> but also lists the newest versions in the
repository. The following tag might appear in the map.

=over 4

=item NEW

The package exists in the repository but isn't required yet.

=back

=item B<-M>

Similar to B<-s> but print a short dependency map.

=item B<-L>

Print a list of packages in the repository that depend on the target.

=item B<-W>

Include all conditional dependencies as if all possible configuration
options had been switched on. This has little use except for generating
an all-inclusive list with the B<-L> option.
I<ATTENTION: Even mutually exclusive options are evaluated to be 'on',
building packages with B<-W> therefore might fail or cause unusable
results!>

=item B<-X>

Ignore an installed XML parser module but use the internal
simple text parser instead.

=item B<-K>

Keep packages that were installed temporarily during the build process.

=item B<-e>

Rebuild exact version from repository even when you have installed
a newer version from another repository.

=item B<-b>

Wrap rebuild commands with build-time check for existing binary packages
if the package is rebuilt as a dependency. This is best to use with
B<-u> to defer all such checks until build-time.

=item B<-B>

Same as -b but also check all packages for existing binary packages
at run-time.

=item B<-g>

The generated script will rebuild all packages selected even when the
most recent version is already installed. Dependencies are not affected.

=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(8). If I<priv-cmd>
starts with a dash it will be run without the dash and the command
line it should execute is passed as a single quoted string.

=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(8). If I<priv-cmd>
starts with a dash it will be run without the dash and the command
line it should execute is passed as a single quoted string.

=item B<-p> I<platform>

The platform string that is matched against the index for binary
packages. Default is an empty string so that no binary packages
are matched.

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

Specify configuration options for selected packages. This can be
either B<-D>I<with_xxx>=I<yyy> or just B<-D>I<with_xxx>, the
latter is equivalent to a B<-D>I<with_xxx>=I<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.

If the option name is prefixed with a package name followed by two colons
then it applies only to the specified package. E.g. B<-D>I<gcc::with_binutils>.

=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<-H> I<name>

Hint about packages that should be preferred when more than one fits
a requirement. 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(8), sudo(8)

=head1 HISTORY

The 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> E<lt>http://www.cw.com/E<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