comparison: openpkg/stack.pod
openpkg/stack.pod
- changeset 700
- 2164082fa57f
equal
deleted
inserted
replaced
| -1:000000000000 | 0:5cb118930738 |
|---|---|
| 1 ## | |
| 2 ## OpenPKG Software Stack Generation Utility | |
| 3 ## Copyright (c) 2012 OpenPKG GmbH <http://openpkg.com/> | |
| 4 ## | |
| 5 ## This software is property of the OpenPKG GmbH, DE MUC HRB 160208. | |
| 6 ## All rights reserved. Licenses which grant limited permission to use, | |
| 7 ## copy, modify and distribute this software are available from the | |
| 8 ## OpenPKG GmbH. | |
| 9 ## | |
| 10 ## THIS SOFTWARE IS PROVIDED "AS IS" AND ANY EXPRESSED OR IMPLIED | |
| 11 ## WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF | |
| 12 ## MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. | |
| 13 ## IN NO EVENT SHALL THE AUTHORS AND COPYRIGHT HOLDERS AND THEIR | |
| 14 ## CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, | |
| 15 ## SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT | |
| 16 ## LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF | |
| 17 ## USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND | |
| 18 ## ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, | |
| 19 ## OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT | |
| 20 ## OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | |
| 21 ## SUCH DAMAGE. | |
| 22 ## | |
| 23 | |
| 24 =pod | |
| 25 | |
| 26 =head1 NAME | |
| 27 | |
| 28 B<openpkg stack> - B<OpenPKG Software Stack Generation> | |
| 29 | |
| 30 =head1 SYNOPSIS | |
| 31 | |
| 32 B<openpkg stack> | |
| 33 [B<-h>|B<--help>] | |
| 34 [B<-v>|B<--verbose> I<level>] | |
| 35 [B<-o>|B<--output> I<dir>] | |
| 36 [B<-D>|B<--define> I<name>=I<value> ...] | |
| 37 [B<-u>|B<--unversioned>] | |
| 38 [B<-q>|B<--query>] | |
| 39 F<I<name>.stk> | |
| 40 | |
| 41 =head1 DESCRIPTION | |
| 42 | |
| 43 The B<openpkg stack> command reads a OpenPKG software stack definition | |
| 44 F<I<name>.stk>, generates a OpenPKG software stack deployment script | |
| 45 F<I<name>[-I<version>-I<release>].sh>, determines, downloads and | |
| 46 stores all required corresponding OpenPKG source packages under | |
| 47 F<I<name>[-I<version>-I<release>].src.d/*.src.{sh,rpm}>. | |
| 48 | |
| 49 On executing the generated OpenPKG software stack deployment | |
| 50 script F<I<name>[-I<version>-I<release>].sh>, an OpenPKG | |
| 51 instance is created (or reused if existing), all packages | |
| 52 built and installed in topologically correct dependency order | |
| 53 and the resulting OpenPKG binary packages stored as | |
| 54 F<I<name>[-I<version>-I<release>].I<platform>-I<tag>.d/*.{sh,rpm}>. | |
| 55 | |
| 56 The main design decisions and intentions of OpenPKG software stacks are: | |
| 57 | |
| 58 =over 4 | |
| 59 | |
| 60 =item 1. | |
| 61 | |
| 62 OpenPKG software stacks can be centrally defined in a single file | |
| 63 F<I<name>.stk>, similar to the definition of OpenPKG software packages in | |
| 64 F<I<name>.spec> files. This definition includes both OpenPKG framework | |
| 65 bootstrap parameters, OpenPKG package build parameters and OpenPKG | |
| 66 software stack specific deployment-time prolog and epilog scripts. | |
| 67 | |
| 68 =item 2. | |
| 69 | |
| 70 OpenPKG software stacks depend on particular OpenPKG software packages | |
| 71 (and perhaps even their particular versions) and by downloading and | |
| 72 locally storing all relevant OpenPKG software packages an OpenPKG | |
| 73 software stack remains stable and self-contained -- even if new versions | |
| 74 of OpenPKG software packages are released. | |
| 75 | |
| 76 =item 3. | |
| 77 | |
| 78 For generating the OpenPKG software stack files, an OpenPKG instance | |
| 79 and its B<openpkg stack> command is required, but executing the OpenPKG | |
| 80 software stack deployment script does NOT require any pre-existing | |
| 81 OpenPKG instances. | |
| 82 | |
| 83 =item 4. | |
| 84 | |
| 85 By wrapping F<I<name>[-I<version>-I<release>].sh> and | |
| 86 F<I<name>[-I<version>-I<release>].src.d/> into a I<Shell Execution | |
| 87 Archive> F<I<name>[-I<version>-I<release>].src.sh> with the B<openpkg | |
| 88 sea> command, you can provide a single self-contained file for building | |
| 89 and installing an OpenPKG software stack from OpenPKG source packages. | |
| 90 | |
| 91 =item 5. | |
| 92 | |
| 93 By wrapping F<I<name>[-I<version>-I<release>].sh> and | |
| 94 F<I<name>[-I<version>-I<release>].I<platform>-I<tag>.d/> | |
| 95 into a I<Shell Execution Archive> | |
| 96 F<I<name>[-I<version>-I<release>].I<platform>-I<tag>.sh> with the | |
| 97 B<openpkg sea> command, you can provide a single self-contained file for | |
| 98 installing an OpenPKG software stack from OpenPKG binary packages. | |
| 99 | |
| 100 =back | |
| 101 | |
| 102 =head1 COMMAND-LINE OPTIONS AND ARGUMENTS | |
| 103 | |
| 104 =over 4 | |
| 105 | |
| 106 =item B<-h>|B<--help> | |
| 107 | |
| 108 Just shows a short usage information for the B<openpkg stack> command. | |
| 109 | |
| 110 =item B<-v>|B<--verbose> I<level> | |
| 111 | |
| 112 Sets the verbosity level for outputs, from C<0> (no output at all) to 4 | |
| 113 (all possible outputs). The default is C<4>. | |
| 114 | |
| 115 =item B<-o>|B<--output> I<dir> | |
| 116 | |
| 117 The output directory for the OpenPKG software stack files. | |
| 118 The default is the current directory (F<.>). | |
| 119 | |
| 120 =item [B<-D>|B<--define> I<name>=I<value> ...] | |
| 121 | |
| 122 On-the-fly overrides the value of option macro C<%{I<name>}> with | |
| 123 I<value>. Use this to generate a variant of an OpenPKG software stack | |
| 124 without modifying the software stack definition file. | |
| 125 | |
| 126 =item [B<-u>|B<--unversioned>] | |
| 127 | |
| 128 By default B<openpkg stack> creates the file | |
| 129 C<I<name>-I<version>-I<release>.sh> (deployment script) and the | |
| 130 directory C<I<name>-I<version>-I<release>.src.d/> (source packages). | |
| 131 With this option the names are C<I<name>.sh> and C<I<name>.src.d/> only. | |
| 132 | |
| 133 =item [B<-q>|B<--query>] | |
| 134 | |
| 135 Forces a different operation mode where a shell script is output | |
| 136 on F<stdout> containing variable definitions in the format | |
| 137 C<I<name>="I<value>";> with information about the software stack | |
| 138 definition. The provided variable names are C<name>, C<summary>, | |
| 139 C<packager>, C<version> and C<release> for the corresponding headers, | |
| 140 plus variables for all defined software stack options (see C<%option> | |
| 141 section below). | |
| 142 | |
| 143 =item I<name>F<.stk> | |
| 144 | |
| 145 The mandatory OpenPKG software stack definition file. | |
| 146 See below under B<SOFTWARE STACK DEFINITION> for details. | |
| 147 | |
| 148 =back | |
| 149 | |
| 150 =head1 SOFTWARE STACK DEFINITION | |
| 151 | |
| 152 An OpenPKG software stack is defined by a configuration file | |
| 153 containing headers (C<Foo:>) and sections (<%foo>). | |
| 154 | |
| 155 =head2 Configuration Headers | |
| 156 | |
| 157 =over 4 | |
| 158 | |
| 159 =item B<Name> | |
| 160 | |
| 161 The name of the OpenPKG software stack. Also used as a prefix for many | |
| 162 files. Should match the regular expression C<^[a-z][a-zA-Z0-9]+>, | |
| 163 although this is not enforced. Example: C<Name: example>. | |
| 164 | |
| 165 =item B<Summary> | |
| 166 | |
| 167 A single line, shortly summarizing the purpose of the OpenPKG software | |
| 168 stack. Example: C<Summary: Example Stack>. | |
| 169 | |
| 170 =item B<Packager> | |
| 171 | |
| 172 Name of the packager of the OpenPKG software software stack. | |
| 173 Example: C<Packager: OpenPKG GmbH>. | |
| 174 | |
| 175 =item B<Version> | |
| 176 | |
| 177 Version identifier of the OpenPKG software stack. Describes the | |
| 178 I<logical> revision of the software stack definition. Should match the | |
| 179 regular expression C<^[0-9]+\.[0-9]\.[0-9]+$>, although this is not | |
| 180 enforced. Example: C<Version: 1.0.0>. | |
| 181 | |
| 182 =item B<Release> | |
| 183 | |
| 184 Release identifier of the OpenPKG software stack. Describes the | |
| 185 I<physical> revision of the stack definition. Should be in the format | |
| 186 C<YYYYMMDD> and hence match the regular expression C<^[0-9]{8}$>, | |
| 187 although this is not enforced. Example: C<Release: 20120101>. | |
| 188 | |
| 189 =back | |
| 190 | |
| 191 =head2 Configuration Sections | |
| 192 | |
| 193 =over 4 | |
| 194 | |
| 195 =item B<%options> | |
| 196 | |
| 197 Zero or more options for the OpenPKG software stack, one per line, in | |
| 198 the format "I<name> I<default-value>". Options can be overridden on | |
| 199 the command-line with B<-D>I<name>=I<value>. Example: C<with_ssl yes>. | |
| 200 Option values can be expanded in all headers and sections through the | |
| 201 following constructs: | |
| 202 | |
| 203 =over 4 | |
| 204 | |
| 205 =item C<%{I<name>}> | |
| 206 | |
| 207 Expand to the value of option I<name>. | |
| 208 | |
| 209 =item C<%{?I<name>:I<value>}> | |
| 210 | |
| 211 Expand to I<value> if option I<name> is defined. | |
| 212 | |
| 213 =item C<%{!?I<name>:I<value>}> | |
| 214 | |
| 215 Expand to I<value> if option I<name> is NOT defined. | |
| 216 | |
| 217 =back | |
| 218 | |
| 219 =item B<%description> | |
| 220 | |
| 221 A single textual paragraph describing the purpose of the OpenPKG | |
| 222 software stack in more detail than header C<Summary>. | |
| 223 | |
| 224 =item B<%framework> | |
| 225 | |
| 226 The command-line parameters passed to the OpenPKG framework | |
| 227 bootstrap source shell package F<openpkg-*.src.sh>. Usually at | |
| 228 least the parameters B<--prefix=>I<path>, B<--user=>I<username>, | |
| 229 B<--group=>I<groupname> and B<--tag=>I<tagname> are given here. In order | |
| 230 to allow an OpenPKG software stack to be easily reused one creates | |
| 231 the options (see C<%option> above) named C<prefix>, C<user>, C<group> | |
| 232 and C<tag> and then use C<--prefix=%{prefix}>, C<--user=%{user}>, | |
| 233 C<--group=%{group}> and C<--tag=%{tag}> in this C<%framework> section. | |
| 234 | |
| 235 =item B<%packages> | |
| 236 | |
| 237 The packages to build and install for the OpenPKG software stack, in | |
| 238 the format of "B<-DI<package>::I<option>=I<value>>" and "I<package>" | |
| 239 specifications as understood by the C<openpkg build> tool. Example: | |
| 240 C<-Dapache::with_mod_ssl=yes -Dapache-php::with_json=yes apache | |
| 241 apache-php>. | |
| 242 | |
| 243 =item B<%prolog> | |
| 244 | |
| 245 A shell script executed before installation of all packages. | |
| 246 The variable C<$prefix> is available to access the | |
| 247 OpenPKG software stack without having to hard-code a path. | |
| 248 | |
| 249 =item B<%epilog> | |
| 250 | |
| 251 A shell script executed after installation of all packages. This | |
| 252 is usually used for applying OpenPKG software stack specific | |
| 253 configurations. The variable C<$prefix> is available to access the | |
| 254 OpenPKG software stack without having to hard-code a path. Example: | |
| 255 C<echo "openldap_enable=no" E<gt>E<gt>$prefix/etc/rc.conf>. | |
| 256 | |
| 257 =back | |
| 258 | |
| 259 =head1 EXAMPLES | |
| 260 | |
| 261 $ cat xamp.stk | |
| 262 | |
| 263 Name: xamp | |
| 264 Summary: Apache-MySQL-PHP Server | |
| 265 Packager: OpenPKG GmbH | |
| 266 Version: 1.0.0 | |
| 267 Release: 20120407 | |
| 268 | |
| 269 %description | |
| 270 This software stack contains a so-called xAMP web stack, consisting | |
| 271 of the major components Apache, MySQL and PHP. | |
| 272 | |
| 273 %options | |
| 274 repo http://download.openpkg.org/stacks/current/source/ | |
| 275 prefix /xamp | |
| 276 user xamp | |
| 277 group xamp | |
| 278 tag xamp | |
| 279 with_ldap no | |
| 280 with_ssl no | |
| 281 addr 127.0.0.1 | |
| 282 | |
| 283 %repository | |
| 284 %{repo} | |
| 285 | |
| 286 %framework | |
| 287 --prefix=%{prefix} | |
| 288 --user=%{user} | |
| 289 --group=%{group} | |
| 290 --tag=%{tag} | |
| 291 | |
| 292 %packages | |
| 293 -D apache::with_mod_dav=yes | |
| 294 -D apache::with_mod_deflate=yes | |
| 295 -D apache::with_mod_ldap=%{with_ldap} | |
| 296 -D apache::with_mod_proxy=yes | |
| 297 -D apache::with_mod_ssl=%{with_ssl} | |
| 298 -D apache-php::with_curl=yes | |
| 299 -D apache-php::with_freetype=yes | |
| 300 -D apache-php::with_gd=yes | |
| 301 -D apache-php::with_iconv=yes | |
| 302 -D apache-php::with_json=yes | |
| 303 -D apache-php::with_mbregex=yes | |
| 304 -D apache-php::with_mbstring=yes | |
| 305 -D apache-php::with_mysql=yes | |
| 306 -D apache-php::with_openldap=%{with_ldap} | |
| 307 -D apache-php::with_session=yes | |
| 308 -D apache-php::with_simplexml=yes | |
| 309 -D apache-php::with_sqlite=yes | |
| 310 -D apache-php::with_ssl=%{with_ssl} | |
| 311 -D apache-php::with_xml=yes | |
| 312 -D apache-php::with_zlib=yes | |
| 313 apache | |
| 314 apache-php | |
| 315 mysql | |
| 316 | |
| 317 %epilog | |
| 318 shtool subst \ | |
| 319 -e 's;127\.0\.0\.1:%{addr};g' \ | |
| 320 %{prefix}/etc/apache/apache.conf | |
| 321 if [ ".%{with_ldap}" = .yes ]; then | |
| 322 echo "openldap_enable=\"no\"" >>%{prefix}/etc/rc.conf | |
| 323 fi | |
| 324 | |
| 325 $ openpkg stack -v4 \ | |
| 326 -Dprefix=/v/xamp -Duser=xamp-sw -Dgroup=xamp-sw \ | |
| 327 --unversioned xamp.stk | |
| 328 | |
| 329 $ openpkg sea -o xamp.src.sh xamp.sh xamp.src.d/ | |
| 330 | |
| 331 $ sh xamp.src.sh -v4 -S sudo | |
| 332 | |
| 333 $ openpkg sea -o xamp.bin.sh xamp.sh xamp.*-*.d/ | |
| 334 | |
| 335 =head1 HISTORY | |
| 336 | |
| 337 The B<openpkg stack> command was implemented in April 2012 by I<Ralf S. Engelschall> | |
| 338 E<lt>rse@engelschall.comE<gt> for the OpenPKG Framework of the OpenPKG GmbH. | |
| 339 | |
| 340 =cut | |
| 341 |
