OpenPKG CVS Repository
http://cvs.openpkg.org/
____________________________________________________________________________
Server: cvs.openpkg.org Name: Ralf S. Engelschall
Root: /v/openpkg/cvs Email: [EMAIL PROTECTED]
Module: openpkg-tools Date: 27-Jun-2006 18:04:50
Branch: HEAD Handle: 2006062717044900
Modified files:
openpkg-tools/cmd build.pl
Log:
major overhaul of the 'openpkg build' manual page
Summary:
Revision Changes Path
1.21 +186 -94 openpkg-tools/cmd/build.pl
____________________________________________________________________________
patch -p0 <<'@@ .'
Index: openpkg-tools/cmd/build.pl
============================================================================
$ cvs diff -u -r1.20 -r1.21 build.pl
--- openpkg-tools/cmd/build.pl 27 Jun 2006 13:15:33 -0000 1.20
+++ openpkg-tools/cmd/build.pl 27 Jun 2006 16:04:49 -0000 1.21
@@ -2501,7 +2501,7 @@
=head1 NAME
-B<openpkg build> - B<OpenPKG> Maintenance Tool (Building)
+B<openpkg build> - B<OpenPKG> Maintenance Tool
=head1 SYNOPSIS
@@ -2538,18 +2538,26 @@
=head1 DESCRIPTION
The B<openpkg build> tool provides automated recursive from-scratch
-installation and updating of existing RPM packages (B<openpkg build>).
-It writes a shell script to standard output that installs or upgrades
-software packages including all dependencies. Packages that are upgraded
-automatically trigger rebuilds of all packages that depend on the
-upgraded package ("reverse dependencies"). The dependency information is
-read from an index generated by B<openpkg index>.
+installation of packages and the updating and upgrading of installed
+packages.
+
+It generates a Bourne-Shell script on standard output (F<stdout>)
+that can be executed to perform the package installation or
+updating/upgrading procedure for all requested packages and their
+dependencies.
+
+Packages that are upgraded automatically trigger rebuilds of all
+packages that depend on the upgraded package ("reverse dependencies").
+The dependency information is read from an XML/RDF index generated by
+the companion tool B<openpkg index>.
+
+=head1 ARGUMENTS
Packages are selected by providing a list of name patterns. Each
-pattern is either a package name or a prefix followed by a '*'
-character. Additionally you can append a discrimination prefix separated
-by a comma that matches against the full name-version-revision
-string.
+pattern is either a package name or a name prefix followed by a 'F<*>'
+character. Additionally, in order to resolve ambiguous dependencies, you
+can append a discrimination prefix separated by a comma that matches
+against the full "I<name>-I<version>-I<revision>" string of a package.
=head1 OPTIONS
@@ -2557,24 +2565,26 @@
=over 4
-=item B<-R> I<rpm>
+=item B<-R> I<command>
-Specify a path to the installed B<OpenPKG> C<rpm> command. Several
-other internal paths are deduced from the I<rpm> path, so this should be
-something like "I<%{l_prefix}>C</bin/openpkg rpm>".
+Specify the "B<openpkg rpm>" command with fully qualified path.
+Several other internal paths are deduced from the I<command> path,
+so this should be something like "I<prefix>C</bin/openpkg rpm>".
=item B<-r> I<repository>
-Specify a path to an RPM repository, this can be a URL or a directory
+Specify the path to an OpenPKG RPM package repository. This can be a URL or
a directory
path. The name of the package file is appended to this path.
-The default is to use a URL pointing to the B<OpenPKG> FTP server.
+The default is to use a URL pointing to the B<OpenPKG> FTP server
+as determined by the "B<openpkg release>" command.
=item B<-f> I<index.rdf>
-Specify a path to the primary XML/RDF index, this can be a URL or a
-file path. If the index contains references to other indexes these are
-included automatically. The default is to use a URL pointing to the
-B<OpenPKG> FTP server for the B<OpenPKG> release you are using.
+Specify the path to the primary XML/RDF index. This can be a URL or a
+file path. If the index contains references to other indices, these
+are recursively included automatically. The default is to use a URL
+pointing to the B<OpenPKG> FTP server as as determined by the "B<openpkg
+release>" command.
=item B<-u>
@@ -2585,7 +2595,8 @@
=item B<-U>
The generated script will try to upgrade all selected packages
-including their dependencies to the most recent version.
+including their dependencies to the most recent version. Use
+this for usual upgrade tasks in combination with option "B<-a>".
=item B<-z>
@@ -2596,7 +2607,7 @@
=item B<-Z>
B<openpkg build> ignores all installed packages, the
-script will rebuild all selected packages from scratch.
+generated script will rebuild all selected packages from scratch.
=item B<-i>
@@ -2605,19 +2616,22 @@
=item B<-q>
-Ignore all reverse dependencies.
-I<ATTENTION: this might break already installed packages!>
+Ignore all reverse dependencies. This means that all packages which are
+rebuild do I<not> trigger a rebuild of packages which depend on them.
+I<ATTENTION: this might break already installed packages and has to be
+used with care! You should really know what you are doing.>
=item B<-s>
-Print a status map instead of the install script. The map consists
-of 3 columns: "old", "tag" and "new". "old" shows the installed
-version of a package or just the package name if no package of
-that name is installed and "new" shows the repository version
-of a package if it is considered for installation. "tag" has the
-following possible values:
+Generate a status map instead of the shell script. The map consists
+of 3 columns: I<old>, I<tag> and I<new>. The I<old> column shows
+the installed version of a package (I<name>-I<version>-I<release>)
+or just the package name (I<name>) if no package of that name
+is installed and the I<new> column shows the repository version
+(I<name>-I<version>-I<release>) of a package if it is considered for
+installation. The I<tag> column shows the following possible values:
-=over 4
+=over 10
=item OK
@@ -2634,7 +2648,7 @@
=item DEPEND
The installed package needs rebuilding because one of its
-dependencies is rebuilt.
+dependencies is rebuild.
=item MISMATCH
@@ -2654,20 +2668,20 @@
=item B<-S>
-Similar to B<-s> but also lists the newest versions in the
-repository. The following tag might appear in the map.
+Similar to option "B<-s>" but also lists the newest versions in the
+repository. The following I<tag> might appear in the map:
-=over 4
+=over 10
=item NEW
-The package exists in the repository but isn't required yet.
+The package exists in the repository but is not required yet.
=back
=item B<-M>
-Similar to B<-s> but print a short dependency map.
+Similar to option "B<-s>" but print a short dependency map.
=item B<-L>
@@ -2676,127 +2690,205 @@
=item B<-W>
Include all conditional dependencies as if all possible configuration
-options had been switched on. This has little use except for generating
-an all-inclusive list with the B<-L> option.
-I<ATTENTION: Even mutually exclusive options are evaluated to be 'on',
-building packages with B<-W> therefore might fail or cause unusable
-results!>
+options had been switched on. This has little use in practice except for
+generating an all-inclusive list with option "B<-L>". I<ATTENTION: Even
+mutually exclusive options are evaluated to be 'on', building packages
+with option "-W" therefore might fail or cause unusable results!>
=item B<-X>
-Ignore an installed XML parser module but use the internal
-simple text parser instead.
+Ignore an installed Perl XML parser module and use the internal
+simple XML/RDF parser instead.
=item B<-K>
Keep packages that were installed temporarily during the build process.
+Without this option those packages are removed.
=item B<-e>
-Rebuild exact version from repository even when you have installed
-a newer version from another repository.
+Rebuild exact version of a package from repository even when you have
+installed a newer version from another repository.
=item B<-b>
-Wrap rebuild commands with build-time check for existing binary packages
-if the package is rebuilt as a dependency. Wrap install commands with a
-build/install-time check for different MD5 signature checksum of binary
-package and installed package. This is best to use with B<-u> to defer
-all such checks until build-time.
+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
+MD5 signature checksums of binary packages and installed packages. This
+is best to use with option "B<-u>" to defer all such checks until script
+execution-time.
=item B<-B>
-Same as -b but also check all packages for existing binary packages
-at run-time.
+Same as option "B<-b>" but also check all packages for existing binary
+packages at script execution-time.
=item B<-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 "B<-D>").
=item B<-P> I<priv-cmd>
-Command prefix to use for install commands that require elevated
-privileges. The most common tool for this is sudo(8). If I<priv-cmd>
-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.
+Command prefix to use for generated script commands that require
+elevated privileges (like "B<openpkg rpm -Uvh>"). The most common tool
+for this is sudo(8). If I<priv-cmd> 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 C<openpkg build>" command as the
+management user, use "C<-P sudo>" to make sure that the "B<openpkg rpm
+-Uvh>" commands in the generated script execute with necessary elevated
+privileges.
=item B<-N> I<non-priv-cmd>
-Command prefix to use for install commands that do not require elevated
-privileges. The most common tool for this is sudo(8). If I<priv-cmd>
-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.
+Command prefix to use for generated script commands that do I<not>
+require elevated privileges (like "B<openpkg rpm --rebuild>"). The most
+common tool for this is su(8). If I<non-priv-cmd> 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 C<openpkg build>"
+command as the B<root> user, use "C<-N '-su - >I<musr>C< -c'>" to make
+sure that the non-privileged commands in the generated script execute
+with privileges of the management user I<musr>.
=item B<-p> I<platform>
-The platform string that is matched against the index for binary
-packages. Default is an empty string so that no binary packages
-are matched.
+The platform string that is matched against the XML/RDF index for binary
+packages. The default is an empty I<platform> string so that no binary
+packages are matched at all.
=item B<-D>I<var>=I<val>
-Specify configuration options for selected packages. This can be
-either B<-D>I<with_xxx>=I<yyy> or just B<-D>I<with_xxx>, the
-latter is equivalent to a B<-D>I<with_xxx>=I<yes>. 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
-B<-D> options.
-
-If the option name is prefixed with a package name followed by two colons
-then it applies only to the specified package. E.g.
B<-D>I<gcc::with_binutils>.
+Specify build options for selected packages. This can be either
+"B<-D>I<with_xxx>=I<yyy>" or just "B<-D>I<with_xxx>". The latter is
+equivalent to a "B<-D>I<with_xxx>=I<yes>". 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 "B<-D>"
+options.
+
+If the option name is prefixed with a package name followed by
+two colons then it applies only to the specified package, e.g.,
+"B<-D>I<foo::with_bar>".
=item B<-E> I<name>
Ignore a package with the specified I<name>. This can be used to avoid
-upgrading to a broken package in the repository. If you use a
-wildcard pattern or the B<-a> or B<-A> options then I<name> will not
-be selected. There can be multiple B<-E> options.
+upgrading to a broken package in the repository or to skip a package
+upgrade temporarily. If you use a wildcard pattern or the options
+"B<-a>" or "B<-A>" then I<name> will be excluded. There can be multiple
+"B<-E>" options.
=item B<-H> I<name>
Hint about packages that should be preferred when more than one fits
-a requirement. There can be multiple B<-E> options.
+a requirement. There can be multiple "B<-H>" options.
=item B<-a>
Select all installed packages. You cannot specify a pattern list together
-with the B<-a> option.
+with the "B<-a>" option.
=item B<-A>
Select all packages in the repository. You cannot specify a pattern list
-together with the B<-A> option.
+together with the "B<-A>" option.
=back
=head1 CONFIGURATION
-B<openpkg build> reads the configuration file I<$HOME/.openpkg/build>.
+B<openpkg build> reads the configuration file F<$HOME/.openpkg/build>.
The file lists default options, one option per line and section tags
-of the form C<[>I<prefix>C<]>. Options following such a tag are only
-evaluated if the selected RPM path matches the prefix so that you can
-define default options for multiple B<OpenPKG> hierarchies.
+of the form C<[>I<rpm>C<]>. Options following such a tag are only
+evaluated if the selected RPM command matches I<rpm> so that you can
+define default options for multiple B<OpenPKG> instances.
-=head1 CAVEATS
+Example:
-Parallel execution of B<openpkg build> causes undefined effects.
+ [/openpkg/openpkg rpm]
+ -X
+ -P sudo
+
+=head1 EXAMPLES
+
+The following shows a few typical OpenPKG instance
+maintenance tasks which involve the B<openpkg build> command:
+
+=head2 Installation
+
+The following examples shows how to initially install an OpenPKG
+instance under F</openpkg> with Apache/PHP & MySQL:
+
+ # bootstrap the OpenPKG instance
+ $ ftp ftp.openpkg.org
+ ftp> cd release/2.X/SRC
+ ftp> get openpkg-2.X.0-2.X.0.src.sh
+ ftp> bye
+ $ sh openpkg-2.X.0-2.X.0.src.sh --prefix=/openpkg \
+ --user=openpkg --group=openpkg --tag=openpkg
+ $ sh openpkg-2.X.0-2.X.0.*-*-openpkg.sh
+
+ # install the OpenPKG Tool Chain
+ # (includes "openpkg build" command)
+ $ /openpkg/bin/openpkg build openpkg-tools | sh
+
+ # install Apache/PHP & MySQL
+ $ /openpkg/bin/openpkg build \
+ -Dapache::with_mod_php=yes apache mysql | sh
+
+=head2 Update
-=head1 SEE ALSO
+The following example shows how to update (no major
+OpenPKG version change) an OpenPKG instance under F</openpkg>:
-rpm(8), sudo(8)
+ # update all packages to their latest version
+ $ /openpkg/bin/openpkg build -Ua | sh
+
+=head2 Upgrade
+
+The following examples shows a complete procedure for upgrading (major
+OpenPKG version change) the an instance under F</openpkg> to OpenPKG
+2.X:
+
+ # upgrade the bootstrap package
+ $ /openpkg/bin/openpkg rpm --rebuild \
+ ftp://ftp.openpkg.org/release/2.X/SRC/openpkg-2.X.0-2.X.0.src.rpm
+ $ /openpkg/bin/openpkg rpm -Uvh \
+ /openpkg/RPM/PKG/openpkg-2.X.0-2.X.0.*.rpm
+
+ # upgrade OpenPKG Tool Chain
+ # (includes latest "openpkg build" command!)
+ $ /openpkg/bin/openpkg rpm -e openpkg-tools
+ $ /openpkg/bin/openpkg build openpkg-tools | sh
+
+ # upgrade the whole OpenPKG instance, in correct dependency
+ # order and by keeping all chosen build-time options.
+ $ /openpkg/bin/openpkg build -ZaKB | sh
+
+=head2 Deinstallation
+
+The following example shows how to deinstall
+an entire OpenPKG intance under F</openpkg>:
+
+ # remove all packages and the instance itself
+ $ /openpkg/bin/openpkg rpm -e \
+ `/openpkg/bin/openpkg rpm -qa`
+
+=head1 CAVEATS
+
+Parallel execution of B<openpkg build> causes undefined effects.
=head1 HISTORY
The B<openpkg build> command was invented in November 2002 by I<Michael
van Elst> E<lt>[EMAIL PROTECTED]<gt> under contract with I<Cable
& Wireless> E<lt>http://www.cw.com/E<gt> for use inside the B<OpenPKG>
-project E<lt>http://www.openpkg.org/E<gt>.
-
-=head1 AUTHORS
-
- Michael van Elst
- [EMAIL PROTECTED]
+project E<lt>http://www.openpkg.org/E<gt>. It was then further
+refined by the B<OpenPKG Foundation e.V.> as part of the OpenPKG Tool Chain.
=cut
@@ .
______________________________________________________________________
The OpenPKG Project www.openpkg.org
CVS Repository Commit List openpkg-cvs@openpkg.org
