openpkg-packages/openpkg/README

  OpenPKG Source Code 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 ;)

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

  gzip-1.3.tar ............ untouched distribution tarball of the GNU gzip tool
  make-3.79.1.tar.gz ...... untouched distribution tarball of the GNU make tool
  patch-2.5.4.tar.gz ...... untouched distribution tarball of the GNU patch tool
  bash-2.05a.tar.gz ....... untouched distribution tarball of the GNU bash tool

  rpm-4.0.2.tar.gz ........ distribution tarball of the RPM tool
  rpm-4.0.2.patch.bugfix .. patch for RPM (bugfixing parts) 
  rpm-4.0.2.patch.feature . patch for RPM (new features parts) 
  rpm-4.0.2.patch.porting . patch for RPM (portability enhancement parts) 
  rpm-4.0.2.patch.regen ... patch for RPM (re-generated files parts) 
  db-3.2.9.tar.gz ......... untouched distribution tarball of the Berkeley-DB library
  db-3.2.9.patch .......... patch for Berkeley-DB library
  bzip2-1.0.1.tar.gz ...... untouched distribution tarball of the BZIP2 library
  zlib-1.1.3.tar.gz ....... untouched distribution tarball of the ZLIB library
  curl-7.9.1.tar.gz ....... untouched distribution tarball of the cURL tool

  rpmpopt ................. extensions for RPM's popt configuration
  rpmrc ................... replacements for RPM's run-commands
  rpmmacros ............... replacements for RPM's macros

  root.README ............. the <root>/README file for the installation area
  local.README ............ the <root>/local/README file for the installation area
  dot.bashrc .............. the <root>/.bashrc file 
  dot.bash_login .......... the <root>/.bash_login file 
  dot.lsyncrc ............. the <root>/local/.lsyncrc file 
  
  rc ...................... the run-command handling script
  rc.func ................. the run-command function definitions
  rc.conf ................. the run-command configuration template
  rc.openpkg .............. the run-command script for the OpenPKG hierarchy

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

  wrap1.sh ................ wrapper script for generating openpkg-X.X-X.src.sh
  wrap2.sh ................ wrapper script for generating openpkg-X.X-X.YYY-YYYY-ZZ.sh 

  openpkg.pgp ............. the OpenPGP public key of "The OpenPKG Project"

  shtool .................. the pre-generated GNU shtool program

  rpmx.sh ................. RPM eXtension (Shell wrapper)
  rpmx.pl ................. RPM eXtension (Perl program)

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

  The complexity of this RPM package results from the fact that we force
  us to treat RPM equal to every other package. This implies first that
  RPM itself is an RPM package (means: its build procedure is a RPM
  spec-file and it can be installed and upgraded through a binary or
  source RPM), second that RPM is installed into the same filesystem
  hierarchy as all other packages and third that RPM manages its own
  files. The reason for this should be obvious: 100% consistency for the
  whole software package facility!

  The drawback is that the RPM 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 RPM with the assumption that RPM is already available. This
  way we can provide RPM as an RPM package. Remains the problem how we
  actually bootstrap in the case where RPM is still not available, i.e.,
  when we reach a new platform. Here the openpkg.boot script comes into
  play. It executes the openpkg.spec build procedure very similar to the way
  RPM would do it. That is, openpkg.boot partly emulates RPM -- just enough
  that openpkg.spec works. As a result, openpkg.spec cannot use any fancy 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 "rpm" command which allows the installed
  "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 RPM package is again "built" via openpkg.spec -- but this time
  with the real RPM tool. To avoid unneccessary re-compilation, the
  openpkg.spec skips %prep, %build and %install if RPM_BOOT is defined, so
  on this second build phase, only %files is executed, i.e., a binary
  RPM openpkg-X.X-X.YYYY-YYYYYY-ZZ.rpm is rolled from the files in the
  build root. Additionally a source RPM openpkg-X.X-X.src.rpm is rolled
  for consistency reasons.

  Finally we override the installation in the build root again by
  installing the now rolled binary RPM -- again by using the real RPM
  tool. This way we achieve that RPM is remembered as an RPM package
  in its own 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 filelist for "rpm" in the database. Instead we use the
  tricky --justdb option for "rpm" which means "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 RPM installed with itself. What is now remaining is to
  roll a bootstrap package with this stuff for initial installation. For
  this the build root is packed into a tarball, compressed, uuencoded,
  and finally wrapped into a self-extracting shell script. The result
  is the binary bootstrap script openpkg-X.X-X.YYYY-YYYYYYY-ZZ.sh
  which can be used to bootstrap the target hierarchy from
  scratch. If one later wants to upgrade this hierarchy one uses
  openpkg-X.X-X.YYYY-YYYYYYY-ZZ.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-X.X-X.src.sh script which is a self-extracting script containing a
  tarball of this directory. This script is like openpkg-X.X-X.src.rpm, but
  for bootstrapping situations.

  Supported Platforms
  -------------------

  Currently the following platforms are supported:

                    _______ Supported ________
  Operating System  Still    Official Already 
  ----------------- -------- -------- --------
  FreeBSD           4.[0-2]  4.3-S    5.0-C
  Debian GNU/Linux  -        2.2      3.0
  Solaris           2.[67]   2.8      -
  ----------------- -------- -------- --------
  NetBSD            1.5      1.5.1    -
  OpenBSD           -        2.9      -
  Tru64             -        5.0A     5.1A