diff -r 71503088f51b -r f880f219c566 openpkg/build.pod
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/openpkg/build.pod	Tue Jul 31 12:23:42 2012 +0200
@@ -0,0 +1,460 @@
+##
+##  build.pod -- OpenPKG Package Building and Installing
+##  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<openpkg build> - B<OpenPKG> Package Building and Installing
+
+=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<-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<pattern> ...)
+
+=head1 DESCRIPTION
+
+The B<openpkg build> tool provides automated recursive from-scratch
+installation of packages and the updating and upgrading of installed
+packages.
+
+It generates a Bourne-Shell script on standard output (F<stdout>)
+that can be executed to perform the package installation or
+updating/upgrading procedure for all requested packages and their
+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 XML/RDF index generated by
+the companion tool B<openpkg index>.
+
+=head1 ARGUMENTS
+
+Packages are selected by providing a list of name patterns. Each
+pattern is either a package name or a name prefix followed by a 'F<*>'
+character. Additionally, in order to resolve ambiguous dependencies, you
+can append a discrimination prefix separated by a comma that matches
+against the full "I<name>-I<version>-I<revision>" string of a package.
+
+=head1 OPTIONS
+
+The following command line options exist:
+
+=over 4
+
+=item B<-R> I<command>
+
+Specify the "B<openpkg rpm>" command with fully qualified path.
+Several other internal paths are deduced from the I<command> path,
+so this has to be something like "I<prefix>C</bin/openpkg rpm>".
+
+=item B<-r> I<repository>
+
+Specify the path to an OpenPKG RPM package repository.
+This can be a URL (including "file://") to download packages from or
+an absolute directory path (identified by leading "/") or
+a relative directory path (identified by leading "./") to access packages directly.
+The name of the package file is appended to this path.
+The default is to use a URL pointing to the B<OpenPKG> download service
+as determined by the "B<openpkg release>" command.
+
+=item B<-f> I<index.rdf>
+
+Specify the path to the primary XML/RDF index. This can be a URL or a
+file path. If the index contains references to other indices, these
+are recursively included automatically. The default is to use a URL
+pointing to the B<OpenPKG> FTP server as as determined by the "B<openpkg
+release>" command.
+
+=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. Use
+this for usual upgrade tasks in combination with option "B<-a>".
+
+=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
+generated script will rebuild all selected packages from scratch.
+
+=item B<-i>
+
+The generated script will ignore run-time errors.
+
+=item B<-q>
+
+Ignore all reverse dependencies. This means that all packages which are
+rebuild do I<not> trigger a rebuild of packages which depend on them.
+I<ATTENTION: this might break already installed packages and has to be
+used with care! You should really know what you are doing.>
+
+=item B<-s>
+
+Generate a status map instead of the shell script. The map consists
+of 3 columns: I<old>, I<tag> and I<new>. The I<old> column shows
+the installed version of a package (I<name>-I<version>-I<release>)
+or just the package name (I<name>) if no package of that name
+is installed and the I<new> column shows the repository version
+(I<name>-I<version>-I<release>) of a package if it is considered for
+installation. The I<tag> column shows the following possible values:
+
+=over 10
+
+=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 rebuild.
+
+=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 option "B<-s>" but also lists the newest versions in the
+repository. The following I<tag> might appear in the map:
+
+=over 10
+
+=item NEW
+
+The package exists in the repository but is not required yet.
+
+=back
+
+=item B<-M>
+
+Similar to option "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 in practice except for
+generating an all-inclusive list with option "B<-L>". I<ATTENTION: Even
+mutually exclusive options are evaluated to be 'on', building packages
+with option "-W" therefore might fail or cause unusable results!>
+
+=item B<-X>
+
+Use the slower but more robust external Perl XML parser module
+XML::Simple instead of the simple internal XML/RDF parser.
+
+=item B<-K>
+
+Keep packages that were installed temporarily during the build process.
+Without this option those packages are removed.
+
+=item B<-k>
+
+Keep packages that were downloaded temporarily for installation or building.
+Without this option those packages are removed.
+
+=item B<-e>
+
+Rebuild exact version of a package from repository even when you have
+installed a newer version from another repository.
+
+=item B<-b>
+
+Wrap package rebuilding commands with script execution-time checks for
+existing binary packages if the package is rebuild as a dependency. Wrap
+package install commands with script execution-time checks for different
+MD5 signature checksums of binary packages and installed packages. This
+is best to use with option "B<-u>" to defer all such checks until script
+execution-time.
+
+=item B<-B>
+
+Same as option "B<-b>" but also check all explicit target packages for
+existing binary packages at script execution-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.
+Use this especially for updating a package with different build options
+(see option "B<-D>").
+
+=item B<-P> I<priv-cmd>
+
+Command prefix to use for generated script commands that require
+elevated privileges (like "B<openpkg rpm -Uvh>"). 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. Use this option for upgrading privileges. For
+instance, if you are running the C<openpkg build>" command as the
+management user, use "C<-P sudo>" to make sure that the "B<openpkg rpm
+-Uvh>" commands in the generated script execute with necessary elevated
+privileges.
+
+=item B<-N> I<non-priv-cmd>
+
+Command prefix to use for generated script commands that do I<not>
+require elevated privileges (like "B<openpkg rpm --rebuild>"). The most
+common tool for this is su(8). If I<non-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. Use this option for downgrading
+privileges. For instance, if you are running the C<openpkg build>"
+command as the B<root> user, use "C<-N '-su - >I<musr>C< -c'>" to make
+sure that the non-privileged commands in the generated script execute
+with privileges of the management user I<musr>.
+
+=item B<-p> I<platform>
+
+The platform string that is matched against the XML/RDF index for binary
+packages. The default is an empty I<platform> string so that no binary
+packages are matched at all.
+
+=item B<-D> I<var>=I<val>
+
+Specify build 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<foo::with_bar>".
+
+=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 or to skip a package
+upgrade temporarily. If you use a wildcard pattern or the options
+"B<-a>" or "B<-A>" then I<name> will be excluded. 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<-H>" options.
+
+=item B<-a>
+
+Select all installed packages. You cannot specify a pattern list together
+with the "B<-a>" option.
+
+=item B<-A>
+
+Select all packages in the repository. You cannot specify a pattern list
+together with the "B<-A>" option.
+
+=back
+
+=head1 ARGUMENTS
+
+In case neither option B<-a> nor option B<-A> are specified,
+the command line has to contain one or more package I<pattern>
+arguments. Each I<pattern> can have the following forms:
+
+=over 4
+
+=item I<name>
+
+A regular package name.
+
+=item I<name>B<*>
+
+A package name wildcard pattern.
+
+=item I<name>B<,>I<name>[B<->I<version>[B<->I<release>]]
+
+A regular package name followed by a constraint
+which particular package should be chosen.
+
+=back
+
+=head1 CONFIGURATION
+
+B<openpkg build> reads the configuration file F<$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 for the particular B<OpenPKG> instance so that you can
+define default options for multiple B<OpenPKG> instances.
+
+Example:
+
+ # global options
+ -X
+
+ [/openpkg/current]
+ # options for CURRENT stack only
+ -r http://download.openpkg.org/stacks/current/source/
+
+ [/openpkg/foo]
+ # options for a FOO stack only
+ -r http://download.openpkg.org/stacks/foo/source/
+
+=head1 EXAMPLES
+
+The following shows a few typical OpenPKG instance
+maintenance tasks which involve the B<openpkg build> command:
+
+=head2 Installation
+
+The following examples shows how to initially install an OpenPKG
+instance under F</openpkg> with Apache/PHP & MySQL:
+
+ # bootstrap the OpenPKG instance
+ $ curl -L -O http://openpkg.org/go/download/openpkg.src.sh
+ $ sh openpkg-*-*.src.sh --prefix=/openpkg \
+   --user=openpkg --group=openpkg --tag=openpkg
+ $ sh openpkg-*-*.*-*-openpkg.sh
+
+ # install Apache/PHP & MySQL
+ $ /openpkg/bin/openpkg build \
+   -D apache-php::with_mysql=yes \
+   apache apache-php mysql | sh
+
+=head2 Reinstallation
+
+The following example shows how to rebuild and reinstall the already
+installed package "foo":
+
+ # rebuild and reinstall package
+ $ /openpkg/bin/openpkg build -g -u foo | sh
+
+=head2 Change
+
+The following fictive example shows how to change the already
+installed package "foo" by rebuilding and reinstalling it with the
+"C<foo::with_bar>" build-time option enabled.
+
+ # change a package
+ $ /openpkg/bin/openpkg build -g -D with_bar=yes foo | sh
+
+=head2 Update
+
+The following example shows how to update (no major
+OpenPKG version change) an OpenPKG instance under F</openpkg>:
+
+ # update all packages to their latest version
+ $ /openpkg/bin/openpkg build -Ua | sh
+
+=head2 Upgrade
+
+The following examples shows a complete procedure for upgrading (major
+OpenPKG version change) the instance under F</openpkg> to OpenPKG
+4.X:
+
+ # upgrade the bootstrap package
+ $ /openpkg/bin/openpkg build \
+   -r http://download.openpkg.org/stacks/current/source/ openpkg | sh
+
+ # upgrade the whole OpenPKG instance, in correct dependency
+ # order and by keeping all chosen build-time options.
+ $ /openpkg/bin/openpkg build -ZaKB | sh
+
+=head2 Deinstallation
+
+The following example shows how to deinstall
+an entire OpenPKG intance under F</openpkg>:
+
+ # remove all packages and the instance itself
+ $ /openpkg/bin/openpkg rpm -e \
+   `/openpkg/bin/openpkg rpm -qa`
+
+=head1 CAVEATS
+
+Parallel execution of B<openpkg build> causes undefined effects.
+
+=head1 HISTORY
+
+The B<openpkg build> command was invented in November 2002 by I<Michael
+van Elst> E<lt>mlelstv@serpens.deE<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>. It was then further
+refined by the B<OpenPKG Foundation e.V.> as part of the OpenPKG Tool Chain.
+
+=cut
+