
  OpenPKG Boostrap Package Source Tree
  ====================================

  This is the source code tree for the OpenPKG bootstrap package. What
  you find here is rather complex and tricky stuff, so don't be confused
  if you don't understand everything immediately.

  The Files
  ---------

  README .................. this file ;-)
  HISTORY ................. change history tracking of this package

  openpkg.spec ............ the regular build procedure
  openpkg.boot ............ the bootstrapping procedure

  gzip-*.tar .............. untouched distribution tarball of the GNU gzip tool
  make-*.tar.gz ........... untouched distribution tarball of the GNU make tool
  patch-*.tar.gz .......... untouched distribution tarball of the GNU patch tool
  bash-*.tar.gz ........... untouched distribution tarball of the GNU bash tool
  tar-*.tar.gz ............ untouched distribution tarball of the GNU tar tool
  uuid-*.tar.gz ........... untouched distribution tarball of the OSSP uuid tool
  curl-*.tar.gz ........... untouched distribution tarball of the cURL tool
  bzip2-*.tar.gz .......... untouched distribution tarball of the BZIP2 library
  zlib-*.tar.gz ........... untouched distribution tarball of the ZLIB library
  beecrypt-*.tar.gz ....... untouched distribution tarball of the BeeCrypt library
  rpm-*.tar.gz ............ untouched distribution tarball of the RPM tool
  config-*.tar.gz ......... untouched distribution tarball of the GNU config scripts
  openpkg-registry-*.tar.gz untouched distribution tarball of the OpenPKG Registry
  openpkg-tools-*.tar.gz .. untouched distribution tarball of the OpenPKG Tool Chain
  openssl-*.tar.gz ........ untouched distribution tarball of the OpenSSL toolkit
  perl-*-mini.tar.gz ...... stripped down distribution tarball of the Perl tool

  make.patch .............. patch for GNU make
  bash.patch .............. patch for GNU bash
  tar.patch ............... patch for GNU tar
  beecrypt.patch .......... patch for BeeCrypt
  openssl.patch ........... patch for OpenSSL
  perl.patch .............. patch for Perl
  gzip.c .................. replacement file for GNU gzip
  rpm.patch.bugfix ........ patch for RPM (bugfixing parts)
  rpm.patch.feature ....... patch for RPM (new features parts)
  rpm.patch.porting ....... patch for RPM (portability enhancement parts)
  rpm.patch.regen ......... patch for RPM (re-generated files parts)

  rpmpopt ................. replacements/extensions for RPM's POPT configuration
  rpmmacros ............... replacements/extensions for RPM's macros
  rpmrc ................... replacements for RPM's run-command configuration

  root.README ............. the source for installed <prefix>/README
  local.README ............ the source for installed <prefix>/local/README
  dot.bashrc .............. the source for installed <prefix>/.bashrc
  dot.bash_login .......... the source for installed <prefix>/.bash_login
  dot.lsyncrc ............. the source for installed <prefix>/local/.lsyncrc

  openpkg.c ............... the OpenPKG frontend (set-uid wrapper)
  openpkg.sh .............. the OpenPKG frontend (main script)
  openpkg.pod ............. the OpenPKG frontend manual page (source)
  openpkg.1 ............... the OpenPKG frontend manual page (pre-generated output)

  rc ...................... the OpenPKG run-command handling script
  rc.func ................. the OpenPKG run-command function definitions
  rc.conf ................. the OpenPKG run-command configuration template
  rc.openpkg .............. the OpenPKG run-command script for the bootstrap package
  rc.pod .................. the OpenPKG run-command script manual page (source)
  rc.8 .................... the OpenPKG run-command script manual page (pre-generated output)

  release.sh .............. the OpenPKG release information utility script
  release.pod ............. the OpenPKG release information utility manual page (source)
  release.8 ............... the OpenPKG release information utility manual page (pre-generated output)

  uuid.sh ................. the OpenPKG UUID management utility script
  uuid.pod ................ the OpenPKG UUID management utility manual page (source)
  uuid.8 .................. the OpenPKG UUID management utility manual page (pre-generated output)

  rpmdb ................... the OpenPKG RPM database management utility

  rpmtool ................. the rpmtool tool (program source)
  rpmtool.8 ............... the rpmtool tool (manual page)
  rpmtool.pod ............. the rpmtool tool (manual page source)
  shtool .................. the portable shell tool (GNU shtool)

  rpm-config.sh ........... the RPM C API helper script
  rpm-config.pod .......... the RPM C API helper manual page (source)
  rpm-config.8 ............ the RPM C API helper manual page (pre-generated output)

  lsync ................... the lsync tool (program source)
  lsync.8 ................. the lsync tool (manual page)
  lsync.pod ............... the lsync tool (manual page source)

  aux.usrgrp.sh ........... user/group name/id determination script
  aux.prereq.sh ........... prerequisite checking script
  aux.wrapsrc.sh .......... wrapper script for generating openpkg-V-R.src.sh
  aux.wrapbin.sh .......... wrapper script for generating openpkg-V-R.P-L.sh

  pod2man.sh .............. helper script for pre-generating manual page outputs
  man.sh .................. helper script for "openpkg man" command
  install.sh .............. helper script for "openpkg install" command

  openpkg.org.pgp ......... the OpenPGP public key "OpenPKG <openpkg@openpkg.org>"
  openpkg.com.pgp ......... the OpenPGP public key "OpenPKG GmbH <openpkg@openpkg.com>"
  openpkg.net.pgp ......... the OpenPGP public key "OpenPKG Foundation e.V. <openpkg@openpkg.net>"

  The Bootstrapping Procedure
  ---------------------------

  The complexity of this OpenPKG RPM package results from the fact that
  we force us to treat this bootstrapping package equal to every other
  regular OpenPKG RPM package. First, this implies that the packaging
  tool RPM is packaged with itself as an OpenPKG RPM package (means: its
  build procedure is a real RPM .spec file and it can be installed and
  upgraded through a binary or source RPM). Second, RPM is installed
  into the same filesystem hierarchy as all other packages. Third, RPM
  manages its own files. The reason for this approach should be obvious:
  100% consistency for the whole OpenPKG software packaging facility!

  The drawback is that this package requires a very tricky bootstrapping
  procedure which had cost a lot of time to figure out and establish. If
  you ever wanted to know the gory details, here they are...

  The first step was that we wrote the regular openpkg.spec file for
  building the bootstrap package with OpenPKG RPM under the assumption
  that OpenPKG RPM is already available. This way we can provide OpenPKG
  RPM as an RPM package. Just remains the problem how we actually
  bootstrap in case where OpenPKG RPM is still not available, i.e.,
  when we reach a new platform and have to build the package from
  scratch. Here the "openpkg.boot" script comes into play. It executes
  the "openpkg.spec" build procedure very similar to the way the real
  OpenPKG RPM would do ("openpkg rpm -bb"). That is, "openpkg.boot"
  partly emulates OpenPKG RPM -- just enough that "openpkg.spec" works.
  As a result, "openpkg.spec" cannot use any fancy OpenPKG RPM features
  or other things before "openpkg.boot" is able to emulate it, of
  course.

  After "openpkg.boot" executed the "%prep", "%build" and "%install"
  scripts of "openpkg.spec", there is a fresh version of the target
  filesystem hierarchy staying under a temporary "build root". The
  "openpkg.boot" script then creates a very special temporary "openpkg
  rpm" command which allows the installed "openpkg rpm" command inside
  the "build root" to work (although it is built for the final target
  filesystem path). Then the $RPM_BOOT variable is set and the package
  is _again_ build via "openpkg.spec" -- but this time with the real
  OpenPKG RPM. To avoid unneccessary re-compilation, the "openpkg.spec"
  skips "%prep", "%build" and "%install" sections if $RPM_BOOT is
  defined. So, on this second build phase, only the "%files" section is
  executed, i.e., a binary OpenPKG RPM package "openpkg-V-R.P-T.rpm"
  is rolled from the files in the "build root". Additionally, a source
  OpenPKG RPM package "openpkg-V-R.src.rpm" is rolled for consistency
  reasons.

  Finally, we override the installation in the "build root"
  again by installing the now rolled binary OpenPKG RPM package
  "openpkg-V-R.P-T.rpm" by using the real OpenPKG RPM. This way
  we achieve that OpenPKG RPM is remembered as a real OpenPKG RPM
  package in the RPM database. We just have to make sure the package
  is still relocated to the "build root" while installing. For this
  we could use "--prefix=$RPM_BUILD_ROOT%{l_prefix}", but this would
  create an incorrect file list for the package "openpkg" in the RPM
  database. Instead we use the tricky "--justdb" option for "openpkg
  rpm" which means "openpkg rpm" behaves as it would install into the
  real location, but does not actually install anything. But as a
  side-effect, the database inside the "build root" is now correct.

  After this procedure, the "build root" contains the target filesystem
  hierarchy with OpenPKG RPM installed with itself. What is now just
  remaining is to roll a bootstrap package "openpkg" with this stuff for
  initial installation without OpenPKG RPM. For this the "build root"
  is packed into a "tarball", compressed, again wrapped into another
  tarball together with the uncompression tools ("bzip2" and "tar"),
  and finally wrapped into a self-extracting shell script by appending
  "aux.wrapbin.sh" (padded to 64KB for easier unpacking of the attached
  tarball) to its front.

  The result is the binary bootstrap script "openpkg-V-R.P-T.sh" which
  can be used to install the target hierarchy from scratch without any
  pre-installed OpenPKG RPM. Nevetheless, the installed target hierarchy
  looks _exactly_ as it would have been installed with OpenPKG RPM.
  If one later wants to upgrade this hierarchy one can just use the
  generated (or a newer) "openpkg-V-R.P-T.rpm".

  To allow one to easily repeat this from-source bootstrapping procedure
  on other machines, one can run "./openpkg.boot -s" which rolls
  a "openpkg-V-R.src.sh" script which is a self-extracting script
  containing an attached tarball of the sources of this directory. This
  script contains the same contents like "openpkg-V-R.src.rpm", but
  is intended for running the described bootstrapping procedure from
  scratch without any OpenPKG RPM.

