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 ICICIC<.spec> michael@428: michael@428: =item ICICI michael@428: michael@428: =item ICICI 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 ICIC<.spec> michael@428: michael@428: =item ICI michael@428: michael@428: =item ICI 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 puts everything into one directory. michael@428: michael@428: =item B michael@428: michael@428: =over 4 michael@428: michael@428: =item ICIC michael@428: michael@428: =item ICICIC<.spec> michael@428: michael@428: =item ICICI michael@428: michael@428: =item ICICI michael@428: michael@428: =item ICI michael@428: michael@428: =item ICI 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 ICIC michael@428: michael@428: =item ICICIC<.spec> michael@428: michael@428: =item ICICI michael@428: michael@428: =item ICICI michael@428: michael@428: =item ICIC[C]I michael@428: michael@428: =item ICIC[C]I michael@428: michael@428: =item ICICI 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 ICC<.openpkg/rpmmacros> michael@428: michael@428: =item ICCICIC<.spec> michael@428: michael@428: =item ICCICI michael@428: michael@428: =item ICCICI michael@428: michael@428: =item ICC[C]I michael@428: michael@428: =item ICC[C]I michael@428: michael@428: =item ICCI 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: