diff -r 71503088f51b -r f880f219c566 openpkg/stack.pod
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/openpkg/stack.pod	Tue Jul 31 12:23:42 2012 +0200
@@ -0,0 +1,341 @@
+##
+##  OpenPKG Software Stack Generation Utility
+##  Copyright (c) 2012 OpenPKG GmbH <http://openpkg.com/>
+##
+##  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
+##  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
+##  CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+##  SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+##  LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
+##  USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+##  ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+##  OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
+##  OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+##  SUCH DAMAGE.
+##
+
+=pod
+
+=head1 NAME
+
+B<openpkg stack> - B<OpenPKG Software Stack Generation>
+
+=head1 SYNOPSIS
+
+B<openpkg stack>
+[B<-h>|B<--help>]
+[B<-v>|B<--verbose> I<level>]
+[B<-o>|B<--output> I<dir>]
+[B<-D>|B<--define> I<name>=I<value> ...]
+[B<-u>|B<--unversioned>]
+[B<-q>|B<--query>]
+F<I<name>.stk>
+
+=head1 DESCRIPTION
+
+The B<openpkg stack> command reads a OpenPKG software stack definition
+F<I<name>.stk>, generates a OpenPKG software stack deployment script
+F<I<name>[-I<version>-I<release>].sh>, determines, downloads and
+stores all required corresponding OpenPKG source packages under
+F<I<name>[-I<version>-I<release>].src.d/*.src.{sh,rpm}>.
+
+On executing the generated OpenPKG software stack deployment
+script F<I<name>[-I<version>-I<release>].sh>, an OpenPKG
+instance is created (or reused if existing), all packages
+built and installed in topologically correct dependency order
+and the resulting OpenPKG binary packages stored as
+F<I<name>[-I<version>-I<release>].I<platform>-I<tag>.d/*.{sh,rpm}>.
+
+The main design decisions and intentions of OpenPKG software stacks are:
+
+=over 4
+
+=item 1.
+
+OpenPKG software stacks can be centrally defined in a single file
+F<I<name>.stk>, similar to the definition of OpenPKG software packages in
+F<I<name>.spec> files. This definition includes both OpenPKG framework
+bootstrap parameters, OpenPKG package build parameters and OpenPKG
+software stack specific deployment-time prolog and epilog scripts.
+
+=item 2.
+
+OpenPKG software stacks depend on particular OpenPKG software packages
+(and perhaps even their particular versions) and by downloading and
+locally storing all relevant OpenPKG software packages an OpenPKG
+software stack remains stable and self-contained -- even if new versions
+of OpenPKG software packages are released.
+
+=item 3.
+
+For generating the OpenPKG software stack files, an OpenPKG instance
+and its B<openpkg stack> command is required, but executing the OpenPKG
+software stack deployment script does NOT require any pre-existing
+OpenPKG instances.
+
+=item 4.
+
+By wrapping F<I<name>[-I<version>-I<release>].sh> and
+F<I<name>[-I<version>-I<release>].src.d/> into a I<Shell Execution
+Archive> F<I<name>[-I<version>-I<release>].src.sh> with the B<openpkg
+sea> command, you can provide a single self-contained file for building
+and installing an OpenPKG software stack from OpenPKG source packages.
+
+=item 5.
+
+By wrapping F<I<name>[-I<version>-I<release>].sh> and
+F<I<name>[-I<version>-I<release>].I<platform>-I<tag>.d/>
+into a I<Shell Execution Archive>
+F<I<name>[-I<version>-I<release>].I<platform>-I<tag>.sh> with the
+B<openpkg sea> command, you can provide a single self-contained file for
+installing an OpenPKG software stack from OpenPKG binary packages.
+
+=back
+
+=head1 COMMAND-LINE OPTIONS AND ARGUMENTS
+
+=over 4
+
+=item B<-h>|B<--help>
+
+Just shows a short usage information for the B<openpkg stack> command.
+
+=item B<-v>|B<--verbose> I<level>
+
+Sets the verbosity level for outputs, from C<0> (no output at all) to 4
+(all possible outputs). The default is C<4>.
+
+=item B<-o>|B<--output> I<dir>
+
+The output directory for the OpenPKG software stack files.
+The default is the current directory (F<.>).
+
+=item [B<-D>|B<--define> I<name>=I<value> ...]
+
+On-the-fly overrides the value of option macro C<%{I<name>}> with
+I<value>. Use this to generate a variant of an OpenPKG software stack
+without modifying the software stack definition file.
+
+=item [B<-u>|B<--unversioned>]
+
+By default B<openpkg stack> creates the file
+C<I<name>-I<version>-I<release>.sh> (deployment script) and the
+directory C<I<name>-I<version>-I<release>.src.d/> (source packages).
+With this option the names are C<I<name>.sh> and C<I<name>.src.d/> only.
+
+=item [B<-q>|B<--query>]
+
+Forces a different operation mode where a shell script is output
+on F<stdout> containing variable definitions in the format
+C<I<name>="I<value>";> with information about the software stack
+definition. The provided variable names are C<name>, C<summary>,
+C<packager>, C<version> and C<release> for the corresponding headers,
+plus variables for all defined software stack options (see C<%option>
+section below).
+
+=item I<name>F<.stk>
+
+The mandatory OpenPKG software stack definition file.
+See below under B<SOFTWARE STACK DEFINITION> for details.
+
+=back
+
+=head1 SOFTWARE STACK DEFINITION
+
+An OpenPKG software stack is defined by a configuration file
+containing headers (C<Foo:>) and sections (<%foo>).
+
+=head2 Configuration Headers
+
+=over 4
+
+=item B<Name>
+
+The name of the OpenPKG software stack. Also used as a prefix for many
+files. Should match the regular expression C<^[a-z][a-zA-Z0-9]+>,
+although this is not enforced. Example: C<Name: example>.
+
+=item B<Summary>
+
+A single line, shortly summarizing the purpose of the OpenPKG software
+stack. Example: C<Summary: Example Stack>.
+
+=item B<Packager>
+
+Name of the packager of the OpenPKG software software stack.
+Example: C<Packager: OpenPKG GmbH>.
+
+=item B<Version>
+
+Version identifier of the OpenPKG software stack. Describes the
+I<logical> revision of the software stack definition. Should match the
+regular expression C<^[0-9]+\.[0-9]\.[0-9]+$>, although this is not
+enforced. Example: C<Version: 1.0.0>.
+
+=item B<Release>
+
+Release identifier of the OpenPKG software stack. Describes the
+I<physical> revision of the stack definition. Should be in the format
+C<YYYYMMDD> and hence match the regular expression C<^[0-9]{8}$>,
+although this is not enforced. Example: C<Release: 20120101>.
+
+=back
+
+=head2 Configuration Sections
+
+=over 4
+
+=item B<%options>
+
+Zero or more options for the OpenPKG software stack, one per line, in
+the format "I<name> I<default-value>". Options can be overridden on
+the command-line with B<-D>I<name>=I<value>. Example: C<with_ssl yes>.
+Option values can be expanded in all headers and sections through the
+following constructs:
+
+=over 4
+
+=item C<%{I<name>}>
+
+Expand to the value of option I<name>.
+
+=item C<%{?I<name>:I<value>}>
+
+Expand to I<value> if option I<name> is defined.
+
+=item C<%{!?I<name>:I<value>}>
+
+Expand to I<value> if option I<name> is NOT defined.
+
+=back
+
+=item B<%description>
+
+A single textual paragraph describing the purpose of the OpenPKG
+software stack in more detail than header C<Summary>.
+
+=item B<%framework>
+
+The command-line parameters passed to the OpenPKG framework
+bootstrap source shell package F<openpkg-*.src.sh>. Usually at
+least the parameters B<--prefix=>I<path>, B<--user=>I<username>,
+B<--group=>I<groupname> and B<--tag=>I<tagname> are given here. In order
+to allow an OpenPKG software stack to be easily reused one creates
+the options (see C<%option> above) named C<prefix>, C<user>, C<group>
+and C<tag> and then use C<--prefix=%{prefix}>, C<--user=%{user}>,
+C<--group=%{group}> and C<--tag=%{tag}> in this C<%framework> section.
+
+=item B<%packages>
+
+The packages to build and install for the OpenPKG software stack, in
+the format of "B<-DI<package>::I<option>=I<value>>" and "I<package>"
+specifications as understood by the C<openpkg build> tool. Example:
+C<-Dapache::with_mod_ssl=yes -Dapache-php::with_json=yes apache
+apache-php>.
+
+=item B<%prolog>
+
+A shell script executed before installation of all packages.
+The variable C<$prefix> is available to access the
+OpenPKG software stack without having to hard-code a path.
+
+=item B<%epilog>
+
+A shell script executed after installation of all packages. This
+is usually used for applying OpenPKG software stack specific
+configurations. The variable C<$prefix> is available to access the
+OpenPKG software stack without having to hard-code a path. Example:
+C<echo "openldap_enable=no" E<gt>E<gt>$prefix/etc/rc.conf>.
+
+=back
+
+=head1 EXAMPLES
+
+ $ cat xamp.stk
+ 
+ Name:         xamp
+ Summary:      Apache-MySQL-PHP Server
+ Packager:     OpenPKG GmbH
+ Version:      1.0.0
+ Release:      20120407
+  
+ %description
+     This software stack contains a so-called xAMP web stack, consisting
+     of the major components Apache, MySQL and PHP.
+  
+ %options
+     repo      http://download.openpkg.org/stacks/current/source/
+     prefix    /xamp
+     user      xamp
+     group     xamp
+     tag       xamp
+     with_ldap no
+     with_ssl  no
+     addr      127.0.0.1
+  
+ %repository
+     %{repo}
+  
+ %framework
+     --prefix=%{prefix}
+     --user=%{user}
+     --group=%{group}
+     --tag=%{tag}
+  
+ %packages
+     -D apache::with_mod_dav=yes
+     -D apache::with_mod_deflate=yes
+     -D apache::with_mod_ldap=%{with_ldap}
+     -D apache::with_mod_proxy=yes
+     -D apache::with_mod_ssl=%{with_ssl}
+     -D apache-php::with_curl=yes
+     -D apache-php::with_freetype=yes
+     -D apache-php::with_gd=yes
+     -D apache-php::with_iconv=yes
+     -D apache-php::with_json=yes
+     -D apache-php::with_mbregex=yes
+     -D apache-php::with_mbstring=yes
+     -D apache-php::with_mysql=yes
+     -D apache-php::with_openldap=%{with_ldap}
+     -D apache-php::with_session=yes
+     -D apache-php::with_simplexml=yes
+     -D apache-php::with_sqlite=yes
+     -D apache-php::with_ssl=%{with_ssl}
+     -D apache-php::with_xml=yes
+     -D apache-php::with_zlib=yes
+     apache
+     apache-php
+     mysql
+  
+ %epilog
+     shtool subst \
+         -e 's;127\.0\.0\.1:%{addr};g' \
+         %{prefix}/etc/apache/apache.conf
+     if [ ".%{with_ldap}" = .yes ]; then
+         echo "openldap_enable=\"no\"" >>%{prefix}/etc/rc.conf
+     fi
+  
+ $ openpkg stack -v4 \
+   -Dprefix=/v/xamp -Duser=xamp-sw -Dgroup=xamp-sw \
+   --unversioned xamp.stk
+
+ $ openpkg sea -o xamp.src.sh xamp.sh xamp.src.d/
+
+ $ sh xamp.src.sh -v4 -S sudo
+
+ $ openpkg sea -o xamp.bin.sh xamp.sh xamp.*-*.d/
+
+=head1 HISTORY
+
+The B<openpkg stack> command was implemented in April 2012 by I<Ralf S. Engelschall>
+E<lt>rse@engelschall.comE<gt> for the OpenPKG Framework of the OpenPKG GmbH. 
+
+=cut
+