OpenPKG Specs / file revision

 ##

 ##  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