OpenPKG Specs: openpkg/stack.pod@a2c6460cfb16 (annotated)

openpkg/stack.pod@a2c6460cfb16 (annotated)

openpkg/stack.pod

Mon, 28 Jan 2013 17:37:18 +0100

author: Michael Schloh von Bennewitz <michael@schloh.com>
date: Mon, 28 Jan 2013 17:37:18 +0100
changeset 758: a2c6460cfb16
permissions: -rw-r--r--

Correct socket error reporting improvement with IPv6 portable code,
after helpful recommendation by Saúl Ibarra Corretgé on OSips devlist.

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

OpenPKG Specs / annotate

openpkg/stack.pod@a2c6460cfb16 (annotated)

openpkg/stack.pod