diff -r 71503088f51b -r f880f219c566 openpkg/openpkg.pod --- a/openpkg/openpkg.pod Tue Jul 31 12:12:54 2012 +0200 +++ b/openpkg/openpkg.pod Tue Jul 31 12:23:42 2012 +0200 @@ -1,14 +1,13 @@ ## ## openpkg -- OpenPKG Tool Chain -## Copyright (c) 2000-2007 OpenPKG Foundation e.V. -## Copyright (c) 2000-2007 Ralf S. Engelschall +## Copyright (c) 2000-2012 OpenPKG GmbH ## -## Permission to use, copy, modify, and distribute this software for -## any purpose with or without fee is hereby granted, provided that -## the above copyright notice and this permission notice appear in all -## copies. +## This software is property of the OpenPKG GmbH, DE MUC HRB 160208. +## All rights reserved. Licenses which grant limited permission to use, +## copy, modify and distribute this software are available from the +## OpenPKG GmbH. ## -## THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED +## THIS SOFTWARE IS PROVIDED "AS IS" AND ANY EXPRESSED OR IMPLIED ## WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF ## MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. ## IN NO EVENT SHALL THE AUTHORS AND COPYRIGHT HOLDERS AND THEIR @@ -28,45 +27,16 @@ =head1 NAME -B -- Cross-Platform Unix Software Packaging Facility +B -- Cross-Platform Unix Software Packaging =head1 SYNOPSIS -=over 4 - -=item Command Line Interface - $ B [I ...] I [I ...] [I ...] $ B B I -=item Project Locations +=head1 DESCRIPTION - http://www.openpkg.org/ web service - http://cvs.openpkg.org/ repository service - http://pgp.openpkg.org/ OpenPGP service - ftp://ftp.openpkg.org/ download service - -=item Project Forums - - petidomo@openpkg.org mailing-list manager - openpkg-announce@openpkg.org project announcements - openpkg-dev@openpkg.org developer forum - openpkg-users@openpkg.org users forum - -=item Local Documentation - - openpkg-rpm(1) RPM package manager - openpkg-rpmbuild(1) RPM package manager (build only) - openpkg-rpm2cpio(1) RPM payload utility - openpkg-rpm-config(1) RPM C API utility - openpkg-lsync(1) local area synchronization - openpkg-rc(1) run-command facility - -=back - -=head1 DESCRIPTION - OpenPKG is the world leading instrument for deployment and maintenance of Open Source software when administration crosses Unix platform boundaries. The OpenPKG project is a collaboration effort with the @@ -82,5 +52,140 @@ scratch the initial state of the whole OpenPKG software packaging system. +=head1 TUTORIAL + +=over 3 + +=item B<1. System Preparation (optional)> + +Before you start, the Unix system optionally should be prepared. Here +especially the necessary disk space requirements of OpenPKG have to be +taken into account. + + # optionally direct /openpkg to at least 150MB free disk space: + $ mkdir /storage/openpkg + $ ln -s /storage/openpkg /openpkg + + # optionally direct temp-directory to at least 250MB free disk space: + $ TMPDIR=/var/tmp + $ export TMPDIR + + # switch to temporary directory: + $ cd $TMPDIR + +=item B<2. Instance Bootstrapping> + +The next step is to bootstrap the OpenPKG instance. Here we are using +the standard /openpkg filesystem prefix. An arbitrary prefix can be +used as long as at least the "Bootstrap From Source" approach is used. + + # download bootstrap source shell package: + $ wget http://openpkg.org/go/download/openpkg.src.sh + + # build bootstrap binary shell package from source shell package: + $ sh openpkg.src.sh \ + --prefix=/openpkg --tag=openpkg \ + --user=openpkg --group=openpkg \ + --tag=openpkg + + # install bootstrap binary script package: + $ sh openpkg-*-*.*-openpkg.sh + +=item B<3. Software Deployment> + +Now you can install arbitrary OpenPKG software packages by either using +the lower-level OpenPKG RPM command or the higher-level OpenPKG tool +chain build command. As a simple illustration example the GNU Bash +package of OpenPKG is installed. + + # build and install GNU Bash: + $ /openpkg/bin/openpkg build bash | sh + +=item B<4. Software Usage> + +Finally, you can use the deployed software. Either through explicit +paths (reasonable if leveraging OpenPKG's multiple-instance feature) or +implicitly by merging the OpenPKG instance into the local environment. + + # explicit usage: + $ /openpkg/bin/bash --version + + # implicit usage (alternatively) + $ eval `/openpkg/bin/openpkg rc --eval all env` + $ bash --version + +=item B<5. Go Ahead!> + +Want to know more now? Please read the manual pages of at least the +deployment commands and then proceed by searching and deploying even +more software into your OpenPKG instance. + + # read manual pages: + $ /openpkg/bin/openpkg man search + $ /openpkg/bin/openpkg man build + + # search for a package + $ /openpkg/bin/openpkg search [-v] + + # deploy even more packages + $ /openpkg/bin/openpkg build \ + [-D[::]with_] \ + [-D[::]with_] \ + ... | sh + +For instance, to install and start an Apache HTTP server with SSL/TLS +support you can use: + + $ /openpkg/bin/openpkg search -v apache | more + $ /openpkg/bin/openpkg build -D with_mod_ssl=yes apache | sh + $ /openpkg/bin/openpkg rc apache start + +=item B<6. Cleanup> + +OpenPKG has not convinced you? Well, it's a pity, but no problem. You +can easily get rid of anything you installed at once (both the OpenPKG +instance and any of its OpenPKG packages) with the following simple +command: + + $ /openpkg/bin/openpkg rc all stop + $ /openpkg/bin/openpkg rpm -e `/openpkg/bin/openpkg rpm -qa` + +=back + +=head1 SEE ALSO + +OpenPKG local documentation can be viewed the command "B +I", where I is one of the following commands: + + index OpenPKG package indexing + search OpenPKG package searching + mirror OpenPKG package mirroring + build OpenPKG package building and installing + rc OpenPKG run-command facility + lsync OpenPKG local area synchronization + + stack OpenPKG software stack generation + makeproxy OpenPKG proxy package generation + dev OpenPKG development tool + + rpm RPM package manager + rpm2cpio RPM payload utility + rpm-config RPM C API utility + rpmtool OpenPKG RPM packaging helper tool + + license OpenPKG license management + release OpenPKG release information + register OpenPKG registry client (obsolete) + + sea Shell Execution Archive tool + uuid Universal Unique Identifiers tool + +Additionally, OpenPKG can be found under the following locations on the +Internet: + + http://openpkg.org/ OpenPKG Project (Distribution) + http://openpkg.com/ OpenPKG GmbH (Framework, Support) + http://openpkg.net/ OpenPKG Foundation e.V. (Packages) + =cut