1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/openpkg/README Tue Jan 06 23:40:39 2009 +0100
1.3 @@ -0,0 +1,189 @@
1.4 +
1.5 + OpenPKG Boostrap Package Source Tree
1.6 + ====================================
1.7 +
1.8 + This is the source code tree for the OpenPKG bootstrap package. What
1.9 + you find here is rather complex and tricky stuff, so don't be confused
1.10 + if you don't understand everything immediately.
1.11 +
1.12 + The Files
1.13 + ---------
1.14 +
1.15 + README .................. this file ;-)
1.16 + HISTORY ................. change history tracking of this package
1.17 +
1.18 + openpkg.spec ............ the regular build procedure
1.19 + openpkg.boot ............ the bootstrapping procedure
1.20 +
1.21 + gzip-*.tar .............. untouched distribution tarball of the GNU gzip tool
1.22 + make-*.tar.gz ........... untouched distribution tarball of the GNU make tool
1.23 + patch-*.tar.gz .......... untouched distribution tarball of the GNU patch tool
1.24 + bash-*.tar.gz ........... untouched distribution tarball of the GNU bash tool
1.25 + tar-*.tar.gz ............ untouched distribution tarball of the GNU tar tool
1.26 + uuid-*.tar.gz ........... untouched distribution tarball of the OSSP uuid tool
1.27 + curl-*.tar.gz ........... untouched distribution tarball of the cURL tool
1.28 + bzip2-*.tar.gz .......... untouched distribution tarball of the BZIP2 library
1.29 + zlib-*.tar.gz ........... untouched distribution tarball of the ZLIB library
1.30 + beecrypt-*.tar.gz ....... untouched distribution tarball of the BeeCrypt library
1.31 + rpm-*.tar.gz ............ untouched distribution tarball of the RPM tool
1.32 + config-*.tar.gz ......... untouched distribution tarball of the GNU config scripts
1.33 + openpkg-registry-*.tar.gz untouched distribution tarball of the OpenPKG Registry
1.34 + openpkg-tools-*.tar.gz .. untouched distribution tarball of the OpenPKG Tool Chain
1.35 + openssl-*.tar.gz ........ untouched distribution tarball of the OpenSSL toolkit
1.36 + perl-*-mini.tar.gz ...... stripped down distribution tarball of the Perl tool
1.37 +
1.38 + make.patch .............. patch for GNU make
1.39 + bash.patch .............. patch for GNU bash
1.40 + tar.patch ............... patch for GNU tar
1.41 + beecrypt.patch .......... patch for BeeCrypt
1.42 + openssl.patch ........... patch for OpenSSL
1.43 + perl.patch .............. patch for Perl
1.44 + gzip.c .................. replacement file for GNU gzip
1.45 + rpm.patch.bugfix ........ patch for RPM (bugfixing parts)
1.46 + rpm.patch.feature ....... patch for RPM (new features parts)
1.47 + rpm.patch.porting ....... patch for RPM (portability enhancement parts)
1.48 + rpm.patch.regen ......... patch for RPM (re-generated files parts)
1.49 +
1.50 + rpmpopt ................. replacements/extensions for RPM's POPT configuration
1.51 + rpmmacros ............... replacements/extensions for RPM's macros
1.52 + rpmrc ................... replacements for RPM's run-command configuration
1.53 +
1.54 + root.README ............. the source for installed <prefix>/README
1.55 + local.README ............ the source for installed <prefix>/local/README
1.56 + dot.bashrc .............. the source for installed <prefix>/.bashrc
1.57 + dot.bash_login .......... the source for installed <prefix>/.bash_login
1.58 + dot.lsyncrc ............. the source for installed <prefix>/local/.lsyncrc
1.59 +
1.60 + openpkg.c ............... the OpenPKG frontend (set-uid wrapper)
1.61 + openpkg.sh .............. the OpenPKG frontend (main script)
1.62 + openpkg.pod ............. the OpenPKG frontend manual page (source)
1.63 + openpkg.1 ............... the OpenPKG frontend manual page (pre-generated output)
1.64 +
1.65 + rc ...................... the OpenPKG run-command handling script
1.66 + rc.func ................. the OpenPKG run-command function definitions
1.67 + rc.conf ................. the OpenPKG run-command configuration template
1.68 + rc.openpkg .............. the OpenPKG run-command script for the bootstrap package
1.69 + rc.pod .................. the OpenPKG run-command script manual page (source)
1.70 + rc.8 .................... the OpenPKG run-command script manual page (pre-generated output)
1.71 +
1.72 + release.sh .............. the OpenPKG release information utility script
1.73 + release.pod ............. the OpenPKG release information utility manual page (source)
1.74 + release.8 ............... the OpenPKG release information utility manual page (pre-generated output)
1.75 +
1.76 + uuid.sh ................. the OpenPKG UUID management utility script
1.77 + uuid.pod ................ the OpenPKG UUID management utility manual page (source)
1.78 + uuid.8 .................. the OpenPKG UUID management utility manual page (pre-generated output)
1.79 +
1.80 + rpmdb ................... the OpenPKG RPM database management utility
1.81 +
1.82 + rpmtool ................. the rpmtool tool (program source)
1.83 + rpmtool.8 ............... the rpmtool tool (manual page)
1.84 + rpmtool.pod ............. the rpmtool tool (manual page source)
1.85 + shtool .................. the portable shell tool (GNU shtool)
1.86 +
1.87 + rpm-config.sh ........... the RPM C API helper script
1.88 + rpm-config.pod .......... the RPM C API helper manual page (source)
1.89 + rpm-config.8 ............ the RPM C API helper manual page (pre-generated output)
1.90 +
1.91 + lsync ................... the lsync tool (program source)
1.92 + lsync.8 ................. the lsync tool (manual page)
1.93 + lsync.pod ............... the lsync tool (manual page source)
1.94 +
1.95 + aux.usrgrp.sh ........... user/group name/id determination script
1.96 + aux.prereq.sh ........... prerequisite checking script
1.97 + aux.wrapsrc.sh .......... wrapper script for generating openpkg-V-R.src.sh
1.98 + aux.wrapbin.sh .......... wrapper script for generating openpkg-V-R.P-L.sh
1.99 +
1.100 + pod2man.sh .............. helper script for pre-generating manual page outputs
1.101 + man.sh .................. helper script for "openpkg man" command
1.102 + install.sh .............. helper script for "openpkg install" command
1.103 +
1.104 + openpkg.org.pgp ......... the OpenPGP public key "OpenPKG <openpkg@openpkg.org>"
1.105 + openpkg.com.pgp ......... the OpenPGP public key "OpenPKG GmbH <openpkg@openpkg.com>"
1.106 + openpkg.net.pgp ......... the OpenPGP public key "OpenPKG Foundation e.V. <openpkg@openpkg.net>"
1.107 +
1.108 + The Bootstrapping Procedure
1.109 + ---------------------------
1.110 +
1.111 + The complexity of this OpenPKG RPM package results from the fact that
1.112 + we force us to treat this bootstrapping package equal to every other
1.113 + regular OpenPKG RPM package. First, this implies that the packaging
1.114 + tool RPM is packaged with itself as an OpenPKG RPM package (means: its
1.115 + build procedure is a real RPM .spec file and it can be installed and
1.116 + upgraded through a binary or source RPM). Second, RPM is installed
1.117 + into the same filesystem hierarchy as all other packages. Third, RPM
1.118 + manages its own files. The reason for this approach should be obvious:
1.119 + 100% consistency for the whole OpenPKG software packaging facility!
1.120 +
1.121 + The drawback is that this package requires a very tricky bootstrapping
1.122 + procedure which had cost a lot of time to figure out and establish. If
1.123 + you ever wanted to know the gory details, here they are...
1.124 +
1.125 + The first step was that we wrote the regular openpkg.spec file for
1.126 + building the bootstrap package with OpenPKG RPM under the assumption
1.127 + that OpenPKG RPM is already available. This way we can provide OpenPKG
1.128 + RPM as an RPM package. Just remains the problem how we actually
1.129 + bootstrap in case where OpenPKG RPM is still not available, i.e.,
1.130 + when we reach a new platform and have to build the package from
1.131 + scratch. Here the "openpkg.boot" script comes into play. It executes
1.132 + the "openpkg.spec" build procedure very similar to the way the real
1.133 + OpenPKG RPM would do ("openpkg rpm -bb"). That is, "openpkg.boot"
1.134 + partly emulates OpenPKG RPM -- just enough that "openpkg.spec" works.
1.135 + As a result, "openpkg.spec" cannot use any fancy OpenPKG RPM features
1.136 + or other things before "openpkg.boot" is able to emulate it, of
1.137 + course.
1.138 +
1.139 + After "openpkg.boot" executed the "%prep", "%build" and "%install"
1.140 + scripts of "openpkg.spec", there is a fresh version of the target
1.141 + filesystem hierarchy staying under a temporary "build root". The
1.142 + "openpkg.boot" script then creates a very special temporary "openpkg
1.143 + rpm" command which allows the installed "openpkg rpm" command inside
1.144 + the "build root" to work (although it is built for the final target
1.145 + filesystem path). Then the $RPM_BOOT variable is set and the package
1.146 + is _again_ build via "openpkg.spec" -- but this time with the real
1.147 + OpenPKG RPM. To avoid unneccessary re-compilation, the "openpkg.spec"
1.148 + skips "%prep", "%build" and "%install" sections if $RPM_BOOT is
1.149 + defined. So, on this second build phase, only the "%files" section is
1.150 + executed, i.e., a binary OpenPKG RPM package "openpkg-V-R.P-T.rpm"
1.151 + is rolled from the files in the "build root". Additionally, a source
1.152 + OpenPKG RPM package "openpkg-V-R.src.rpm" is rolled for consistency
1.153 + reasons.
1.154 +
1.155 + Finally, we override the installation in the "build root"
1.156 + again by installing the now rolled binary OpenPKG RPM package
1.157 + "openpkg-V-R.P-T.rpm" by using the real OpenPKG RPM. This way
1.158 + we achieve that OpenPKG RPM is remembered as a real OpenPKG RPM
1.159 + package in the RPM database. We just have to make sure the package
1.160 + is still relocated to the "build root" while installing. For this
1.161 + we could use "--prefix=$RPM_BUILD_ROOT%{l_prefix}", but this would
1.162 + create an incorrect file list for the package "openpkg" in the RPM
1.163 + database. Instead we use the tricky "--justdb" option for "openpkg
1.164 + rpm" which means "openpkg rpm" behaves as it would install into the
1.165 + real location, but does not actually install anything. But as a
1.166 + side-effect, the database inside the "build root" is now correct.
1.167 +
1.168 + After this procedure, the "build root" contains the target filesystem
1.169 + hierarchy with OpenPKG RPM installed with itself. What is now just
1.170 + remaining is to roll a bootstrap package "openpkg" with this stuff for
1.171 + initial installation without OpenPKG RPM. For this the "build root"
1.172 + is packed into a "tarball", compressed, again wrapped into another
1.173 + tarball together with the uncompression tools ("bzip2" and "tar"),
1.174 + and finally wrapped into a self-extracting shell script by appending
1.175 + "aux.wrapbin.sh" (padded to 64KB for easier unpacking of the attached
1.176 + tarball) to its front.
1.177 +
1.178 + The result is the binary bootstrap script "openpkg-V-R.P-T.sh" which
1.179 + can be used to install the target hierarchy from scratch without any
1.180 + pre-installed OpenPKG RPM. Nevetheless, the installed target hierarchy
1.181 + looks _exactly_ as it would have been installed with OpenPKG RPM.
1.182 + If one later wants to upgrade this hierarchy one can just use the
1.183 + generated (or a newer) "openpkg-V-R.P-T.rpm".
1.184 +
1.185 + To allow one to easily repeat this from-source bootstrapping procedure
1.186 + on other machines, one can run "./openpkg.boot -s" which rolls
1.187 + a "openpkg-V-R.src.sh" script which is a self-extracting script
1.188 + containing an attached tarball of the sources of this directory. This
1.189 + script contains the same contents like "openpkg-V-R.src.rpm", but
1.190 + is intended for running the described bootstrapping procedure from
1.191 + scratch without any OpenPKG RPM.
1.192 +
