OpenPKG Specs: openpkg/build.pod@a2c6460cfb16 (annotated)

openpkg/build.pod@a2c6460cfb16 (annotated)

openpkg/build.pod

Mon, 28 Jan 2013 17:37:18 +0100

author: Michael Schloh von Bennewitz <michael@schloh.com>
date: Mon, 28 Jan 2013 17:37:18 +0100
changeset 758: a2c6460cfb16
permissions: -rw-r--r--

Correct socket error reporting improvement with IPv6 portable code,
after helpful recommendation by Saúl Ibarra Corretgé on OSips devlist.

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

OpenPKG Specs / annotate

openpkg/build.pod@a2c6460cfb16 (annotated)

openpkg/build.pod