OpenPKG Specs / file revision

 .\" 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 <mlelstv@serpens.de> under contract with \fICable

 & Wireless\fR <http://www.cw.com/> for use inside the \fBOpenPKG\fR

 project <http://www.openpkg.org/>. It was then further

 refined by the \fBOpenPKG Foundation e.V.\fR as part of the OpenPKG Tool Chain.