1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/openpkg/stack.pod Tue Jul 31 12:23:42 2012 +0200
1.3 @@ -0,0 +1,341 @@
1.4 +##
1.5 +## OpenPKG Software Stack Generation Utility
1.6 +## Copyright (c) 2012 OpenPKG GmbH <http://openpkg.com/>
1.7 +##
1.8 +## This software is property of the OpenPKG GmbH, DE MUC HRB 160208.
1.9 +## All rights reserved. Licenses which grant limited permission to use,
1.10 +## copy, modify and distribute this software are available from the
1.11 +## OpenPKG GmbH.
1.12 +##
1.13 +## THIS SOFTWARE IS PROVIDED "AS IS" AND ANY EXPRESSED OR IMPLIED
1.14 +## WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
1.15 +## MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
1.16 +## IN NO EVENT SHALL THE AUTHORS AND COPYRIGHT HOLDERS AND THEIR
1.17 +## CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
1.18 +## SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
1.19 +## LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
1.20 +## USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
1.21 +## ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
1.22 +## OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
1.23 +## OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
1.24 +## SUCH DAMAGE.
1.25 +##
1.26 +
1.27 +=pod
1.28 +
1.29 +=head1 NAME
1.30 +
1.31 +B<openpkg stack> - B<OpenPKG Software Stack Generation>
1.32 +
1.33 +=head1 SYNOPSIS
1.34 +
1.35 +B<openpkg stack>
1.36 +[B<-h>|B<--help>]
1.37 +[B<-v>|B<--verbose> I<level>]
1.38 +[B<-o>|B<--output> I<dir>]
1.39 +[B<-D>|B<--define> I<name>=I<value> ...]
1.40 +[B<-u>|B<--unversioned>]
1.41 +[B<-q>|B<--query>]
1.42 +F<I<name>.stk>
1.43 +
1.44 +=head1 DESCRIPTION
1.45 +
1.46 +The B<openpkg stack> command reads a OpenPKG software stack definition
1.47 +F<I<name>.stk>, generates a OpenPKG software stack deployment script
1.48 +F<I<name>[-I<version>-I<release>].sh>, determines, downloads and
1.49 +stores all required corresponding OpenPKG source packages under
1.50 +F<I<name>[-I<version>-I<release>].src.d/*.src.{sh,rpm}>.
1.51 +
1.52 +On executing the generated OpenPKG software stack deployment
1.53 +script F<I<name>[-I<version>-I<release>].sh>, an OpenPKG
1.54 +instance is created (or reused if existing), all packages
1.55 +built and installed in topologically correct dependency order
1.56 +and the resulting OpenPKG binary packages stored as
1.57 +F<I<name>[-I<version>-I<release>].I<platform>-I<tag>.d/*.{sh,rpm}>.
1.58 +
1.59 +The main design decisions and intentions of OpenPKG software stacks are:
1.60 +
1.61 +=over 4
1.62 +
1.63 +=item 1.
1.64 +
1.65 +OpenPKG software stacks can be centrally defined in a single file
1.66 +F<I<name>.stk>, similar to the definition of OpenPKG software packages in
1.67 +F<I<name>.spec> files. This definition includes both OpenPKG framework
1.68 +bootstrap parameters, OpenPKG package build parameters and OpenPKG
1.69 +software stack specific deployment-time prolog and epilog scripts.
1.70 +
1.71 +=item 2.
1.72 +
1.73 +OpenPKG software stacks depend on particular OpenPKG software packages
1.74 +(and perhaps even their particular versions) and by downloading and
1.75 +locally storing all relevant OpenPKG software packages an OpenPKG
1.76 +software stack remains stable and self-contained -- even if new versions
1.77 +of OpenPKG software packages are released.
1.78 +
1.79 +=item 3.
1.80 +
1.81 +For generating the OpenPKG software stack files, an OpenPKG instance
1.82 +and its B<openpkg stack> command is required, but executing the OpenPKG
1.83 +software stack deployment script does NOT require any pre-existing
1.84 +OpenPKG instances.
1.85 +
1.86 +=item 4.
1.87 +
1.88 +By wrapping F<I<name>[-I<version>-I<release>].sh> and
1.89 +F<I<name>[-I<version>-I<release>].src.d/> into a I<Shell Execution
1.90 +Archive> F<I<name>[-I<version>-I<release>].src.sh> with the B<openpkg
1.91 +sea> command, you can provide a single self-contained file for building
1.92 +and installing an OpenPKG software stack from OpenPKG source packages.
1.93 +
1.94 +=item 5.
1.95 +
1.96 +By wrapping F<I<name>[-I<version>-I<release>].sh> and
1.97 +F<I<name>[-I<version>-I<release>].I<platform>-I<tag>.d/>
1.98 +into a I<Shell Execution Archive>
1.99 +F<I<name>[-I<version>-I<release>].I<platform>-I<tag>.sh> with the
1.100 +B<openpkg sea> command, you can provide a single self-contained file for
1.101 +installing an OpenPKG software stack from OpenPKG binary packages.
1.102 +
1.103 +=back
1.104 +
1.105 +=head1 COMMAND-LINE OPTIONS AND ARGUMENTS
1.106 +
1.107 +=over 4
1.108 +
1.109 +=item B<-h>|B<--help>
1.110 +
1.111 +Just shows a short usage information for the B<openpkg stack> command.
1.112 +
1.113 +=item B<-v>|B<--verbose> I<level>
1.114 +
1.115 +Sets the verbosity level for outputs, from C<0> (no output at all) to 4
1.116 +(all possible outputs). The default is C<4>.
1.117 +
1.118 +=item B<-o>|B<--output> I<dir>
1.119 +
1.120 +The output directory for the OpenPKG software stack files.
1.121 +The default is the current directory (F<.>).
1.122 +
1.123 +=item [B<-D>|B<--define> I<name>=I<value> ...]
1.124 +
1.125 +On-the-fly overrides the value of option macro C<%{I<name>}> with
1.126 +I<value>. Use this to generate a variant of an OpenPKG software stack
1.127 +without modifying the software stack definition file.
1.128 +
1.129 +=item [B<-u>|B<--unversioned>]
1.130 +
1.131 +By default B<openpkg stack> creates the file
1.132 +C<I<name>-I<version>-I<release>.sh> (deployment script) and the
1.133 +directory C<I<name>-I<version>-I<release>.src.d/> (source packages).
1.134 +With this option the names are C<I<name>.sh> and C<I<name>.src.d/> only.
1.135 +
1.136 +=item [B<-q>|B<--query>]
1.137 +
1.138 +Forces a different operation mode where a shell script is output
1.139 +on F<stdout> containing variable definitions in the format
1.140 +C<I<name>="I<value>";> with information about the software stack
1.141 +definition. The provided variable names are C<name>, C<summary>,
1.142 +C<packager>, C<version> and C<release> for the corresponding headers,
1.143 +plus variables for all defined software stack options (see C<%option>
1.144 +section below).
1.145 +
1.146 +=item I<name>F<.stk>
1.147 +
1.148 +The mandatory OpenPKG software stack definition file.
1.149 +See below under B<SOFTWARE STACK DEFINITION> for details.
1.150 +
1.151 +=back
1.152 +
1.153 +=head1 SOFTWARE STACK DEFINITION
1.154 +
1.155 +An OpenPKG software stack is defined by a configuration file
1.156 +containing headers (C<Foo:>) and sections (<%foo>).
1.157 +
1.158 +=head2 Configuration Headers
1.159 +
1.160 +=over 4
1.161 +
1.162 +=item B<Name>
1.163 +
1.164 +The name of the OpenPKG software stack. Also used as a prefix for many
1.165 +files. Should match the regular expression C<^[a-z][a-zA-Z0-9]+>,
1.166 +although this is not enforced. Example: C<Name: example>.
1.167 +
1.168 +=item B<Summary>
1.169 +
1.170 +A single line, shortly summarizing the purpose of the OpenPKG software
1.171 +stack. Example: C<Summary: Example Stack>.
1.172 +
1.173 +=item B<Packager>
1.174 +
1.175 +Name of the packager of the OpenPKG software software stack.
1.176 +Example: C<Packager: OpenPKG GmbH>.
1.177 +
1.178 +=item B<Version>
1.179 +
1.180 +Version identifier of the OpenPKG software stack. Describes the
1.181 +I<logical> revision of the software stack definition. Should match the
1.182 +regular expression C<^[0-9]+\.[0-9]\.[0-9]+$>, although this is not
1.183 +enforced. Example: C<Version: 1.0.0>.
1.184 +
1.185 +=item B<Release>
1.186 +
1.187 +Release identifier of the OpenPKG software stack. Describes the
1.188 +I<physical> revision of the stack definition. Should be in the format
1.189 +C<YYYYMMDD> and hence match the regular expression C<^[0-9]{8}$>,
1.190 +although this is not enforced. Example: C<Release: 20120101>.
1.191 +
1.192 +=back
1.193 +
1.194 +=head2 Configuration Sections
1.195 +
1.196 +=over 4
1.197 +
1.198 +=item B<%options>
1.199 +
1.200 +Zero or more options for the OpenPKG software stack, one per line, in
1.201 +the format "I<name> I<default-value>". Options can be overridden on
1.202 +the command-line with B<-D>I<name>=I<value>. Example: C<with_ssl yes>.
1.203 +Option values can be expanded in all headers and sections through the
1.204 +following constructs:
1.205 +
1.206 +=over 4
1.207 +
1.208 +=item C<%{I<name>}>
1.209 +
1.210 +Expand to the value of option I<name>.
1.211 +
1.212 +=item C<%{?I<name>:I<value>}>
1.213 +
1.214 +Expand to I<value> if option I<name> is defined.
1.215 +
1.216 +=item C<%{!?I<name>:I<value>}>
1.217 +
1.218 +Expand to I<value> if option I<name> is NOT defined.
1.219 +
1.220 +=back
1.221 +
1.222 +=item B<%description>
1.223 +
1.224 +A single textual paragraph describing the purpose of the OpenPKG
1.225 +software stack in more detail than header C<Summary>.
1.226 +
1.227 +=item B<%framework>
1.228 +
1.229 +The command-line parameters passed to the OpenPKG framework
1.230 +bootstrap source shell package F<openpkg-*.src.sh>. Usually at
1.231 +least the parameters B<--prefix=>I<path>, B<--user=>I<username>,
1.232 +B<--group=>I<groupname> and B<--tag=>I<tagname> are given here. In order
1.233 +to allow an OpenPKG software stack to be easily reused one creates
1.234 +the options (see C<%option> above) named C<prefix>, C<user>, C<group>
1.235 +and C<tag> and then use C<--prefix=%{prefix}>, C<--user=%{user}>,
1.236 +C<--group=%{group}> and C<--tag=%{tag}> in this C<%framework> section.
1.237 +
1.238 +=item B<%packages>
1.239 +
1.240 +The packages to build and install for the OpenPKG software stack, in
1.241 +the format of "B<-DI<package>::I<option>=I<value>>" and "I<package>"
1.242 +specifications as understood by the C<openpkg build> tool. Example:
1.243 +C<-Dapache::with_mod_ssl=yes -Dapache-php::with_json=yes apache
1.244 +apache-php>.
1.245 +
1.246 +=item B<%prolog>
1.247 +
1.248 +A shell script executed before installation of all packages.
1.249 +The variable C<$prefix> is available to access the
1.250 +OpenPKG software stack without having to hard-code a path.
1.251 +
1.252 +=item B<%epilog>
1.253 +
1.254 +A shell script executed after installation of all packages. This
1.255 +is usually used for applying OpenPKG software stack specific
1.256 +configurations. The variable C<$prefix> is available to access the
1.257 +OpenPKG software stack without having to hard-code a path. Example:
1.258 +C<echo "openldap_enable=no" E<gt>E<gt>$prefix/etc/rc.conf>.
1.259 +
1.260 +=back
1.261 +
1.262 +=head1 EXAMPLES
1.263 +
1.264 + $ cat xamp.stk
1.265 +
1.266 + Name: xamp
1.267 + Summary: Apache-MySQL-PHP Server
1.268 + Packager: OpenPKG GmbH
1.269 + Version: 1.0.0
1.270 + Release: 20120407
1.271 +
1.272 + %description
1.273 + This software stack contains a so-called xAMP web stack, consisting
1.274 + of the major components Apache, MySQL and PHP.
1.275 +
1.276 + %options
1.277 + repo http://download.openpkg.org/stacks/current/source/
1.278 + prefix /xamp
1.279 + user xamp
1.280 + group xamp
1.281 + tag xamp
1.282 + with_ldap no
1.283 + with_ssl no
1.284 + addr 127.0.0.1
1.285 +
1.286 + %repository
1.287 + %{repo}
1.288 +
1.289 + %framework
1.290 + --prefix=%{prefix}
1.291 + --user=%{user}
1.292 + --group=%{group}
1.293 + --tag=%{tag}
1.294 +
1.295 + %packages
1.296 + -D apache::with_mod_dav=yes
1.297 + -D apache::with_mod_deflate=yes
1.298 + -D apache::with_mod_ldap=%{with_ldap}
1.299 + -D apache::with_mod_proxy=yes
1.300 + -D apache::with_mod_ssl=%{with_ssl}
1.301 + -D apache-php::with_curl=yes
1.302 + -D apache-php::with_freetype=yes
1.303 + -D apache-php::with_gd=yes
1.304 + -D apache-php::with_iconv=yes
1.305 + -D apache-php::with_json=yes
1.306 + -D apache-php::with_mbregex=yes
1.307 + -D apache-php::with_mbstring=yes
1.308 + -D apache-php::with_mysql=yes
1.309 + -D apache-php::with_openldap=%{with_ldap}
1.310 + -D apache-php::with_session=yes
1.311 + -D apache-php::with_simplexml=yes
1.312 + -D apache-php::with_sqlite=yes
1.313 + -D apache-php::with_ssl=%{with_ssl}
1.314 + -D apache-php::with_xml=yes
1.315 + -D apache-php::with_zlib=yes
1.316 + apache
1.317 + apache-php
1.318 + mysql
1.319 +
1.320 + %epilog
1.321 + shtool subst \
1.322 + -e 's;127\.0\.0\.1:%{addr};g' \
1.323 + %{prefix}/etc/apache/apache.conf
1.324 + if [ ".%{with_ldap}" = .yes ]; then
1.325 + echo "openldap_enable=\"no\"" >>%{prefix}/etc/rc.conf
1.326 + fi
1.327 +
1.328 + $ openpkg stack -v4 \
1.329 + -Dprefix=/v/xamp -Duser=xamp-sw -Dgroup=xamp-sw \
1.330 + --unversioned xamp.stk
1.331 +
1.332 + $ openpkg sea -o xamp.src.sh xamp.sh xamp.src.d/
1.333 +
1.334 + $ sh xamp.src.sh -v4 -S sudo
1.335 +
1.336 + $ openpkg sea -o xamp.bin.sh xamp.sh xamp.*-*.d/
1.337 +
1.338 +=head1 HISTORY
1.339 +
1.340 +The B<openpkg stack> command was implemented in April 2012 by I<Ralf S. Engelschall>
1.341 +E<lt>rse@engelschall.comE<gt> for the OpenPKG Framework of the OpenPKG GmbH.
1.342 +
1.343 +=cut
1.344 +
