diff -r 71503088f51b -r f880f219c566 openpkg/dev.pod
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/openpkg/dev.pod	Tue Jul 31 12:23:42 2012 +0200
@@ -0,0 +1,543 @@
+##
+##  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
+