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