diff -r 71503088f51b -r f880f219c566 openpkg/build.8 --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/openpkg/build.8 Tue Jul 31 12:23:42 2012 +0200 @@ -0,0 +1,513 @@ +.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.22) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` +. ds C' +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is turned on, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.ie \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. nr % 0 +. rr F +.\} +.el \{\ +. de IX +.. +.\} +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "BUILD 8" +.TH BUILD 8 "OpenPKG" "BUILD(8)" "OpenPKG" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +openpkg build \- OpenPKG Package Building and Installing +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +\&\fBopenpkg\fR +\&\fBbuild\fR +[\fB\-R\fR \fIrpm\fR] +[\fB\-r\fR \fIrepository\fR] +[\fB\-f\fR \fIindex.rdf\fR] +[\fB\-u\fR] +[\fB\-U\fR] +[\fB\-z\fR] +[\fB\-Z\fR] +[\fB\-i\fR] +[\fB\-q\fR] +[\fB\-s\fR] +[\fB\-S\fR] +[\fB\-M\fR] +[\fB\-L\fR] +[\fB\-W\fR] +[\fB\-X\fR] +[\fB\-K\fR] +[\fB\-k\fR] +[\fB\-e\fR] +[\fB\-b\fR] +[\fB\-B\fR] +[\fB\-G\fR] +[\fB\-P\fR \fIpriv-cmd\fR] +[\fB\-N\fR \fInon-priv-cmd\fR] +[\fB\-p\fR \fIplatform\fR] +[\fB\-D\fR \fIvar\fR=\fIval\fR ...] +[\fB\-E\fR \fIname\fR ...] +[\fB\-H\fR \fIname\fR ...] +([\fB\-a\fR] [\fB\-A\fR] | \fIpattern\fR ...) +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +The \fBopenpkg build\fR tool provides automated recursive from-scratch +installation of packages and the updating and upgrading of installed +packages. +.PP +It generates a Bourne-Shell script on standard output (\fIstdout\fR) +that can be executed to perform the package installation or +updating/upgrading procedure for all requested packages and their +dependencies. +.PP +Packages that are upgraded automatically trigger rebuilds of all +packages that depend on the upgraded package (\*(L"reverse dependencies\*(R"). +The dependency information is read from an \s-1XML/RDF\s0 index generated by +the companion tool \fBopenpkg index\fR. +.SH "ARGUMENTS" +.IX Header "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 '\fI*\fR' +character. Additionally, in order to resolve ambiguous dependencies, you +can append a discrimination prefix separated by a comma that matches +against the full "\fIname\fR\-\fIversion\fR\-\fIrevision\fR" string of a package. +.SH "OPTIONS" +.IX Header "OPTIONS" +The following command line options exist: +.IP "\fB\-R\fR \fIcommand\fR" 4 +.IX Item "-R command" +Specify the "\fBopenpkg rpm\fR" command with fully qualified path. +Several other internal paths are deduced from the \fIcommand\fR path, +so this has to be something like "\fIprefix\fR\f(CW\*(C`/bin/openpkg rpm\*(C'\fR". +.IP "\fB\-r\fR \fIrepository\fR" 4 +.IX Item "-r repository" +Specify the path to an OpenPKG \s-1RPM\s0 package repository. +This can be a \s-1URL\s0 (including \*(L"file://\*(R") to download packages from or +an absolute directory path (identified by leading \*(L"/\*(R") or +a relative directory path (identified by leading \*(L"./\*(R") to access packages directly. +The name of the package file is appended to this path. +The default is to use a \s-1URL\s0 pointing to the \fBOpenPKG\fR download service +as determined by the "\fBopenpkg release\fR" command. +.IP "\fB\-f\fR \fIindex.rdf\fR" 4 +.IX Item "-f index.rdf" +Specify the path to the primary \s-1XML/RDF\s0 index. This can be a \s-1URL\s0 or a +file path. If the index contains references to other indices, these +are recursively included automatically. The default is to use a \s-1URL\s0 +pointing to the \fBOpenPKG\fR \s-1FTP\s0 server as as determined by the "\fBopenpkg +release\fR" command. +.IP "\fB\-u\fR" 4 +.IX Item "-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. +.IP "\fB\-U\fR" 4 +.IX Item "-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 "\fB\-a\fR". +.IP "\fB\-z\fR" 4 +.IX Item "-z" +The generated script will rebuild all selected packages +including their dependencies even when the most recent version +is already installed. +.IP "\fB\-Z\fR" 4 +.IX Item "-Z" +\&\fBopenpkg build\fR ignores all installed packages, the +generated script will rebuild all selected packages from scratch. +.IP "\fB\-i\fR" 4 +.IX Item "-i" +The generated script will ignore run-time errors. +.IP "\fB\-q\fR" 4 +.IX Item "-q" +Ignore all reverse dependencies. This means that all packages which are +rebuild do \fInot\fR trigger a rebuild of packages which depend on them. +\&\fI\s-1ATTENTION:\s0 this might break already installed packages and has to be +used with care! You should really know what you are doing.\fR +.IP "\fB\-s\fR" 4 +.IX Item "-s" +Generate a status map instead of the shell script. The map consists +of 3 columns: \fIold\fR, \fItag\fR and \fInew\fR. The \fIold\fR column shows +the installed version of a package (\fIname\fR\-\fIversion\fR\-\fIrelease\fR) +or just the package name (\fIname\fR) if no package of that name +is installed and the \fInew\fR column shows the repository version +(\fIname\fR\-\fIversion\fR\-\fIrelease\fR) of a package if it is considered for +installation. The \fItag\fR column shows the following possible values: +.RS 4 +.IP "\s-1OK\s0" 10 +.IX Item "OK" +The installed package is suitable and will not be touched. +.IP "\s-1ADD\s0" 10 +.IX Item "ADD" +There is no installed package yet. +.IP "\s-1UPGRADE\s0" 10 +.IX Item "UPGRADE" +The installed package is outdated and requires an update. +.IP "\s-1DEPEND\s0" 10 +.IX Item "DEPEND" +The installed package needs rebuilding because one of its +dependencies is rebuild. +.IP "\s-1MISMATCH\s0" 10 +.IX Item "MISMATCH" +The installed package needs rebuilding because it was build +with different parameters. +.IP "\s-1CONFLICT\s0" 10 +.IX Item "CONFLICT" +The required new package cannot be installed because it +conflicts with some already installed package. +.IP "\s-1UNDEF\s0" 10 +.IX Item "UNDEF" +The package has an invalid or ambiguous dependency. +.RE +.RS 4 +.RE +.IP "\fB\-S\fR" 4 +.IX Item "-S" +Similar to option "\fB\-s\fR" but also lists the newest versions in the +repository. The following \fItag\fR might appear in the map: +.RS 4 +.IP "\s-1NEW\s0" 10 +.IX Item "NEW" +The package exists in the repository but is not required yet. +.RE +.RS 4 +.RE +.IP "\fB\-M\fR" 4 +.IX Item "-M" +Similar to option "\fB\-s\fR" but print a short dependency map. +.IP "\fB\-L\fR" 4 +.IX Item "-L" +Print a list of packages in the repository that depend on the target. +.IP "\fB\-W\fR" 4 +.IX Item "-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 "\fB\-L\fR". \fI\s-1ATTENTION:\s0 Even +mutually exclusive options are evaluated to be 'on', building packages +with option \*(L"\-W\*(R" therefore might fail or cause unusable results!\fR +.IP "\fB\-X\fR" 4 +.IX Item "-X" +Use the slower but more robust external Perl \s-1XML\s0 parser module +XML::Simple instead of the simple internal \s-1XML/RDF\s0 parser. +.IP "\fB\-K\fR" 4 +.IX Item "-K" +Keep packages that were installed temporarily during the build process. +Without this option those packages are removed. +.IP "\fB\-k\fR" 4 +.IX Item "-k" +Keep packages that were downloaded temporarily for installation or building. +Without this option those packages are removed. +.IP "\fB\-e\fR" 4 +.IX Item "-e" +Rebuild exact version of a package from repository even when you have +installed a newer version from another repository. +.IP "\fB\-b\fR" 4 +.IX Item "-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 +\&\s-1MD5\s0 signature checksums of binary packages and installed packages. This +is best to use with option "\fB\-u\fR" to defer all such checks until script +execution-time. +.IP "\fB\-B\fR" 4 +.IX Item "-B" +Same as option "\fB\-b\fR" but also check all explicit target packages for +existing binary packages at script execution-time. +.IP "\fB\-g\fR" 4 +.IX Item "-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 "\fB\-D\fR"). +.IP "\fB\-P\fR \fIpriv-cmd\fR" 4 +.IX Item "-P priv-cmd" +Command prefix to use for generated script commands that require +elevated privileges (like "\fBopenpkg rpm \-Uvh\fR"). The most common tool +for this is \fIsudo\fR\|(8). If \fIpriv-cmd\fR 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 \f(CW\*(C`openpkg build\*(C'\fR\*(L" command as the +management user, use \*(R"\f(CW\*(C`\-P sudo\*(C'\fR\*(L" to make sure that the \*(R"\fBopenpkg rpm +\&\-Uvh\fR" commands in the generated script execute with necessary elevated +privileges. +.IP "\fB\-N\fR \fInon-priv-cmd\fR" 4 +.IX Item "-N non-priv-cmd" +Command prefix to use for generated script commands that do \fInot\fR +require elevated privileges (like "\fBopenpkg rpm \-\-rebuild\fR"). The most +common tool for this is \fIsu\fR\|(8). If \fInon-priv-cmd\fR 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 \f(CW\*(C`openpkg build\*(C'\fR" +command as the \fBroot\fR user, use "\f(CW\*(C`\-N \*(Aq\-su \- \*(C'\fR\fImusr\fR\f(CW\*(C` \-c\*(Aq\*(C'\fR" to make +sure that the non-privileged commands in the generated script execute +with privileges of the management user \fImusr\fR. +.IP "\fB\-p\fR \fIplatform\fR" 4 +.IX Item "-p platform" +The platform string that is matched against the \s-1XML/RDF\s0 index for binary +packages. The default is an empty \fIplatform\fR string so that no binary +packages are matched at all. +.IP "\fB\-D\fR \fIvar\fR=\fIval\fR" 4 +.IX Item "-D var=val" +Specify build options for selected packages. This can be either +"\fB\-D\fR \fIwith_xxx\fR=\fIyyy\fR\*(L" or just \*(R"\fB\-D\fR \fIwith_xxx\fR\*(L". The latter is +equivalent to a \*(R"\fB\-D\fR \fIwith_xxx\fR=\fIyes\fR\*(L". 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 \*(R"\fB\-D\fR" +options. +.Sp +If the option name is prefixed with a package name followed by +two colons then it applies only to the specified package, e.g., +"\fB\-D\fR\fIfoo::with_bar\fR". +.IP "\fB\-E\fR \fIname\fR" 4 +.IX Item "-E name" +Ignore a package with the specified \fIname\fR. 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 +"\fB\-a\fR\*(L" or \*(R"\fB\-A\fR" then \fIname\fR will be excluded. There can be multiple +"\fB\-E\fR" options. +.IP "\fB\-H\fR \fIname\fR" 4 +.IX Item "-H name" +Hint about packages that should be preferred when more than one fits +a requirement. There can be multiple "\fB\-H\fR" options. +.IP "\fB\-a\fR" 4 +.IX Item "-a" +Select all installed packages. You cannot specify a pattern list together +with the "\fB\-a\fR" option. +.IP "\fB\-A\fR" 4 +.IX Item "-A" +Select all packages in the repository. You cannot specify a pattern list +together with the "\fB\-A\fR" option. +.SH "ARGUMENTS" +.IX Header "ARGUMENTS" +In case neither option \fB\-a\fR nor option \fB\-A\fR are specified, +the command line has to contain one or more package \fIpattern\fR +arguments. Each \fIpattern\fR can have the following forms: +.IP "\fIname\fR" 4 +.IX Item "name" +A regular package name. +.IP "\fIname\fR\fB*\fR" 4 +.IX Item "name*" +A package name wildcard pattern. +.IP "\fIname\fR\fB,\fR\fIname\fR[\fB\-\fR\fIversion\fR[\fB\-\fR\fIrelease\fR]]" 4 +.IX Item "name,name[-version[-release]]" +A regular package name followed by a constraint +which particular package should be chosen. +.SH "CONFIGURATION" +.IX Header "CONFIGURATION" +\&\fBopenpkg build\fR reads the configuration file \fI\f(CI$HOME\fI/.openpkg/build\fR. +The file lists default options, one option per line and section tags +of the form \f(CW\*(C`[\*(C'\fR\fIprefix\fR\f(CW\*(C`]\*(C'\fR. Options following such a tag are only +evaluated for the particular \fBOpenPKG\fR instance so that you can +define default options for multiple \fBOpenPKG\fR instances. +.PP +Example: +.PP +.Vb 2 +\& # 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/ +.Ve +.SH "EXAMPLES" +.IX Header "EXAMPLES" +The following shows a few typical OpenPKG instance +maintenance tasks which involve the \fBopenpkg build\fR command: +.SS "Installation" +.IX Subsection "Installation" +The following examples shows how to initially install an OpenPKG +instance under \fI/openpkg\fR with Apache/PHP & MySQL: +.PP +.Vb 5 +\& # bootstrap the OpenPKG instance +\& $ curl \-L \-O http://openpkg.org/go/download/openpkg.src.sh +\& $ sh openpkg\-*\-*.src.sh \-\-prefix=/openpkg \e +\& \-\-user=openpkg \-\-group=openpkg \-\-tag=openpkg +\& $ sh openpkg\-*\-*.*\-*\-openpkg.sh +\& +\& # install Apache/PHP & MySQL +\& $ /openpkg/bin/openpkg build \e +\& \-D apache\-php::with_mysql=yes \e +\& apache apache\-php mysql | sh +.Ve +.SS "Reinstallation" +.IX Subsection "Reinstallation" +The following example shows how to rebuild and reinstall the already +installed package \*(L"foo\*(R": +.PP +.Vb 2 +\& # rebuild and reinstall package +\& $ /openpkg/bin/openpkg build \-g \-u foo | sh +.Ve +.SS "Change" +.IX Subsection "Change" +The following fictive example shows how to change the already +installed package \*(L"foo\*(R" by rebuilding and reinstalling it with the +"\f(CW\*(C`foo::with_bar\*(C'\fR" build-time option enabled. +.PP +.Vb 2 +\& # change a package +\& $ /openpkg/bin/openpkg build \-g \-D with_bar=yes foo | sh +.Ve +.SS "Update" +.IX Subsection "Update" +The following example shows how to update (no major +OpenPKG version change) an OpenPKG instance under \fI/openpkg\fR: +.PP +.Vb 2 +\& # update all packages to their latest version +\& $ /openpkg/bin/openpkg build \-Ua | sh +.Ve +.SS "Upgrade" +.IX Subsection "Upgrade" +The following examples shows a complete procedure for upgrading (major +OpenPKG version change) the instance under \fI/openpkg\fR to OpenPKG +4.X: +.PP +.Vb 3 +\& # upgrade the bootstrap package +\& $ /openpkg/bin/openpkg build \e +\& \-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 +.Ve +.SS "Deinstallation" +.IX Subsection "Deinstallation" +The following example shows how to deinstall +an entire OpenPKG intance under \fI/openpkg\fR: +.PP +.Vb 3 +\& # remove all packages and the instance itself +\& $ /openpkg/bin/openpkg rpm \-e \e +\& \`/openpkg/bin/openpkg rpm \-qa\` +.Ve +.SH "CAVEATS" +.IX Header "CAVEATS" +Parallel execution of \fBopenpkg build\fR causes undefined effects. +.SH "HISTORY" +.IX Header "HISTORY" +The \fBopenpkg build\fR command was invented in November 2002 by \fIMichael +van Elst\fR under contract with \fICable +& Wireless\fR for use inside the \fBOpenPKG\fR +project . It was then further +refined by the \fBOpenPKG Foundation e.V.\fR as part of the OpenPKG Tool Chain.