michael@428: ##
michael@428: ##  build.pod -- OpenPKG Package Building and Installing
michael@428: ##  Copyright (c) 2000-2012 OpenPKG GmbH <http://openpkg.com/>
michael@428: ##
michael@428: ##  This software is property of the OpenPKG GmbH, DE MUC HRB 160208.
michael@428: ##  All rights reserved. Licenses which grant limited permission to use,
michael@428: ##  copy, modify and distribute this software are available from the
michael@428: ##  OpenPKG GmbH.
michael@428: ##
michael@428: ##  THIS SOFTWARE IS PROVIDED "AS IS" AND ANY EXPRESSED OR IMPLIED
michael@428: ##  WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
michael@428: ##  MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
michael@428: ##  IN NO EVENT SHALL THE AUTHORS AND COPYRIGHT HOLDERS AND THEIR
michael@428: ##  CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
michael@428: ##  SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
michael@428: ##  LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
michael@428: ##  USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
michael@428: ##  ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
michael@428: ##  OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
michael@428: ##  OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
michael@428: ##  SUCH DAMAGE.
michael@428: ##
michael@428: 
michael@428: =pod
michael@428: 
michael@428: =head1 NAME
michael@428: 
michael@428: B<openpkg build> - B<OpenPKG> Package Building and Installing
michael@428: 
michael@428: =head1 SYNOPSIS
michael@428: 
michael@428: B<openpkg>
michael@428: B<build>
michael@428: [B<-R> I<rpm>]
michael@428: [B<-r> I<repository>]
michael@428: [B<-f> I<index.rdf>]
michael@428: [B<-u>]
michael@428: [B<-U>]
michael@428: [B<-z>]
michael@428: [B<-Z>]
michael@428: [B<-i>]
michael@428: [B<-q>]
michael@428: [B<-s>]
michael@428: [B<-S>]
michael@428: [B<-M>]
michael@428: [B<-L>]
michael@428: [B<-W>]
michael@428: [B<-X>]
michael@428: [B<-K>]
michael@428: [B<-k>]
michael@428: [B<-e>]
michael@428: [B<-b>]
michael@428: [B<-B>]
michael@428: [B<-G>]
michael@428: [B<-P> I<priv-cmd>]
michael@428: [B<-N> I<non-priv-cmd>]
michael@428: [B<-p> I<platform>]
michael@428: [B<-D> I<var>=I<val> ...]
michael@428: [B<-E> I<name> ...]
michael@428: [B<-H> I<name> ...]
michael@428: ([B<-a>] [B<-A>] | I<pattern> ...)
michael@428: 
michael@428: =head1 DESCRIPTION
michael@428: 
michael@428: The B<openpkg build> tool provides automated recursive from-scratch
michael@428: installation of packages and the updating and upgrading of installed
michael@428: packages.
michael@428: 
michael@428: It generates a Bourne-Shell script on standard output (F<stdout>)
michael@428: that can be executed to perform the package installation or
michael@428: updating/upgrading procedure for all requested packages and their
michael@428: dependencies.
michael@428: 
michael@428: Packages that are upgraded automatically trigger rebuilds of all
michael@428: packages that depend on the upgraded package ("reverse dependencies").
michael@428: The dependency information is read from an XML/RDF index generated by
michael@428: the companion tool B<openpkg index>.
michael@428: 
michael@428: =head1 ARGUMENTS
michael@428: 
michael@428: Packages are selected by providing a list of name patterns. Each
michael@428: pattern is either a package name or a name prefix followed by a 'F<*>'
michael@428: character. Additionally, in order to resolve ambiguous dependencies, you
michael@428: can append a discrimination prefix separated by a comma that matches
michael@428: against the full "I<name>-I<version>-I<revision>" string of a package.
michael@428: 
michael@428: =head1 OPTIONS
michael@428: 
michael@428: The following command line options exist:
michael@428: 
michael@428: =over 4
michael@428: 
michael@428: =item B<-R> I<command>
michael@428: 
michael@428: Specify the "B<openpkg rpm>" command with fully qualified path.
michael@428: Several other internal paths are deduced from the I<command> path,
michael@428: so this has to be something like "I<prefix>C</bin/openpkg rpm>".
michael@428: 
michael@428: =item B<-r> I<repository>
michael@428: 
michael@428: Specify the path to an OpenPKG RPM package repository.
michael@428: This can be a URL (including "file://") to download packages from or
michael@428: an absolute directory path (identified by leading "/") or
michael@428: a relative directory path (identified by leading "./") to access packages directly.
michael@428: The name of the package file is appended to this path.
michael@428: The default is to use a URL pointing to the B<OpenPKG> download service
michael@428: as determined by the "B<openpkg release>" command.
michael@428: 
michael@428: =item B<-f> I<index.rdf>
michael@428: 
michael@428: Specify the path to the primary XML/RDF index. This can be a URL or a
michael@428: file path. If the index contains references to other indices, these
michael@428: are recursively included automatically. The default is to use a URL
michael@428: pointing to the B<OpenPKG> FTP server as as determined by the "B<openpkg
michael@428: release>" command.
michael@428: 
michael@428: =item B<-u>
michael@428: 
michael@428: The generated script will ignore binary RPMs that are stored on
michael@428: your system. Instead it will either fetch binary RPMs or rebuild
michael@428: from source RPMs fetched from the repository.
michael@428: 
michael@428: =item B<-U>
michael@428: 
michael@428: The generated script will try to upgrade all selected packages
michael@428: including their dependencies to the most recent version. Use
michael@428: this for usual upgrade tasks in combination with option "B<-a>".
michael@428: 
michael@428: =item B<-z>
michael@428: 
michael@428: The generated script will rebuild all selected packages
michael@428: including their dependencies even when the most recent version
michael@428: is already installed.
michael@428: 
michael@428: =item B<-Z>
michael@428: 
michael@428: B<openpkg build> ignores all installed packages, the
michael@428: generated script will rebuild all selected packages from scratch.
michael@428: 
michael@428: =item B<-i>
michael@428: 
michael@428: The generated script will ignore run-time errors.
michael@428: 
michael@428: =item B<-q>
michael@428: 
michael@428: Ignore all reverse dependencies. This means that all packages which are
michael@428: rebuild do I<not> trigger a rebuild of packages which depend on them.
michael@428: I<ATTENTION: this might break already installed packages and has to be
michael@428: used with care! You should really know what you are doing.>
michael@428: 
michael@428: =item B<-s>
michael@428: 
michael@428: Generate a status map instead of the shell script. The map consists
michael@428: of 3 columns: I<old>, I<tag> and I<new>. The I<old> column shows
michael@428: the installed version of a package (I<name>-I<version>-I<release>)
michael@428: or just the package name (I<name>) if no package of that name
michael@428: is installed and the I<new> column shows the repository version
michael@428: (I<name>-I<version>-I<release>) of a package if it is considered for
michael@428: installation. The I<tag> column shows the following possible values:
michael@428: 
michael@428: =over 10
michael@428: 
michael@428: =item OK
michael@428: 
michael@428: The installed package is suitable and will not be touched.
michael@428: 
michael@428: =item ADD
michael@428: 
michael@428: There is no installed package yet.
michael@428: 
michael@428: =item UPGRADE
michael@428: 
michael@428: The installed package is outdated and requires an update.
michael@428: 
michael@428: =item DEPEND
michael@428: 
michael@428: The installed package needs rebuilding because one of its
michael@428: dependencies is rebuild.
michael@428: 
michael@428: =item MISMATCH
michael@428: 
michael@428: The installed package needs rebuilding because it was build
michael@428: with different parameters.
michael@428: 
michael@428: =item CONFLICT
michael@428: 
michael@428: The required new package cannot be installed because it
michael@428: conflicts with some already installed package.
michael@428: 
michael@428: =item UNDEF
michael@428: 
michael@428: The package has an invalid or ambiguous dependency.
michael@428: 
michael@428: =back
michael@428: 
michael@428: =item B<-S>
michael@428: 
michael@428: Similar to option "B<-s>" but also lists the newest versions in the
michael@428: repository. The following I<tag> might appear in the map:
michael@428: 
michael@428: =over 10
michael@428: 
michael@428: =item NEW
michael@428: 
michael@428: The package exists in the repository but is not required yet.
michael@428: 
michael@428: =back
michael@428: 
michael@428: =item B<-M>
michael@428: 
michael@428: Similar to option "B<-s>" but print a short dependency map.
michael@428: 
michael@428: =item B<-L>
michael@428: 
michael@428: Print a list of packages in the repository that depend on the target.
michael@428: 
michael@428: =item B<-W>
michael@428: 
michael@428: Include all conditional dependencies as if all possible configuration
michael@428: options had been switched on. This has little use in practice except for
michael@428: generating an all-inclusive list with option "B<-L>". I<ATTENTION: Even
michael@428: mutually exclusive options are evaluated to be 'on', building packages
michael@428: with option "-W" therefore might fail or cause unusable results!>
michael@428: 
michael@428: =item B<-X>
michael@428: 
michael@428: Use the slower but more robust external Perl XML parser module
michael@428: XML::Simple instead of the simple internal XML/RDF parser.
michael@428: 
michael@428: =item B<-K>
michael@428: 
michael@428: Keep packages that were installed temporarily during the build process.
michael@428: Without this option those packages are removed.
michael@428: 
michael@428: =item B<-k>
michael@428: 
michael@428: Keep packages that were downloaded temporarily for installation or building.
michael@428: Without this option those packages are removed.
michael@428: 
michael@428: =item B<-e>
michael@428: 
michael@428: Rebuild exact version of a package from repository even when you have
michael@428: installed a newer version from another repository.
michael@428: 
michael@428: =item B<-b>
michael@428: 
michael@428: Wrap package rebuilding commands with script execution-time checks for
michael@428: existing binary packages if the package is rebuild as a dependency. Wrap
michael@428: package install commands with script execution-time checks for different
michael@428: MD5 signature checksums of binary packages and installed packages. This
michael@428: is best to use with option "B<-u>" to defer all such checks until script
michael@428: execution-time.
michael@428: 
michael@428: =item B<-B>
michael@428: 
michael@428: Same as option "B<-b>" but also check all explicit target packages for
michael@428: existing binary packages at script execution-time.
michael@428: 
michael@428: =item B<-g>
michael@428: 
michael@428: The generated script will rebuild all packages selected even when the
michael@428: most recent version is already installed. Dependencies are not affected.
michael@428: Use this especially for updating a package with different build options
michael@428: (see option "B<-D>").
michael@428: 
michael@428: =item B<-P> I<priv-cmd>
michael@428: 
michael@428: Command prefix to use for generated script commands that require
michael@428: elevated privileges (like "B<openpkg rpm -Uvh>"). The most common tool
michael@428: for this is sudo(8). If I<priv-cmd> starts with a dash it will be run
michael@428: without the dash and the command line it should execute is passed as
michael@428: a single quoted string. Use this option for upgrading privileges. For
michael@428: instance, if you are running the C<openpkg build>" command as the
michael@428: management user, use "C<-P sudo>" to make sure that the "B<openpkg rpm
michael@428: -Uvh>" commands in the generated script execute with necessary elevated
michael@428: privileges.
michael@428: 
michael@428: =item B<-N> I<non-priv-cmd>
michael@428: 
michael@428: Command prefix to use for generated script commands that do I<not>
michael@428: require elevated privileges (like "B<openpkg rpm --rebuild>"). The most
michael@428: common tool for this is su(8). If I<non-priv-cmd> starts with a dash
michael@428: it will be run without the dash and the command line it should execute
michael@428: is passed as a single quoted string. Use this option for downgrading
michael@428: privileges. For instance, if you are running the C<openpkg build>"
michael@428: command as the B<root> user, use "C<-N '-su - >I<musr>C< -c'>" to make
michael@428: sure that the non-privileged commands in the generated script execute
michael@428: with privileges of the management user I<musr>.
michael@428: 
michael@428: =item B<-p> I<platform>
michael@428: 
michael@428: The platform string that is matched against the XML/RDF index for binary
michael@428: packages. The default is an empty I<platform> string so that no binary
michael@428: packages are matched at all.
michael@428: 
michael@428: =item B<-D> I<var>=I<val>
michael@428: 
michael@428: Specify build options for selected packages. This can be either
michael@428: "B<-D> I<with_xxx>=I<yyy>" or just "B<-D> I<with_xxx>". The latter is
michael@428: equivalent to a "B<-D> I<with_xxx>=I<yes>". The parameters are matched
michael@428: against selected packages that are already installed. If they do
michael@428: indicate a change, the package is rebuild. There can be multiple "B<-D>"
michael@428: options.
michael@428: 
michael@428: If the option name is prefixed with a package name followed by
michael@428: two colons then it applies only to the specified package, e.g.,
michael@428: "B<-D>I<foo::with_bar>".
michael@428: 
michael@428: =item B<-E> I<name>
michael@428: 
michael@428: Ignore a package with the specified I<name>. This can be used to avoid
michael@428: upgrading to a broken package in the repository or to skip a package
michael@428: upgrade temporarily. If you use a wildcard pattern or the options
michael@428: "B<-a>" or "B<-A>" then I<name> will be excluded. There can be multiple
michael@428: "B<-E>" options.
michael@428: 
michael@428: =item B<-H> I<name>
michael@428: 
michael@428: Hint about packages that should be preferred when more than one fits
michael@428: a requirement. There can be multiple "B<-H>" options.
michael@428: 
michael@428: =item B<-a>
michael@428: 
michael@428: Select all installed packages. You cannot specify a pattern list together
michael@428: with the "B<-a>" option.
michael@428: 
michael@428: =item B<-A>
michael@428: 
michael@428: Select all packages in the repository. You cannot specify a pattern list
michael@428: together with the "B<-A>" option.
michael@428: 
michael@428: =back
michael@428: 
michael@428: =head1 ARGUMENTS
michael@428: 
michael@428: In case neither option B<-a> nor option B<-A> are specified,
michael@428: the command line has to contain one or more package I<pattern>
michael@428: arguments. Each I<pattern> can have the following forms:
michael@428: 
michael@428: =over 4
michael@428: 
michael@428: =item I<name>
michael@428: 
michael@428: A regular package name.
michael@428: 
michael@428: =item I<name>B<*>
michael@428: 
michael@428: A package name wildcard pattern.
michael@428: 
michael@428: =item I<name>B<,>I<name>[B<->I<version>[B<->I<release>]]
michael@428: 
michael@428: A regular package name followed by a constraint
michael@428: which particular package should be chosen.
michael@428: 
michael@428: =back
michael@428: 
michael@428: =head1 CONFIGURATION
michael@428: 
michael@428: B<openpkg build> reads the configuration file F<$HOME/.openpkg/build>.
michael@428: The file lists default options, one option per line and section tags
michael@428: of the form C<[>I<prefix>C<]>. Options following such a tag are only
michael@428: evaluated for the particular B<OpenPKG> instance so that you can
michael@428: define default options for multiple B<OpenPKG> instances.
michael@428: 
michael@428: Example:
michael@428: 
michael@428:  # global options
michael@428:  -X
michael@428: 
michael@428:  [/openpkg/current]
michael@428:  # options for CURRENT stack only
michael@428:  -r http://download.openpkg.org/stacks/current/source/
michael@428: 
michael@428:  [/openpkg/foo]
michael@428:  # options for a FOO stack only
michael@428:  -r http://download.openpkg.org/stacks/foo/source/
michael@428: 
michael@428: =head1 EXAMPLES
michael@428: 
michael@428: The following shows a few typical OpenPKG instance
michael@428: maintenance tasks which involve the B<openpkg build> command:
michael@428: 
michael@428: =head2 Installation
michael@428: 
michael@428: The following examples shows how to initially install an OpenPKG
michael@428: instance under F</openpkg> with Apache/PHP & MySQL:
michael@428: 
michael@428:  # bootstrap the OpenPKG instance
michael@428:  $ curl -L -O http://openpkg.org/go/download/openpkg.src.sh
michael@428:  $ sh openpkg-*-*.src.sh --prefix=/openpkg \
michael@428:    --user=openpkg --group=openpkg --tag=openpkg
michael@428:  $ sh openpkg-*-*.*-*-openpkg.sh
michael@428: 
michael@428:  # install Apache/PHP & MySQL
michael@428:  $ /openpkg/bin/openpkg build \
michael@428:    -D apache-php::with_mysql=yes \
michael@428:    apache apache-php mysql | sh
michael@428: 
michael@428: =head2 Reinstallation
michael@428: 
michael@428: The following example shows how to rebuild and reinstall the already
michael@428: installed package "foo":
michael@428: 
michael@428:  # rebuild and reinstall package
michael@428:  $ /openpkg/bin/openpkg build -g -u foo | sh
michael@428: 
michael@428: =head2 Change
michael@428: 
michael@428: The following fictive example shows how to change the already
michael@428: installed package "foo" by rebuilding and reinstalling it with the
michael@428: "C<foo::with_bar>" build-time option enabled.
michael@428: 
michael@428:  # change a package
michael@428:  $ /openpkg/bin/openpkg build -g -D with_bar=yes foo | sh
michael@428: 
michael@428: =head2 Update
michael@428: 
michael@428: The following example shows how to update (no major
michael@428: OpenPKG version change) an OpenPKG instance under F</openpkg>:
michael@428: 
michael@428:  # update all packages to their latest version
michael@428:  $ /openpkg/bin/openpkg build -Ua | sh
michael@428: 
michael@428: =head2 Upgrade
michael@428: 
michael@428: The following examples shows a complete procedure for upgrading (major
michael@428: OpenPKG version change) the instance under F</openpkg> to OpenPKG
michael@428: 4.X:
michael@428: 
michael@428:  # upgrade the bootstrap package
michael@428:  $ /openpkg/bin/openpkg build \
michael@428:    -r http://download.openpkg.org/stacks/current/source/ openpkg | sh
michael@428: 
michael@428:  # upgrade the whole OpenPKG instance, in correct dependency
michael@428:  # order and by keeping all chosen build-time options.
michael@428:  $ /openpkg/bin/openpkg build -ZaKB | sh
michael@428: 
michael@428: =head2 Deinstallation
michael@428: 
michael@428: The following example shows how to deinstall
michael@428: an entire OpenPKG intance under F</openpkg>:
michael@428: 
michael@428:  # remove all packages and the instance itself
michael@428:  $ /openpkg/bin/openpkg rpm -e \
michael@428:    `/openpkg/bin/openpkg rpm -qa`
michael@428: 
michael@428: =head1 CAVEATS
michael@428: 
michael@428: Parallel execution of B<openpkg build> causes undefined effects.
michael@428: 
michael@428: =head1 HISTORY
michael@428: 
michael@428: The B<openpkg build> command was invented in November 2002 by I<Michael
michael@428: van Elst> E<lt>mlelstv@serpens.deE<gt> under contract with I<Cable
michael@428: & Wireless> E<lt>http://www.cw.com/E<gt> for use inside the B<OpenPKG>
michael@428: project E<lt>http://www.openpkg.org/E<gt>. It was then further
michael@428: refined by the B<OpenPKG Foundation e.V.> as part of the OpenPKG Tool Chain.
michael@428: 
michael@428: =cut
michael@428: