OpenPKG Specs / file revision

 ##

 ##  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