1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/openpkg/build.pod Tue Jul 31 12:23:42 2012 +0200
1.3 @@ -0,0 +1,460 @@
1.4 +##
1.5 +## build.pod -- OpenPKG Package Building and Installing
1.6 +## Copyright (c) 2000-2012 OpenPKG GmbH <http://openpkg.com/>
1.7 +##
1.8 +## This software is property of the OpenPKG GmbH, DE MUC HRB 160208.
1.9 +## All rights reserved. Licenses which grant limited permission to use,
1.10 +## copy, modify and distribute this software are available from the
1.11 +## OpenPKG GmbH.
1.12 +##
1.13 +## THIS SOFTWARE IS PROVIDED "AS IS" AND ANY EXPRESSED OR IMPLIED
1.14 +## WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
1.15 +## MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
1.16 +## IN NO EVENT SHALL THE AUTHORS AND COPYRIGHT HOLDERS AND THEIR
1.17 +## CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
1.18 +## SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
1.19 +## LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
1.20 +## USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
1.21 +## ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
1.22 +## OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
1.23 +## OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
1.24 +## SUCH DAMAGE.
1.25 +##
1.26 +
1.27 +=pod
1.28 +
1.29 +=head1 NAME
1.30 +
1.31 +B<openpkg build> - B<OpenPKG> Package Building and Installing
1.32 +
1.33 +=head1 SYNOPSIS
1.34 +
1.35 +B<openpkg>
1.36 +B<build>
1.37 +[B<-R> I<rpm>]
1.38 +[B<-r> I<repository>]
1.39 +[B<-f> I<index.rdf>]
1.40 +[B<-u>]
1.41 +[B<-U>]
1.42 +[B<-z>]
1.43 +[B<-Z>]
1.44 +[B<-i>]
1.45 +[B<-q>]
1.46 +[B<-s>]
1.47 +[B<-S>]
1.48 +[B<-M>]
1.49 +[B<-L>]
1.50 +[B<-W>]
1.51 +[B<-X>]
1.52 +[B<-K>]
1.53 +[B<-k>]
1.54 +[B<-e>]
1.55 +[B<-b>]
1.56 +[B<-B>]
1.57 +[B<-G>]
1.58 +[B<-P> I<priv-cmd>]
1.59 +[B<-N> I<non-priv-cmd>]
1.60 +[B<-p> I<platform>]
1.61 +[B<-D> I<var>=I<val> ...]
1.62 +[B<-E> I<name> ...]
1.63 +[B<-H> I<name> ...]
1.64 +([B<-a>] [B<-A>] | I<pattern> ...)
1.65 +
1.66 +=head1 DESCRIPTION
1.67 +
1.68 +The B<openpkg build> tool provides automated recursive from-scratch
1.69 +installation of packages and the updating and upgrading of installed
1.70 +packages.
1.71 +
1.72 +It generates a Bourne-Shell script on standard output (F<stdout>)
1.73 +that can be executed to perform the package installation or
1.74 +updating/upgrading procedure for all requested packages and their
1.75 +dependencies.
1.76 +
1.77 +Packages that are upgraded automatically trigger rebuilds of all
1.78 +packages that depend on the upgraded package ("reverse dependencies").
1.79 +The dependency information is read from an XML/RDF index generated by
1.80 +the companion tool B<openpkg index>.
1.81 +
1.82 +=head1 ARGUMENTS
1.83 +
1.84 +Packages are selected by providing a list of name patterns. Each
1.85 +pattern is either a package name or a name prefix followed by a 'F<*>'
1.86 +character. Additionally, in order to resolve ambiguous dependencies, you
1.87 +can append a discrimination prefix separated by a comma that matches
1.88 +against the full "I<name>-I<version>-I<revision>" string of a package.
1.89 +
1.90 +=head1 OPTIONS
1.91 +
1.92 +The following command line options exist:
1.93 +
1.94 +=over 4
1.95 +
1.96 +=item B<-R> I<command>
1.97 +
1.98 +Specify the "B<openpkg rpm>" command with fully qualified path.
1.99 +Several other internal paths are deduced from the I<command> path,
1.100 +so this has to be something like "I<prefix>C</bin/openpkg rpm>".
1.101 +
1.102 +=item B<-r> I<repository>
1.103 +
1.104 +Specify the path to an OpenPKG RPM package repository.
1.105 +This can be a URL (including "file://") to download packages from or
1.106 +an absolute directory path (identified by leading "/") or
1.107 +a relative directory path (identified by leading "./") to access packages directly.
1.108 +The name of the package file is appended to this path.
1.109 +The default is to use a URL pointing to the B<OpenPKG> download service
1.110 +as determined by the "B<openpkg release>" command.
1.111 +
1.112 +=item B<-f> I<index.rdf>
1.113 +
1.114 +Specify the path to the primary XML/RDF index. This can be a URL or a
1.115 +file path. If the index contains references to other indices, these
1.116 +are recursively included automatically. The default is to use a URL
1.117 +pointing to the B<OpenPKG> FTP server as as determined by the "B<openpkg
1.118 +release>" command.
1.119 +
1.120 +=item B<-u>
1.121 +
1.122 +The generated script will ignore binary RPMs that are stored on
1.123 +your system. Instead it will either fetch binary RPMs or rebuild
1.124 +from source RPMs fetched from the repository.
1.125 +
1.126 +=item B<-U>
1.127 +
1.128 +The generated script will try to upgrade all selected packages
1.129 +including their dependencies to the most recent version. Use
1.130 +this for usual upgrade tasks in combination with option "B<-a>".
1.131 +
1.132 +=item B<-z>
1.133 +
1.134 +The generated script will rebuild all selected packages
1.135 +including their dependencies even when the most recent version
1.136 +is already installed.
1.137 +
1.138 +=item B<-Z>
1.139 +
1.140 +B<openpkg build> ignores all installed packages, the
1.141 +generated script will rebuild all selected packages from scratch.
1.142 +
1.143 +=item B<-i>
1.144 +
1.145 +The generated script will ignore run-time errors.
1.146 +
1.147 +=item B<-q>
1.148 +
1.149 +Ignore all reverse dependencies. This means that all packages which are
1.150 +rebuild do I<not> trigger a rebuild of packages which depend on them.
1.151 +I<ATTENTION: this might break already installed packages and has to be
1.152 +used with care! You should really know what you are doing.>
1.153 +
1.154 +=item B<-s>
1.155 +
1.156 +Generate a status map instead of the shell script. The map consists
1.157 +of 3 columns: I<old>, I<tag> and I<new>. The I<old> column shows
1.158 +the installed version of a package (I<name>-I<version>-I<release>)
1.159 +or just the package name (I<name>) if no package of that name
1.160 +is installed and the I<new> column shows the repository version
1.161 +(I<name>-I<version>-I<release>) of a package if it is considered for
1.162 +installation. The I<tag> column shows the following possible values:
1.163 +
1.164 +=over 10
1.165 +
1.166 +=item OK
1.167 +
1.168 +The installed package is suitable and will not be touched.
1.169 +
1.170 +=item ADD
1.171 +
1.172 +There is no installed package yet.
1.173 +
1.174 +=item UPGRADE
1.175 +
1.176 +The installed package is outdated and requires an update.
1.177 +
1.178 +=item DEPEND
1.179 +
1.180 +The installed package needs rebuilding because one of its
1.181 +dependencies is rebuild.
1.182 +
1.183 +=item MISMATCH
1.184 +
1.185 +The installed package needs rebuilding because it was build
1.186 +with different parameters.
1.187 +
1.188 +=item CONFLICT
1.189 +
1.190 +The required new package cannot be installed because it
1.191 +conflicts with some already installed package.
1.192 +
1.193 +=item UNDEF
1.194 +
1.195 +The package has an invalid or ambiguous dependency.
1.196 +
1.197 +=back
1.198 +
1.199 +=item B<-S>
1.200 +
1.201 +Similar to option "B<-s>" but also lists the newest versions in the
1.202 +repository. The following I<tag> might appear in the map:
1.203 +
1.204 +=over 10
1.205 +
1.206 +=item NEW
1.207 +
1.208 +The package exists in the repository but is not required yet.
1.209 +
1.210 +=back
1.211 +
1.212 +=item B<-M>
1.213 +
1.214 +Similar to option "B<-s>" but print a short dependency map.
1.215 +
1.216 +=item B<-L>
1.217 +
1.218 +Print a list of packages in the repository that depend on the target.
1.219 +
1.220 +=item B<-W>
1.221 +
1.222 +Include all conditional dependencies as if all possible configuration
1.223 +options had been switched on. This has little use in practice except for
1.224 +generating an all-inclusive list with option "B<-L>". I<ATTENTION: Even
1.225 +mutually exclusive options are evaluated to be 'on', building packages
1.226 +with option "-W" therefore might fail or cause unusable results!>
1.227 +
1.228 +=item B<-X>
1.229 +
1.230 +Use the slower but more robust external Perl XML parser module
1.231 +XML::Simple instead of the simple internal XML/RDF parser.
1.232 +
1.233 +=item B<-K>
1.234 +
1.235 +Keep packages that were installed temporarily during the build process.
1.236 +Without this option those packages are removed.
1.237 +
1.238 +=item B<-k>
1.239 +
1.240 +Keep packages that were downloaded temporarily for installation or building.
1.241 +Without this option those packages are removed.
1.242 +
1.243 +=item B<-e>
1.244 +
1.245 +Rebuild exact version of a package from repository even when you have
1.246 +installed a newer version from another repository.
1.247 +
1.248 +=item B<-b>
1.249 +
1.250 +Wrap package rebuilding commands with script execution-time checks for
1.251 +existing binary packages if the package is rebuild as a dependency. Wrap
1.252 +package install commands with script execution-time checks for different
1.253 +MD5 signature checksums of binary packages and installed packages. This
1.254 +is best to use with option "B<-u>" to defer all such checks until script
1.255 +execution-time.
1.256 +
1.257 +=item B<-B>
1.258 +
1.259 +Same as option "B<-b>" but also check all explicit target packages for
1.260 +existing binary packages at script execution-time.
1.261 +
1.262 +=item B<-g>
1.263 +
1.264 +The generated script will rebuild all packages selected even when the
1.265 +most recent version is already installed. Dependencies are not affected.
1.266 +Use this especially for updating a package with different build options
1.267 +(see option "B<-D>").
1.268 +
1.269 +=item B<-P> I<priv-cmd>
1.270 +
1.271 +Command prefix to use for generated script commands that require
1.272 +elevated privileges (like "B<openpkg rpm -Uvh>"). The most common tool
1.273 +for this is sudo(8). If I<priv-cmd> starts with a dash it will be run
1.274 +without the dash and the command line it should execute is passed as
1.275 +a single quoted string. Use this option for upgrading privileges. For
1.276 +instance, if you are running the C<openpkg build>" command as the
1.277 +management user, use "C<-P sudo>" to make sure that the "B<openpkg rpm
1.278 +-Uvh>" commands in the generated script execute with necessary elevated
1.279 +privileges.
1.280 +
1.281 +=item B<-N> I<non-priv-cmd>
1.282 +
1.283 +Command prefix to use for generated script commands that do I<not>
1.284 +require elevated privileges (like "B<openpkg rpm --rebuild>"). The most
1.285 +common tool for this is su(8). If I<non-priv-cmd> starts with a dash
1.286 +it will be run without the dash and the command line it should execute
1.287 +is passed as a single quoted string. Use this option for downgrading
1.288 +privileges. For instance, if you are running the C<openpkg build>"
1.289 +command as the B<root> user, use "C<-N '-su - >I<musr>C< -c'>" to make
1.290 +sure that the non-privileged commands in the generated script execute
1.291 +with privileges of the management user I<musr>.
1.292 +
1.293 +=item B<-p> I<platform>
1.294 +
1.295 +The platform string that is matched against the XML/RDF index for binary
1.296 +packages. The default is an empty I<platform> string so that no binary
1.297 +packages are matched at all.
1.298 +
1.299 +=item B<-D> I<var>=I<val>
1.300 +
1.301 +Specify build options for selected packages. This can be either
1.302 +"B<-D> I<with_xxx>=I<yyy>" or just "B<-D> I<with_xxx>". The latter is
1.303 +equivalent to a "B<-D> I<with_xxx>=I<yes>". The parameters are matched
1.304 +against selected packages that are already installed. If they do
1.305 +indicate a change, the package is rebuild. There can be multiple "B<-D>"
1.306 +options.
1.307 +
1.308 +If the option name is prefixed with a package name followed by
1.309 +two colons then it applies only to the specified package, e.g.,
1.310 +"B<-D>I<foo::with_bar>".
1.311 +
1.312 +=item B<-E> I<name>
1.313 +
1.314 +Ignore a package with the specified I<name>. This can be used to avoid
1.315 +upgrading to a broken package in the repository or to skip a package
1.316 +upgrade temporarily. If you use a wildcard pattern or the options
1.317 +"B<-a>" or "B<-A>" then I<name> will be excluded. There can be multiple
1.318 +"B<-E>" options.
1.319 +
1.320 +=item B<-H> I<name>
1.321 +
1.322 +Hint about packages that should be preferred when more than one fits
1.323 +a requirement. There can be multiple "B<-H>" options.
1.324 +
1.325 +=item B<-a>
1.326 +
1.327 +Select all installed packages. You cannot specify a pattern list together
1.328 +with the "B<-a>" option.
1.329 +
1.330 +=item B<-A>
1.331 +
1.332 +Select all packages in the repository. You cannot specify a pattern list
1.333 +together with the "B<-A>" option.
1.334 +
1.335 +=back
1.336 +
1.337 +=head1 ARGUMENTS
1.338 +
1.339 +In case neither option B<-a> nor option B<-A> are specified,
1.340 +the command line has to contain one or more package I<pattern>
1.341 +arguments. Each I<pattern> can have the following forms:
1.342 +
1.343 +=over 4
1.344 +
1.345 +=item I<name>
1.346 +
1.347 +A regular package name.
1.348 +
1.349 +=item I<name>B<*>
1.350 +
1.351 +A package name wildcard pattern.
1.352 +
1.353 +=item I<name>B<,>I<name>[B<->I<version>[B<->I<release>]]
1.354 +
1.355 +A regular package name followed by a constraint
1.356 +which particular package should be chosen.
1.357 +
1.358 +=back
1.359 +
1.360 +=head1 CONFIGURATION
1.361 +
1.362 +B<openpkg build> reads the configuration file F<$HOME/.openpkg/build>.
1.363 +The file lists default options, one option per line and section tags
1.364 +of the form C<[>I<prefix>C<]>. Options following such a tag are only
1.365 +evaluated for the particular B<OpenPKG> instance so that you can
1.366 +define default options for multiple B<OpenPKG> instances.
1.367 +
1.368 +Example:
1.369 +
1.370 + # global options
1.371 + -X
1.372 +
1.373 + [/openpkg/current]
1.374 + # options for CURRENT stack only
1.375 + -r http://download.openpkg.org/stacks/current/source/
1.376 +
1.377 + [/openpkg/foo]
1.378 + # options for a FOO stack only
1.379 + -r http://download.openpkg.org/stacks/foo/source/
1.380 +
1.381 +=head1 EXAMPLES
1.382 +
1.383 +The following shows a few typical OpenPKG instance
1.384 +maintenance tasks which involve the B<openpkg build> command:
1.385 +
1.386 +=head2 Installation
1.387 +
1.388 +The following examples shows how to initially install an OpenPKG
1.389 +instance under F</openpkg> with Apache/PHP & MySQL:
1.390 +
1.391 + # bootstrap the OpenPKG instance
1.392 + $ curl -L -O http://openpkg.org/go/download/openpkg.src.sh
1.393 + $ sh openpkg-*-*.src.sh --prefix=/openpkg \
1.394 + --user=openpkg --group=openpkg --tag=openpkg
1.395 + $ sh openpkg-*-*.*-*-openpkg.sh
1.396 +
1.397 + # install Apache/PHP & MySQL
1.398 + $ /openpkg/bin/openpkg build \
1.399 + -D apache-php::with_mysql=yes \
1.400 + apache apache-php mysql | sh
1.401 +
1.402 +=head2 Reinstallation
1.403 +
1.404 +The following example shows how to rebuild and reinstall the already
1.405 +installed package "foo":
1.406 +
1.407 + # rebuild and reinstall package
1.408 + $ /openpkg/bin/openpkg build -g -u foo | sh
1.409 +
1.410 +=head2 Change
1.411 +
1.412 +The following fictive example shows how to change the already
1.413 +installed package "foo" by rebuilding and reinstalling it with the
1.414 +"C<foo::with_bar>" build-time option enabled.
1.415 +
1.416 + # change a package
1.417 + $ /openpkg/bin/openpkg build -g -D with_bar=yes foo | sh
1.418 +
1.419 +=head2 Update
1.420 +
1.421 +The following example shows how to update (no major
1.422 +OpenPKG version change) an OpenPKG instance under F</openpkg>:
1.423 +
1.424 + # update all packages to their latest version
1.425 + $ /openpkg/bin/openpkg build -Ua | sh
1.426 +
1.427 +=head2 Upgrade
1.428 +
1.429 +The following examples shows a complete procedure for upgrading (major
1.430 +OpenPKG version change) the instance under F</openpkg> to OpenPKG
1.431 +4.X:
1.432 +
1.433 + # upgrade the bootstrap package
1.434 + $ /openpkg/bin/openpkg build \
1.435 + -r http://download.openpkg.org/stacks/current/source/ openpkg | sh
1.436 +
1.437 + # upgrade the whole OpenPKG instance, in correct dependency
1.438 + # order and by keeping all chosen build-time options.
1.439 + $ /openpkg/bin/openpkg build -ZaKB | sh
1.440 +
1.441 +=head2 Deinstallation
1.442 +
1.443 +The following example shows how to deinstall
1.444 +an entire OpenPKG intance under F</openpkg>:
1.445 +
1.446 + # remove all packages and the instance itself
1.447 + $ /openpkg/bin/openpkg rpm -e \
1.448 + `/openpkg/bin/openpkg rpm -qa`
1.449 +
1.450 +=head1 CAVEATS
1.451 +
1.452 +Parallel execution of B<openpkg build> causes undefined effects.
1.453 +
1.454 +=head1 HISTORY
1.455 +
1.456 +The B<openpkg build> command was invented in November 2002 by I<Michael
1.457 +van Elst> E<lt>mlelstv@serpens.deE<gt> under contract with I<Cable
1.458 +& Wireless> E<lt>http://www.cw.com/E<gt> for use inside the B<OpenPKG>
1.459 +project E<lt>http://www.openpkg.org/E<gt>. It was then further
1.460 +refined by the B<OpenPKG Foundation e.V.> as part of the OpenPKG Tool Chain.
1.461 +
1.462 +=cut
1.463 +
