1.1 --- a/openpkg/openpkg.1 Tue Jul 31 12:12:54 2012 +0200
1.2 +++ b/openpkg/openpkg.1 Tue Jul 31 12:23:42 2012 +0200
1.3 @@ -1,15 +1,7 @@
1.4 -.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
1.5 +.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.22)
1.6 .\"
1.7 .\" Standard preamble:
1.8 .\" ========================================================================
1.9 -.de Sh \" Subsection heading
1.10 -.br
1.11 -.if t .Sp
1.12 -.ne 5
1.13 -.PP
1.14 -\fB\\$1\fR
1.15 -.PP
1.16 -..
1.17 .de Sp \" Vertical space (when we can't use .PP)
1.18 .if t .sp .5v
1.19 .if n .sp
1.20 @@ -25,11 +17,11 @@
1.21 ..
1.22 .\" Set up some character translations and predefined strings. \*(-- will
1.23 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
1.24 -.\" double quote, and \*(R" will give a right double quote. | will give a
1.25 -.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to
1.26 -.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C'
1.27 -.\" expand to `' in nroff, nothing in troff, for use with C<>.
1.28 -.tr \(*W-|\(bv\*(Tr
1.29 +.\" double quote, and \*(R" will give a right double quote. \*(C+ will
1.30 +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
1.31 +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
1.32 +.\" nothing in troff, for use with C<>.
1.33 +.tr \(*W-
1.34 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
1.35 .ie n \{\
1.36 . ds -- \(*W-
1.37 @@ -48,22 +40,25 @@
1.38 . ds R" ''
1.39 'br\}
1.40 .\"
1.41 +.\" Escape single quotes in literal strings from groff's Unicode transform.
1.42 +.ie \n(.g .ds Aq \(aq
1.43 +.el .ds Aq '
1.44 +.\"
1.45 .\" If the F register is turned on, we'll generate index entries on stderr for
1.46 -.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
1.47 +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
1.48 .\" entries marked with X<> in POD. Of course, you'll have to process the
1.49 .\" output yourself in some meaningful fashion.
1.50 -.if \nF \{\
1.51 +.ie \nF \{\
1.52 . de IX
1.53 . tm Index:\\$1\t\\n%\t"\\$2"
1.54 ..
1.55 . nr % 0
1.56 . rr F
1.57 .\}
1.58 -.\"
1.59 -.\" For nroff, turn off justification. Always turn off hyphenation; it makes
1.60 -.\" way too many mistakes in technical documents.
1.61 -.hy 0
1.62 -.if n .na
1.63 +.el \{\
1.64 +. de IX
1.65 +..
1.66 +.\}
1.67 .\"
1.68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
1.69 .\" Fear. Run. Save yourself. No user-serviceable parts.
1.70 @@ -130,41 +125,17 @@
1.71 .\"
1.72 .IX Title "OPENPKG 1"
1.73 .TH OPENPKG 1 "OpenPKG" "OPENPKG(8)" "OpenPKG"
1.74 +.\" For nroff, turn off justification. Always turn off hyphenation; it makes
1.75 +.\" way too many mistakes in technical documents.
1.76 +.if n .ad l
1.77 +.nh
1.78 .SH "NAME"
1.79 -\&\fBOpenPKG\fR \-\- Cross\-Platform Unix Software Packaging Facility
1.80 +OpenPKG \-\- Cross\-Platform Unix Software Packaging
1.81 .SH "SYNOPSIS"
1.82 .IX Header "SYNOPSIS"
1.83 -.IP "Command Line Interface" 4
1.84 -.IX Item "Command Line Interface"
1.85 $ \fBopenpkg\fR [\fIopt\fR ...] \fIcmd\fR [\fIcmd_opt\fR ...] [\fIcmd_arg\fR ...]
1.86 -.Sp
1.87 +.PP
1.88 $ \fBopenpkg\fR \fBman\fR \fIcmd\fR
1.89 -.IP "Project Locations" 4
1.90 -.IX Item "Project Locations"
1.91 -.Vb 4
1.92 -\& http://www.openpkg.org/ web service
1.93 -\& http://cvs.openpkg.org/ repository service
1.94 -\& http://pgp.openpkg.org/ OpenPGP service
1.95 -\& ftp://ftp.openpkg.org/ download service
1.96 -.Ve
1.97 -.IP "Project Forums" 4
1.98 -.IX Item "Project Forums"
1.99 -.Vb 4
1.100 -\& petidomo@openpkg.org mailing-list manager
1.101 -\& openpkg-announce@openpkg.org project announcements
1.102 -\& openpkg-dev@openpkg.org developer forum
1.103 -\& openpkg-users@openpkg.org users forum
1.104 -.Ve
1.105 -.IP "Local Documentation" 4
1.106 -.IX Item "Local Documentation"
1.107 -.Vb 6
1.108 -\& openpkg-rpm(1) RPM package manager
1.109 -\& openpkg-rpmbuild(1) RPM package manager (build only)
1.110 -\& openpkg-rpm2cpio(1) RPM payload utility
1.111 -\& openpkg-rpm-config(1) RPM C API utility
1.112 -\& openpkg-lsync(1) local area synchronization
1.113 -\& openpkg-rc(1) run-command facility
1.114 -.Ve
1.115 .SH "DESCRIPTION"
1.116 .IX Header "DESCRIPTION"
1.117 OpenPKG is the world leading instrument for deployment and maintenance
1.118 @@ -181,3 +152,145 @@
1.119 a tricky bootstrapping procedure in order to allow one to create from
1.120 scratch the initial state of the whole OpenPKG software packaging
1.121 system.
1.122 +.SH "TUTORIAL"
1.123 +.IX Header "TUTORIAL"
1.124 +.IP "\fB1. System Preparation (optional)\fR" 3
1.125 +.IX Item "1. System Preparation (optional)"
1.126 +Before you start, the Unix system optionally should be prepared. Here
1.127 +especially the necessary disk space requirements of OpenPKG have to be
1.128 +taken into account.
1.129 +.Sp
1.130 +.Vb 3
1.131 +\& # optionally direct /openpkg to at least 150MB free disk space:
1.132 +\& $ mkdir /storage/openpkg
1.133 +\& $ ln \-s /storage/openpkg /openpkg
1.134 +\&
1.135 +\& # optionally direct temp\-directory to at least 250MB free disk space:
1.136 +\& $ TMPDIR=/var/tmp
1.137 +\& $ export TMPDIR
1.138 +\&
1.139 +\& # switch to temporary directory:
1.140 +\& $ cd $TMPDIR
1.141 +.Ve
1.142 +.IP "\fB2. Instance Bootstrapping\fR" 3
1.143 +.IX Item "2. Instance Bootstrapping"
1.144 +The next step is to bootstrap the OpenPKG instance. Here we are using
1.145 +the standard /openpkg filesystem prefix. An arbitrary prefix can be
1.146 +used as long as at least the \*(L"Bootstrap From Source\*(R" approach is used.
1.147 +.Sp
1.148 +.Vb 2
1.149 +\& # download bootstrap source shell package:
1.150 +\& $ wget http://openpkg.org/go/download/openpkg.src.sh
1.151 +\&
1.152 +\& # build bootstrap binary shell package from source shell package:
1.153 +\& $ sh openpkg.src.sh \e
1.154 +\& \-\-prefix=/openpkg \-\-tag=openpkg \e
1.155 +\& \-\-user=openpkg \-\-group=openpkg \e
1.156 +\& \-\-tag=openpkg
1.157 +\&
1.158 +\& # install bootstrap binary script package:
1.159 +\& $ sh openpkg\-*\-*.*\-openpkg.sh
1.160 +.Ve
1.161 +.IP "\fB3. Software Deployment\fR" 3
1.162 +.IX Item "3. Software Deployment"
1.163 +Now you can install arbitrary OpenPKG software packages by either using
1.164 +the lower-level OpenPKG \s-1RPM\s0 command or the higher-level OpenPKG tool
1.165 +chain build command. As a simple illustration example the \s-1GNU\s0 Bash
1.166 +package of OpenPKG is installed.
1.167 +.Sp
1.168 +.Vb 2
1.169 +\& # build and install GNU Bash:
1.170 +\& $ /openpkg/bin/openpkg build bash | sh
1.171 +.Ve
1.172 +.IP "\fB4. Software Usage\fR" 3
1.173 +.IX Item "4. Software Usage"
1.174 +Finally, you can use the deployed software. Either through explicit
1.175 +paths (reasonable if leveraging OpenPKG's multiple-instance feature) or
1.176 +implicitly by merging the OpenPKG instance into the local environment.
1.177 +.Sp
1.178 +.Vb 2
1.179 +\& # explicit usage:
1.180 +\& $ /openpkg/bin/bash \-\-version
1.181 +\&
1.182 +\& # implicit usage (alternatively)
1.183 +\& $ eval \`/openpkg/bin/openpkg rc \-\-eval all env\`
1.184 +\& $ bash \-\-version
1.185 +.Ve
1.186 +.IP "\fB5. Go Ahead!\fR" 3
1.187 +.IX Item "5. Go Ahead!"
1.188 +Want to know more now? Please read the manual pages of at least the
1.189 +deployment commands and then proceed by searching and deploying even
1.190 +more software into your OpenPKG instance.
1.191 +.Sp
1.192 +.Vb 3
1.193 +\& # read manual pages:
1.194 +\& $ /openpkg/bin/openpkg man search
1.195 +\& $ /openpkg/bin/openpkg man build
1.196 +\&
1.197 +\& # search for a package
1.198 +\& $ /openpkg/bin/openpkg search [\-v] <regex>
1.199 +\&
1.200 +\& # deploy even more packages
1.201 +\& $ /openpkg/bin/openpkg build \e
1.202 +\& [\-D[<package1>::]with_<name>] \e
1.203 +\& [\-D[<package2>::]with_<name>] \e
1.204 +\& <package1> <package2> ... | sh
1.205 +.Ve
1.206 +.Sp
1.207 +For instance, to install and start an Apache \s-1HTTP\s0 server with \s-1SSL/TLS\s0
1.208 +support you can use:
1.209 +.Sp
1.210 +.Vb 3
1.211 +\& $ /openpkg/bin/openpkg search \-v apache | more
1.212 +\& $ /openpkg/bin/openpkg build \-D with_mod_ssl=yes apache | sh
1.213 +\& $ /openpkg/bin/openpkg rc apache start
1.214 +.Ve
1.215 +.IP "\fB6. Cleanup\fR" 3
1.216 +.IX Item "6. Cleanup"
1.217 +OpenPKG has not convinced you? Well, it's a pity, but no problem. You
1.218 +can easily get rid of anything you installed at once (both the OpenPKG
1.219 +instance and any of its OpenPKG packages) with the following simple
1.220 +command:
1.221 +.Sp
1.222 +.Vb 2
1.223 +\& $ /openpkg/bin/openpkg rc all stop
1.224 +\& $ /openpkg/bin/openpkg rpm \-e \`/openpkg/bin/openpkg rpm \-qa\`
1.225 +.Ve
1.226 +.SH "SEE ALSO"
1.227 +.IX Header "SEE ALSO"
1.228 +OpenPKG local documentation can be viewed the command "\fBopenpkg man\fR
1.229 +\&\fIcmd\fR", where \fIcmd\fR is one of the following commands:
1.230 +.PP
1.231 +.Vb 6
1.232 +\& index OpenPKG package indexing
1.233 +\& search OpenPKG package searching
1.234 +\& mirror OpenPKG package mirroring
1.235 +\& build OpenPKG package building and installing
1.236 +\& rc OpenPKG run\-command facility
1.237 +\& lsync OpenPKG local area synchronization
1.238 +\&
1.239 +\& stack OpenPKG software stack generation
1.240 +\& makeproxy OpenPKG proxy package generation
1.241 +\& dev OpenPKG development tool
1.242 +\&
1.243 +\& rpm RPM package manager
1.244 +\& rpm2cpio RPM payload utility
1.245 +\& rpm\-config RPM C API utility
1.246 +\& rpmtool OpenPKG RPM packaging helper tool
1.247 +\&
1.248 +\& license OpenPKG license management
1.249 +\& release OpenPKG release information
1.250 +\& register OpenPKG registry client (obsolete)
1.251 +\&
1.252 +\& sea Shell Execution Archive tool
1.253 +\& uuid Universal Unique Identifiers tool
1.254 +.Ve
1.255 +.PP
1.256 +Additionally, OpenPKG can be found under the following locations on the
1.257 +Internet:
1.258 +.PP
1.259 +.Vb 3
1.260 +\& http://openpkg.org/ OpenPKG Project (Distribution)
1.261 +\& http://openpkg.com/ OpenPKG GmbH (Framework, Support)
1.262 +\& http://openpkg.net/ OpenPKG Foundation e.V. (Packages)
1.263 +.Ve
