Mon, 28 Jan 2013 17:37:18 +0100
Correct socket error reporting improvement with IPv6 portable code,
after helpful recommendation by Saúl Ibarra Corretgé on OSips devlist.
1 .\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.22)
2 .\"
3 .\" Standard preamble:
4 .\" ========================================================================
5 .de Sp \" Vertical space (when we can't use .PP)
6 .if t .sp .5v
7 .if n .sp
8 ..
9 .de Vb \" Begin verbatim text
10 .ft CW
11 .nf
12 .ne \\$1
13 ..
14 .de Ve \" End verbatim text
15 .ft R
16 .fi
17 ..
18 .\" Set up some character translations and predefined strings. \*(-- will
19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
20 .\" double quote, and \*(R" will give a right double quote. \*(C+ will
21 .\" give a nicer C++. Capital omega is used to do unbreakable dashes and
22 .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
23 .\" nothing in troff, for use with C<>.
24 .tr \(*W-
25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
26 .ie n \{\
27 . ds -- \(*W-
28 . ds PI pi
29 . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
30 . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
31 . ds L" ""
32 . ds R" ""
33 . ds C`
34 . ds C'
35 'br\}
36 .el\{\
37 . ds -- \|\(em\|
38 . ds PI \(*p
39 . ds L" ``
40 . ds R" ''
41 'br\}
42 .\"
43 .\" Escape single quotes in literal strings from groff's Unicode transform.
44 .ie \n(.g .ds Aq \(aq
45 .el .ds Aq '
46 .\"
47 .\" If the F register is turned on, we'll generate index entries on stderr for
48 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
49 .\" entries marked with X<> in POD. Of course, you'll have to process the
50 .\" output yourself in some meaningful fashion.
51 .ie \nF \{\
52 . de IX
53 . tm Index:\\$1\t\\n%\t"\\$2"
54 ..
55 . nr % 0
56 . rr F
57 .\}
58 .el \{\
59 . de IX
60 ..
61 .\}
62 .\"
63 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
64 .\" Fear. Run. Save yourself. No user-serviceable parts.
65 . \" fudge factors for nroff and troff
66 .if n \{\
67 . ds #H 0
68 . ds #V .8m
69 . ds #F .3m
70 . ds #[ \f1
71 . ds #] \fP
72 .\}
73 .if t \{\
74 . ds #H ((1u-(\\\\n(.fu%2u))*.13m)
75 . ds #V .6m
76 . ds #F 0
77 . ds #[ \&
78 . ds #] \&
79 .\}
80 . \" simple accents for nroff and troff
81 .if n \{\
82 . ds ' \&
83 . ds ` \&
84 . ds ^ \&
85 . ds , \&
86 . ds ~ ~
87 . ds /
88 .\}
89 .if t \{\
90 . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
91 . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
92 . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
93 . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
94 . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
95 . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
96 .\}
97 . \" troff and (daisy-wheel) nroff accents
98 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
99 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
100 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
101 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
102 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
103 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
104 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
105 .ds ae a\h'-(\w'a'u*4/10)'e
106 .ds Ae A\h'-(\w'A'u*4/10)'E
107 . \" corrections for vroff
108 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
109 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
110 . \" for low resolution devices (crt and lpr)
111 .if \n(.H>23 .if \n(.V>19 \
112 \{\
113 . ds : e
114 . ds 8 ss
115 . ds o a
116 . ds d- d\h'-1'\(ga
117 . ds D- D\h'-1'\(hy
118 . ds th \o'bp'
119 . ds Th \o'LP'
120 . ds ae ae
121 . ds Ae AE
122 .\}
123 .rm #[ #] #H #V #F C
124 .\" ========================================================================
125 .\"
126 .IX Title "STACK 8"
127 .TH STACK 8 "OpenPKG" "STACK(8)" "OpenPKG"
128 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
129 .\" way too many mistakes in technical documents.
130 .if n .ad l
131 .nh
132 .SH "NAME"
133 openpkg stack \- OpenPKG Software Stack Generation
134 .SH "SYNOPSIS"
135 .IX Header "SYNOPSIS"
136 \&\fBopenpkg stack\fR
137 [\fB\-h\fR|\fB\-\-help\fR]
138 [\fB\-v\fR|\fB\-\-verbose\fR \fIlevel\fR]
139 [\fB\-o\fR|\fB\-\-output\fR \fIdir\fR]
140 [\fB\-D\fR|\fB\-\-define\fR \fIname\fR=\fIvalue\fR ...]
141 [\fB\-u\fR|\fB\-\-unversioned\fR]
142 [\fB\-q\fR|\fB\-\-query\fR]
143 \&\fI\fIname\fI.stk\fR
144 .SH "DESCRIPTION"
145 .IX Header "DESCRIPTION"
146 The \fBopenpkg stack\fR command reads a OpenPKG software stack definition
147 \&\fI\fIname\fI.stk\fR, generates a OpenPKG software stack deployment script
148 \&\fI\fIname\fI[\-\fIversion\fI\-\fIrelease\fI].sh\fR, determines, downloads and
149 stores all required corresponding OpenPKG source packages under
150 \&\fI\fIname\fI[\-\fIversion\fI\-\fIrelease\fI].src.d/*.src.{sh,rpm}\fR.
151 .PP
152 On executing the generated OpenPKG software stack deployment
153 script \fI\fIname\fI[\-\fIversion\fI\-\fIrelease\fI].sh\fR, an OpenPKG
154 instance is created (or reused if existing), all packages
155 built and installed in topologically correct dependency order
156 and the resulting OpenPKG binary packages stored as
157 \&\fI\fIname\fI[\-\fIversion\fI\-\fIrelease\fI].\fIplatform\fI\-\fItag\fI.d/*.{sh,rpm}\fR.
158 .PP
159 The main design decisions and intentions of OpenPKG software stacks are:
160 .IP "1." 4
161 OpenPKG software stacks can be centrally defined in a single file
162 \&\fI\fIname\fI.stk\fR, similar to the definition of OpenPKG software packages in
163 \&\fI\fIname\fI.spec\fR files. This definition includes both OpenPKG framework
164 bootstrap parameters, OpenPKG package build parameters and OpenPKG
165 software stack specific deployment-time prolog and epilog scripts.
166 .IP "2." 4
167 OpenPKG software stacks depend on particular OpenPKG software packages
168 (and perhaps even their particular versions) and by downloading and
169 locally storing all relevant OpenPKG software packages an OpenPKG
170 software stack remains stable and self-contained \*(-- even if new versions
171 of OpenPKG software packages are released.
172 .IP "3." 4
173 For generating the OpenPKG software stack files, an OpenPKG instance
174 and its \fBopenpkg stack\fR command is required, but executing the OpenPKG
175 software stack deployment script does \s-1NOT\s0 require any pre-existing
176 OpenPKG instances.
177 .IP "4." 4
178 By wrapping \fI\fIname\fI[\-\fIversion\fI\-\fIrelease\fI].sh\fR and
179 \&\fI\fIname\fI[\-\fIversion\fI\-\fIrelease\fI].src.d/\fR into a \fIShell Execution
180 Archive\fR \fI\fIname\fI[\-\fIversion\fI\-\fIrelease\fI].src.sh\fR with the \fBopenpkg
181 sea\fR command, you can provide a single self-contained file for building
182 and installing an OpenPKG software stack from OpenPKG source packages.
183 .IP "5." 4
184 By wrapping \fI\fIname\fI[\-\fIversion\fI\-\fIrelease\fI].sh\fR and
185 \&\fI\fIname\fI[\-\fIversion\fI\-\fIrelease\fI].\fIplatform\fI\-\fItag\fI.d/\fR
186 into a \fIShell Execution Archive\fR
187 \&\fI\fIname\fI[\-\fIversion\fI\-\fIrelease\fI].\fIplatform\fI\-\fItag\fI.sh\fR with the
188 \&\fBopenpkg sea\fR command, you can provide a single self-contained file for
189 installing an OpenPKG software stack from OpenPKG binary packages.
190 .SH "COMMAND-LINE OPTIONS AND ARGUMENTS"
191 .IX Header "COMMAND-LINE OPTIONS AND ARGUMENTS"
192 .IP "\fB\-h\fR|\fB\-\-help\fR" 4
193 .IX Item "-h|--help"
194 Just shows a short usage information for the \fBopenpkg stack\fR command.
195 .IP "\fB\-v\fR|\fB\-\-verbose\fR \fIlevel\fR" 4
196 .IX Item "-v|--verbose level"
197 Sets the verbosity level for outputs, from \f(CW0\fR (no output at all) to 4
198 (all possible outputs). The default is \f(CW4\fR.
199 .IP "\fB\-o\fR|\fB\-\-output\fR \fIdir\fR" 4
200 .IX Item "-o|--output dir"
201 The output directory for the OpenPKG software stack files.
202 The default is the current directory (\fI.\fR).
203 .IP "[\fB\-D\fR|\fB\-\-define\fR \fIname\fR=\fIvalue\fR ...]" 4
204 .IX Item "[-D|--define name=value ...]"
205 On-the-fly overrides the value of option macro \f(CW\*(C`%{\f(CIname\f(CW}\*(C'\fR with
206 \&\fIvalue\fR. Use this to generate a variant of an OpenPKG software stack
207 without modifying the software stack definition file.
208 .IP "[\fB\-u\fR|\fB\-\-unversioned\fR]" 4
209 .IX Item "[-u|--unversioned]"
210 By default \fBopenpkg stack\fR creates the file
211 \&\f(CW\*(C`\f(CIname\f(CW\-\f(CIversion\f(CW\-\f(CIrelease\f(CW.sh\*(C'\fR (deployment script) and the
212 directory \f(CW\*(C`\f(CIname\f(CW\-\f(CIversion\f(CW\-\f(CIrelease\f(CW.src.d/\*(C'\fR (source packages).
213 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.
214 .IP "[\fB\-q\fR|\fB\-\-query\fR]" 4
215 .IX Item "[-q|--query]"
216 Forces a different operation mode where a shell script is output
217 on \fIstdout\fR containing variable definitions in the format
218 \&\f(CW\*(C`\f(CIname\f(CW="\f(CIvalue\f(CW";\*(C'\fR with information about the software stack
219 definition. The provided variable names are \f(CW\*(C`name\*(C'\fR, \f(CW\*(C`summary\*(C'\fR,
220 \&\f(CW\*(C`packager\*(C'\fR, \f(CW\*(C`version\*(C'\fR and \f(CW\*(C`release\*(C'\fR for the corresponding headers,
221 plus variables for all defined software stack options (see \f(CW%option\fR
222 section below).
223 .IP "\fIname\fR\fI.stk\fR" 4
224 .IX Item "name.stk"
225 The mandatory OpenPKG software stack definition file.
226 See below under \fB\s-1SOFTWARE\s0 \s-1STACK\s0 \s-1DEFINITION\s0\fR for details.
227 .SH "SOFTWARE STACK DEFINITION"
228 .IX Header "SOFTWARE STACK DEFINITION"
229 An OpenPKG software stack is defined by a configuration file
230 containing headers (\f(CW\*(C`Foo:\*(C'\fR) and sections (<%foo>).
231 .SS "Configuration Headers"
232 .IX Subsection "Configuration Headers"
233 .IP "\fBName\fR" 4
234 .IX Item "Name"
235 The name of the OpenPKG software stack. Also used as a prefix for many
236 files. Should match the regular expression \f(CW\*(C`^[a\-z][a\-zA\-Z0\-9]+\*(C'\fR,
237 although this is not enforced. Example: \f(CW\*(C`Name: example\*(C'\fR.
238 .IP "\fBSummary\fR" 4
239 .IX Item "Summary"
240 A single line, shortly summarizing the purpose of the OpenPKG software
241 stack. Example: \f(CW\*(C`Summary: Example Stack\*(C'\fR.
242 .IP "\fBPackager\fR" 4
243 .IX Item "Packager"
244 Name of the packager of the OpenPKG software software stack.
245 Example: \f(CW\*(C`Packager: OpenPKG GmbH\*(C'\fR.
246 .IP "\fBVersion\fR" 4
247 .IX Item "Version"
248 Version identifier of the OpenPKG software stack. Describes the
249 \&\fIlogical\fR revision of the software stack definition. Should match the
250 regular expression \f(CW\*(C`^[0\-9]+\e.[0\-9]\e.[0\-9]+$\*(C'\fR, although this is not
251 enforced. Example: \f(CW\*(C`Version: 1.0.0\*(C'\fR.
252 .IP "\fBRelease\fR" 4
253 .IX Item "Release"
254 Release identifier of the OpenPKG software stack. Describes the
255 \&\fIphysical\fR revision of the stack definition. Should be in the format
256 \&\f(CW\*(C`YYYYMMDD\*(C'\fR and hence match the regular expression \f(CW\*(C`^[0\-9]{8}$\*(C'\fR,
257 although this is not enforced. Example: \f(CW\*(C`Release: 20120101\*(C'\fR.
258 .SS "Configuration Sections"
259 .IX Subsection "Configuration Sections"
260 .ie n .IP "\fB\fB%options\fB\fR" 4
261 .el .IP "\fB\f(CB%options\fB\fR" 4
262 .IX Item "%options"
263 Zero or more options for the OpenPKG software stack, one per line, in
264 the format "\fIname\fR \fIdefault-value\fR". Options can be overridden on
265 the command-line with \fB\-D\fR\fIname\fR=\fIvalue\fR. Example: \f(CW\*(C`with_ssl yes\*(C'\fR.
266 Option values can be expanded in all headers and sections through the
267 following constructs:
268 .RS 4
269 .ie n .IP "\*(C`%{\f(CIname\f(CW}\*(C'" 4
270 .el .IP "\f(CW\*(C`%{\f(CIname\f(CW}\*(C'\fR" 4
271 .IX Item "%{name}"
272 Expand to the value of option \fIname\fR.
273 .ie n .IP "\*(C`%{?\f(CIname\f(CW:\f(CIvalue\f(CW}\*(C'" 4
274 .el .IP "\f(CW\*(C`%{?\f(CIname\f(CW:\f(CIvalue\f(CW}\*(C'\fR" 4
275 .IX Item "%{?name:value}"
276 Expand to \fIvalue\fR if option \fIname\fR is defined.
277 .ie n .IP "\*(C`%{!?\f(CIname\f(CW:\f(CIvalue\f(CW}\*(C'" 4
278 .el .IP "\f(CW\*(C`%{!?\f(CIname\f(CW:\f(CIvalue\f(CW}\*(C'\fR" 4
279 .IX Item "%{!?name:value}"
280 Expand to \fIvalue\fR if option \fIname\fR is \s-1NOT\s0 defined.
281 .RE
282 .RS 4
283 .RE
284 .ie n .IP "\fB\fB%description\fB\fR" 4
285 .el .IP "\fB\f(CB%description\fB\fR" 4
286 .IX Item "%description"
287 A single textual paragraph describing the purpose of the OpenPKG
288 software stack in more detail than header \f(CW\*(C`Summary\*(C'\fR.
289 .ie n .IP "\fB\fB%framework\fB\fR" 4
290 .el .IP "\fB\f(CB%framework\fB\fR" 4
291 .IX Item "%framework"
292 The command-line parameters passed to the OpenPKG framework
293 bootstrap source shell package \fIopenpkg\-*.src.sh\fR. Usually at
294 least the parameters \fB\-\-prefix=\fR\fIpath\fR, \fB\-\-user=\fR\fIusername\fR,
295 \&\fB\-\-group=\fR\fIgroupname\fR and \fB\-\-tag=\fR\fItagname\fR are given here. In order
296 to allow an OpenPKG software stack to be easily reused one creates
297 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
298 and \f(CW\*(C`tag\*(C'\fR and then use \f(CW\*(C`\-\-prefix=%{prefix}\*(C'\fR, \f(CW\*(C`\-\-user=%{user}\*(C'\fR,
299 \&\f(CW\*(C`\-\-group=%{group}\*(C'\fR and \f(CW\*(C`\-\-tag=%{tag}\*(C'\fR in this \f(CW%framework\fR section.
300 .ie n .IP "\fB\fB%packages\fB\fR" 4
301 .el .IP "\fB\f(CB%packages\fB\fR" 4
302 .IX Item "%packages"
303 The packages to build and install for the OpenPKG software stack, in
304 the format of "\fB\-D\f(BIpackage\fB::\f(BIoption\fB=\f(BIvalue\fB\fR\*(L" and \*(R"\fIpackage\fR"
305 specifications as understood by the \f(CW\*(C`openpkg build\*(C'\fR tool. Example:
306 \&\f(CW\*(C`\-Dapache::with_mod_ssl=yes \-Dapache\-php::with_json=yes apache
307 apache\-php\*(C'\fR.
308 .ie n .IP "\fB\fB%prolog\fB\fR" 4
309 .el .IP "\fB\f(CB%prolog\fB\fR" 4
310 .IX Item "%prolog"
311 A shell script executed before installation of all packages.
312 The variable \f(CW$prefix\fR is available to access the
313 OpenPKG software stack without having to hard-code a path.
314 .ie n .IP "\fB\fB%epilog\fB\fR" 4
315 .el .IP "\fB\f(CB%epilog\fB\fR" 4
316 .IX Item "%epilog"
317 A shell script executed after installation of all packages. This
318 is usually used for applying OpenPKG software stack specific
319 configurations. The variable \f(CW$prefix\fR is available to access the
320 OpenPKG software stack without having to hard-code a path. Example:
321 \&\f(CW\*(C`echo "openldap_enable=no" >>$prefix/etc/rc.conf\*(C'\fR.
322 .SH "EXAMPLES"
323 .IX Header "EXAMPLES"
324 .Vb 1
325 \& $ cat xamp.stk
326 \&
327 \& Name: xamp
328 \& Summary: Apache\-MySQL\-PHP Server
329 \& Packager: OpenPKG GmbH
330 \& Version: 1.0.0
331 \& Release: 20120407
332 \&
333 \& %description
334 \& This software stack contains a so\-called xAMP web stack, consisting
335 \& of the major components Apache, MySQL and PHP.
336 \&
337 \& %options
338 \& repo http://download.openpkg.org/stacks/current/source/
339 \& prefix /xamp
340 \& user xamp
341 \& group xamp
342 \& tag xamp
343 \& with_ldap no
344 \& with_ssl no
345 \& addr 127.0.0.1
346 \&
347 \& %repository
348 \& %{repo}
349 \&
350 \& %framework
351 \& \-\-prefix=%{prefix}
352 \& \-\-user=%{user}
353 \& \-\-group=%{group}
354 \& \-\-tag=%{tag}
355 \&
356 \& %packages
357 \& \-D apache::with_mod_dav=yes
358 \& \-D apache::with_mod_deflate=yes
359 \& \-D apache::with_mod_ldap=%{with_ldap}
360 \& \-D apache::with_mod_proxy=yes
361 \& \-D apache::with_mod_ssl=%{with_ssl}
362 \& \-D apache\-php::with_curl=yes
363 \& \-D apache\-php::with_freetype=yes
364 \& \-D apache\-php::with_gd=yes
365 \& \-D apache\-php::with_iconv=yes
366 \& \-D apache\-php::with_json=yes
367 \& \-D apache\-php::with_mbregex=yes
368 \& \-D apache\-php::with_mbstring=yes
369 \& \-D apache\-php::with_mysql=yes
370 \& \-D apache\-php::with_openldap=%{with_ldap}
371 \& \-D apache\-php::with_session=yes
372 \& \-D apache\-php::with_simplexml=yes
373 \& \-D apache\-php::with_sqlite=yes
374 \& \-D apache\-php::with_ssl=%{with_ssl}
375 \& \-D apache\-php::with_xml=yes
376 \& \-D apache\-php::with_zlib=yes
377 \& apache
378 \& apache\-php
379 \& mysql
380 \&
381 \& %epilog
382 \& shtool subst \e
383 \& \-e \*(Aqs;127\e.0\e.0\e.1:%{addr};g\*(Aq \e
384 \& %{prefix}/etc/apache/apache.conf
385 \& if [ ".%{with_ldap}" = .yes ]; then
386 \& echo "openldap_enable=\e"no\e"" >>%{prefix}/etc/rc.conf
387 \& fi
388 \&
389 \& $ openpkg stack \-v4 \e
390 \& \-Dprefix=/v/xamp \-Duser=xamp\-sw \-Dgroup=xamp\-sw \e
391 \& \-\-unversioned xamp.stk
392 \&
393 \& $ openpkg sea \-o xamp.src.sh xamp.sh xamp.src.d/
394 \&
395 \& $ sh xamp.src.sh \-v4 \-S sudo
396 \&
397 \& $ openpkg sea \-o xamp.bin.sh xamp.sh xamp.*\-*.d/
398 .Ve
399 .SH "HISTORY"
400 .IX Header "HISTORY"
401 The \fBopenpkg stack\fR command was implemented in April 2012 by \fIRalf S. Engelschall\fR
402 <rse@engelschall.com> for the OpenPKG Framework of the OpenPKG GmbH.