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

openpkg/stack.8@a2c6460cfb16 (annotated)

openpkg/stack.8

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.

 .\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.22)
 .\"
 .\" Standard preamble:
 .\" ========================================================================
 .de Sp \" Vertical space (when we can't use .PP)
 .if t .sp .5v
 .if n .sp
 ..
 .de Vb \" Begin verbatim text
 .ft CW
 .nf
 .ne \\$1
 ..
 .de Ve \" End verbatim text
 .ft R
 .fi
 ..
 .\" Set up some character translations and predefined strings.  \*(-- will
 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
 .\" nothing in troff, for use with C<>.
 .tr \(*W-
 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
 .ie n \{\
 .    ds -- \(*W-
 .    ds PI pi
 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
 .    ds L" ""
 .    ds R" ""
 .    ds C`
 .    ds C'
 'br\}
 .el\{\
 .    ds -- \|\(em\|
 .    ds PI \(*p
 .    ds L" ``
 .    ds R" ''
 'br\}
 .\"
 .\" Escape single quotes in literal strings from groff's Unicode transform.
 .ie \n(.g .ds Aq \(aq
 .el       .ds Aq '
 .\"
 .\" If the F register is turned on, we'll generate index entries on stderr for
 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
 .\" entries marked with X<> in POD.  Of course, you'll have to process the
 .\" output yourself in some meaningful fashion.
 .ie \nF \{\
 .    de IX
 .    tm Index:\\$1\t\\n%\t"\\$2"
 ..
 .    nr % 0
 .    rr F
 .\}
 .el \{\
 .    de IX
 ..
 .\}
 .\"
 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
 .    \" fudge factors for nroff and troff
 .if n \{\
 .    ds #H 0
 .    ds #V .8m
 .    ds #F .3m
 .    ds #[ \f1
 .    ds #] \fP
 .\}
 .if t \{\
 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
 .    ds #V .6m
 .    ds #F 0
 .    ds #[ \&
 .    ds #] \&
 .\}
 .    \" simple accents for nroff and troff
 .if n \{\
 .    ds ' \&
 .    ds ` \&
 .    ds ^ \&
 .    ds , \&
 .    ds ~ ~
 .    ds /
 .\}
 .if t \{\
 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 .\}
 .    \" troff and (daisy-wheel) nroff accents
 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 .ds ae a\h'-(\w'a'u*4/10)'e
 .ds Ae A\h'-(\w'A'u*4/10)'E
 .    \" corrections for vroff
 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 .    \" for low resolution devices (crt and lpr)
 .if \n(.H>23 .if \n(.V>19 \
 \{\
 .    ds : e
 .    ds 8 ss
 .    ds o a
 .    ds d- d\h'-1'\(ga
 .    ds D- D\h'-1'\(hy
 .    ds th \o'bp'
 .    ds Th \o'LP'
 .    ds ae ae
 .    ds Ae AE
 .\}
 .rm #[ #] #H #V #F C
 .\" ========================================================================
 .\"
 .IX Title "STACK 8"
 .TH STACK 8 "OpenPKG" "STACK(8)" "OpenPKG"
 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 .\" way too many mistakes in technical documents.
 .if n .ad l
 .nh
 .SH "NAME"
 openpkg stack \- OpenPKG Software Stack Generation
 .SH "SYNOPSIS"
 .IX Header "SYNOPSIS"
 \&\fBopenpkg stack\fR
 [\fB\-h\fR|\fB\-\-help\fR]
 [\fB\-v\fR|\fB\-\-verbose\fR \fIlevel\fR]
 [\fB\-o\fR|\fB\-\-output\fR \fIdir\fR]
 [\fB\-D\fR|\fB\-\-define\fR \fIname\fR=\fIvalue\fR ...]
 [\fB\-u\fR|\fB\-\-unversioned\fR]
 [\fB\-q\fR|\fB\-\-query\fR]
 \&\fI\fIname\fI.stk\fR
 .SH "DESCRIPTION"
 .IX Header "DESCRIPTION"
 The \fBopenpkg stack\fR command reads a OpenPKG software stack definition
 \&\fI\fIname\fI.stk\fR, generates a OpenPKG software stack deployment script
 \&\fI\fIname\fI[\-\fIversion\fI\-\fIrelease\fI].sh\fR, determines, downloads and
 stores all required corresponding OpenPKG source packages under
 \&\fI\fIname\fI[\-\fIversion\fI\-\fIrelease\fI].src.d/*.src.{sh,rpm}\fR.
 .PP
 On executing the generated OpenPKG software stack deployment
 script \fI\fIname\fI[\-\fIversion\fI\-\fIrelease\fI].sh\fR, 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
 \&\fI\fIname\fI[\-\fIversion\fI\-\fIrelease\fI].\fIplatform\fI\-\fItag\fI.d/*.{sh,rpm}\fR.
 .PP
 The main design decisions and intentions of OpenPKG software stacks are:
 .IP "1." 4
 OpenPKG software stacks can be centrally defined in a single file
 \&\fI\fIname\fI.stk\fR, similar to the definition of OpenPKG software packages in
 \&\fI\fIname\fI.spec\fR files. This definition includes both OpenPKG framework
 bootstrap parameters, OpenPKG package build parameters and OpenPKG
 software stack specific deployment-time prolog and epilog scripts.
 .IP "2." 4
 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.
 .IP "3." 4
 For generating the OpenPKG software stack files, an OpenPKG instance
 and its \fBopenpkg stack\fR command is required, but executing the OpenPKG
 software stack deployment script does \s-1NOT\s0 require any pre-existing
 OpenPKG instances.
 .IP "4." 4
 By wrapping \fI\fIname\fI[\-\fIversion\fI\-\fIrelease\fI].sh\fR and
 \&\fI\fIname\fI[\-\fIversion\fI\-\fIrelease\fI].src.d/\fR into a \fIShell Execution
 Archive\fR \fI\fIname\fI[\-\fIversion\fI\-\fIrelease\fI].src.sh\fR with the \fBopenpkg
 sea\fR command, you can provide a single self-contained file for building
 and installing an OpenPKG software stack from OpenPKG source packages.
 .IP "5." 4
 By wrapping \fI\fIname\fI[\-\fIversion\fI\-\fIrelease\fI].sh\fR and
 \&\fI\fIname\fI[\-\fIversion\fI\-\fIrelease\fI].\fIplatform\fI\-\fItag\fI.d/\fR
 into a \fIShell Execution Archive\fR
 \&\fI\fIname\fI[\-\fIversion\fI\-\fIrelease\fI].\fIplatform\fI\-\fItag\fI.sh\fR with the
 \&\fBopenpkg sea\fR command, you can provide a single self-contained file for
 installing an OpenPKG software stack from OpenPKG binary packages.
 .SH "COMMAND-LINE OPTIONS AND ARGUMENTS"
 .IX Header "COMMAND-LINE OPTIONS AND ARGUMENTS"
 .IP "\fB\-h\fR|\fB\-\-help\fR" 4
 .IX Item "-h|--help"
 Just shows a short usage information for the \fBopenpkg stack\fR command.
 .IP "\fB\-v\fR|\fB\-\-verbose\fR \fIlevel\fR" 4
 .IX Item "-v|--verbose level"
 Sets the verbosity level for outputs, from \f(CW0\fR (no output at all) to 4
 (all possible outputs). The default is \f(CW4\fR.
 .IP "\fB\-o\fR|\fB\-\-output\fR \fIdir\fR" 4
 .IX Item "-o|--output dir"
 The output directory for the OpenPKG software stack files.
 The default is the current directory (\fI.\fR).
 .IP "[\fB\-D\fR|\fB\-\-define\fR \fIname\fR=\fIvalue\fR ...]" 4
 .IX Item "[-D|--define name=value ...]"
 On-the-fly overrides the value of option macro \f(CW\*(C`%{\f(CIname\f(CW}\*(C'\fR with
 \&\fIvalue\fR. Use this to generate a variant of an OpenPKG software stack
 without modifying the software stack definition file.
 .IP "[\fB\-u\fR|\fB\-\-unversioned\fR]" 4
 .IX Item "[-u|--unversioned]"
 By default \fBopenpkg stack\fR creates the file
 \&\f(CW\*(C`\f(CIname\f(CW\-\f(CIversion\f(CW\-\f(CIrelease\f(CW.sh\*(C'\fR (deployment script) and the
 directory \f(CW\*(C`\f(CIname\f(CW\-\f(CIversion\f(CW\-\f(CIrelease\f(CW.src.d/\*(C'\fR (source packages).
 With this option the names are \f(CW\*(C`\f(CIname\f(CW.sh\*(C'\fR and \f(CW\*(C`\f(CIname\f(CW.src.d/\*(C'\fR only.
 .IP "[\fB\-q\fR|\fB\-\-query\fR]" 4
 .IX Item "[-q|--query]"
 Forces a different operation mode where a shell script is output
 on \fIstdout\fR containing variable definitions in the format
 \&\f(CW\*(C`\f(CIname\f(CW="\f(CIvalue\f(CW";\*(C'\fR with information about the software stack
 definition. The provided variable names are \f(CW\*(C`name\*(C'\fR, \f(CW\*(C`summary\*(C'\fR,
 \&\f(CW\*(C`packager\*(C'\fR, \f(CW\*(C`version\*(C'\fR and \f(CW\*(C`release\*(C'\fR for the corresponding headers,
 plus variables for all defined software stack options (see \f(CW%option\fR
 section below).
 .IP "\fIname\fR\fI.stk\fR" 4
 .IX Item "name.stk"
 The mandatory OpenPKG software stack definition file.
 See below under \fB\s-1SOFTWARE\s0 \s-1STACK\s0 \s-1DEFINITION\s0\fR for details.
 .SH "SOFTWARE STACK DEFINITION"
 .IX Header "SOFTWARE STACK DEFINITION"
 An OpenPKG software stack is defined by a configuration file
 containing headers (\f(CW\*(C`Foo:\*(C'\fR) and sections (<%foo>).
 .SS "Configuration Headers"
 .IX Subsection "Configuration Headers"
 .IP "\fBName\fR" 4
 .IX Item "Name"
 The name of the OpenPKG software stack. Also used as a prefix for many
 files. Should match the regular expression \f(CW\*(C`^[a\-z][a\-zA\-Z0\-9]+\*(C'\fR,
 although this is not enforced. Example: \f(CW\*(C`Name: example\*(C'\fR.
 .IP "\fBSummary\fR" 4
 .IX Item "Summary"
 A single line, shortly summarizing the purpose of the OpenPKG software
 stack. Example: \f(CW\*(C`Summary: Example Stack\*(C'\fR.
 .IP "\fBPackager\fR" 4
 .IX Item "Packager"
 Name of the packager of the OpenPKG software software stack.
 Example: \f(CW\*(C`Packager: OpenPKG GmbH\*(C'\fR.
 .IP "\fBVersion\fR" 4
 .IX Item "Version"
 Version identifier of the OpenPKG software stack. Describes the
 \&\fIlogical\fR revision of the software stack definition. Should match the
 regular expression \f(CW\*(C`^[0\-9]+\e.[0\-9]\e.[0\-9]+$\*(C'\fR, although this is not
 enforced. Example: \f(CW\*(C`Version: 1.0.0\*(C'\fR.
 .IP "\fBRelease\fR" 4
 .IX Item "Release"
 Release identifier of the OpenPKG software stack. Describes the
 \&\fIphysical\fR revision of the stack definition. Should be in the format
 \&\f(CW\*(C`YYYYMMDD\*(C'\fR and hence match the regular expression \f(CW\*(C`^[0\-9]{8}$\*(C'\fR,
 although this is not enforced. Example: \f(CW\*(C`Release: 20120101\*(C'\fR.
 .SS "Configuration Sections"
 .IX Subsection "Configuration Sections"
 .ie n .IP "\fB\fB%options\fB\fR" 4
 .el .IP "\fB\f(CB%options\fB\fR" 4
 .IX Item "%options"
 Zero or more options for the OpenPKG software stack, one per line, in
 the format "\fIname\fR \fIdefault-value\fR". Options can be overridden on
 the command-line with \fB\-D\fR\fIname\fR=\fIvalue\fR. Example: \f(CW\*(C`with_ssl yes\*(C'\fR.
 Option values can be expanded in all headers and sections through the
 following constructs:
 .RS 4
 .ie n .IP "\*(C`%{\f(CIname\f(CW}\*(C'" 4
 .el .IP "\f(CW\*(C`%{\f(CIname\f(CW}\*(C'\fR" 4
 .IX Item "%{name}"
 Expand to the value of option \fIname\fR.
 .ie n .IP "\*(C`%{?\f(CIname\f(CW:\f(CIvalue\f(CW}\*(C'" 4
 .el .IP "\f(CW\*(C`%{?\f(CIname\f(CW:\f(CIvalue\f(CW}\*(C'\fR" 4
 .IX Item "%{?name:value}"
 Expand to \fIvalue\fR if option \fIname\fR is defined.
 .ie n .IP "\*(C`%{!?\f(CIname\f(CW:\f(CIvalue\f(CW}\*(C'" 4
 .el .IP "\f(CW\*(C`%{!?\f(CIname\f(CW:\f(CIvalue\f(CW}\*(C'\fR" 4
 .IX Item "%{!?name:value}"
 Expand to \fIvalue\fR if option \fIname\fR is \s-1NOT\s0 defined.
 .RE
 .RS 4
 .RE
 .ie n .IP "\fB\fB%description\fB\fR" 4
 .el .IP "\fB\f(CB%description\fB\fR" 4
 .IX Item "%description"
 A single textual paragraph describing the purpose of the OpenPKG
 software stack in more detail than header \f(CW\*(C`Summary\*(C'\fR.
 .ie n .IP "\fB\fB%framework\fB\fR" 4
 .el .IP "\fB\f(CB%framework\fB\fR" 4
 .IX Item "%framework"
 The command-line parameters passed to the OpenPKG framework
 bootstrap source shell package \fIopenpkg\-*.src.sh\fR. Usually at
 least the parameters \fB\-\-prefix=\fR\fIpath\fR, \fB\-\-user=\fR\fIusername\fR,
 \&\fB\-\-group=\fR\fIgroupname\fR and \fB\-\-tag=\fR\fItagname\fR are given here. In order
 to allow an OpenPKG software stack to be easily reused one creates
 the options (see \f(CW%option\fR above) named \f(CW\*(C`prefix\*(C'\fR, \f(CW\*(C`user\*(C'\fR, \f(CW\*(C`group\*(C'\fR
 and \f(CW\*(C`tag\*(C'\fR and then use \f(CW\*(C`\-\-prefix=%{prefix}\*(C'\fR, \f(CW\*(C`\-\-user=%{user}\*(C'\fR,
 \&\f(CW\*(C`\-\-group=%{group}\*(C'\fR and \f(CW\*(C`\-\-tag=%{tag}\*(C'\fR in this \f(CW%framework\fR section.
 .ie n .IP "\fB\fB%packages\fB\fR" 4
 .el .IP "\fB\f(CB%packages\fB\fR" 4
 .IX Item "%packages"
 The packages to build and install for the OpenPKG software stack, in
 the format of "\fB\-D\f(BIpackage\fB::\f(BIoption\fB=\f(BIvalue\fB\fR\*(L" and \*(R"\fIpackage\fR"
 specifications as understood by the \f(CW\*(C`openpkg build\*(C'\fR tool. Example:
 \&\f(CW\*(C`\-Dapache::with_mod_ssl=yes \-Dapache\-php::with_json=yes apache
 apache\-php\*(C'\fR.
 .ie n .IP "\fB\fB%prolog\fB\fR" 4
 .el .IP "\fB\f(CB%prolog\fB\fR" 4
 .IX Item "%prolog"
 A shell script executed before installation of all packages.
 The variable \f(CW$prefix\fR is available to access the
 OpenPKG software stack without having to hard-code a path.
 .ie n .IP "\fB\fB%epilog\fB\fR" 4
 .el .IP "\fB\f(CB%epilog\fB\fR" 4
 .IX Item "%epilog"
 A shell script executed after installation of all packages. This
 is usually used for applying OpenPKG software stack specific
 configurations. The variable \f(CW$prefix\fR is available to access the
 OpenPKG software stack without having to hard-code a path. Example:
 \&\f(CW\*(C`echo "openldap_enable=no" >>$prefix/etc/rc.conf\*(C'\fR.
 .SH "EXAMPLES"
 .IX Header "EXAMPLES"
 .Vb 1
 \& $ 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
 \&         \-e \*(Aqs;127\e.0\e.0\e.1:%{addr};g\*(Aq \e
 \&         %{prefix}/etc/apache/apache.conf
 \&     if [ ".%{with_ldap}" = .yes ]; then
 \&         echo "openldap_enable=\e"no\e"" >>%{prefix}/etc/rc.conf
 \&     fi
 \&
 \& $ openpkg stack \-v4 \e
 \&   \-Dprefix=/v/xamp \-Duser=xamp\-sw \-Dgroup=xamp\-sw \e
 \&   \-\-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/
 .Ve
 .SH "HISTORY"
 .IX Header "HISTORY"
 The \fBopenpkg stack\fR command was implemented in April 2012 by \fIRalf S. Engelschall\fR
 <rse@engelschall.com> for the OpenPKG Framework of the OpenPKG GmbH.

OpenPKG Specs / annotate

openpkg/stack.8@a2c6460cfb16 (annotated)

openpkg/stack.8