michael@428: ##
michael@428: ## openpkg dev -- OpenPKG Package Development Tool
michael@428: ## Copyright (c) 2008-2012 OpenPKG GmbH
michael@428: ##
michael@428: ## This software is property of the OpenPKG GmbH, DE MUC HRB 160208.
michael@428: ## All rights reserved. Licenses which grant limited permission to use,
michael@428: ## copy, modify and distribute this software are available from the
michael@428: ## OpenPKG GmbH.
michael@428: ##
michael@428: ## THIS SOFTWARE IS PROVIDED "AS IS" AND ANY EXPRESSED OR IMPLIED
michael@428: ## WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
michael@428: ## MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
michael@428: ## IN NO EVENT SHALL THE AUTHORS AND COPYRIGHT HOLDERS AND THEIR
michael@428: ## CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
michael@428: ## SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
michael@428: ## LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
michael@428: ## USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
michael@428: ## ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
michael@428: ## OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
michael@428: ## OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
michael@428: ## SUCH DAMAGE.
michael@428: ##
michael@428:
michael@428: =pod
michael@428:
michael@428: B - OpenPKG Package Development Tool
michael@428:
michael@428: =head1 DESCRIPTION
michael@428:
michael@428: B is a package development tool for B.
michael@428:
michael@428: =head2 SOURCE PACKAGE HANDLING
michael@428:
michael@428: =over 4
michael@428:
michael@428: =item B
michael@428: [C<-l> I]
michael@428: [C<-b> I]
michael@428: [C<-s>]
michael@428: [C<-d>]
michael@428: IC<->IC<->IC<.src.rpm>
michael@428:
michael@428: Unpacks an OpenPKG source RPM package
michael@428: IC<->IC<->IC<.src.rpm> into I
michael@428: (default is IC<->IC<->I)
michael@428: using I (default is I).
michael@428: Additionally,
michael@428: I
michael@428: configuration file is generated where
michael@428: C<-s> enables shared mode and
michael@428: C<-d> enables debug mode, see I.
michael@428:
michael@428: =back
michael@428:
michael@428: =head2 SOURCE PACKAGE DEVELOPMENT
michael@428:
michael@428: =over 4
michael@428:
michael@428: =item B
michael@428:
michael@428: This is a convenience command which enters an interactive B
michael@428: shell which provides the following work environment:
michael@428:
michael@428: =over 4
michael@428:
michael@428: =item B
michael@428:
michael@428: OPENPKG_PREFIX ""
michael@428: PS1 "\\[\\e[31;1m\\]\\u\\[\\e[0m\\]@\\h:\\w [OPENPKG_PREFIX=$OPENPKG_PREFIX]\n\\\$ "
michael@428: T %{_tmppath}
michael@428: S %{_specdir}
michael@428: D %{_sourcedir}
michael@428:
michael@428: =item B
michael@428:
michael@428: openpkg "${OPENPKG_PREFIX}/bin/openpkg"
michael@428: opd "${OPENPKG_PREFIX}/bin/openpkg dev"
michael@428:
michael@428: =item B
michael@428:
michael@428: ESC+x "opd unpack\n"
michael@428: ESC+v "opd edit\n"
michael@428: ESC+t "opd build -s track\n"
michael@428: ESC+f "opd build -s fetch\n"
michael@428: ESC+b "opd build\n"
michael@428: ESC+1 "opd build -s prep\n"
michael@428: ESC+2 "opd build -s compile\n"
michael@428: ESC+3 "opd build -s install\n"
michael@428: ESC+4 "opd build -s binary\n"
michael@428: ESC+s "opd build -s source\n"
michael@428: ESC+p "opd peek\n"
michael@428: ESC+d "opd diff\n"
michael@428: ESC+i "opd install\n"
michael@428: ESC+e "opd erase\n"
michael@428: ESC+l "opd lint\n"
michael@428: ESC+r "opd release\n"
michael@428:
michael@428: =back
michael@428:
michael@428: If option C<-s> is passed to B and screen(1) is
michael@428: available in C<$PATH>, the interactive development shell is started up
michael@428: in a convenient virtual screen environment.
michael@428:
michael@428: =item B
michael@428:
michael@428: Load spec file into editor.
michael@428:
michael@428: =over 4
michael@428:
michael@428: =item B
michael@428:
michael@428: EDITOR "vi"
michael@428:
michael@428: =back
michael@428:
michael@428: =item B
michael@428: [C<-s> I]
michael@428: [C<-D> I[=I]]
michael@428: [C<-w> I]
michael@428:
michael@428: Builds package steps. Default I is C. Option C<-D> translated
michael@428: into "C<--define 'I I'>" while option C<-w> translated
michael@428: into "C<--with> I". The I arguments translate into the
michael@428: following RPM options:
michael@428:
michael@428: track: -bt
michael@428: fetch: -bf
michael@428: prep: -bp
michael@428: compile: -bc --short-circuit
michael@428: install: -bi --short-circuit
michael@428: binary: -bb --short-circuit
michael@428: source: -bs
michael@428: all: -ba
michael@428:
michael@428: =item B
michael@428:
michael@428: Peeks file list from package and tags configuration and documentation files.
michael@428:
michael@428: =item B
michael@428:
michael@428: Shows modifications with the help of a possibly underlying Version
michael@428: Control System (VCS) like CVS, Subversion, Monotone, Git, Mercurial or
michael@428: (as a fallback ) OSSP svs.
michael@428:
michael@428: =item B
michael@428: [C<-f>]
michael@428: [C<-o>]
michael@428: [C<-n>]
michael@428: [C<-s>]
michael@428:
michael@428: Installs package.
michael@428: Option
michael@428: C<-f> adds C<--force>,
michael@428: C<-n> adds C<--nodeps> and
michael@428: C<-o> adds C<--oldpackage>
michael@428: to the underlying C call.
michael@428: Option C<-s> prefixes the command with sudo(1).
michael@428:
michael@428: =item B
michael@428: [C<-f>]
michael@428: [C<-o>]
michael@428: [C<-a>]
michael@428: [C<-s>]
michael@428:
michael@428: Erases package.
michael@428: Option
michael@428: C<-f> adds C<--force>,
michael@428: C<-n> adds C<--nodeps> and
michael@428: C<-a> adds C<--allmatches>
michael@428: to the underlying C call.
michael@428: Option C<-s> prefixes the command with sudo(1).
michael@428:
michael@428: =item B
michael@428: [C<-v>]
michael@428: [C<-b>]
michael@428:
michael@428: Lints package sources C<*.spec>, C, C and binary package files.
michael@428: Option C<-v> enables verboseness.
michael@428: Option C<-b> disables the linting of an existing binary package file.
michael@428:
michael@428: =item B
michael@428: [C<-m> I]
michael@428: [C<-n>]
michael@428:
michael@428: Releases package specification to the repository. Unlike previous
michael@428: incarnations of "openpkg dev" this one is not tied to any repository or
michael@428: structure. The default message is created using the difference between
michael@428: the previous and current version of the package specification. In order
michael@428: to grab the previous version, the working directory and three levels
michael@428: towards root are checked for signs of CVS, Subversion, Monotone, Git,
michael@428: Mercurial or SVS information, in that order. The appropriate command is
michael@428: then executed to retrieve the data and the VCS found is passed to the
michael@428: actual release command.
michael@428:
michael@428: Finally, the command specified by the environment variable
michael@428: C or, if omitted, specified by the rpm macro
michael@428: C<%{openpkg_dev_release}> is run and passed the following positional
michael@428: arguments:
michael@428:
michael@428: =over 4
michael@428:
michael@428: openpkg-prefix
michael@428: spec-dir
michael@428: source-dir
michael@428: binary-rpm-file
michael@428: source-rpm-file
michael@428: package-name
michael@428: package-version
michael@428: package-release
michael@428: package-version-old
michael@428: package-release-old
michael@428: commit-message
michael@428: vcs
michael@428:
michael@428: =back
michael@428:
michael@428: For a dry run, set C<$OPENPKG_DEV_RELEASE> to "echo" or use option "C<-n>".
michael@428:
michael@428: =back
michael@428:
michael@428: =head1 UNPACKED SOURCE RPM PACKAGE FILESYSTEM LAYOUT
michael@428:
michael@428: When an OpenPKG source RPM package
michael@428: IC<->IC<->IC<.src.rpm> is unpacked to the
michael@428: filesystem, the following distinct filesystem layouts are known:
michael@428:
michael@428: =over 4
michael@428:
michael@428: =item B
michael@428:
michael@428: =over 4
michael@428:
michael@428: =item ICIC
michael@428:
michael@428: =item ICIC>IC<.spec>
michael@428:
michael@428: =item ICIC>I
michael@428:
michael@428: =item ICIC>I
michael@428:
michael@428: =item ICI
michael@428:
michael@428: =item ICI
michael@428:
michael@428: =item ICI
michael@428:
michael@428: =back
michael@428:
michael@428: This is just the "simple" filesystem layout (see below) with the
michael@428: I set to IC.
michael@428:
michael@428: This is the filesystem layout used by default for building OpenPKG
michael@428: packages during C or the underlying C commands.
michael@428:
michael@428: =item B
michael@428:
michael@428: =over 4
michael@428:
michael@428: =item IC
michael@428:
michael@428: =item IC>IC<.spec>
michael@428:
michael@428: =item IC>I
michael@428:
michael@428: =item IC>I
michael@428:
michael@428: =item IC>I
michael@428:
michael@428: =item IC>I
michael@428:
michael@428: =item IC>I
michael@428:
michael@428: =back
michael@428:
michael@428: This puts everything into one directory.
michael@428:
michael@428: =item B
michael@428:
michael@428: =over 4
michael@428:
michael@428: =item IC>IC
michael@428:
michael@428: =item IC>IC>IC<.spec>
michael@428:
michael@428: =item IC>IC>I
michael@428:
michael@428: =item IC>IC>I
michael@428:
michael@428: =item IC>I
michael@428:
michael@428: =item IC>I
michael@428:
michael@428: =item I<$TMPDIR>CI
michael@428:
michael@428: =back
michael@428:
michael@428: This is the simple filesystem layout of an unpacked
michael@428: OpenPKG package. All files are simply put into a sub-directory with the
michael@428: I of the package.
michael@428:
michael@428: This is the filesystem layout used for the quick patching of a single
michael@428: OpenPKG package in a stand-alone environment.
michael@428:
michael@428: =item B
michael@428:
michael@428: =over 4
michael@428:
michael@428: =item IC>IC
michael@428:
michael@428: =item IC>ICIC<.spec>
michael@428:
michael@428: =item IC>ICI
michael@428:
michael@428: =item IC>ICI
michael@428:
michael@428: =item IC>IC[C]I
michael@428:
michael@428: =item IC>IC[C]I
michael@428:
michael@428: =item IC>ICI
michael@428:
michael@428: =back
michael@428:
michael@428: This is the structured (and default) filesystem layout of an unpacked
michael@428: OpenPKG package. A top-level sub-directory with the I of the
michael@428: package is created. There the package specification and all packaging
michael@428: source files are put into the sub-directory I and all the
michael@428: third-party distribution files are put into the sub-directory I.
michael@428:
michael@428: This is the filesystem layout used for the development of a single
michael@428: OpenPKG package in a stand-alone environment.
michael@428:
michael@428: =item B
michael@428:
michael@428: =over 4
michael@428:
michael@428: =item IC>C<.openpkg/rpmmacros>
michael@428:
michael@428: =item IC>CIC>IC<.spec>
michael@428:
michael@428: =item IC>CIC>I
michael@428:
michael@428: =item IC>CIC>I
michael@428:
michael@428: =item IC>C[C]I
michael@428:
michael@428: =item IC>C[C]I
michael@428:
michael@428: =item IC>CI
michael@428:
michael@428: =back
michael@428:
michael@428: This is the distributed filesystem layout of an unpacked OpenPKG
michael@428: package. It is similar to the structured filesystem layout but the
michael@428: C and C directories and the I directory are swapped,
michael@428: mainly with the intention of bundling together all third-party
michael@428: distribution files of a large number of packages.
michael@428:
michael@428: This is the filesystem layout used for regular OpenPKG package
michael@428: development.
michael@428:
michael@428: =back
michael@428:
michael@428:
michael@428: =head1 LOCAL RPM MACROS FILE (.openpkg/rpmmacros)
michael@428:
michael@428: OpenPKG supports local RPM macros files F<.openpkg/rpmmacros> which
michael@428: can be used to configure RPM in a local scope. This is especially
michael@428: interesting to configure a local (even per-package) build environment
michael@428: with the help of the C<%openpkg_layout> macro.
michael@428:
michael@428: C<%openpkg_layout>
michael@428: [CI]
michael@428: [CI]
michael@428: [CI]
michael@428: [CI]
michael@428: [CI]
michael@428: [CI]
michael@428: [CI]
michael@428: [CI]
michael@428: [CI]
michael@428: [CI]
michael@428:
michael@428: =over 4
michael@428:
michael@428: =item CI
michael@428:
michael@428: Absolute file path of the C<.openpkg/rpmmacros> file where this
michael@428: C<%openpkg_layout> macro is defined. Usually, the intended usage is to
michael@428: leverage from OpenPKG RPM's special C<%{macrosfile}> macro by simply
michael@428: using C. This parameter is important as
michael@428: the default C is derived from it.
michael@428:
michael@428: =item CI
michael@428:
michael@428: Absolute directory path where the C<.openpkg/rpmmacros> file is
michael@428: located under. Usually, the intended usage is to not explicitly
michael@428: set this parameter but let it be determined indirectly via
michael@428: C. The effective default value is equal to a value like
michael@428: C<%{realpath:%{dirname:%{realpath:%{macrosfile}}}/..}> This parameter is
michael@428: important as all standard filesystem layouts (see parameter C)
michael@428: are always at least partially based on this base directory in order
michael@428: to provide absolute-path-independent flexible filesystem layouts.
michael@428:
michael@428: =item CI
michael@428:
michael@428: The name of the filesystem layout type to use. The following standard
michael@428: filesystem layout types are pre-defined: C, C, C,
michael@428: C (default) and C.
michael@428:
michael@428: global macrosdir /etc/openpkg
michael@428: global macrosfile /etc/openpkg/rpmmacros
michael@428: global specdir /RPM/SRC/$name
michael@428: global sourcedir /RPM/SRC/$name
michael@428: global builddir /RPM/TMP
michael@428: global tmpdir /RPM/TMP
michael@428: global binrpmdir /RPM/PKG
michael@428: global srcrpmdir /RPM/PKG
michael@428:
michael@428: local macrosdir /.openpkg
michael@428: local macrosfile /.openpkg/rpmmacros
michael@428: local specdir
michael@428: local sourcedir
michael@428: local builddir
michael@428: local tmpdir
michael@428: local binrpmdir
michael@428: local srcrpmdir
michael@428:
michael@428: simple macrosdir /.openpkg
michael@428: simple macrosfile /.openpkg/rpmmacros
michael@428: simple specdir
michael@428: simple sourcedir
michael@428: simple builddir
michael@428: simple tmpdir
michael@428: simple binrpmdir /..
michael@428: simple srcrpmdir /..
michael@428:
michael@428: structured macrosdir /.openpkg
michael@428: structured macrosfile /.openpkg/rpmmacros
michael@428: structured specdir /src
michael@428: structured sourcedir /dst
michael@428: structured builddir /tmp
michael@428: structured tmpdir /tmp
michael@428: structured binrpmdir /pkg/bin
michael@428: structured srcrpmdir /pkg/src
michael@428:
michael@428: distributed macrosdir /.openpkg
michael@428: distributed macrosfile /.openpkg/rpmmacros
michael@428: distributed specdir /src/
michael@428: distributed sourcedir /dst/
michael@428: distributed builddir /tmp
michael@428: distributed tmpdir /tmp
michael@428: distributed binrpmdir /pkg/bin
michael@428: distributed srcrpmdir /pkg/src
michael@428:
michael@428:
michael@428: =item CI
michael@428:
michael@428: =item CI
michael@428:
michael@428: =item CI
michael@428:
michael@428: =item CI
michael@428:
michael@428: =item CI
michael@428:
michael@428: =item CI
michael@428:
michael@428: These parameters correspond to the six individual directories provided
michael@428: by a standard layout and allow you to selectively adjust parts of a
michael@428: standard layout to local needs and without having to define a full
michael@428: standard layout yourself.
michael@428:
michael@428: The I is a whitespace-separated list of
michael@428: I[C<:>[C<+>]I] specifications which are
michael@428: "first-match" searched for existence. The last directory in the list
michael@428: is always taken as the fallback and if it is not existing it is
michael@428: even created on-the-fly. The IC<:>I
michael@428: syntax variant allows the existence test to use I,
michael@428: but expands to I (replace mode). The
michael@428: IC<:+>I syntax variant allows
michael@428: the existence test to use I, but expands to
michael@428: II (append mode). For instance
michael@428: C will first check for ~/tmp (and then use
michael@428: ~/tmp/openpkg), then for $TMPDIR (and use $TMPDIR/openpkg) and finally
michael@428: it will use /tmp/$LOGNAME/openpkg at last resort.
michael@428:
michael@428: Paths are usually assembled by using RPM macros like
michael@428: C<%{l_prefix}> (the instance prefix), C<%{__openpkg_basename}> (the
michael@428: I parameter), C<%{realpath:} (path resolution),
michael@428: C<%{dirname:} (directory name extraction), C<%{basename:}
michael@428: (file name extraction), etc.
michael@428:
michael@428: =item CI
michael@428:
michael@428: This enables the I components in the standard filesystem
michael@428: layouts by setting it to an automatically generated sub-directory named
michael@428: IC<->I-I. This allows one to build the same OpenPKG
michael@428: package in parallel on multiple hosts in a shared environment (usually
michael@428: on an NFS based filesystem).
michael@428:
michael@428: =item CI
michael@428:
michael@428: This enables debug outputs which shows the effectively used directory
michael@428: paths.
michael@428:
michael@428: =back
michael@428:
michael@428: The generated C<.openpkg/rpmmacros> file contains the generic filesystem
michael@428: layout glue configuration for the particular filesystem I.
michael@428:
michael@428: =over 1
michael@428:
michael@428: =item C<%openpkg_layout macrosfile=%{macrosfile} layout=>I
michael@428:
michael@428: =back
michael@428:
michael@428: =head1 CONFIGURATION
michael@428:
michael@428: =over 4
michael@428:
michael@428: OPENPKG_NAME="Ralf S. Engelschall"
michael@428: OPENPKG_MAIL="rse@openpkg.net"
michael@428: OPENPKG_MODE="developer"
michael@428:
michael@428: OPENPKG_PREFIX="/openpkg"
michael@428: OPENPKG_TMPDIR="${TMPDIR-/tmp}/openpkg"
michael@428:
michael@428: OPENPKG_VCS="cvs ci -m '' ."
michael@428: OPENPKG_UPLD="scp openpkg-ftp@ftp.openpkg.org:/current/SRC/00UPLOAD/"
michael@428:
michael@428: =back
michael@428:
michael@428: =head1 ABOUT
michael@428:
michael@428: OpenPKG B is Ralf S. Engelschall's Perl-based clean-room partial
michael@428: re-implementation of 2008 for OpenPKG 4.0 of Thomas Lotterer's original
michael@428: OpenPKG B Bash-based shell from 2002.
michael@428:
michael@428: =cut
michael@428: