OpenPKG Specs: openpkg/dev.pod@a2c6460cfb16 (annotated)

openpkg/dev.pod@a2c6460cfb16 (annotated)

openpkg/dev.pod

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.

 ##
 ##  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

OpenPKG Specs / annotate

openpkg/dev.pod@a2c6460cfb16 (annotated)

openpkg/dev.pod