diff -r 333964c621f1 -r cb59d6afeb61 openpkg/README --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/openpkg/README Tue Jan 06 23:40:39 2009 +0100 @@ -0,0 +1,189 @@ + + 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 /README + local.README ............ the source for installed /local/README + dot.bashrc .............. the source for installed /.bashrc + dot.bash_login .......... the source for installed /.bash_login + dot.lsyncrc ............. the source for installed /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.com.pgp ......... the OpenPGP public key "OpenPKG GmbH " + openpkg.net.pgp ......... the OpenPGP public key "OpenPKG Foundation e.V. " + + 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. +