1.1 --- a/openpkg/openpkg.pod Tue Jul 31 12:12:54 2012 +0200
1.2 +++ b/openpkg/openpkg.pod Tue Jul 31 12:23:42 2012 +0200
1.3 @@ -1,14 +1,13 @@
1.4 ##
1.5 ## openpkg -- OpenPKG Tool Chain
1.6 -## Copyright (c) 2000-2007 OpenPKG Foundation e.V. <http://openpkg.net/>
1.7 -## Copyright (c) 2000-2007 Ralf S. Engelschall <http://engelschall.com/>
1.8 +## Copyright (c) 2000-2012 OpenPKG GmbH <http://openpkg.com/>
1.9 ##
1.10 -## Permission to use, copy, modify, and distribute this software for
1.11 -## any purpose with or without fee is hereby granted, provided that
1.12 -## the above copyright notice and this permission notice appear in all
1.13 -## copies.
1.14 +## This software is property of the OpenPKG GmbH, DE MUC HRB 160208.
1.15 +## All rights reserved. Licenses which grant limited permission to use,
1.16 +## copy, modify and distribute this software are available from the
1.17 +## OpenPKG GmbH.
1.18 ##
1.19 -## THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
1.20 +## THIS SOFTWARE IS PROVIDED "AS IS" AND ANY EXPRESSED OR IMPLIED
1.21 ## WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
1.22 ## MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
1.23 ## IN NO EVENT SHALL THE AUTHORS AND COPYRIGHT HOLDERS AND THEIR
1.24 @@ -28,45 +27,16 @@
1.25
1.26 =head1 NAME
1.27
1.28 -B<OpenPKG> -- Cross-Platform Unix Software Packaging Facility
1.29 +B<OpenPKG> -- Cross-Platform Unix Software Packaging
1.30
1.31 =head1 SYNOPSIS
1.32
1.33 -=over 4
1.34 -
1.35 -=item Command Line Interface
1.36 -
1.37 $ B<openpkg> [I<opt> ...] I<cmd> [I<cmd_opt> ...] [I<cmd_arg> ...]
1.38
1.39 $ B<openpkg> B<man> I<cmd>
1.40
1.41 -=item Project Locations
1.42 +=head1 DESCRIPTION
1.43
1.44 - http://www.openpkg.org/ web service
1.45 - http://cvs.openpkg.org/ repository service
1.46 - http://pgp.openpkg.org/ OpenPGP service
1.47 - ftp://ftp.openpkg.org/ download service
1.48 -
1.49 -=item Project Forums
1.50 -
1.51 - petidomo@openpkg.org mailing-list manager
1.52 - openpkg-announce@openpkg.org project announcements
1.53 - openpkg-dev@openpkg.org developer forum
1.54 - openpkg-users@openpkg.org users forum
1.55 -
1.56 -=item Local Documentation
1.57 -
1.58 - openpkg-rpm(1) RPM package manager
1.59 - openpkg-rpmbuild(1) RPM package manager (build only)
1.60 - openpkg-rpm2cpio(1) RPM payload utility
1.61 - openpkg-rpm-config(1) RPM C API utility
1.62 - openpkg-lsync(1) local area synchronization
1.63 - openpkg-rc(1) run-command facility
1.64 -
1.65 -=back
1.66 -
1.67 -=head1 DESCRIPTION
1.68 -
1.69 OpenPKG is the world leading instrument for deployment and maintenance
1.70 of Open Source software when administration crosses Unix platform
1.71 boundaries. The OpenPKG project is a collaboration effort with the
1.72 @@ -82,5 +52,140 @@
1.73 scratch the initial state of the whole OpenPKG software packaging
1.74 system.
1.75
1.76 +=head1 TUTORIAL
1.77 +
1.78 +=over 3
1.79 +
1.80 +=item B<1. System Preparation (optional)>
1.81 +
1.82 +Before you start, the Unix system optionally should be prepared. Here
1.83 +especially the necessary disk space requirements of OpenPKG have to be
1.84 +taken into account.
1.85 +
1.86 + # optionally direct /openpkg to at least 150MB free disk space:
1.87 + $ mkdir /storage/openpkg
1.88 + $ ln -s /storage/openpkg /openpkg
1.89 +
1.90 + # optionally direct temp-directory to at least 250MB free disk space:
1.91 + $ TMPDIR=/var/tmp
1.92 + $ export TMPDIR
1.93 +
1.94 + # switch to temporary directory:
1.95 + $ cd $TMPDIR
1.96 +
1.97 +=item B<2. Instance Bootstrapping>
1.98 +
1.99 +The next step is to bootstrap the OpenPKG instance. Here we are using
1.100 +the standard /openpkg filesystem prefix. An arbitrary prefix can be
1.101 +used as long as at least the "Bootstrap From Source" approach is used.
1.102 +
1.103 + # download bootstrap source shell package:
1.104 + $ wget http://openpkg.org/go/download/openpkg.src.sh
1.105 +
1.106 + # build bootstrap binary shell package from source shell package:
1.107 + $ sh openpkg.src.sh \
1.108 + --prefix=/openpkg --tag=openpkg \
1.109 + --user=openpkg --group=openpkg \
1.110 + --tag=openpkg
1.111 +
1.112 + # install bootstrap binary script package:
1.113 + $ sh openpkg-*-*.*-openpkg.sh
1.114 +
1.115 +=item B<3. Software Deployment>
1.116 +
1.117 +Now you can install arbitrary OpenPKG software packages by either using
1.118 +the lower-level OpenPKG RPM command or the higher-level OpenPKG tool
1.119 +chain build command. As a simple illustration example the GNU Bash
1.120 +package of OpenPKG is installed.
1.121 +
1.122 + # build and install GNU Bash:
1.123 + $ /openpkg/bin/openpkg build bash | sh
1.124 +
1.125 +=item B<4. Software Usage>
1.126 +
1.127 +Finally, you can use the deployed software. Either through explicit
1.128 +paths (reasonable if leveraging OpenPKG's multiple-instance feature) or
1.129 +implicitly by merging the OpenPKG instance into the local environment.
1.130 +
1.131 + # explicit usage:
1.132 + $ /openpkg/bin/bash --version
1.133 +
1.134 + # implicit usage (alternatively)
1.135 + $ eval `/openpkg/bin/openpkg rc --eval all env`
1.136 + $ bash --version
1.137 +
1.138 +=item B<5. Go Ahead!>
1.139 +
1.140 +Want to know more now? Please read the manual pages of at least the
1.141 +deployment commands and then proceed by searching and deploying even
1.142 +more software into your OpenPKG instance.
1.143 +
1.144 + # read manual pages:
1.145 + $ /openpkg/bin/openpkg man search
1.146 + $ /openpkg/bin/openpkg man build
1.147 +
1.148 + # search for a package
1.149 + $ /openpkg/bin/openpkg search [-v] <regex>
1.150 +
1.151 + # deploy even more packages
1.152 + $ /openpkg/bin/openpkg build \
1.153 + [-D[<package1>::]with_<name>] \
1.154 + [-D[<package2>::]with_<name>] \
1.155 + <package1> <package2> ... | sh
1.156 +
1.157 +For instance, to install and start an Apache HTTP server with SSL/TLS
1.158 +support you can use:
1.159 +
1.160 + $ /openpkg/bin/openpkg search -v apache | more
1.161 + $ /openpkg/bin/openpkg build -D with_mod_ssl=yes apache | sh
1.162 + $ /openpkg/bin/openpkg rc apache start
1.163 +
1.164 +=item B<6. Cleanup>
1.165 +
1.166 +OpenPKG has not convinced you? Well, it's a pity, but no problem. You
1.167 +can easily get rid of anything you installed at once (both the OpenPKG
1.168 +instance and any of its OpenPKG packages) with the following simple
1.169 +command:
1.170 +
1.171 + $ /openpkg/bin/openpkg rc all stop
1.172 + $ /openpkg/bin/openpkg rpm -e `/openpkg/bin/openpkg rpm -qa`
1.173 +
1.174 +=back
1.175 +
1.176 +=head1 SEE ALSO
1.177 +
1.178 +OpenPKG local documentation can be viewed the command "B<openpkg man>
1.179 +I<cmd>", where I<cmd> is one of the following commands:
1.180 +
1.181 + index OpenPKG package indexing
1.182 + search OpenPKG package searching
1.183 + mirror OpenPKG package mirroring
1.184 + build OpenPKG package building and installing
1.185 + rc OpenPKG run-command facility
1.186 + lsync OpenPKG local area synchronization
1.187 +
1.188 + stack OpenPKG software stack generation
1.189 + makeproxy OpenPKG proxy package generation
1.190 + dev OpenPKG development tool
1.191 +
1.192 + rpm RPM package manager
1.193 + rpm2cpio RPM payload utility
1.194 + rpm-config RPM C API utility
1.195 + rpmtool OpenPKG RPM packaging helper tool
1.196 +
1.197 + license OpenPKG license management
1.198 + release OpenPKG release information
1.199 + register OpenPKG registry client (obsolete)
1.200 +
1.201 + sea Shell Execution Archive tool
1.202 + uuid Universal Unique Identifiers tool
1.203 +
1.204 +Additionally, OpenPKG can be found under the following locations on the
1.205 +Internet:
1.206 +
1.207 + http://openpkg.org/ OpenPKG Project (Distribution)
1.208 + http://openpkg.com/ OpenPKG GmbH (Framework, Support)
1.209 + http://openpkg.net/ OpenPKG Foundation e.V. (Packages)
1.210 +
1.211 =cut
1.212
