OpenPKG Specs / file revision

 ##

 ##  openpkg dev -- OpenPKG Package Development Tool

 ##  Copyright (c) 2008-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

 B<openpkg dev> - OpenPKG Package Development Tool

 =head1 DESCRIPTION

 B<openpkg dev> is a package development tool for B<OpenPKG>.

 =head2 SOURCE PACKAGE HANDLING

 =over 4

 =item B<openpkg dev unpack>

 [C<-l> I<layout>]

 [C<-b> I<basedir>]

 [C<-s>]

 [C<-d>]

 I<name>C<->I<version>C<->I<release>C<.src.rpm>

 Unpacks an OpenPKG source RPM package

 I<name>C<->I<version>C<->I<release>C<.src.rpm> into I<basedir>

 (default is I<name>C<->I<version>C<->I<release>)

 using I<layout> (default is I<structured>).

 Additionally,

 I<file-rpmmacros>

 configuration file is generated where

 C<-s> enables shared mode and

 C<-d> enables debug mode, see I<file-rpmmacros>.

 =back

 =head2 SOURCE PACKAGE DEVELOPMENT

 =over 4

 =item B<openpkg dev shell>

 This is a convenience command which enters an interactive B<GNU Bash>

 shell which provides the following work environment:

 =over 4

 =item B<Environment Variables:>

  OPENPKG_PREFIX "<prefix>"

  PS1            "\\[\\e[31;1m\\]\\u\\[\\e[0m\\]@\\h:\\w [OPENPKG_PREFIX=$OPENPKG_PREFIX]\n\\\$ "

  T              %{_tmppath}

  S              %{_specdir}

  D              %{_sourcedir}

 =item B<Command-Line Aliases:>

  openpkg        "${OPENPKG_PREFIX}/bin/openpkg"

  opd            "${OPENPKG_PREFIX}/bin/openpkg dev"

 =item B<Command-Line Keystrokes:>

  ESC+x          "opd unpack\n"

  ESC+v          "opd edit\n"

  ESC+t          "opd build -s track\n"

  ESC+f          "opd build -s fetch\n"

  ESC+b          "opd build\n"

  ESC+1          "opd build -s prep\n"

  ESC+2          "opd build -s compile\n"

  ESC+3          "opd build -s install\n"

  ESC+4          "opd build -s binary\n"

  ESC+s          "opd build -s source\n"

  ESC+p          "opd peek\n"

  ESC+d          "opd diff\n"

  ESC+i          "opd install\n"

  ESC+e          "opd erase\n"

  ESC+l          "opd lint\n"

  ESC+r          "opd release\n"

 =back

 If option C<-s> is passed to B<openpkg dev shell> and screen(1) is

 available in C<$PATH>, the interactive development shell is started up

 in a convenient virtual screen environment.

 =item B<openpkg dev edit>

 Load spec file into editor.

 =over 4

 =item B<Environment Variables:>

  EDITOR "vi"

 =back

 =item B<openpkg dev build>

 [C<-s> I<step>]

 [C<-D> I<define>[=I<value>]]

 [C<-w> I<variant>]

 Builds package steps. Default I<step> is C<all>. Option C<-D> translated

 into "C<--define 'I<define> I<value>'>" while option C<-w> translated

 into "C<--with> I<variant>". The I<step> arguments translate into the

 following RPM options:

   track:   -bt

   fetch:   -bf

   prep:    -bp

   compile: -bc --short-circuit

   install: -bi --short-circuit

   binary:  -bb --short-circuit

   source:  -bs

   all:     -ba

 =item B<openpkg dev peek>

 Peeks file list from package and tags configuration and documentation files.

 =item B<openpkg dev diff>

 Shows modifications with the help of a possibly underlying Version

 Control System (VCS) like CVS, Subversion, Monotone, Git, Mercurial or

 (as a fallback ) OSSP svs.

 =item B<openpkg dev install>

 [C<-f>]

 [C<-o>]

 [C<-n>]

 [C<-s>]

 Installs package.

 Option

 C<-f> adds C<--force>,

 C<-n> adds C<--nodeps> and

 C<-o> adds C<--oldpackage>

 to the underlying C<rpm> call.

 Option C<-s> prefixes the command with sudo(1).

 =item B<openpkg dev erase>

 [C<-f>]

 [C<-o>]

 [C<-a>]

 [C<-s>]

 Erases package.

 Option

 C<-f> adds C<--force>,

 C<-n> adds C<--nodeps> and

 C<-a> adds C<--allmatches>

 to the underlying C<rpm> call.

 Option C<-s> prefixes the command with sudo(1).

 =item B<openpkg dev lint>

 [C<-v>]

 [C<-b>]

 Lints package sources C<*.spec>, C<fsl.*>, C<rc.*> and binary package files.

 Option C<-v> enables verboseness.

 Option C<-b> disables the linting of an existing binary package file.

 =item B<openpkg dev release>

 [C<-m> I<message>]

 [C<-n>]

 Releases package specification to the repository. Unlike previous

 incarnations of "openpkg dev" this one is not tied to any repository or

 structure. The default message is created using the difference between

 the previous and current version of the package specification. In order

 to grab the previous version, the working directory and three levels

 towards root are checked for signs of CVS, Subversion, Monotone, Git,

 Mercurial or SVS information, in that order. The appropriate command is

 then executed to retrieve the data and the VCS found is passed to the

 actual release command.

 Finally, the command specified by the environment variable

 C<OPENPKG_DEV_RELEASE> or, if omitted, specified by the rpm macro

 C<%{openpkg_dev_release}> is run and passed the following positional

 arguments:

 =over 4

 	openpkg-prefix

 	spec-dir

 	source-dir

 	binary-rpm-file

 	source-rpm-file

 	package-name

 	package-version

 	package-release

 	package-version-old

 	package-release-old

 	commit-message

 	vcs

 =back

 For a dry run, set C<$OPENPKG_DEV_RELEASE> to "echo" or use option "C<-n>".

 =back

 =head1 UNPACKED SOURCE RPM PACKAGE FILESYSTEM LAYOUT

 When an OpenPKG source RPM package

 I<name>C<->I<version>C<->I<release>C<.src.rpm> is unpacked to the

 filesystem, the following distinct filesystem layouts are known:

 =over 4

 =item B<global>

 =over 4

 =item I<prefix>C</RPM/SRC/>I<name>C</.openpkg/rpmmacros>

 =item I<prefix>C</RPM/SRC/>I<name>C</>I<name>C<.spec>

 =item I<prefix>C</RPM/SRC/>I<name>C</>I<packaging-source-file>

 =item I<prefix>C</RPM/SRC/>I<name>C</>I<thirdparty-distribution-file>

 =item I<prefix>C</RPM/PKG/>I<binary-rpm-package-file>

 =item I<prefix>C</RPM/PKG/>I<source-rpm-package-file>

 =item I<prefix>C</RPM/TMP/>I<temporary-file>

 =back

 This is just the "simple" filesystem layout (see below) with the

 I<base-dir> set to I<prefix>C</RPM/SRC/>.

 This is the filesystem layout used by default for building OpenPKG

 packages during C<openpkg build> or the underlying C<openpkg rpm

 --rebuild> commands.

 =item B<local>

 =over 4

 =item I<base-dir>C</.openpkg/rpmmacros>

 =item I<base-dir>C</>I<name>C<.spec>

 =item I<base-dir>C</>I<packaging-source-file>

 =item I<base-dir>C</>I<thirdparty-distribution-file>

 =item I<base-dir>C</>I<binary-rpm-package-file>

 =item I<base-dir>C</>I<source-rpm-package-file>

 =item I<base-dir>C</>I<temporary-file>

 =back

 This puts everything into one directory.

 =item B<simple>

 =over 4

 =item I<base-dir>C</>I<name>C</.openpkg/rpmmacros>

 =item I<base-dir>C</>I<name>C</>I<name>C<.spec>

 =item I<base-dir>C</>I<name>C</>I<packaging-source-file>

 =item I<base-dir>C</>I<name>C</>I<thirdparty-distribution-file>

 =item I<base-dir>C</>I<binary-rpm-package-file>

 =item I<base-dir>C</>I<source-rpm-package-file>

 =item I<$TMPDIR>C</openpkg/>I<temporary-file>

 =back

 This is the simple filesystem layout of an unpacked

 OpenPKG package. All files are simply put into a sub-directory with the

 I<name> of the package.

 This is the filesystem layout used for the quick patching of a single

 OpenPKG package in a stand-alone environment.

 =item B<structured>

 =over 4

 =item I<base-dir>C</>I<name>C</.openpkg/rpmmacros>

 =item I<base-dir>C</>I<name>C</src/>I<name>C<.spec>

 =item I<base-dir>C</>I<name>C</src/>I<packaging-source-file>

 =item I<base-dir>C</>I<name>C</dst/>I<thirdparty-distribution-file>

 =item I<base-dir>C</>I<name>C</pkg/>[C<bin/>]I<binary-rpm-package-file>

 =item I<base-dir>C</>I<name>C</pkg/>[C<src/>]I<source-rpm-package-file>

 =item I<base-dir>C</>I<name>C</tmp/>I<temporary-file>

 =back

 This is the structured (and default) filesystem layout of an unpacked

 OpenPKG package. A top-level sub-directory with the I<name> of the

 package is created. There the package specification and all packaging

 source files are put into the sub-directory I<src> and all the

 third-party distribution files are put into the sub-directory I<dst>.

 This is the filesystem layout used for the development of a single

 OpenPKG package in a stand-alone environment.

 =item B<distributed>

 =over 4

 =item I<base-dir>C</>C<.openpkg/rpmmacros>

 =item I<base-dir>C</>C<src/>I<name>C</>I<name>C<.spec>

 =item I<base-dir>C</>C<src/>I<name>C</>I<packaging-source-file>

 =item I<base-dir>C</>C<dst/>I<name>C</>I<thirdparty-distribution-file>

 =item I<base-dir>C</>C<pkg/>[C<bin/>]I<binary-rpm-package-file>

 =item I<base-dir>C</>C<pkg/>[C<src/>]I<source-rpm-package-file>

 =item I<base-dir>C</>C<tmp/>I<temporary-file>

 =back

 This is the distributed filesystem layout of an unpacked OpenPKG

 package. It is similar to the structured filesystem layout but the

 C<src> and C<dst> directories and the I<name> directory are swapped,

 mainly with the intention of bundling together all third-party

 distribution files of a large number of packages.

 This is the filesystem layout used for regular OpenPKG package

 development.

 =back

 =head1 LOCAL RPM MACROS FILE (.openpkg/rpmmacros)

 OpenPKG supports local RPM macros files F<.openpkg/rpmmacros> which

 can be used to configure RPM in a local scope. This is especially

 interesting to configure a local (even per-package) build environment

 with the help of the C<%openpkg_layout> macro.

 C<%openpkg_layout>

 [C<macrosfile=>I<filename>]

 [C<basedir=>I<directory>]

 [C<specdir=>I<directory>]

 [C<sourcedir=>I<directory>]

 [C<builddir=>I<directory>]

 [C<tmpdir=>I<directory>]

 [C<binrpmdir=>I<directory>]

 [C<srcrpmdir=>I<directory>]

 [C<shared=>I<yes-or-no>]

 [C<debug=>I<yes-or-no>]

 =over 4

 =item C<macrosfile=>I<filename>

 Absolute file path of the C<.openpkg/rpmmacros> file where this

 C<%openpkg_layout> macro is defined. Usually, the intended usage is to

 leverage from OpenPKG RPM's special C<%{macrosfile}> macro by simply

 using C<macrosfile=%{macrosfile}>. This parameter is important as

 the default C<basename> is derived from it.

 =item C<basedir=>I<directory>

 Absolute directory path where the C<.openpkg/rpmmacros> file is

 located under. Usually, the intended usage is to not explicitly

 set this parameter but let it be determined indirectly via

 C<macrosfile>. The effective default value is equal to a value like

 C<%{realpath:%{dirname:%{realpath:%{macrosfile}}}/..}> This parameter is

 important as all standard filesystem layouts (see parameter C<layout>)

 are always at least partially based on this base directory in order

 to provide absolute-path-independent flexible filesystem layouts.

 =item C<layout=>I<layout>

 The name of the filesystem layout type to use. The following standard

 filesystem layout types are pre-defined: C<global>, C<local>, C<simple>,

 C<structured> (default) and C<distributed>.

  global      macrosdir   <openpkg_prefix>/etc/openpkg

  global      macrosfile  <openpkg_prefix>/etc/openpkg/rpmmacros

  global      specdir     <openpkg_prefix>/RPM/SRC/$name

  global      sourcedir   <openpkg_prefix>/RPM/SRC/$name

  global      builddir    <openpkg_prefix>/RPM/TMP

  global      tmpdir      <openpkg_prefix>/RPM/TMP

  global      binrpmdir   <openpkg_prefix>/RPM/PKG

  global      srcrpmdir   <openpkg_prefix>/RPM/PKG

  local       macrosdir   <basedir>/.openpkg

  local       macrosfile  <basedir>/.openpkg/rpmmacros

  local       specdir     <basedir>

  local       sourcedir   <basedir>

  local       builddir    <basedir>

  local       tmpdir      <basedir>

  local       binrpmdir   <basedir>

  local       srcrpmdir   <basedir>

  simple      macrosdir   <basedir>/.openpkg

  simple      macrosfile  <basedir>/.openpkg/rpmmacros

  simple      specdir     <basedir>

  simple      sourcedir   <basedir>

  simple      builddir    <tmpdir>

  simple      tmpdir      <tmpdir>

  simple      binrpmdir   <basedir>/..

  simple      srcrpmdir   <basedir>/..

  structured  macrosdir   <basedir>/.openpkg

  structured  macrosfile  <basedir>/.openpkg/rpmmacros

  structured  specdir     <basedir>/src

  structured  sourcedir   <basedir>/dst

  structured  builddir    <basedir>/tmp

  structured  tmpdir      <basedir>/tmp

  structured  binrpmdir   <basedir>/pkg/bin

  structured  srcrpmdir   <basedir>/pkg/src

  distributed macrosdir   <basedir>/.openpkg

  distributed macrosfile  <basedir>/.openpkg/rpmmacros

  distributed specdir     <basedir>/src/<name>

  distributed sourcedir   <basedir>/dst/<name>

  distributed builddir    <basedir>/tmp

  distributed tmpdir      <basedir>/tmp

  distributed binrpmdir   <basedir>/pkg/bin

  distributed srcrpmdir   <basedir>/pkg/src

 =item C<specdir=>I<directory-list>

 =item C<sourcedir=>I<directory-list>

 =item C<builddir=>I<directory-list>

 =item C<tmpdir=>I<directory-list>

 =item C<binrpmdir=>I<directory-list>

 =item C<srcrpmdir=>I<directory-list>

 These parameters correspond to the six individual directories provided

 by a standard layout and allow you to selectively adjust parts of a

 standard layout to local needs and without having to define a full

 standard layout yourself.

 The I<directory-list> is a whitespace-separated list of

 I<directory>[C<:>[C<+>]I<directory>] specifications which are

 "first-match" searched for existence. The last directory in the list

 is always taken as the fallback and if it is not existing it is

 even created on-the-fly. The I<directory-check>C<:>I<directory-use>

 syntax variant allows the existence test to use I<directory-check>,

 but expands to I<directory-use> (replace mode). The

 I<directory-check>C<:+>I<directory-use> syntax variant allows

 the existence test to use I<directory-check>, but expands to

 I<directory-check>I<directory-use> (append mode). For instance

 C<tmpdir="%{getenv:HOME)/tmp:+/openpkg %{getenv:TMPDIR}:+/openpkg

 /tmp/%(echo $LOGNAME)/openpkg"> will first check for ~/tmp (and then use

 ~/tmp/openpkg), then for $TMPDIR (and use $TMPDIR/openpkg) and finally

 it will use /tmp/$LOGNAME/openpkg at last resort.

 Paths are usually assembled by using RPM macros like

 C<%{l_prefix}> (the instance prefix), C<%{__openpkg_basename}> (the

 I<basename> parameter), C<%{realpath:<path>} (path resolution),

 C<%{dirname:<path>} (directory name extraction), C<%{basename:<path>}

 (file name extraction), etc.

 =item C<shared=>I<yes-or-no>

 This enables the I<subdir> components in the standard filesystem

 layouts by setting it to an automatically generated sub-directory named

 I<host>C<->I<arch>-I<os>. This allows one to build the same OpenPKG

 package in parallel on multiple hosts in a shared environment (usually

 on an NFS based filesystem).

 =item C<debug=>I<yes-or-no>

 This enables debug outputs which shows the effectively used directory

 paths.

 =back

 The generated C<.openpkg/rpmmacros> file contains the generic filesystem

 layout glue configuration for the particular filesystem I<layout>.

 =over 1

 =item C<%openpkg_layout  macrosfile=%{macrosfile} layout=>I<type>

 =back

 =head1 CONFIGURATION

 =over 4

  OPENPKG_NAME="Ralf S. Engelschall"

  OPENPKG_MAIL="rse@openpkg.net"

  OPENPKG_MODE="developer"

  OPENPKG_PREFIX="/openpkg"

  OPENPKG_TMPDIR="${TMPDIR-/tmp}/openpkg"

  OPENPKG_VCS="cvs ci -m '<msg>' ."

  OPENPKG_UPLD="scp <srpm> openpkg-ftp@ftp.openpkg.org:/current/SRC/00UPLOAD/"

 =back

 =head1 ABOUT

 OpenPKG B<dev> is Ralf S. Engelschall's Perl-based clean-room partial

 re-implementation of 2008 for OpenPKG 4.0 of Thomas Lotterer's original

 OpenPKG B<dev> Bash-based shell from 2002.

 =cut