comparison: openpkg/build.pod
openpkg/build.pod
- changeset 794
- 07be25b95aca
equal
deleted
inserted
replaced
| -1:000000000000 | 0:dd377d258041 |
|---|---|
| 1 ## | |
| 2 ## build.pod -- OpenPKG Package Building and Installing | |
| 3 ## Copyright (c) 2000-2012 OpenPKG GmbH <http://openpkg.com/> | |
| 4 ## | |
| 5 ## This software is property of the OpenPKG GmbH, DE MUC HRB 160208. | |
| 6 ## All rights reserved. Licenses which grant limited permission to use, | |
| 7 ## copy, modify and distribute this software are available from the | |
| 8 ## OpenPKG GmbH. | |
| 9 ## | |
| 10 ## THIS SOFTWARE IS PROVIDED "AS IS" AND ANY EXPRESSED OR IMPLIED | |
| 11 ## WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF | |
| 12 ## MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. | |
| 13 ## IN NO EVENT SHALL THE AUTHORS AND COPYRIGHT HOLDERS AND THEIR | |
| 14 ## CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, | |
| 15 ## SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT | |
| 16 ## LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF | |
| 17 ## USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND | |
| 18 ## ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, | |
| 19 ## OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT | |
| 20 ## OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | |
| 21 ## SUCH DAMAGE. | |
| 22 ## | |
| 23 | |
| 24 =pod | |
| 25 | |
| 26 =head1 NAME | |
| 27 | |
| 28 B<openpkg build> - B<OpenPKG> Package Building and Installing | |
| 29 | |
| 30 =head1 SYNOPSIS | |
| 31 | |
| 32 B<openpkg> | |
| 33 B<build> | |
| 34 [B<-R> I<rpm>] | |
| 35 [B<-r> I<repository>] | |
| 36 [B<-f> I<index.rdf>] | |
| 37 [B<-u>] | |
| 38 [B<-U>] | |
| 39 [B<-z>] | |
| 40 [B<-Z>] | |
| 41 [B<-i>] | |
| 42 [B<-q>] | |
| 43 [B<-s>] | |
| 44 [B<-S>] | |
| 45 [B<-M>] | |
| 46 [B<-L>] | |
| 47 [B<-W>] | |
| 48 [B<-X>] | |
| 49 [B<-K>] | |
| 50 [B<-k>] | |
| 51 [B<-e>] | |
| 52 [B<-b>] | |
| 53 [B<-B>] | |
| 54 [B<-G>] | |
| 55 [B<-P> I<priv-cmd>] | |
| 56 [B<-N> I<non-priv-cmd>] | |
| 57 [B<-p> I<platform>] | |
| 58 [B<-D> I<var>=I<val> ...] | |
| 59 [B<-E> I<name> ...] | |
| 60 [B<-H> I<name> ...] | |
| 61 ([B<-a>] [B<-A>] | I<pattern> ...) | |
| 62 | |
| 63 =head1 DESCRIPTION | |
| 64 | |
| 65 The B<openpkg build> tool provides automated recursive from-scratch | |
| 66 installation of packages and the updating and upgrading of installed | |
| 67 packages. | |
| 68 | |
| 69 It generates a Bourne-Shell script on standard output (F<stdout>) | |
| 70 that can be executed to perform the package installation or | |
| 71 updating/upgrading procedure for all requested packages and their | |
| 72 dependencies. | |
| 73 | |
| 74 Packages that are upgraded automatically trigger rebuilds of all | |
| 75 packages that depend on the upgraded package ("reverse dependencies"). | |
| 76 The dependency information is read from an XML/RDF index generated by | |
| 77 the companion tool B<openpkg index>. | |
| 78 | |
| 79 =head1 ARGUMENTS | |
| 80 | |
| 81 Packages are selected by providing a list of name patterns. Each | |
| 82 pattern is either a package name or a name prefix followed by a 'F<*>' | |
| 83 character. Additionally, in order to resolve ambiguous dependencies, you | |
| 84 can append a discrimination prefix separated by a comma that matches | |
| 85 against the full "I<name>-I<version>-I<revision>" string of a package. | |
| 86 | |
| 87 =head1 OPTIONS | |
| 88 | |
| 89 The following command line options exist: | |
| 90 | |
| 91 =over 4 | |
| 92 | |
| 93 =item B<-R> I<command> | |
| 94 | |
| 95 Specify the "B<openpkg rpm>" command with fully qualified path. | |
| 96 Several other internal paths are deduced from the I<command> path, | |
| 97 so this has to be something like "I<prefix>C</bin/openpkg rpm>". | |
| 98 | |
| 99 =item B<-r> I<repository> | |
| 100 | |
| 101 Specify the path to an OpenPKG RPM package repository. | |
| 102 This can be a URL (including "file://") to download packages from or | |
| 103 an absolute directory path (identified by leading "/") or | |
| 104 a relative directory path (identified by leading "./") to access packages directly. | |
| 105 The name of the package file is appended to this path. | |
| 106 The default is to use a URL pointing to the B<OpenPKG> download service | |
| 107 as determined by the "B<openpkg release>" command. | |
| 108 | |
| 109 =item B<-f> I<index.rdf> | |
| 110 | |
| 111 Specify the path to the primary XML/RDF index. This can be a URL or a | |
| 112 file path. If the index contains references to other indices, these | |
| 113 are recursively included automatically. The default is to use a URL | |
| 114 pointing to the B<OpenPKG> FTP server as as determined by the "B<openpkg | |
| 115 release>" command. | |
| 116 | |
| 117 =item B<-u> | |
| 118 | |
| 119 The generated script will ignore binary RPMs that are stored on | |
| 120 your system. Instead it will either fetch binary RPMs or rebuild | |
| 121 from source RPMs fetched from the repository. | |
| 122 | |
| 123 =item B<-U> | |
| 124 | |
| 125 The generated script will try to upgrade all selected packages | |
| 126 including their dependencies to the most recent version. Use | |
| 127 this for usual upgrade tasks in combination with option "B<-a>". | |
| 128 | |
| 129 =item B<-z> | |
| 130 | |
| 131 The generated script will rebuild all selected packages | |
| 132 including their dependencies even when the most recent version | |
| 133 is already installed. | |
| 134 | |
| 135 =item B<-Z> | |
| 136 | |
| 137 B<openpkg build> ignores all installed packages, the | |
| 138 generated script will rebuild all selected packages from scratch. | |
| 139 | |
| 140 =item B<-i> | |
| 141 | |
| 142 The generated script will ignore run-time errors. | |
| 143 | |
| 144 =item B<-q> | |
| 145 | |
| 146 Ignore all reverse dependencies. This means that all packages which are | |
| 147 rebuild do I<not> trigger a rebuild of packages which depend on them. | |
| 148 I<ATTENTION: this might break already installed packages and has to be | |
| 149 used with care! You should really know what you are doing.> | |
| 150 | |
| 151 =item B<-s> | |
| 152 | |
| 153 Generate a status map instead of the shell script. The map consists | |
| 154 of 3 columns: I<old>, I<tag> and I<new>. The I<old> column shows | |
| 155 the installed version of a package (I<name>-I<version>-I<release>) | |
| 156 or just the package name (I<name>) if no package of that name | |
| 157 is installed and the I<new> column shows the repository version | |
| 158 (I<name>-I<version>-I<release>) of a package if it is considered for | |
| 159 installation. The I<tag> column shows the following possible values: | |
| 160 | |
| 161 =over 10 | |
| 162 | |
| 163 =item OK | |
| 164 | |
| 165 The installed package is suitable and will not be touched. | |
| 166 | |
| 167 =item ADD | |
| 168 | |
| 169 There is no installed package yet. | |
| 170 | |
| 171 =item UPGRADE | |
| 172 | |
| 173 The installed package is outdated and requires an update. | |
| 174 | |
| 175 =item DEPEND | |
| 176 | |
| 177 The installed package needs rebuilding because one of its | |
| 178 dependencies is rebuild. | |
| 179 | |
| 180 =item MISMATCH | |
| 181 | |
| 182 The installed package needs rebuilding because it was build | |
| 183 with different parameters. | |
| 184 | |
| 185 =item CONFLICT | |
| 186 | |
| 187 The required new package cannot be installed because it | |
| 188 conflicts with some already installed package. | |
| 189 | |
| 190 =item UNDEF | |
| 191 | |
| 192 The package has an invalid or ambiguous dependency. | |
| 193 | |
| 194 =back | |
| 195 | |
| 196 =item B<-S> | |
| 197 | |
| 198 Similar to option "B<-s>" but also lists the newest versions in the | |
| 199 repository. The following I<tag> might appear in the map: | |
| 200 | |
| 201 =over 10 | |
| 202 | |
| 203 =item NEW | |
| 204 | |
| 205 The package exists in the repository but is not required yet. | |
| 206 | |
| 207 =back | |
| 208 | |
| 209 =item B<-M> | |
| 210 | |
| 211 Similar to option "B<-s>" but print a short dependency map. | |
| 212 | |
| 213 =item B<-L> | |
| 214 | |
| 215 Print a list of packages in the repository that depend on the target. | |
| 216 | |
| 217 =item B<-W> | |
| 218 | |
| 219 Include all conditional dependencies as if all possible configuration | |
| 220 options had been switched on. This has little use in practice except for | |
| 221 generating an all-inclusive list with option "B<-L>". I<ATTENTION: Even | |
| 222 mutually exclusive options are evaluated to be 'on', building packages | |
| 223 with option "-W" therefore might fail or cause unusable results!> | |
| 224 | |
| 225 =item B<-X> | |
| 226 | |
| 227 Use the slower but more robust external Perl XML parser module | |
| 228 XML::Simple instead of the simple internal XML/RDF parser. | |
| 229 | |
| 230 =item B<-K> | |
| 231 | |
| 232 Keep packages that were installed temporarily during the build process. | |
| 233 Without this option those packages are removed. | |
| 234 | |
| 235 =item B<-k> | |
| 236 | |
| 237 Keep packages that were downloaded temporarily for installation or building. | |
| 238 Without this option those packages are removed. | |
| 239 | |
| 240 =item B<-e> | |
| 241 | |
| 242 Rebuild exact version of a package from repository even when you have | |
| 243 installed a newer version from another repository. | |
| 244 | |
| 245 =item B<-b> | |
| 246 | |
| 247 Wrap package rebuilding commands with script execution-time checks for | |
| 248 existing binary packages if the package is rebuild as a dependency. Wrap | |
| 249 package install commands with script execution-time checks for different | |
| 250 MD5 signature checksums of binary packages and installed packages. This | |
| 251 is best to use with option "B<-u>" to defer all such checks until script | |
| 252 execution-time. | |
| 253 | |
| 254 =item B<-B> | |
| 255 | |
| 256 Same as option "B<-b>" but also check all explicit target packages for | |
| 257 existing binary packages at script execution-time. | |
| 258 | |
| 259 =item B<-g> | |
| 260 | |
| 261 The generated script will rebuild all packages selected even when the | |
| 262 most recent version is already installed. Dependencies are not affected. | |
| 263 Use this especially for updating a package with different build options | |
| 264 (see option "B<-D>"). | |
| 265 | |
| 266 =item B<-P> I<priv-cmd> | |
| 267 | |
| 268 Command prefix to use for generated script commands that require | |
| 269 elevated privileges (like "B<openpkg rpm -Uvh>"). The most common tool | |
| 270 for this is sudo(8). If I<priv-cmd> starts with a dash it will be run | |
| 271 without the dash and the command line it should execute is passed as | |
| 272 a single quoted string. Use this option for upgrading privileges. For | |
| 273 instance, if you are running the C<openpkg build>" command as the | |
| 274 management user, use "C<-P sudo>" to make sure that the "B<openpkg rpm | |
| 275 -Uvh>" commands in the generated script execute with necessary elevated | |
| 276 privileges. | |
| 277 | |
| 278 =item B<-N> I<non-priv-cmd> | |
| 279 | |
| 280 Command prefix to use for generated script commands that do I<not> | |
| 281 require elevated privileges (like "B<openpkg rpm --rebuild>"). The most | |
| 282 common tool for this is su(8). If I<non-priv-cmd> starts with a dash | |
| 283 it will be run without the dash and the command line it should execute | |
| 284 is passed as a single quoted string. Use this option for downgrading | |
| 285 privileges. For instance, if you are running the C<openpkg build>" | |
| 286 command as the B<root> user, use "C<-N '-su - >I<musr>C< -c'>" to make | |
| 287 sure that the non-privileged commands in the generated script execute | |
| 288 with privileges of the management user I<musr>. | |
| 289 | |
| 290 =item B<-p> I<platform> | |
| 291 | |
| 292 The platform string that is matched against the XML/RDF index for binary | |
| 293 packages. The default is an empty I<platform> string so that no binary | |
| 294 packages are matched at all. | |
| 295 | |
| 296 =item B<-D> I<var>=I<val> | |
| 297 | |
| 298 Specify build options for selected packages. This can be either | |
| 299 "B<-D> I<with_xxx>=I<yyy>" or just "B<-D> I<with_xxx>". The latter is | |
| 300 equivalent to a "B<-D> I<with_xxx>=I<yes>". The parameters are matched | |
| 301 against selected packages that are already installed. If they do | |
| 302 indicate a change, the package is rebuild. There can be multiple "B<-D>" | |
| 303 options. | |
| 304 | |
| 305 If the option name is prefixed with a package name followed by | |
| 306 two colons then it applies only to the specified package, e.g., | |
| 307 "B<-D>I<foo::with_bar>". | |
| 308 | |
| 309 =item B<-E> I<name> | |
| 310 | |
| 311 Ignore a package with the specified I<name>. This can be used to avoid | |
| 312 upgrading to a broken package in the repository or to skip a package | |
| 313 upgrade temporarily. If you use a wildcard pattern or the options | |
| 314 "B<-a>" or "B<-A>" then I<name> will be excluded. There can be multiple | |
| 315 "B<-E>" options. | |
| 316 | |
| 317 =item B<-H> I<name> | |
| 318 | |
| 319 Hint about packages that should be preferred when more than one fits | |
| 320 a requirement. There can be multiple "B<-H>" options. | |
| 321 | |
| 322 =item B<-a> | |
| 323 | |
| 324 Select all installed packages. You cannot specify a pattern list together | |
| 325 with the "B<-a>" option. | |
| 326 | |
| 327 =item B<-A> | |
| 328 | |
| 329 Select all packages in the repository. You cannot specify a pattern list | |
| 330 together with the "B<-A>" option. | |
| 331 | |
| 332 =back | |
| 333 | |
| 334 =head1 ARGUMENTS | |
| 335 | |
| 336 In case neither option B<-a> nor option B<-A> are specified, | |
| 337 the command line has to contain one or more package I<pattern> | |
| 338 arguments. Each I<pattern> can have the following forms: | |
| 339 | |
| 340 =over 4 | |
| 341 | |
| 342 =item I<name> | |
| 343 | |
| 344 A regular package name. | |
| 345 | |
| 346 =item I<name>B<*> | |
| 347 | |
| 348 A package name wildcard pattern. | |
| 349 | |
| 350 =item I<name>B<,>I<name>[B<->I<version>[B<->I<release>]] | |
| 351 | |
| 352 A regular package name followed by a constraint | |
| 353 which particular package should be chosen. | |
| 354 | |
| 355 =back | |
| 356 | |
| 357 =head1 CONFIGURATION | |
| 358 | |
| 359 B<openpkg build> reads the configuration file F<$HOME/.openpkg/build>. | |
| 360 The file lists default options, one option per line and section tags | |
| 361 of the form C<[>I<prefix>C<]>. Options following such a tag are only | |
| 362 evaluated for the particular B<OpenPKG> instance so that you can | |
| 363 define default options for multiple B<OpenPKG> instances. | |
| 364 | |
| 365 Example: | |
| 366 | |
| 367 # global options | |
| 368 -X | |
| 369 | |
| 370 [/openpkg/current] | |
| 371 # options for CURRENT stack only | |
| 372 -r http://download.openpkg.org/stacks/current/source/ | |
| 373 | |
| 374 [/openpkg/foo] | |
| 375 # options for a FOO stack only | |
| 376 -r http://download.openpkg.org/stacks/foo/source/ | |
| 377 | |
| 378 =head1 EXAMPLES | |
| 379 | |
| 380 The following shows a few typical OpenPKG instance | |
| 381 maintenance tasks which involve the B<openpkg build> command: | |
| 382 | |
| 383 =head2 Installation | |
| 384 | |
| 385 The following examples shows how to initially install an OpenPKG | |
| 386 instance under F</openpkg> with Apache/PHP & MySQL: | |
| 387 | |
| 388 # bootstrap the OpenPKG instance | |
| 389 $ curl -L -O http://openpkg.org/go/download/openpkg.src.sh | |
| 390 $ sh openpkg-*-*.src.sh --prefix=/openpkg \ | |
| 391 --user=openpkg --group=openpkg --tag=openpkg | |
| 392 $ sh openpkg-*-*.*-*-openpkg.sh | |
| 393 | |
| 394 # install Apache/PHP & MySQL | |
| 395 $ /openpkg/bin/openpkg build \ | |
| 396 -D apache-php::with_mysql=yes \ | |
| 397 apache apache-php mysql | sh | |
| 398 | |
| 399 =head2 Reinstallation | |
| 400 | |
| 401 The following example shows how to rebuild and reinstall the already | |
| 402 installed package "foo": | |
| 403 | |
| 404 # rebuild and reinstall package | |
| 405 $ /openpkg/bin/openpkg build -g -u foo | sh | |
| 406 | |
| 407 =head2 Change | |
| 408 | |
| 409 The following fictive example shows how to change the already | |
| 410 installed package "foo" by rebuilding and reinstalling it with the | |
| 411 "C<foo::with_bar>" build-time option enabled. | |
| 412 | |
| 413 # change a package | |
| 414 $ /openpkg/bin/openpkg build -g -D with_bar=yes foo | sh | |
| 415 | |
| 416 =head2 Update | |
| 417 | |
| 418 The following example shows how to update (no major | |
| 419 OpenPKG version change) an OpenPKG instance under F</openpkg>: | |
| 420 | |
| 421 # update all packages to their latest version | |
| 422 $ /openpkg/bin/openpkg build -Ua | sh | |
| 423 | |
| 424 =head2 Upgrade | |
| 425 | |
| 426 The following examples shows a complete procedure for upgrading (major | |
| 427 OpenPKG version change) the instance under F</openpkg> to OpenPKG | |
| 428 4.X: | |
| 429 | |
| 430 # upgrade the bootstrap package | |
| 431 $ /openpkg/bin/openpkg build \ | |
| 432 -r http://download.openpkg.org/stacks/current/source/ openpkg | sh | |
| 433 | |
| 434 # upgrade the whole OpenPKG instance, in correct dependency | |
| 435 # order and by keeping all chosen build-time options. | |
| 436 $ /openpkg/bin/openpkg build -ZaKB | sh | |
| 437 | |
| 438 =head2 Deinstallation | |
| 439 | |
| 440 The following example shows how to deinstall | |
| 441 an entire OpenPKG intance under F</openpkg>: | |
| 442 | |
| 443 # remove all packages and the instance itself | |
| 444 $ /openpkg/bin/openpkg rpm -e \ | |
| 445 `/openpkg/bin/openpkg rpm -qa` | |
| 446 | |
| 447 =head1 CAVEATS | |
| 448 | |
| 449 Parallel execution of B<openpkg build> causes undefined effects. | |
| 450 | |
| 451 =head1 HISTORY | |
| 452 | |
| 453 The B<openpkg build> command was invented in November 2002 by I<Michael | |
| 454 van Elst> E<lt>mlelstv@serpens.deE<gt> under contract with I<Cable | |
| 455 & Wireless> E<lt>http://www.cw.com/E<gt> for use inside the B<OpenPKG> | |
| 456 project E<lt>http://www.openpkg.org/E<gt>. It was then further | |
| 457 refined by the B<OpenPKG Foundation e.V.> as part of the OpenPKG Tool Chain. | |
| 458 | |
| 459 =cut | |
| 460 |
